Skip to content

Commit 7583bba

Browse files
author
Michael Burke
committed
Further edits from testing
1 parent 6ac3828 commit 7583bba

File tree

2 files changed

+147
-3
lines changed

2 files changed

+147
-3
lines changed

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

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
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.
9+
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. This can be helpful in cluster with low bandwidth, unreliable internet connectivity, or in a disconnected environment.
1010

1111
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.
1212

1313
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.
1414

1515
Preloading and pinning images prevents image garbage collection from removing the pinned images.
1616

17-
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.
17+
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` object and the UUID assigned to the object.
1818

1919
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:
2020

@@ -28,6 +28,36 @@ pinned_images=[
2828
]
2929
----
3030

31+
Before pulling the images, the Machine Config Operator (MCO) verifies that there is enough space available on each affected node to store the images. If the node has sufficient space, the MCO creates the pinned image file, pulls the images, and reloads CRI-O.
32+
33+
The `PinnedImageSet` object reports if the images have been pinned and pulled successfully or lists error conditions if the pin and pull fails.
34+
35+
.Example successful `PinnedImageSet` status
36+
[source,yaml]
37+
----
38+
status:
39+
conditions:
40+
- type: Ready
41+
status: "True"
42+
- type: Failed
43+
status: "False"
44+
----
45+
46+
.Example filaed `PinnedImageSet` status
47+
[source,yaml]
48+
----
49+
50+
status:
51+
conditions:
52+
- type: Ready
53+
status: "False"
54+
- type: Failed
55+
status: "True"
56+
message: |
57+
Pulling the images in `node12` requires at least 16 GiB of disk
58+
space, but there are only 10 GiB available
59+
----
60+
3161

3262
include::modules/machine-config-pin-preload-images-configuring.adoc[leveloffset=+1]
3363

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

Lines changed: 115 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,120 @@
66
[id="machine-config-pin-preload-images_{context}"]
77
= Preloading and pinning and images
88

9-
You can preload and pin images by using a a `PinnedImageSet` custom resource (CR).
9+
You can preload and pin images by using a `PinnedImageSet` custom resource (CR). The pinned image set defines the list of images to preload and the machine config pool that the images should be pinned to.
1010

11+
The file is stored in the the `/etc/crio/crio.conf.d` directory under a name that is a concatenation of the name of the `PinnedImageSet` object and the UUID assigned to the object.
12+
13+
.Procedure
14+
15+
. Create a YAML file that defines the `PinnedImageSet` similar to the following example:
16+
+
17+
[source,yaml]
18+
----
19+
apiVersion: machineconfiguration.openshift.io/v1
20+
kind: PinnedImageSet
21+
metadata:
22+
labels:
23+
machineconfiguration.openshift.io/role: worker <1>
24+
name: worker-pinned-images
25+
spec:
26+
pinnedImages: <2>
27+
- name: quay.io/openshifttest/busybox@sha256:0415f56ccc05526
28+
- name: quay.io/openshifttest/alpine@sha256:be92b18a369e989a
29+
----
30+
<1> Optional: A node selector to specify the machine config pool to pin the images to. If not specified, the images are pinned to all nodes in the cluster.
31+
<2> A list of one or more images to preload.
32+
33+
.. Create the `PinnedImageSet` object by running the following command:
34+
+
35+
[source,terminal]
36+
----
37+
$ oc create -f <file_name>.yaml
38+
----
39+
40+
.Verification
41+
42+
. Check that the pinned image set is reported in the machine config node object for the affected machine config pool by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ oc describe machineconfignode <machine_confignode_name>
47+
----
48+
+
49+
.Example command
50+
[source,terminal]
51+
----
52+
$ oc describe machineconfignode ci-ln-25hlkvt-72292-jrs48-worker-a-2bdj
53+
----
54+
+
55+
.Example output
56+
+
57+
[source,terminal]
58+
----
59+
apiVersion: machineconfiguration.openshift.io/v1
60+
kind: MachineConfigNode
61+
metadata:
62+
creationTimestamp: "2025-04-28T18:40:29Z"
63+
generation: 3
64+
name: <machine_config_node_name> <1>
65+
# ...
66+
status
67+
pinnedImageSets:
68+
- desiredGeneration: 1
69+
name: worker-pinned-images
70+
----
71+
+
72+
[NOTE]
73+
====
74+
It can take a few moments for the object to be fully updated.
75+
====
76+
77+
. Check that the pinned image file is created and contains the correct images. The contents of the file appear similar to the following example:
78+
79+
.. Start a debug session for a node by running the following command:
80+
+
81+
[source,terminal]
82+
----
83+
$ oc debug node/<node_name>
84+
----
85+
86+
.. Set `/host` as the root directory within the debug shell by running the following command:
87+
+
88+
[source,terminal]
89+
----
90+
sh-5.1# chroot /host
91+
----
92+
93+
.. Verify the contents of the pinned image file by running the following command:
94+
+
95+
[source,terminal]
96+
----
97+
$ cat /etc/crio/crio.conf.d/<pinned_image_set_name>
98+
----
99+
100+
.Example command
101+
[source,terminal]
102+
----
103+
$ cat /etc/crio/crio.conf.d/worker-pinned-images-0b38991f-90d4-4d54-b111
104+
----
105+
+
106+
.Example output
107+
+
108+
[source,terminal]
109+
----
110+
pinned_images=[
111+
"quay.io/openshift-release-dev/ocp-release@sha256:...",
112+
"quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...",
113+
"quay.io/openshift-release-dev/ocp-v4.0-art-dev@sha256:...",
114+
...
115+
]
116+
----
117+
118+
. Verify that the that pin and pull was successful by checking the `PinnedImageSet` object status:
119+
+
120+
+
121+
[source,terminal]
122+
----
123+
$ oc describe PinnedImageSet worker-pinned-images
124+
----
11125

0 commit comments

Comments
 (0)