Edit

Purpose: For platform engineers, provides the full specification of the win-containerd role — variables, handlers, task sequence, and edge cases.

Overview

The opencenter-cloud.opencenter_windows_workers.win-containerd role installs and configures ContainerD as a Windows service, along with crictl for runtime debugging. It handles Windows feature installation, reboots, and service registration.

Variables

| Variable | Default | Required | Description | |---|---|---|---| | containerd_version | (none) | Yes | ContainerD release version to install (e.g., 1.7.13). Used to construct the GitHub download URL. | | crictl_version | (none) | Yes | crictl release version to install (e.g., 1.29.0). Used to construct the GitHub download URL. | | skip_hypervisor_support_check | false | No | When true, skips standard Hyper-V feature installation and uses DISM to enable a minimal Hyper-V configuration. Use on VMs without nested virtualization. | | cni_bin_path | c:/opt/cni/bin | No | Filesystem path where CNI plugin binaries are stored. Written into ContainerD’s config.toml. | | cni_config_path | c:/etc/cni/net.d | No | Filesystem path for CNI configuration files. Written into ContainerD’s config.toml. | | containerd_path | {{ ansible_env.ProgramFiles }}\containerd | No | Installation directory for ContainerD binaries and config. Defaults to C:\Program Files\containerd. |

Source: roles/win-containerd/defaults/main.yaml

Handlers

| Handler | Trigger | Behavior | |---|---|---| | set reboot flag | Windows feature installation | Sets reboot_required: true fact. The role checks this flag and reboots if needed. | | restart containerd service | ContainerD config change | Restarts the containerd Windows service. Only runs if the service is already registered. |

Source: roles/win-containerd/handlers/main.yaml

Task sequence

  1. Check for pending reboots (registry keys: PendingFileRenameOperations, RebootRequired, RebootPending). Reboot if pending.

  2. Detect installed Windows features (Containers, Hyper-V, Hyper-V-PowerShell).

  3. Install missing features. If skip_hypervisor_support_check is true, use DISM for Microsoft-Hyper-V and disable Microsoft-Hyper-V-Online instead.

  4. Reboot if any features were installed.

  5. Create ContainerD directory.

  6. Download and extract ContainerD binaries from https://github.com/containerd/containerd/releases/. Skipped if containerd.exe already exists at the target path.

  7. Add ContainerD directory to system PATH.

  8. Generate config.toml using containerd.exe config default, then patch bin_dir and conf_dir with the CNI paths. Only writes if content changed.

  9. Create CNI directories (cni_bin_path, cni_config_path).

  10. Register ContainerD as a Windows service (if not already registered).

  11. Start and enable the ContainerD service (start_mode: auto).

  12. Download and extract crictl. Skipped if the installed version matches crictl_version.

  13. Create ~/.crictl/crictl.yaml with the named pipe endpoint: npipe://./pipe/containerd-containerd.

Idempotency

  • ContainerD download is skipped if containerd.exe exists at containerd_path.

  • crictl download is skipped if the installed version matches crictl_version.

  • Config file is only written when content differs from the existing file.

  • Windows features are only installed if not already present.

Reboots

This role may trigger up to 2 reboots: . If a reboot was already pending before the role started. . After Windows feature installation (Containers, Hyper-V).

Reboots use a 600-second timeout and wait for the SSH service to become available.

Download URLs

ContainerD: https://github.com/containerd/containerd/releases/download/v{version}/containerd-{version}-windows-amd64.tar.gz
crictl:     https://github.com/kubernetes-sigs/cri-tools/releases/download/v{version}/crictl-v{version}-windows-amd64.tar.gz