diff --git a/modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc b/modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc new file mode 100644 index 0000000000..7305f748cd --- /dev/null +++ b/modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc @@ -0,0 +1,228 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc + +:_content-type: PROCEDURE +[id="talm-prechache-user-specified-images-preparing-crs_{context}"] +== Creating the custom resources for pre-caching + +You must create the `PreCachingConfig` CR before or concurrently with the `ClusterGroupUpgrade` CR. + +. Create the `PreCachingConfig` CR with the list of additional images you want to pre-cache. ++ +[source,yaml] +---- +apiVersion: ran.openshift.io/v1alpha1 +kind: PreCachingConfig +metadata: + name: exampleconfig + namespace: default <1> +spec: +[...] + spaceRequired: 30Gi <2> + additionalImages: + - quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef + - quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef + - quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09 +---- +<1> The `namespace` must be accessible to the hub cluster. +<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. + +. Create a `ClusterGroupUpgrade` CR with the `preCaching` field set to `true` and specify the `PreCachingConfig` CR created in the previous step: ++ +[source,yaml] +---- +apiVersion: ran.openshift.io/v1alpha1 +kind: ClusterGroupUpgrade +metadata: + name: cgu + namespace: default +spec: + clusters: + - sno1 + - sno2 + preCaching: true + preCachingConfigRef: + - name: exampleconfig + namespace: default + managedPolicies: + - du-upgrade-platform-upgrade + - du-upgrade-operator-catsrc-policy + - common-subscriptions-policy + remediationStrategy: + timeout: 240 +---- + ++ +[WARNING] +==== +Once you install the images on the cluster, you cannot change or delete them. +==== + ++ +. When you want to start pre-caching the images, apply the `ClusterGroupUpgrade` CR by running the following command: ++ +[source,terminal] +---- +$ oc apply -f cgu.yaml +---- + +{cgu-operator} verifies the `ClusterGroupUpgrade` CR. + +From this point, you can continue with the {cgu-operator} pre-caching workflow. + +[NOTE] +==== +All sites are pre-cached concurrently. +==== + +.Verification + +. Check the pre-caching status on the hub cluster where the `ClusterUpgradeGroup` CR is applied by running the following command: ++ +[source,terminal] +---- +$ oc get cgu -n -oyaml +---- + ++ +.Example output +[source,yaml] +---- + precaching: + spec: + platformImage: quay.io/openshift-release-dev/ocp-release@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef + operatorsIndexes: + - registry.example.com:5000/custom-redhat-operators:1.0.0 + operatorsPackagesAndChannels: + - local-storage-operator: stable + - ptp-operator: stable + - sriov-network-operator: stable + excludePrecachePatterns: + - aws + - vsphere + additionalImages: + - quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef + - quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef + - quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09 + spaceRequired: "30" + status: + sno1: Starting + sno2: Starting +---- + ++ +The pre-caching configurations are validated by checking if the managed policies exist. +Valid configurations of the `ClusterGroupUpgrade` and the `PreCachingConfig` CRs result in the following statuses: + ++ +.Example output of valid CRs +[source,yaml] +---- +- lastTransitionTime: "2023-01-01T00:00:01Z" + message: All selected clusters are valid + reason: ClusterSelectionCompleted + status: "True" + type: ClusterSelected +- lastTransitionTime: "2023-01-01T00:00:02Z" + message: Completed validation + reason: ValidationCompleted + status: "True" + type: Validated +- lastTransitionTime: "2023-01-01T00:00:03Z" + message: Precaching spec is valid and consistent + reason: PrecacheSpecIsWellFormed + status: "True" + type: PrecacheSpecValid +- lastTransitionTime: "2023-01-01T00:00:04Z" + message: Precaching in progress for 1 clusters + reason: InProgress + status: "False" + type: PrecachingSucceeded +---- + ++ +.Example of an invalid PreCachingConfig CR +[source,yaml] +---- +Type: "PrecacheSpecValid" +Status: False, +Reason: "PrecacheSpecIncomplete" +Message: "Precaching spec is incomplete: failed to get PreCachingConfig resource due to PreCachingConfig.ran.openshift.io "" not found" +---- + +. You can find the pre-caching job by running the following command on the managed cluster: ++ +[source,terminal] +---- +$ oc get jobs -n openshift-talo-pre-cache +---- + ++ +.Example of pre-caching job in progress +[source,terminal] +---- +NAME COMPLETIONS DURATION AGE +pre-cache 0/1 1s 1s +---- + +. You can check the status of the pod created for the pre-caching job by running the following command: ++ +[source,terminal] +---- +$ oc describe pod pre-cache -n openshift-talo-pre-cache +---- + ++ +.Example of pre-caching job in progress +[source,terminal] +---- +Type Reason Age From Message +Normal SuccesfulCreate 19s job-controller Created pod: pre-cache-abcd1 +---- + +. You can get live updates on the status of the job by running the following command: ++ +[source,terminal] +---- +$ oc logs -f pre-cache-abcd1 -n openshift-talo-pre-cache +---- + +. To verify the pre-cache job is successfully completed, run the following command: ++ +[source,terminal] +---- +$ oc describe pod pre-cache -n openshift-talo-pre-cache +---- + ++ +.Example of completed pre-cache job +[source,terminal] +---- +Type Reason Age From Message +Normal SuccesfulCreate 5m19s job-controller Created pod: pre-cache-abcd1 +Normal Completed 19s job-controller Job completed +---- + +. To verify that the images are successfully pre-cached on the {sno}, do the following: + +.. Enter into the node in debug mode: ++ +[source,terminal] +---- +$ oc debug node/cnfdf00.example.lab +---- + +.. Change root to `host`: ++ +[source,terminal] +---- +$ chroot /host/ +---- + +.. Search for the desired images: ++ +[source,terminal] +---- +$ sudo podman images | grep +---- \ No newline at end of file diff --git a/modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc b/modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc new file mode 100644 index 0000000000..3db1b8bb70 --- /dev/null +++ b/modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc @@ -0,0 +1,67 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc + +:_content-type: CONCEPT +[id="talm-prechache-user-specified-images-concept_{context}"] += Pre-caching user-specified images with {cgu-operator} on {sno} clusters + +You can pre-cache application-specific workload images on {sno} clusters before upgrading your applications. + +You can specify the configuration options for the pre-caching jobs using the following custom resources (CR): + +* `PreCachingConfig` CR +* `ClusterGroupUpgrade` CR + +[NOTE] +==== +All fields in the `PreCachingConfig` CR are optional. +==== + +.Example PreCachingConfig CR +[source,yaml] +---- +apiVersion: ran.openshift.io/v1alpha1 +kind: PreCachingConfig +metadata: + name: exampleconfig + namespace: exampleconfig-ns +spec: + overrides: <1> + platformImage: quay.io/openshift-release-dev/ocp-release@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef + operatorsIndexes: + - registry.example.com:5000/custom-redhat-operators:1.0.0 + operatorsPackagesAndChannels: + - local-storage-operator: stable + - ptp-operator: stable + - sriov-network-operator: stable + spaceRequired: 30 Gi <2> + excludePrecachePatterns: <3> + - aws + - vsphere + additionalImages: <4> + - quay.io/exampleconfig/application1@sha256:3d5800990dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47e2e1ef + - quay.io/exampleconfig/application2@sha256:3d5800123dee7cd4727d3fe238a97e2d2976d3808fc925ada29c559a47adfaef + - quay.io/exampleconfig/applicationN@sha256:4fe1334adfafadsf987123adfffdaf1243340adfafdedga0991234afdadfsa09 +---- +<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. +<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`. +<3> Specifies the images to exclude from pre-caching based on image name matching. +<4> Specifies the list of additional images to pre-cache. + +.Example ClusterGroupUpgrade CR with PreCachingConfig CR reference +[source,yaml] +---- +apiVersion: ran.openshift.io/v1alpha1 +kind: ClusterGroupUpgrade +metadata: + name: cgu +spec: + preCaching: true <1> + preCachingConfigRef: + name: exampleconfig <2> + namespace: exampleconfig-ns <3> +---- +<1> The `preCaching` field set to `true` enables the pre-caching job. +<2> The `preCachingConfigRef.name` field specifies the `PreCachingConfig` CR that you want to use. +<3> The `preCachingConfigRef.namespace` specifies the namespace of the `PreCachingConfig` CR that you want to use. \ No newline at end of file diff --git a/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc b/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc index 44a149c367..29c996d6d1 100644 --- a/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc +++ b/scalability_and_performance/ztp_far_edge/ztp-talm-updating-managed-policies.adoc @@ -48,4 +48,13 @@ include::modules/cnf-topology-aware-lifecycle-manager-operator-and-platform-upda include::modules/cnf-topology-aware-lifecycle-manager-pao-update.adoc[leveloffset=+2] +include::modules/cnf-topology-aware-lifecycle-manager-precache-user-spec-images.adoc[leveloffset=+2] + +include::modules/cnf-topology-aware-lifecycle-manager-creating-custom-resources.adoc[leveloffset=+2] + +[role="_additional-resources"] +.Additional resources + +* 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]. + include::modules/cnf-topology-aware-lifecycle-manager-autocreate-cgu-cr-ztp.adoc[leveloffset=+1]