{"id":18637110,"url":"https://github.com/openshift/windows-machine-config-operator","last_synced_at":"2025-04-05T13:09:21.256Z","repository":{"id":37502665,"uuid":"241223637","full_name":"openshift/windows-machine-config-operator","owner":"openshift","description":"Windows MCO for OpenShift that handles addition of Windows nodes to the cluster","archived":false,"fork":false,"pushed_at":"2024-10-17T22:15:30.000Z","size":44510,"stargazers_count":41,"open_issues_count":29,"forks_count":68,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-10-19T14:44:19.262Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openshift.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-17T22:45:28.000Z","updated_at":"2024-10-17T04:01:44.000Z","dependencies_parsed_at":"2024-03-29T00:25:21.362Z","dependency_job_id":"df606c63-ddf6-4f67-9c2e-de92c94423e7","html_url":"https://github.com/openshift/windows-machine-config-operator","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fwindows-machine-config-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fwindows-machine-config-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fwindows-machine-config-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openshift%2Fwindows-machine-config-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openshift","download_url":"https://codeload.github.com/openshift/windows-machine-config-operator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247339158,"owners_count":20923014,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T05:33:26.129Z","updated_at":"2025-04-05T13:09:21.222Z","avatar_url":"https://github.com/openshift.png","language":"Go","readme":"# Windows Machine Config Operator\n\n## Introduction\nThe Windows Machine Config Operator configures Windows instances into nodes, enabling Windows container workloads to\nbe ran within OKD/OCP clusters. Windows instances can be added either by creating a [MachineSet](https://docs.openshift.com/container-platform/latest/machine_management/creating_machinesets/creating-machineset-aws.html#machine-api-overview_creating-machineset-aws),\nor by specifying existing instances through a ConfigMap. The operator will do all the necessary steps to configure the instance so that it\ncan join the cluster as a worker node.\n\nMore design details can be explored in the [WMCO enhancement](https://github.com/openshift/enhancements/blob/master/enhancements/windows-containers/windows-machine-config-operator.md).\n\n## Pre-requisites\n- [Cluster and OS pre-requisites](docs/wmco-prerequisites.md)\n\n## Usage\n\n### Installation\nThe operator can be installed from the *community-operators* catalog on OperatorHub.\nIt can also be build and installed from source manually, see the [development instructions](docs/HACKING.md).\n\n### Create a private key secret\nOnce the `openshift-windows-machine-config-operator` namespace has been created, a secret must be created containing\nthe private key that will be used to access the Windows instances:\n```shell script\n# Create secret containing the private key in the openshift-windows-machine-config-operator namespace\noc create secret generic cloud-private-key --from-file=private-key.pem=/path/to/key -n openshift-windows-machine-config-operator\n```\nWe strongly recommend not using the same\n[private key](https://docs.openshift.com/container-platform/latest/installing/installing_azure/installing-azure-default.html#ssh-agent-using_installing-azure-default)\nused when installing the cluster\n\n#### Changing the private key secret\nChanging the private key used by WMCO can be done by updating the contents of the existing `cloud-private-key` secret.\nSome important things to note:\n* Any existing Windows Machines will be destroyed and recreated in order to make use of the new key.\n  This will be done one at a time, until all Machines have been handled.\n* BYOH instances must be updated by the user, such that the new public key is present within the authorized_keys file.\n  You are free to remove the previous key. If the new key is not authorized, WMCO will not be able to access any BYOH\n  nodes. **Upgrade and Node removal functionality will not function properly until this step is complete.**\n\n### Configuring BYOH (Bring Your Own Host) Windows instances\n\n### Instance Pre-requisites\nAny Windows instances that are to be attached to the cluster as a node must fulfill these [pre-requisites](docs/byoh-instance-pre-requisites.md).\n\n### Adding instances\nA ConfigMap named `windows-instances` must be created in the WMCO namespace, describing the instances that should be\njoined to a cluster. The required information to configure an instance is:\n* An address to SSH into the instance with. This can be a DNS name or an ipv4 address.\n  * It is highly recommended that a DNS address is provided when instance IPs are assigned via DHCP. If not, it will be\n    up to the user to update the windows-instances ConfigMap whenever an instance is assigned a new IP.\n* The name of the administrator user set up as part of the [instance pre-requisites](#instance-pre-requisites).\n\nEach entry in the data section of the ConfigMap should be formatted with the address as the key, and a value with the\nformat of username=\\\u003cusername\\\u003e. Please see the example below:\n\n```yaml\nkind: ConfigMap\napiVersion: v1\nmetadata:\n  name: windows-instances\n  namespace: openshift-windows-machine-config-operator\ndata:\n  10.1.42.1: |-\n    username=Administrator\n  instance.example.com: |-\n    username=core\n```\n\n#### Removing BYOH Windows instances\nBYOH instances that are attached to the cluster as a node can be removed by deleting the instance's entry in the\nConfigMap. This process will revert instances back to the state they were in before, barring any logs and container\nruntime artifacts.\n\nIn order for an instance to be cleanly removed, it must be accessible with the current private key provided\nto WMCO.\n\nFor example, in order to remove the instance `10.1.42.1` from the above example, the ConfigMap would be changed to\nthe following:\n\n```yaml\nkind: ConfigMap\napiVersion: v1\nmetadata:\n  name: windows-instances\n  namespace: openshift-windows-machine-config-operator\ndata:\n  instance.example.com: |-\n    username=core\n```\n\nDeleting `windows-instances` is viewed as a request to deconfigure all Windows instances added as Nodes.\n\n### Configuring Windows instances provisioned through MachineSets\nBelow is an example of a vSphere Windows MachineSet which can create Windows Machines that the WMCO can react upon.\nPlease note that the windows-user-data secret will be created by the WMCO lazily when it is configuring the first\nWindows Machine. After that, the windows-user-data will be available for the subsequent MachineSets to be consumed.\nIt might take around 10 minutes for the Windows instance to be configured so that it joins the cluster. Please note that\nthe MachineSet should have following labels:\n* *machine.openshift.io/os-id: Windows*\n* *machine.openshift.io/cluster-api-machine-role: worker*\n* *machine.openshift.io/cluster-api-machine-type: worker*\n\nThe following label has to be added to the Machine spec within the MachineSet spec:\n* *node-role.kubernetes.io/worker: \"\"*\n\nNot having these labels will result in the Windows node not being marked as a worker.\n\n`\u003cinfrastructureID\u003e` should be replaced with the output of:\n```shell script\noc get -o jsonpath='{.status.infrastructureName}{\"\\n\"}' infrastructure cluster\n```\nThe following template variables need to be replaced as follows with values from your vSphere environment:\n* *\\\u003cWindows_VM_template\\\u003e*: template name\n* *\\\u003cVM Network Name\\\u003e*: network name, must match the network name where other Linux workers are in the cluster\n* *\\\u003cvCenter DataCenter Name\\\u003e*: datacenter name\n* *\\\u003cPath to VM Folder in vCenter\\\u003e*: path where your OpenShift cluster is running\n* *\\\u003cvCenter Datastore Name\\\u003e*: datastore name\n* *\\\u003cvCenter Server FQDN/IP\\\u003e*: IP address or FQDN of the vCenter server\n\n*IMPORTANT*:\n- The VM template provided in the MachineSet must use a supported Windows Server\n  version, as described in [vSphere prerequisites](docs/vsphere-prerequisites.md).\n- On vSphere, Windows Machine names cannot be more than 15 characters long. The\n  MachineSet name, therefore, cannot be more than 9 characters long, due to the\n  way Machine names are generated from it.\n```yaml\napiVersion: machine.openshift.io/v1beta1\nkind: MachineSet\nmetadata:\n  labels:\n    machine.openshift.io/cluster-api-cluster: \u003cinfrastructureID\u003e\n  name: winworker\n  namespace: openshift-machine-api\nspec:\n  replicas: 1\n  selector:\n    matchLabels:\n      machine.openshift.io/cluster-api-cluster: \u003cinfrastructureID\u003e\n      machine.openshift.io/cluster-api-machineset: winworker\n  template:\n    metadata:\n      labels:\n        machine.openshift.io/cluster-api-cluster: \u003cinfrastructureID\u003e\n        machine.openshift.io/cluster-api-machine-role: worker\n        machine.openshift.io/cluster-api-machine-type: worker\n        machine.openshift.io/cluster-api-machineset: winworker\n        machine.openshift.io/os-id: Windows\n    spec:\n      metadata:\n        labels:\n          node-role.kubernetes.io/worker: \"\"\n      providerSpec:\n        value:\n          apiVersion: vsphereprovider.openshift.io/v1beta1\n          credentialsSecret:\n            name: vsphere-cloud-credentials\n          diskGiB: 128\n          kind: VSphereMachineProviderSpec\n          memoryMiB: 16384\n          metadata:\n            creationTimestamp: null\n          network:\n            devices:\n            - networkName:  \"\u003cVM Network Name\u003e\"\n          numCPUs: 4\n          numCoresPerSocket: 1\n          snapshot: \"\"\n          template: \u003cWindows_VM_template\u003e\n          userDataSecret:\n            name: windows-user-data\n          workspace:\n             datacenter: \u003cvCenter DataCenter Name\u003e\n             datastore: \u003cvCenter Datastore Name\u003e\n             folder: \u003cPath to VM Folder in vCenter\u003e # e.g. /DC/vm/ocp45-2tdrm\n             server: \u003cvCenter Server FQDN/IP\u003e\n\n```\n\nExample MachineSet for other cloud providers:\n- [AWS](docs/machineset-aws.md)\n- [Azure](docs/machineset-azure.md)\n- [GCP](docs/machineset-gcp.md)\n- [Nutanix](docs/machineset-nutanix.md)\n\nAlternatively, the [hack/machineset.sh](hack/machineset.sh) script can be used to generate MachineSets for AWS and Azure platforms.\nThe hack script will generate a `MachineSet.yaml` file which can be edited before using or can be used as it is.\nThe script takes optional arguments `apply` and `delete` to directly create/delete MachineSet on the cluster without \ngenerating a `yaml` file.\n\nUsage:\n```shell script\n./hack/machineset.sh                 # to generate yaml file\n./hack/machineset.sh apply/delete    # to create/delete MachineSet directly on cluster\n```\n\n## Windows nodes Kubernetes component upgrade\n\nWhen a new version of WMCO is released that is compatible with the current cluster version, an operator upgrade will \ntake place which will result in the Kubernetes components in the Windows Machine to be upgraded. For a non-disruptive\nupgrade, WMCO processes the Windows Machine that was configured by the previous version of the operator with the\nfollowing steps:\n- drain and cordon the associated Node object\n- re-configure it using the new version\n- uncordon the Node\n\nTo facilitate an upgrade, WMCO adds a version annotation to all the configured nodes. During an upgrade, a mismatch in\nversion annotation will result in a re-configuration or upgrade of the Windows instance. \n\nFor minimal service disruption during an upgrade, WMCO limits the number of Windows nodes that are re-configured or\nupgraded concurrently to one (1). The latter, accounts for both BYOH and MachineSet Windows instances.\n\nWMCO is not responsible for Windows operating system updates. The cluster administrator provides the Window image while\ncreating the VMs and hence, the cluster administrator is responsible for providing an updated image. The cluster \nadministrator can provide an updated image by changing the image in the MachineSet spec.\n\n## Windows nodes Openshift EUS-to-EUS upgrade\n\nWMCO does support upgrading from one [EUS version to another EUS version of OCP](https://access.redhat.com/support/policy/updates/openshift-eus),\nthe Windows nodes will be upgraded from the staring EUS to the new EUS version while keeping the Windows workloads \nin a healthy state with no disruptions.\n\n**Prerequisites**\n- The cluster must be running on a supported EUS version of OCP\n- All Windows nodes must be in a healthy state\n- All Windows nodes must be running on the same version of WMCO\n- All the of the [prerequisites of the EUS-to-EUS OCP upgrade](https://docs.openshift.com/container-platform/latest/updating/updating_a_cluster/eus-eus-update.html)\n\n### Windows nodes EUS-to-EUS update using the web console\n\n**Procedure**\n1. Uninstall WMCO from the [cluster using the web console](https://docs.openshift.com/container-platform/latest/operators/admin/olm-deleting-operators-from-cluster.html#olm-deleting-operators-from-a-cluster-using-web-console_olm-deleting-operators-from-a-cluster) \n2. Follow steps for [EUS-to-EUS update using the web console](https://docs.openshift.com/container-platform/latest/updating/updating_a_cluster/eus-eus-update.html#updating-eus-to-eus-upgrade-console_eus-to-eus-update)\n3. Wait for the upgrade to complete towards the target EUS version\n4. Install the latest available WMCO version [from OperatorHub](https://docs.openshift.com/container-platform/latest/operators/admin/olm-adding-operators-to-cluster.html#olm-installing-from-operatorhub-using-web-console_olm-adding-operators-to-a-cluster) \n5. Wait for the Windows nodes to be upgraded towards the corresponding EUS version\n\n### Windows nodes EUS-to-EUS update using the CLI\n\n**Procedure**\n1. Uninstall WMCO from the [cluster using the CLI](https://docs.openshift.com/container-platform/latest/operators/admin/olm-deleting-operators-from-cluster.html#olm-deleting-operator-from-a-cluster-using-cli_olm-deleting-operators-from-a-cluster)\n2. Follow the steps for [EUS-to-EUS update using the CLI](https://docs.openshift.com/container-platform/latest/updating/updating_a_cluster/eus-eus-update.html#updating-eus-to-eus-upgrade-cli_eus-to-eus-update)\n3. Wait for the upgrade to complete towards the target EUS version\n4. Install the latest available WMCO version [using the CLI](https://docs.openshift.com/container-platform/latest/operators/admin/olm-adding-operators-to-cluster.html#olm-installing-operator-from-operatorhub-using-cli_olm-adding-operators-to-a-cluster)\n5. Wait for the Windows nodes to be upgraded towards the corresponding EUS version\n\n## Enabled features\n\n### Autoscaling Windows nodes\nCluster autoscaling is supported for Windows instances. \n\n- Define and deploy a [ClusterAutoscaler](https://docs.openshift.com/container-platform/latest/machine_management/applying-autoscaling.html#configuring-clusterautoscaler).\n- Create a Windows node through a MachineSet (see spec in [Usage section](https://github.com/openshift/windows-machine-config-operator#usage)).\n- Define and deploy a [MachineAutoscaler](https://docs.openshift.com/container-platform/latest/machine_management/applying-autoscaling.html#configuring-machineautoscaler), referencing a Windows MachineSet.\n\n### Container Runtime\nWindows instances brought up with WMCO are set up with the containerd container runtime. As WMCO installs and manages the container runtime,\nit is recommended not to preinstall containerd in MachineSet or BYOH Windows instances.\n\n### Cluster-wide proxy \nWMCO supports using a [cluster-wide proxy](https://docs.openshift.com/container-platform/latest/networking/enable-cluster-wide-proxy.html)\nto route egress traffic from Windows nodes on OpenShift Container Platform.\n\n### Running in a disconnected/airgapped environment\nWMCO supports running in a disconnected environment.\nPlease follow the [disconnected mirroring docs](https://docs.openshift.com/container-platform/latest/installing/disconnected_install/index.html)\nin order to mirror and run WMCO on your cluster.\n\nNodes can be added through both MachineSets and the windows-instances ConfigMap.\nThe image specified in MachineSets has an extra requirement of having [the OpenSSH.Server~~~~0.0.1.0 Windows capability installed](https://learn.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse?tabs=powershell#install-openssh-for-windows).\nThis is normally installed by WMCO using the Machine's user-data, and is needed to configure a Windows instance.\n\nFor AWS platform, the Windows AMI must have installed the EC2LaunchV2 agent with version 2.0.1643 or later.\nSee install options in the [EC2LaunchV2 documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2launch-v2-install.html#lv2-configure-install).\n\nIn order to run Windows workloads on Nodes, the image `mcr.microsoft.com/oss/kubernetes/pause:3.9` must be mirrored.\nSee [Image configuration resources](https://docs.openshift.com/container-platform/latest/openshift_images/image-configuration.html) for general information on image mirroring.\n\nWindows images mirrored through ImageDigestMirrorSet and ImageTagMirrorSet have specific naming requirements.\nThe mirrored image's suffix (final portion of namespaces and the image name) must match that of the source image.\nFor example, when mirroring the image `mcr.microsoft.com/oss/kubernetes/pause:3.9`, the mirror must have the format\n`$mirrorRegistry/[$optionalNamespaces/]oss/kubernetes/pause:3.9` where `$optionalNamespaces` can be any number of\nleading namespaces. Some valid values could be: `$mirrorRegistry/oss/kubernetes/pause:3.9`,\n`$mirrorRegistry/custom/oss/kubernetes/pause:3.9`, `$mirrorRegistry/x/y/z/oss/kubernetes/pause:3.9`.\n\n### Horizontal Pod Autoscaling\nHorizontal Pod autoscaling is available for Windows workloads.\nPlease follow the [Horizontal Pod autoscaling docs](https://docs.openshift.com/container-platform/latest/nodes/pods/nodes-pods-autoscaling.html) \nto create a horizontal pod autoscaler object for CPU and memory utilization of Windows workloads.\n\n## Limitations\n\n### DeploymentConfigs\nWindows Nodes do not support workloads created via DeploymentConfigs. Please use a normal Deployment, or other method to\ndeploy workloads.\n\n### Storage\nWindows Nodes are running csi-proxy and are ready to use CSI drivers, however Windows CSI driver DaemonSets are not\ndeployed as part of the product. In order to use persistent storage for Windows workloads, the cluster administrator\nmust deploy the appropriate Windows CSI driver Daemonset. This should be done by following the documentation given\nby the chosen storage driver's provider. A list of drivers can be found [here](https://kubernetes-csi.github.io/docs/drivers.html#production-drivers).\n\n### Pod Autoscaling\n[Vertical](https://docs.openshift.com/container-platform/latest/nodes/pods/nodes-pods-vertical-autoscaler.html) Pod\nautoscaling support is not available for Windows workloads.\n\n### Other limitations\nWMCO / Windows nodes does not work with the following products:\n* [odo](https://docs.openshift.com/container-platform/latest/cli_reference/developer_cli_odo/understanding-odo.html)\n* [OpenShift Builds](https://docs.openshift.com/container-platform/latest/cicd/builds/understanding-image-builds.html#understanding-image-builds)\n* [OpenShift Pipelines](https://docs.openshift.com/container-platform/latest/cicd/pipelines/understanding-openshift-pipelines.html#understanding-openshift-pipelines)\n* [OpenShift Service Mesh](https://docs.openshift.com/container-platform/latest/service_mesh/v2x/ossm-about.html)\n* [Red Hat Insights cost management](https://docs.redhat.com/en/documentation/cost_management_service/1-latest)\n* [Red Hat OpenShift Local](https://developers.redhat.com/products/openshift-local/overview)\n* [OpenShift monitoring of user defined project](https://docs.openshift.com/container-platform/latest/monitoring/enabling-monitoring-for-user-defined-projects.html#enabling-monitoring-for-user-defined-projects)\n* [HugePages](https://kubernetes.io/docs/tasks/manage-hugepages/scheduling-hugepages/)\n\n### Trunk port\nWMCO does not support adding Windows nodes to a cluster through a trunk port. The only supported networking setup for adding Windows nodes is through an access port carrying the VLAN traffic.\n\n## Running Windows workloads\nBe sure to set the [OS field in the Pod spec](https://kubernetes.io/docs/concepts/workloads/pods/#pod-os) to Windows\nwhen deploying Windows workloads. This field is used to authoritatively identify the pod OS for validation. \nIn OpenShift, it is used when enforcing OS-specific pod security standards.\n\n## Development\n\nSee [HACKING.md](docs/HACKING.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift%2Fwindows-machine-config-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenshift%2Fwindows-machine-config-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenshift%2Fwindows-machine-config-operator/lists"}