OSDOCS:14467 [GA] Pin and preload images

Author: Michael Burke

_topic_maps/_topic_map.yml

@@ -2352,6 +2352,8 @@ Topics:
   File: machine-config-node-disruption
 - Name: Configuring MCO-related custom resources
   File: machine-configs-custom
+- Name: About preloading and pinning images
+  File: machine-config-pin-preload-images-about
 - Name: Updated boot images
   File: mco-update-boot-images
 - Name: Managing unused rendered machine configs

machine_configuration/machine-config-pin-preload-images-about.adoc

@@ -0,0 +1,36 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="machine-config-pin-preload-images-about"]
+= About preloading and pinning images
+include::_attributes/common-attributes.adoc[]
+:context: machine-config-operator
+
+toc::[]
+
+Slow and unreliable connections to an image registry can interfere with operations that require pulling images, such as updating a cluster or deploying an application. 
+
+For example, an cluster update might require pulling more than one hundred images. Failure to pull those images causes retries that can interfere with the upgrade process and might cause the update fail. One way to improve that is to _preloand_ the required images by pulling them in advance, before they are actually needed. Then, ensuring that the images are available when needed by _pinning_ them to a machine config pool. Pinning and preloading images can provide a more consistent upgrade, which is important when scheduling upgrades into maintenance windows.
+
+Pinning and preloading images can benefit a cluster that has a low bandwidth or an unreliable connection to an image registry server when deploying applications, ensuring that the images are available and application will successfully deploy in a predictable time.
+
+Preloading and pinning images prevents image garbage collection from removing the pinned images.
+
+You can preload and pin images by using a a `PinnedImageSet` custom resource (CR) as described in the following section. Pinned images are stored in a file inside the `/etc/crio/crio.conf.d` directory. The name of this file is a concatenation of the name of the `PinnedImageSet` CR and the UUID assigned to the resulting `PinnedImageSet` object. 
+
+For example, the name of a pinned image file would be similar to the following name: `my-pinned-images-550a1d88-2976-4447-9fc7-b65e457a7f42.conf`. The contents of the file appear similar to the following example:
+
+[source,terminal]
+----
+pinned_images=[
+  "quay.io/openshift-release-dev/ocp-release@sha256:...",
+  "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...",
+  "quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...",
+  ...
+]
+----
+
+
+include::modules/machine-config-pin-preload-images-configuring.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+* xref:

modules/machine-config-pin-preload-images.adoc

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * machine_configuration/machine-config-pin-preload-images-about.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="machine-config-pin-preload-images_{context}"]
+= Preloading and pinning and images
+
+You can preload and pin images by using a a `PinnedImageSet` custom resource (CR).
+
+