Skip to content

Commit 5ab885b

Browse files
jeana-redhatjeana-redhat
authored
Merge pull request #60932 from amolnar-rh/TELCODOCS-1209
TELCODOCS-1209: Enable precaching of user specified images with TALM
2 parents 4b37851 + f3e6f4b commit 5ab885b

File tree

3 files changed

+304
-0
lines changed

3 files changed

+304
-0
lines changed

‎modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="talm-prechache-user-specified-images-preparing-crs_{context}"]
7+
== Creating the custom resources for pre-caching
8+
9+
You must create the `PreCachingConfig` CR before or concurrently with the `ClusterGroupUpgrade` CR.
10+
11+
. Create the `PreCachingConfig` CR with the list of additional images you want to pre-cache.
12+
+
13+
[source,yaml]
14+
----
15+
apiVersion: ran.openshift.io/v1alpha1
16+
kind: PreCachingConfig
17+
metadata:
18+
name: exampleconfig
19+
namespace: default <1>
20+
spec:
21+
[...]
22+
spaceRequired: 30Gi <2>
23+
additionalImages:
24+
- quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef
25+
- quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef
26+
- quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09
27+
----
28+
<1> The `namespace` must be accessible to the hub cluster.
29+
<2> It is recommended to set the minimum disk space required field to ensure that there is sufficient storage space for the pre-cached images.
30+
31+
. Create a `ClusterGroupUpgrade` CR with the `preCaching` field set to `true` and specify the `PreCachingConfig` CR created in the previous step:
32+
+
33+
[source,yaml]
34+
----
35+
apiVersion: ran.openshift.io/v1alpha1
36+
kind: ClusterGroupUpgrade
37+
metadata:
38+
name: cgu
39+
namespace: default
40+
spec:
41+
clusters:
42+
- sno1
43+
- sno2
44+
preCaching: true
45+
preCachingConfigRef:
46+
- name: exampleconfig
47+
namespace: default
48+
managedPolicies:
49+
- du-upgrade-platform-upgrade
50+
- du-upgrade-operator-catsrc-policy
51+
- common-subscriptions-policy
52+
remediationStrategy:
53+
timeout: 240
54+
----
55+
56+
+
57+
[WARNING]
58+
====
59+
Once you install the images on the cluster, you cannot change or delete them.
60+
====
61+
62+
+
63+
. When you want to start pre-caching the images, apply the `ClusterGroupUpgrade` CR by running the following command:
64+
+
65+
[source,terminal]
66+
----
67+
$ oc apply -f cgu.yaml
68+
----
69+
70+
{cgu-operator} verifies the `ClusterGroupUpgrade` CR.
71+
72+
From this point, you can continue with the {cgu-operator} pre-caching workflow.
73+
74+
[NOTE]
75+
====
76+
All sites are pre-cached concurrently.
77+
====
78+
79+
.Verification
80+
81+
. Check the pre-caching status on the hub cluster where the `ClusterUpgradeGroup` CR is applied by running the following command:
82+
+
83+
[source,terminal]
84+
----
85+
$ oc get cgu <cgu_name> -n <cgu_namespace> -oyaml
86+
----
87+
88+
+
89+
.Example output
90+
[source,yaml]
91+
----
92+
precaching:
93+
spec:
94+
platformImage: quay.io/openshift-release-dev/ocp-release@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef
95+
operatorsIndexes:
96+
- registry.example.com:5000/custom-redhat-operators:1.0.0
97+
operatorsPackagesAndChannels:
98+
- local-storage-operator: stable
99+
- ptp-operator: stable
100+
- sriov-network-operator: stable
101+
excludePrecachePatterns:
102+
- aws
103+
- vsphere
104+
additionalImages:
105+
- quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef
106+
- quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef
107+
- quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09
108+
spaceRequired: "30"
109+
status:
110+
sno1: Starting
111+
sno2: Starting
112+
----
113+
114+
+
115+
The pre-caching configurations are validated by checking if the managed policies exist.
116+
Valid configurations of the `ClusterGroupUpgrade` and the `PreCachingConfig` CRs result in the following statuses:
117+
118+
+
119+
.Example output of valid CRs
120+
[source,yaml]
121+
----
122+
- lastTransitionTime: "2023-01-01T00:00:01Z"
123+
message: All selected clusters are valid
124+
reason: ClusterSelectionCompleted
125+
status: "True"
126+
type: ClusterSelected
127+
- lastTransitionTime: "2023-01-01T00:00:02Z"
128+
message: Completed validation
129+
reason: ValidationCompleted
130+
status: "True"
131+
type: Validated
132+
- lastTransitionTime: "2023-01-01T00:00:03Z"
133+
message: Precaching spec is valid and consistent
134+
reason: PrecacheSpecIsWellFormed
135+
status: "True"
136+
type: PrecacheSpecValid
137+
- lastTransitionTime: "2023-01-01T00:00:04Z"
138+
message: Precaching in progress for 1 clusters
139+
reason: InProgress
140+
status: "False"
141+
type: PrecachingSucceeded
142+
----
143+
144+
+
145+
.Example of an invalid PreCachingConfig CR
146+
[source,yaml]
147+
----
148+
Type: "PrecacheSpecValid"
149+
Status: False,
150+
Reason: "PrecacheSpecIncomplete"
151+
Message: "Precaching spec is incomplete: failed to get PreCachingConfig resource due to PreCachingConfig.ran.openshift.io "<pre-caching_cr_name>" not found"
152+
----
153+
154+
. You can find the pre-caching job by running the following command on the managed cluster:
155+
+
156+
[source,terminal]
157+
----
158+
$ oc get jobs -n openshift-talo-pre-cache
159+
----
160+
161+
+
162+
.Example of pre-caching job in progress
163+
[source,terminal]
164+
----
165+
NAME COMPLETIONS DURATION AGE
166+
pre-cache 0/1 1s 1s
167+
----
168+
169+
. You can check the status of the pod created for the pre-caching job by running the following command:
170+
+
171+
[source,terminal]
172+
----
173+
$ oc describe pod pre-cache -n openshift-talo-pre-cache
174+
----
175+
176+
+
177+
.Example of pre-caching job in progress
178+
[source,terminal]
179+
----
180+
Type Reason Age From Message
181+
Normal SuccesfulCreate 19s job-controller Created pod: pre-cache-abcd1
182+
----
183+
184+
. You can get live updates on the status of the job by running the following command:
185+
+
186+
[source,terminal]
187+
----
188+
$ oc logs -f pre-cache-abcd1 -n openshift-talo-pre-cache
189+
----
190+
191+
. To verify the pre-cache job is successfully completed, run the following command:
192+
+
193+
[source,terminal]
194+
----
195+
$ oc describe pod pre-cache -n openshift-talo-pre-cache
196+
----
197+
198+
+
199+
.Example of completed pre-cache job
200+
[source,terminal]
201+
----
202+
Type Reason Age From Message
203+
Normal SuccesfulCreate 5m19s job-controller Created pod: pre-cache-abcd1
204+
Normal Completed 19s job-controller Job completed
205+
----
206+
207+
. To verify that the images are successfully pre-cached on the {sno}, do the following:
208+
209+
.. Enter into the node in debug mode:
210+
+
211+
[source,terminal]
212+
----
213+
$ oc debug node/cnfdf00.example.lab
214+
----
215+
216+
.. Change root to `host`:
217+
+
218+
[source,terminal]
219+
----
220+
$ chroot /host/
221+
----
222+
223+
.. Search for the desired images:
224+
+
225+
[source,terminal]
226+
----
227+
$ sudo podman images | grep <operator_name>
228+
----

‎modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// Module included in the following assemblies:
2+
//
3+
// * scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="talm-prechache-user-specified-images-concept_{context}"]
7+
= Pre-caching user-specified images with {cgu-operator} on {sno} clusters
8+
9+
You can pre-cache application-specific workload images on {sno} clusters before upgrading your applications.
10+
11+
You can specify the configuration options for the pre-caching jobs using the following custom resources (CR):
12+
13+
* `PreCachingConfig` CR
14+
* `ClusterGroupUpgrade` CR
15+
16+
[NOTE]
17+
====
18+
All fields in the `PreCachingConfig` CR are optional.
19+
====
20+
21+
.Example PreCachingConfig CR
22+
[source,yaml]
23+
----
24+
apiVersion: ran.openshift.io/v1alpha1
25+
kind: PreCachingConfig
26+
metadata:
27+
name: exampleconfig
28+
namespace: exampleconfig-ns
29+
spec:
30+
overrides: <1>
31+
platformImage: quay.io/openshift-release-dev/ocp-release@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef
32+
operatorsIndexes:
33+
- registry.example.com:5000/custom-redhat-operators:1.0.0
34+
operatorsPackagesAndChannels:
35+
- local-storage-operator: stable
36+
- ptp-operator: stable
37+
- sriov-network-operator: stable
38+
spaceRequired: 30 Gi <2>
39+
excludePrecachePatterns: <3>
40+
- aws
41+
- vsphere
42+
additionalImages: <4>
43+
- quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef
44+
- quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef
45+
- quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09
46+
----
47+
<1> By default, {cgu-operator} automatically populates the `platformImage`, `operatorsIndexes`, and the `operatorsPackagesAndChannels` fields from the policies of the managed clusters. You can specify values to override the default {cgu-operator}-derived values for these fields.
48+
<2> Specifies the minimum required disk space on the cluster. If unspecified, {cgu-operator} defines a default value for {product-title} images. The disk space field must include an integer value and the storage unit. For example: `40 GiB`, `200 MB`, `1 TiB`.
49+
<3> Specifies the images to exclude from pre-caching based on image name matching.
50+
<4> Specifies the list of additional images to pre-cache.
51+
52+
.Example ClusterGroupUpgrade CR with PreCachingConfig CR reference
53+
[source,yaml]
54+
----
55+
apiVersion: ran.openshift.io/v1alpha1
56+
kind: ClusterGroupUpgrade
57+
metadata:
58+
name: cgu
59+
spec:
60+
preCaching: true <1>
61+
preCachingConfigRef:
62+
name: exampleconfig <2>
63+
namespace: exampleconfig-ns <3>
64+
----
65+
<1> The `preCaching` field set to `true` enables the pre-caching job.
66+
<2> The `preCachingConfigRef.name` field specifies the `PreCachingConfig` CR that you want to use.
67+
<3> The `preCachingConfigRef.namespace` specifies the namespace of the `PreCachingConfig` CR that you want to use.

‎scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,4 +48,13 @@ include::modules/cnf-topology-aware-lifecycle-manager-operator-and-platform-upda
4848

4949
include::modules/cnf-topology-aware-lifecycle-manager-pao-update.adoc[leveloffset=+2]
5050

51+
include::modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc[leveloffset=+2]
52+
53+
include::modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc[leveloffset=+2]
54+
55+
[role="_additional-resources"]
56+
.Additional resources
57+
58+
* For more information about the {cgu-operator} pre-caching workflow, see xref:../../scalability_and_performance/cnf-talm-for-cluster-upgrades.adoc#talo-precache-feature-concept_cnf-topology-aware-lifecycle-manager[Using the container image pre-cache feature].
59+
5160
include::modules/cnf-topology-aware-lifecycle-manager-autocreate-cgu-cr-ztp.adoc[leveloffset=+1]

0 commit comments

Comments
 (0)