Merge pull request #92629 from mburke5678/wmco-optional-namespace-mirroring

OSDOCS14449: Use of optional_namespaces in the ImageTagMirrorSet does not work as documented

Author: mburke5678

modules/images-configuration-registry-mirror-configuring.adoc

@@ -17,7 +17,9 @@ You can create postinstallation mirror configuration custom resources (CR) to re
 ifdef::winc[]
 [IMPORTANT]
 ====
-Windows images mirrored through `ImageDigestMirrorSet` and `ImageTagMirrorSet` objects have specific naming requirements. The final portion of the namespace and the image name of the mirror image must match the image being mirrored. For example, when mirroring the `mcr.microsoft.com/oss/kubernetes/pause:3.9` image, the mirror image must have the `<mirror_registry>/<optional_namespaces>/oss/kubernetes/pause:3.9` format. The `optional_namespaces` can be any number of leading repository namespaces.
+Windows images mirrored through `ImageDigestMirrorSet` and `ImageTagMirrorSet` objects have specific naming requirements. 
+
+include::snippets/wmco-mirror-naming-requirements.adoc[]
 ====
 endif::winc[]
 

modules/wmco-disconnected-cluster.adoc

@@ -28,7 +28,19 @@ After creating the mirror registry and mirroring the images, you can use an `Ima
 
 If changes are made to the IDMS or ITMS object, the WMCO automatically updates the appropriate `hosts.toml` file on your Windows nodes with the new information. Note that the WMCO sequentially updates each Windows node when mirror settings are changed. As such, the time required for these updates increases with the number of Windows nodes in the cluster.
 
-Also, because Windows nodes configured by the WMCO rely on containerd container runtime, the WMCO ensures that the containerd config files are up-to-date with the registry settings. For new nodes, these files are copied to the instances upon creation. For existing nodes, after activating the mirror registry, the registry controller uses SSH to access each node and copy the generated config files, replacing any existing files.
+Because Windows nodes configured by the WMCO rely on the containerd container runtime, the WMCO ensures that the containerd configuration files are up-to-date with the registry settings. For new nodes, these files are copied to the instances upon creation. For existing nodes, after activating the mirror registry, the registry controller uses SSH to access each node and copy the generated configuration files, replacing any existing files.
 
 You can use a mirror registry with machine set or Bring-Your-Own-Host (BYOH) Windows nodes.
 
+When using an IDMS or ITMS object to mirror container images on Windows nodes, take note of the following behaviors that differ from Linux nodes:
+
+* Mirroring on Windows nodes works on the registry level, rather than on the image level used by Linux nodes. As such, Windows images mirrored by using IDMS or ITMS objects have specific naming requirements. 
++
+--
+include::snippets/wmco-mirror-naming-requirements.adoc[]
+--
+
+* A Windows node takes the ITMS object and uses it to configure registry-wide mirrors. In the following example, configuring `quay.io/remote-org/image` to mirror to `quay.io/my-org/image` results in the Windows node using that mirror for all images from `quay.io/remote-org`. As such, `quay.io/remote-org/image:tag` uses the `quay.io/my-org/image:tag` image, as expected, but another container using `quay.io/remote-org/different-image:tag`
+would also try to use the `quay.io/remote-org/different-image:tag` mirror. This can cause unintended behavior if it is not accounted for.
++
+For this reason, specify container images using a digest by an IDMS object instead of an ITMS object. Using a digest can prevent the wrong container image from being used, by ensuring that the image the container specifies and the image being pulled have the same digest.

snippets/wmco-mirror-naming-requirements.adoc

@@ -0,0 +1,8 @@
+// Text snippet included in the following modules:
+//
+// * modules/images-configuration-registry-mirror-configuring
+// * wmco-disconnected-cluster.adoc
+
+:_mod-docs-content-type: SNIPPET
+
+The final portion of the namespace and the image name of the mirror image must match the image being mirrored. For example, when mirroring the `mcr.microsoft.com/oss/kubernetes/pause:3.9` image, the mirror must be in the `$mirrorRegistry/<organization>/oss/kubernetes/pause:3.9` format, where `$org` can be any organization name or namespace or excluded entirely. Some valid values are `$mirrorRegistry/oss/kubernetes/pause:3.9`, `$mirrorRegistry/custom/oss/kubernetes/pause:3.9`, and `$mirrorRegistry/x/y/z/oss/kubernetes/pause:3.9`.