From ce1cd1d1482561e3bc190b8100da8768548c8563 Mon Sep 17 00:00:00 2001 From: Shane Lovern Date: Mon, 20 Jul 2026 17:58:06 +0100 Subject: [PATCH] TELCODOCS-2762: Apply DITA formatting and split downloading module for enterprise-4.20 This PR applies DITA compliance changes to the ZTP pre-caching tool documentation: - Add [role="_abstract"] to all modules and assembly - Convert callout blocks (<1>, <2>, etc.) to "Where:" definition lists - Convert .Example output block titles to inline text - Fix .Procedure/.Note rendering issue in booting-from-live-os module - Split monolithic ztp-precaching-downloading-artifacts.adoc into: - ztp-precaching-downloading-overview.adoc (CONCEPT) - ztp-precaching-preparing-ocp-images.adoc (PROCEDURE) - ztp-precaching-downloading-ocp-images.adoc (PROCEDURE) - ztp-precaching-downloading-operator-images.adoc (PROCEDURE) - ztp-precaching-custom-disconnected.adoc (PROCEDURE) This aligns with changes merged in main PRs #106776 and #115675. Co-authored-by: Cursor --- edge_computing/ztp-precaching-tool.adoc | 11 +- .../ztp-precaching-booting-from-live-os.adoc | 13 +- .../ztp-precaching-custom-disconnected.adoc | 183 ++++++++ .../ztp-precaching-downloading-artifacts.adoc | 413 ------------------ ...ztp-precaching-downloading-ocp-images.adoc | 92 ++++ ...recaching-downloading-operator-images.adoc | 63 +++ .../ztp-precaching-downloading-overview.adoc | 34 ++ modules/ztp-precaching-getting-tool.adoc | 5 +- modules/ztp-precaching-partitioning.adoc | 42 +- .../ztp-precaching-preparing-ocp-images.adoc | 73 ++++ modules/ztp-precaching-troubleshooting.adoc | 4 +- modules/ztp-precaching-ztp-config.adoc | 15 +- 12 files changed, 498 insertions(+), 450 deletions(-) create mode 100644 modules/ztp-precaching-custom-disconnected.adoc delete mode 100644 modules/ztp-precaching-downloading-artifacts.adoc create mode 100644 modules/ztp-precaching-downloading-ocp-images.adoc create mode 100644 modules/ztp-precaching-downloading-operator-images.adoc create mode 100644 modules/ztp-precaching-downloading-overview.adoc create mode 100644 modules/ztp-precaching-preparing-ocp-images.adoc diff --git a/edge_computing/ztp-precaching-tool.adoc b/edge_computing/ztp-precaching-tool.adoc index 1449d91e481f..2a89ae4e5a15 100644 --- a/edge_computing/ztp-precaching-tool.adoc +++ b/edge_computing/ztp-precaching-tool.adoc @@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] In environments with limited bandwidth where you use the {ztp-first} solution to deploy a large number of clusters, you want to avoid downloading all the images that are required for bootstrapping and installing {product-title}. The limited bandwidth at remote {sno} sites can cause long deployment times. The {factory-prestaging-tool} allows you to pre-stage servers before shipping them to the remote site for ZTP provisioning. @@ -38,7 +39,9 @@ include::modules/ztp-precaching-booting-from-live-os.adoc[leveloffset=+1] include::modules/ztp-precaching-partitioning.adoc[leveloffset=+1] -include::modules/ztp-precaching-downloading-artifacts.adoc[leveloffset=+1] +include::modules/ztp-precaching-downloading-overview.adoc[leveloffset=+1] + +include::modules/ztp-precaching-preparing-ocp-images.adoc[leveloffset=+2] [role="_additional-resources"] .Additional resources @@ -47,6 +50,12 @@ include::modules/ztp-precaching-downloading-artifacts.adoc[leveloffset=+1] * For more information about using the multicluster engine, see link:https://access.redhat.com/documentation/en-us/red_hat_advanced_cluster_management_for_kubernetes/2.9/html/clusters/cluster_mce_overview#mce-intro[About cluster lifecycle with the multicluster engine operator]. +include::modules/ztp-precaching-downloading-ocp-images.adoc[leveloffset=+2] + +include::modules/ztp-precaching-downloading-operator-images.adoc[leveloffset=+2] + +include::modules/ztp-precaching-custom-disconnected.adoc[leveloffset=+2] + include::modules/ztp-precaching-ztp-config.adoc[leveloffset=+1] include::modules/ztp-precaching-troubleshooting.adoc[leveloffset=+1] diff --git a/modules/ztp-precaching-booting-from-live-os.adoc b/modules/ztp-precaching-booting-from-live-os.adoc index 2af5ac3737b2..8655f2f02d31 100644 --- a/modules/ztp-precaching-booting-from-live-os.adoc +++ b/modules/ztp-precaching-booting-from-live-os.adoc @@ -6,7 +6,8 @@ [id="ztp-booting-from-live-os_{context}"] = Booting from a live operating system image -You can use the {factory-prestaging-tool} with to boot servers where only one disk is available and external disk drive cannot be attached to the server. +[role="_abstract"] +You can use the {factory-prestaging-tool} to boot servers where only one disk is available and an external disk drive cannot be attached to the server. [WARNING] ==== @@ -19,22 +20,16 @@ Depending on the server hardware, you can mount the {op-system} live ISO on the * Using the HPONCFG tool on a HP server. * Using the Redfish BMC API. -[NOTE] -==== It is recommended to automate the mounting procedure. To automate the procedure, you need to pull the required images and host them on a local HTTP server. -==== .Prerequisites * You powered up the host. * You have network connectivity to the host. -.Procedure +The following example procedure uses the Redfish BMC API to mount the {op-system} live ISO. -[NOTE] -==== -This example procedure uses the Redfish BMC API to mount the {op-system} live ISO. -==== +.Procedure . Mount the {op-system} live ISO: diff --git a/modules/ztp-precaching-custom-disconnected.adoc b/modules/ztp-precaching-custom-disconnected.adoc new file mode 100644 index 000000000000..c7d0ea9fe0c9 --- /dev/null +++ b/modules/ztp-precaching-custom-disconnected.adoc @@ -0,0 +1,183 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ztp-custom-pre-caching-in-disconnected-environment_{context}"] += Pre-caching custom images in disconnected environments + +[role="_abstract"] +The `--generate-imageset` argument stops the {factory-prestaging-tool} after the `ImageSetConfiguration` custom resource (CR) is generated. +This allows you to customize the `ImageSetConfiguration` CR before downloading any images. +After you customized the CR, you can use the `--skip-imageset` argument to download the images that you specified in the `ImageSetConfiguration` CR. + +You can customize the `ImageSetConfiguration` CR in the following ways: + +* Add Operators and additional images +* Remove Operators and additional images +* Change Operator and catalog sources to local or disconnected registries + +.Procedure + +. Pre-cache the images: ++ +[source,terminal,subs="attributes+"] +---- +# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download \ + -r {product-version}.0 \ + --acm-version 2.6.3 \ + --mce-version 2.1.4 \ + -f /mnt \ + --img quay.io/custom/repository \ + --du-profile -s \ + --generate-imageset +---- ++ +Where: ++ +** `factory-precaching-cli download` specifies the downloading function of the {factory-prestaging-tool}. +** `-r {product-version}.0` specifies the {product-title} release version. +** `--acm-version 2.6.3` specifies the {rh-rhacm} version. +** `--mce-version 2.1.4` specifies the multicluster engine version. +** `-f /mnt` specifies the folder where you want to download the images on the disk. +** `--img quay.io/custom/repository` is optional and specifies the repository where you store your additional images. These images are downloaded and pre-cached on the disk. +** `--du-profile -s` specifies pre-caching the Operators included in the DU configuration. +** `--generate-imageset` generates the `ImageSetConfiguration` CR only, which allows you to customize the CR. ++ +The following is example output: ++ +[source,terminal] +---- +Generated /mnt/imageset.yaml +---- ++ +The following example shows the `ImageSetConfiguration` CR: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + platform: + channels: + - name: stable-{product-version} + minVersion: {product-version}.0 + maxVersion: {product-version}.0 + additionalImages: + - name: quay.io/custom/repository + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} + packages: + - name: advanced-cluster-management + channels: + - name: 'release-2.6' + minVersion: 2.6.3 + maxVersion: 2.6.3 + - name: multicluster-engine + channels: + - name: 'stable-2.1' + minVersion: 2.1.4 + maxVersion: 2.1.4 + - name: local-storage-operator + channels: + - name: 'stable' + - name: ptp-operator + channels: + - name: 'stable' + - name: sriov-network-operator + channels: + - name: 'stable' + - name: cluster-logging + channels: + - name: 'stable' + - name: lvms-operator + channels: + - name: 'stable-{product-version}' + - name: amq7-interconnect-operator + channels: + - name: '1.10.x' + - name: bare-metal-event-relay + channels: + - name: 'stable' + - catalog: registry.redhat.io/redhat/certified-operator-index:v{product-version} + packages: + - name: sriov-fec + channels: + - name: 'stable' +---- ++ +Where: ++ +** `mirror.platform.channels.minVersion`, `mirror.platform.channels.maxVersion` -- Specifies the platform versions that match the versions passed to the tool. +** `mirror.operators.packages.name: advanced-cluster-management`, `mirror.operators.packages.name: multicluster-engine` -- Specifies the versions of {rh-rhacm} and the {mce-short} that match the versions passed to the tool. +** `mirror.operators.packages.name: local-storage-operator`, `mirror.operators.packages.name: ptp-operator`, and other Operators -- Specifies all the DU Operators included in the CR. + +. Customize the catalog resource in the CR: ++ +[source,yaml,subs="attributes+"] +---- +apiVersion: mirror.openshift.io/v1alpha2 +kind: ImageSetConfiguration +mirror: + platform: +[...] + operators: + - catalog: eko4.cloud.lab.eng.bos.redhat.com:8443/redhat/certified-operator-index:v{product-version} + packages: + - name: sriov-fec + channels: + - name: 'stable' +---- ++ +When you download images by using a local or disconnected registry, you have to first add certificates for the registries that you want to pull the content from. + +. To avoid any errors, copy the registry certificate into your server: ++ +[source,terminal] +---- +# cp /tmp/eko4-ca.crt /etc/pki/ca-trust/source/anchors/. +---- + +. Then, update the certificates truststore: ++ +[source,terminal] +---- +# update-ca-trust +---- + +. Mount the host `/etc/pki` folder into the factory-cli image: ++ +[source,terminal,subs="attributes+"] +---- +# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker -v /etc/pki:/etc/pki --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- \ +factory-precaching-cli download \ + -r {product-version}.0 \ + --acm-version 2.6.3 \ + --mce-version 2.1.4 \ + -f /mnt \ + --img quay.io/custom/repository \ + --du-profile -s \ + --skip-imageset +---- ++ +Where: ++ +** `factory-precaching-cli download` specifies the downloading function of the {factory-prestaging-tool}. +** `-r {product-version}.0` specifies the {product-title} release version. +** `--acm-version 2.6.3` specifies the {rh-rhacm} version. +** `--mce-version 2.1.4` specifies the multicluster engine version. +** `-f /mnt` specifies the folder where you want to download the images on the disk. +** `--img quay.io/custom/repository` is optional and specifies the repository where you store your additional images. These images are downloaded and pre-cached on the disk. +** `--du-profile -s` specifies pre-caching the Operators included in the DU configuration. +** `--skip-imageset` specifies to download the images in your customized `ImageSetConfiguration` CR. + +. Download the images without generating a new `imageSetConfiguration` CR: ++ +[source,terminal,subs="attributes+"] +---- +# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download -r {product-version}.0 \ +--acm-version 2.6.3 --mce-version 2.1.4 -f /mnt \ +--img quay.io/custom/repository \ +--du-profile -s \ +--skip-imageset +---- diff --git a/modules/ztp-precaching-downloading-artifacts.adoc b/modules/ztp-precaching-downloading-artifacts.adoc deleted file mode 100644 index 26067587c9c6..000000000000 --- a/modules/ztp-precaching-downloading-artifacts.adoc +++ /dev/null @@ -1,413 +0,0 @@ -// Module included in the following assemblies: -// -// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc - -:_mod-docs-content-type: PROCEDURE -[id="ztp-downloading-images_{context}"] -= Downloading the images - -The {factory-prestaging-tool} allows you to download the following images to your partitioned server: - -* {product-title} images -* Operator images that are included in the distributed unit (DU) profile for 5G RAN sites -* Operator images from disconnected registries - -[NOTE] -==== -The list of available Operator images can vary in different {product-title} releases. -==== - -[id="ztp-downloading-images-parallel-workers_{context}"] -== Downloading with parallel workers - -The {factory-prestaging-tool} uses parallel workers to download multiple images simultaneously. -You can configure the number of workers with the `--parallel` or `-p` option. -The default number is set to 80% of the available CPUs to the server. - -[NOTE] -==== -Your login shell may be restricted to a subset of CPUs, which reduces the CPUs available to the container. -To remove this restriction, you can precede your commands with `taskset 0xffffffff`, for example: - -[source,terminal] ----- -# taskset 0xffffffff podman run --rm quay.io/openshift-kni/telco-ran-tools:latest factory-precaching-cli download --help ----- -==== - -[id="ztp-preparing-ocp-images_{context}"] -== Preparing to download the {product-title} images - -To download {product-title} container images, you need to know the multicluster engine version. When you use the `--du-profile` flag, you also need to specify the {rh-rhacm-first} version running in the hub cluster that is going to provision the {sno}. - -.Prerequisites - -* You have {rh-rhacm} and the {mce-short} installed. -* You partitioned the storage device. -* You have enough space for the images on the partitioned device. -* You connected the bare-metal server to the Internet. -* You have a valid pull secret. - -.Procedure - -. Check the {rh-rhacm} version and the multicluster engine version by running the following commands in the hub cluster: -+ -[source,terminal] ----- -$ oc get csv -A | grep -i advanced-cluster-management ----- - -+ -.Example output -[source,terminal] ----- -open-cluster-management advanced-cluster-management.v2.6.3 Advanced Cluster Management for Kubernetes 2.6.3 advanced-cluster-management.v2.6.3 Succeeded ----- - -+ -[source,terminal] ----- -$ oc get csv -A | grep -i multicluster-engine ----- - -+ -.Example output -[source,terminal] ----- -multicluster-engine cluster-group-upgrades-operator.v0.0.3 cluster-group-upgrades-operator 0.0.3 Pending -multicluster-engine multicluster-engine.v2.1.4 multicluster engine for Kubernetes 2.1.4 multicluster-engine.v2.0.3 Succeeded -multicluster-engine openshift-gitops-operator.v1.5.7 Red Hat OpenShift GitOps 1.5.7 openshift-gitops-operator.v1.5.6-0.1664915551.p Succeeded -multicluster-engine openshift-pipelines-operator-rh.v1.6.4 Red Hat OpenShift Pipelines 1.6.4 openshift-pipelines-operator-rh.v1.6.3 Succeeded ----- - -. To access the container registry, copy a valid pull secret on the server to be installed: - -.. Create the `.docker` folder: -+ -[source,terminal] ----- -$ mkdir /root/.docker ----- - -.. Copy the valid pull in the `config.json` file to the previously created `.docker/` folder: -+ -[source,terminal] ----- -$ cp config.json /root/.docker/config.json <1> ----- -<1> `/root/.docker/config.json` is the default path where `podman` checks for the login credentials for the registry. - -[NOTE] -==== -If you use a different registry to pull the required artifacts, you need to copy the proper pull secret. -If the local registry uses TLS, you need to include the certificates from the registry as well. -==== - -[id="ztp-downloading-ocp-images_{context}"] -== Downloading the {product-title} images - -The {factory-prestaging-tool} allows you to pre-cache all the container images required to provision a specific {product-title} release. - -.Procedure - -* Pre-cache the release by running the following command: -+ -[source,terminal,subs="attributes+"] ----- -# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools -- \ - factory-precaching-cli download \ <1> - -r {product-version}.0 \ <2> - --acm-version 2.6.3 \ <3> - --mce-version 2.1.4 \ <4> - -f /mnt \ <5> - --img quay.io/custom/repository <6> ----- -<1> Specifies the downloading function of the {factory-prestaging-tool}. -<2> Defines the {product-title} release version. -<3> Defines the {rh-rhacm} version. -<4> Defines the multicluster engine version. -<5> Defines the folder where you want to download the images on the disk. -<6> Optional. Defines the repository where you store your additional images. These images are downloaded and pre-cached on the disk. - -+ -.Example output -[source,terminal,subs="attributes+"] ----- -Generated /mnt/imageset.yaml -Generating list of pre-cached artifacts... -Processing artifact [1/176]: ocp-v4.0-art-dev@sha256_6ac2b96bf4899c01a87366fd0feae9f57b1b61878e3b5823da0c3f34f707fbf5 -Processing artifact [2/176]: ocp-v4.0-art-dev@sha256_f48b68d5960ba903a0d018a10544ae08db5802e21c2fa5615a14fc58b1c1657c -Processing artifact [3/176]: ocp-v4.0-art-dev@sha256_a480390e91b1c07e10091c3da2257180654f6b2a735a4ad4c3b69dbdb77bbc06 -Processing artifact [4/176]: ocp-v4.0-art-dev@sha256_ecc5d8dbd77e326dba6594ff8c2d091eefbc4d90c963a9a85b0b2f0e6155f995 -Processing artifact [5/176]: ocp-v4.0-art-dev@sha256_274b6d561558a2f54db08ea96df9892315bb773fc203b1dbcea418d20f4c7ad1 -Processing artifact [6/176]: ocp-v4.0-art-dev@sha256_e142bf5020f5ca0d1bdda0026bf97f89b72d21a97c9cc2dc71bf85050e822bbf -... -Processing artifact [175/176]: ocp-v4.0-art-dev@sha256_16cd7eda26f0fb0fc965a589e1e96ff8577e560fcd14f06b5fda1643036ed6c8 -Processing artifact [176/176]: ocp-v4.0-art-dev@sha256_cf4d862b4a4170d4f611b39d06c31c97658e309724f9788e155999ae51e7188f -... -Summary: - -Release: {product-version}.0 -Hub Version: 2.6.3 -ACM Version: 2.6.3 -MCE Version: 2.1.4 -Include DU Profile: No -Workers: 83 ----- - -.Verification - -* Check that all the images are compressed in the target folder of server: -+ -[source,terminal] ----- -$ ls -l /mnt <1> ----- -<1> It is recommended that you pre-cache the images in the `/mnt` folder. - -+ -.Example output -[source,terminal] ----- --rw-r--r--. 1 root root 136352323 Oct 31 15:19 ocp-v4.0-art-dev@sha256_edec37e7cd8b1611d0031d45e7958361c65e2005f145b471a8108f1b54316c07.tgz --rw-r--r--. 1 root root 156092894 Oct 31 15:33 ocp-v4.0-art-dev@sha256_ee51b062b9c3c9f4fe77bd5b3cc9a3b12355d040119a1434425a824f137c61a9.tgz --rw-r--r--. 1 root root 172297800 Oct 31 15:29 ocp-v4.0-art-dev@sha256_ef23d9057c367a36e4a5c4877d23ee097a731e1186ed28a26c8d21501cd82718.tgz --rw-r--r--. 1 root root 171539614 Oct 31 15:23 ocp-v4.0-art-dev@sha256_f0497bb63ef6834a619d4208be9da459510df697596b891c0c633da144dbb025.tgz --rw-r--r--. 1 root root 160399150 Oct 31 15:20 ocp-v4.0-art-dev@sha256_f0c339da117cde44c9aae8d0bd054bceb6f19fdb191928f6912a703182330ac2.tgz --rw-r--r--. 1 root root 175962005 Oct 31 15:17 ocp-v4.0-art-dev@sha256_f19dd2e80fb41ef31d62bb8c08b339c50d193fdb10fc39cc15b353cbbfeb9b24.tgz --rw-r--r--. 1 root root 174942008 Oct 31 15:33 ocp-v4.0-art-dev@sha256_f1dbb81fa1aa724e96dd2b296b855ff52a565fbef003d08030d63590ae6454df.tgz --rw-r--r--. 1 root root 246693315 Oct 31 15:31 ocp-v4.0-art-dev@sha256_f44dcf2c94e4fd843cbbf9b11128df2ba856cd813786e42e3da1fdfb0f6ddd01.tgz --rw-r--r--. 1 root root 170148293 Oct 31 15:00 ocp-v4.0-art-dev@sha256_f48b68d5960ba903a0d018a10544ae08db5802e21c2fa5615a14fc58b1c1657c.tgz --rw-r--r--. 1 root root 168899617 Oct 31 15:16 ocp-v4.0-art-dev@sha256_f5099b0989120a8d08a963601214b5c5cb23417a707a8624b7eb52ab788a7f75.tgz --rw-r--r--. 1 root root 176592362 Oct 31 15:05 ocp-v4.0-art-dev@sha256_f68c0e6f5e17b0b0f7ab2d4c39559ea89f900751e64b97cb42311a478338d9c3.tgz --rw-r--r--. 1 root root 157937478 Oct 31 15:37 ocp-v4.0-art-dev@sha256_f7ba33a6a9db9cfc4b0ab0f368569e19b9fa08f4c01a0d5f6a243d61ab781bd8.tgz --rw-r--r--. 1 root root 145535253 Oct 31 15:26 ocp-v4.0-art-dev@sha256_f8f098911d670287826e9499806553f7a1dd3e2b5332abbec740008c36e84de5.tgz --rw-r--r--. 1 root root 158048761 Oct 31 15:40 ocp-v4.0-art-dev@sha256_f914228ddbb99120986262168a705903a9f49724ffa958bb4bf12b2ec1d7fb47.tgz --rw-r--r--. 1 root root 167914526 Oct 31 15:37 ocp-v4.0-art-dev@sha256_fa3ca9401c7a9efda0502240aeb8d3ae2d239d38890454f17fe5158b62305010.tgz --rw-r--r--. 1 root root 164432422 Oct 31 15:24 ocp-v4.0-art-dev@sha256_fc4783b446c70df30b3120685254b40ce13ba6a2b0bf8fb1645f116cf6a392f1.tgz --rw-r--r--. 1 root root 306643814 Oct 31 15:11 troubleshoot@sha256_b86b8aea29a818a9c22944fd18243fa0347c7a2bf1ad8864113ff2bb2d8e0726.tgz ----- - -[id="ztp-downloading-operator-images_{context}"] -== Downloading the Operator images - -You can also pre-cache Day-2 Operators used in the 5G Radio Access Network (RAN) Distributed Unit (DU) cluster configuration. The Day-2 Operators depend on the installed {product-title} version. - -[IMPORTANT] -==== -You need to include the {rh-rhacm} hub and {mce-short} versions by using the `--acm-version` and `--mce-version` flags so the {factory-prestaging-tool} can pre-cache the appropriate containers images for {rh-rhacm} and the {mce-short}. -==== - -.Procedure - -* Pre-cache the Operator images: -+ -[source,terminal,subs="attributes+"] ----- -# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download \ <1> - -r {product-version}.0 \ <2> - --acm-version 2.6.3 \ <3> - --mce-version 2.1.4 \ <4> - -f /mnt \ <5> - --img quay.io/custom/repository <6> - --du-profile -s <7> ----- -<1> Specifies the downloading function of the {factory-prestaging-tool}. -<2> Defines the {product-title} release version. -<3> Defines the {rh-rhacm} version. -<4> Defines the multicluster engine version. -<5> Defines the folder where you want to download the images on the disk. -<6> Optional. Defines the repository where you store your additional images. These images are downloaded and pre-cached on the disk. -<7> Specifies pre-caching the Operators included in the DU configuration. - -+ -.Example output -[source,terminal,subs="attributes+"] ----- -Generated /mnt/imageset.yaml -Generating list of pre-cached artifacts... -Processing artifact [1/379]: ocp-v4.0-art-dev@sha256_7753a8d9dd5974be8c90649aadd7c914a3d8a1f1e016774c7ac7c9422e9f9958 -Processing artifact [2/379]: ose-kube-rbac-proxy@sha256_c27a7c01e5968aff16b6bb6670423f992d1a1de1a16e7e260d12908d3322431c -Processing artifact [3/379]: ocp-v4.0-art-dev@sha256_370e47a14c798ca3f8707a38b28cfc28114f492bb35fe1112e55d1eb51022c99 -... -Processing artifact [378/379]: ose-local-storage-operator@sha256_0c81c2b79f79307305e51ce9d3837657cf9ba5866194e464b4d1b299f85034d0 -Processing artifact [379/379]: multicluster-operators-channel-rhel8@sha256_c10f6bbb84fe36e05816e873a72188018856ad6aac6cc16271a1b3966f73ceb3 -... -Summary: - -Release: {product-version}.0 -Hub Version: 2.6.3 -ACM Version: 2.6.3 -MCE Version: 2.1.4 -Include DU Profile: Yes -Workers: 83 ----- - -[id="ztp-custom-pre-caching-in-disconnected-environment_{context}"] -== Pre-caching custom images in disconnected environments - -The `--generate-imageset` argument stops the {factory-prestaging-tool} after the `ImageSetConfiguration` custom resource (CR) is generated. -This allows you to customize the `ImageSetConfiguration` CR before downloading any images. -After you customized the CR, you can use the `--skip-imageset` argument to download the images that you specified in the `ImageSetConfiguration` CR. - -You can customize the `ImageSetConfiguration` CR in the following ways: - -* Add Operators and additional images -* Remove Operators and additional images -* Change Operator and catalog sources to local or disconnected registries - -.Procedure - -. Pre-cache the images: -+ -[source,terminal,subs="attributes+"] ----- -# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download \ <1> - -r {product-version}.0 \ <2> - --acm-version 2.6.3 \ <3> - --mce-version 2.1.4 \ <4> - -f /mnt \ <5> - --img quay.io/custom/repository <6> - --du-profile -s \ <7> - --generate-imageset <8> ----- -<1> Specifies the downloading function of the {factory-prestaging-tool}. -<2> Defines the {product-title} release version. -<3> Defines the {rh-rhacm} version. -<4> Defines the multicluster engine version. -<5> Defines the folder where you want to download the images on the disk. -<6> Optional. Defines the repository where you store your additional images. These images are downloaded and pre-cached on the disk. -<7> Specifies pre-caching the Operators included in the DU configuration. -<8> The `--generate-imageset` argument generates the `ImageSetConfiguration` CR only, which allows you to customize the CR. - -+ -.Example output -[source,terminal] ----- -Generated /mnt/imageset.yaml ----- - -+ -.Example ImageSetConfiguration CR -[source,yaml,subs="attributes+"] ----- -apiVersion: mirror.openshift.io/v1alpha2 -kind: ImageSetConfiguration -mirror: - platform: - channels: - - name: stable-{product-version} - minVersion: {product-version}.0 <1> - maxVersion: {product-version}.0 - additionalImages: - - name: quay.io/custom/repository - operators: - - catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} - packages: - - name: advanced-cluster-management <2> - channels: - - name: 'release-2.6' - minVersion: 2.6.3 - maxVersion: 2.6.3 - - name: multicluster-engine <2> - channels: - - name: 'stable-2.1' - minVersion: 2.1.4 - maxVersion: 2.1.4 - - name: local-storage-operator <3> - channels: - - name: 'stable' - - name: ptp-operator <3> - channels: - - name: 'stable' - - name: sriov-network-operator <3> - channels: - - name: 'stable' - - name: cluster-logging <3> - channels: - - name: 'stable' - - name: lvms-operator <3> - channels: - - name: 'stable-{product-version}' - - name: amq7-interconnect-operator <3> - channels: - - name: '1.10.x' - - name: bare-metal-event-relay <3> - channels: - - name: 'stable' - - catalog: registry.redhat.io/redhat/certified-operator-index:v{product-version} - packages: - - name: sriov-fec <3> - channels: - - name: 'stable' ----- -<1> The platform versions match the versions passed to the tool. -<2> The versions of {rh-rhacm} and the {mce-short} match the versions passed to the tool. -<3> The CR contains all the specified DU Operators. - -. Customize the catalog resource in the CR: -+ -[source,yaml,subs="attributes+"] ----- -apiVersion: mirror.openshift.io/v1alpha2 -kind: ImageSetConfiguration -mirror: - platform: -[...] - operators: - - catalog: eko4.cloud.lab.eng.bos.redhat.com:8443/redhat/certified-operator-index:v{product-version} - packages: - - name: sriov-fec - channels: - - name: 'stable' ----- -+ -When you download images by using a local or disconnected registry, you have to first add certificates for the registries that you want to pull the content from. - -. To avoid any errors, copy the registry certificate into your server: -+ -[source,terminal] ----- -# cp /tmp/eko4-ca.crt /etc/pki/ca-trust/source/anchors/. ----- - -. Then, update the certificates trust store: -+ -[source,terminal] ----- -# update-ca-trust ----- - -. Mount the host `/etc/pki` folder into the factory-cli image: -+ -[source,terminal,subs="attributes+"] ----- -# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker -v /etc/pki:/etc/pki --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- \ -factory-precaching-cli download \ <1> - -r {product-version}.0 \ <2> - --acm-version 2.6.3 \ <3> - --mce-version 2.1.4 \ <4> - -f /mnt \ <5> - --img quay.io/custom/repository <6> - --du-profile -s \ <7> - --skip-imageset <8> ----- -<1> Specifies the downloading function of the {factory-prestaging-tool}. -<2> Defines the {product-title} release version. -<3> Defines the {rh-rhacm} version. -<4> Defines the multicluster engine version. -<5> Defines the folder where you want to download the images on the disk. -<6> Optional. Defines the repository where you store your additional images. These images are downloaded and pre-cached on the disk. -<7> Specifies pre-caching the Operators included in the DU configuration. -<8> The `--skip-imageset` argument allows you to download the images that you specified in your customized `ImageSetConfiguration` CR. - -. Download the images without generating a new `imageSetConfiguration` CR: -+ -[source,terminal,subs="attributes+"] ----- -# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download -r {product-version}.0 \ ---acm-version 2.6.3 --mce-version 2.1.4 -f /mnt \ ---img quay.io/custom/repository \ ---du-profile -s \ ---skip-imageset ----- diff --git a/modules/ztp-precaching-downloading-ocp-images.adoc b/modules/ztp-precaching-downloading-ocp-images.adoc new file mode 100644 index 000000000000..4df54f4c8d9f --- /dev/null +++ b/modules/ztp-precaching-downloading-ocp-images.adoc @@ -0,0 +1,92 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ztp-downloading-ocp-images_{context}"] += Downloading the {product-title} images + +[role="_abstract"] +The {factory-prestaging-tool} allows you to pre-cache all the container images required to provision a specific {product-title} release. + +.Procedure + +* Pre-cache the release by running the following command: ++ +[source,terminal,subs="attributes+"] +---- +# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools -- \ + factory-precaching-cli download \ + -r {product-version}.0 \ + --acm-version 2.6.3 \ + --mce-version 2.1.4 \ + -f /mnt \ + --img quay.io/custom/repository +---- ++ +Where: ++ +** `factory-precaching-cli download` specifies the downloading function of the {factory-prestaging-tool}. +** `-r {product-version}.0` specifies the {product-title} release version. +** `--acm-version 2.6.3` specifies the {rh-rhacm} version. +** `--mce-version 2.1.4` specifies the multicluster engine version. +** `-f /mnt` specifies the folder where you want to download the images on the disk. +** `--img quay.io/custom/repository` is optional and specifies the repository where you store your additional images. These images are downloaded and pre-cached on the disk. ++ +The following is example output: ++ +[source,terminal,subs="attributes+"] +---- +Generated /mnt/imageset.yaml +Generating list of pre-cached artifacts... +Processing artifact [1/176]: ocp-v4.0-art-dev@sha256_6ac2b96bf4899c01a87366fd0feae9f57b1b61878e3b5823da0c3f34f707fbf5 +Processing artifact [2/176]: ocp-v4.0-art-dev@sha256_f48b68d5960ba903a0d018a10544ae08db5802e21c2fa5615a14fc58b1c1657c +Processing artifact [3/176]: ocp-v4.0-art-dev@sha256_a480390e91b1c07e10091c3da2257180654f6b2a735a4ad4c3b69dbdb77bbc06 +Processing artifact [4/176]: ocp-v4.0-art-dev@sha256_ecc5d8dbd77e326dba6594ff8c2d091eefbc4d90c963a9a85b0b2f0e6155f995 +Processing artifact [5/176]: ocp-v4.0-art-dev@sha256_274b6d561558a2f54db08ea96df9892315bb773fc203b1dbcea418d20f4c7ad1 +Processing artifact [6/176]: ocp-v4.0-art-dev@sha256_e142bf5020f5ca0d1bdda0026bf97f89b72d21a97c9cc2dc71bf85050e822bbf +... +Processing artifact [175/176]: ocp-v4.0-art-dev@sha256_16cd7eda26f0fb0fc965a589e1e96ff8577e560fcd14f06b5fda1643036ed6c8 +Processing artifact [176/176]: ocp-v4.0-art-dev@sha256_cf4d862b4a4170d4f611b39d06c31c97658e309724f9788e155999ae51e7188f +... +Summary: + +Release: {product-version}.0 +Hub Version: 2.6.3 +ACM Version: 2.6.3 +MCE Version: 2.1.4 +Include DU Profile: No +Workers: 83 +---- + +.Verification + +* Check that all the images are compressed in the target folder of the server. It is recommended that you pre-cache the images in the `/mnt` folder: ++ +[source,terminal] +---- +$ ls -l /mnt +---- ++ +The following is example output: ++ +[source,terminal] +---- +-rw-r--r--. 1 root root 136352323 Oct 31 15:19 ocp-v4.0-art-dev@sha256_edec37e7cd8b1611d0031d45e7958361c65e2005f145b471a8108f1b54316c07.tgz +-rw-r--r--. 1 root root 156092894 Oct 31 15:33 ocp-v4.0-art-dev@sha256_ee51b062b9c3c9f4fe77bd5b3cc9a3b12355d040119a1434425a824f137c61a9.tgz +-rw-r--r--. 1 root root 172297800 Oct 31 15:29 ocp-v4.0-art-dev@sha256_ef23d9057c367a36e4a5c4877d23ee097a731e1186ed28a26c8d21501cd82718.tgz +-rw-r--r--. 1 root root 171539614 Oct 31 15:23 ocp-v4.0-art-dev@sha256_f0497bb63ef6834a619d4208be9da459510df697596b891c0c633da144dbb025.tgz +-rw-r--r--. 1 root root 160399150 Oct 31 15:20 ocp-v4.0-art-dev@sha256_f0c339da117cde44c9aae8d0bd054bceb6f19fdb191928f6912a703182330ac2.tgz +-rw-r--r--. 1 root root 175962005 Oct 31 15:17 ocp-v4.0-art-dev@sha256_f19dd2e80fb41ef31d62bb8c08b339c50d193fdb10fc39cc15b353cbbfeb9b24.tgz +-rw-r--r--. 1 root root 174942008 Oct 31 15:33 ocp-v4.0-art-dev@sha256_f1dbb81fa1aa724e96dd2b296b855ff52a565fbef003d08030d63590ae6454df.tgz +-rw-r--r--. 1 root root 246693315 Oct 31 15:31 ocp-v4.0-art-dev@sha256_f44dcf2c94e4fd843cbbf9b11128df2ba856cd813786e42e3da1fdfb0f6ddd01.tgz +-rw-r--r--. 1 root root 170148293 Oct 31 15:00 ocp-v4.0-art-dev@sha256_f48b68d5960ba903a0d018a10544ae08db5802e21c2fa5615a14fc58b1c1657c.tgz +-rw-r--r--. 1 root root 168899617 Oct 31 15:16 ocp-v4.0-art-dev@sha256_f5099b0989120a8d08a963601214b5c5cb23417a707a8624b7eb52ab788a7f75.tgz +-rw-r--r--. 1 root root 176592362 Oct 31 15:05 ocp-v4.0-art-dev@sha256_f68c0e6f5e17b0b0f7ab2d4c39559ea89f900751e64b97cb42311a478338d9c3.tgz +-rw-r--r--. 1 root root 157937478 Oct 31 15:37 ocp-v4.0-art-dev@sha256_f7ba33a6a9db9cfc4b0ab0f368569e19b9fa08f4c01a0d5f6a243d61ab781bd8.tgz +-rw-r--r--. 1 root root 145535253 Oct 31 15:26 ocp-v4.0-art-dev@sha256_f8f098911d670287826e9499806553f7a1dd3e2b5332abbec740008c36e84de5.tgz +-rw-r--r--. 1 root root 158048761 Oct 31 15:40 ocp-v4.0-art-dev@sha256_f914228ddbb99120986262168a705903a9f49724ffa958bb4bf12b2ec1d7fb47.tgz +-rw-r--r--. 1 root root 167914526 Oct 31 15:37 ocp-v4.0-art-dev@sha256_fa3ca9401c7a9efda0502240aeb8d3ae2d239d38890454f17fe5158b62305010.tgz +-rw-r--r--. 1 root root 164432422 Oct 31 15:24 ocp-v4.0-art-dev@sha256_fc4783b446c70df30b3120685254b40ce13ba6a2b0bf8fb1645f116cf6a392f1.tgz +-rw-r--r--. 1 root root 306643814 Oct 31 15:11 troubleshoot@sha256_b86b8aea29a818a9c22944fd18243fa0347c7a2bf1ad8864113ff2bb2d8e0726.tgz +---- diff --git a/modules/ztp-precaching-downloading-operator-images.adoc b/modules/ztp-precaching-downloading-operator-images.adoc new file mode 100644 index 000000000000..ced1c3fbdd94 --- /dev/null +++ b/modules/ztp-precaching-downloading-operator-images.adoc @@ -0,0 +1,63 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ztp-downloading-operator-images_{context}"] += Downloading the Operator images + +[role="_abstract"] +You can also pre-cache Day-2 Operators used in the 5G Radio Access Network (RAN) Distributed Unit (DU) cluster configuration. The Day-2 Operators depend on the installed {product-title} version. + +[IMPORTANT] +==== +You need to include the {rh-rhacm} hub and {mce-short} versions by using the `--acm-version` and `--mce-version` flags so the {factory-prestaging-tool} can pre-cache the appropriate containers images for {rh-rhacm} and the {mce-short}. +==== + +.Procedure + +* Pre-cache the Operator images: ++ +[source,terminal,subs="attributes+"] +---- +# podman run -v /mnt:/mnt -v /root/.docker:/root/.docker --privileged --rm quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli download \ + -r {product-version}.0 \ + --acm-version 2.6.3 \ + --mce-version 2.1.4 \ + -f /mnt \ + --img quay.io/custom/repository \ + --du-profile -s +---- ++ +Where: ++ +** `factory-precaching-cli download` specifies the downloading function of the {factory-prestaging-tool}. +** `-r {product-version}.0` specifies the {product-title} release version. +** `--acm-version 2.6.3` specifies the {rh-rhacm} version. +** `--mce-version 2.1.4` specifies the multicluster engine version. +** `-f /mnt` specifies the folder where you want to download the images on the disk. +** `--img quay.io/custom/repository` is optional and specifies the repository where you store your additional images. These images are downloaded and pre-cached on the disk. +** `--du-profile -s` specifies pre-caching the Operators included in the DU configuration. ++ +The following is example output: ++ +[source,terminal,subs="attributes+"] +---- +Generated /mnt/imageset.yaml +Generating list of pre-cached artifacts... +Processing artifact [1/379]: ocp-v4.0-art-dev@sha256_7753a8d9dd5974be8c90649aadd7c914a3d8a1f1e016774c7ac7c9422e9f9958 +Processing artifact [2/379]: ose-kube-rbac-proxy@sha256_c27a7c01e5968aff16b6bb6670423f992d1a1de1a16e7e260d12908d3322431c +Processing artifact [3/379]: ocp-v4.0-art-dev@sha256_370e47a14c798ca3f8707a38b28cfc28114f492bb35fe1112e55d1eb51022c99 +... +Processing artifact [378/379]: ose-local-storage-operator@sha256_0c81c2b79f79307305e51ce9d3837657cf9ba5866194e464b4d1b299f85034d0 +Processing artifact [379/379]: multicluster-operators-channel-rhel8@sha256_c10f6bbb84fe36e05816e873a72188018856ad6aac6cc16271a1b3966f73ceb3 +... +Summary: + +Release: {product-version}.0 +Hub Version: 2.6.3 +ACM Version: 2.6.3 +MCE Version: 2.1.4 +Include DU Profile: Yes +Workers: 83 +---- diff --git a/modules/ztp-precaching-downloading-overview.adoc b/modules/ztp-precaching-downloading-overview.adoc new file mode 100644 index 000000000000..605f370d0280 --- /dev/null +++ b/modules/ztp-precaching-downloading-overview.adoc @@ -0,0 +1,34 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc + +:_mod-docs-content-type: CONCEPT +[id="ztp-downloading-images_{context}"] += Downloading the images + +[role="_abstract"] +The {factory-prestaging-tool} allows you to download the following images to your partitioned server: + +* {product-title} images +* Operator images that are included in the distributed unit (DU) profile for 5G RAN sites +* Operator images from disconnected registries + +[NOTE] +==== +The list of available Operator images can vary in different {product-title} releases. +==== + +The {factory-prestaging-tool} uses parallel workers to download multiple images simultaneously. +You can configure the number of workers with the `--parallel` or `-p` option. +The default number is set to 80% of the available CPUs to the server. + +[NOTE] +==== +Your login shell may be restricted to a subset of CPUs, which reduces the CPUs available to the container. +To remove this restriction, you can precede your commands with `taskset 0xffffffff`, for example: + +[source,terminal] +---- +# taskset 0xffffffff podman run --rm quay.io/openshift-kni/telco-ran-tools:latest factory-precaching-cli download --help +---- +==== diff --git a/modules/ztp-precaching-getting-tool.adoc b/modules/ztp-precaching-getting-tool.adoc index c59b07e2a3c7..ff77326c41af 100644 --- a/modules/ztp-precaching-getting-tool.adoc +++ b/modules/ztp-precaching-getting-tool.adoc @@ -6,6 +6,7 @@ [id="ztp-getting-tool_{context}"] = Getting the {factory-prestaging-tool} +[role="_abstract"] The {factory-prestaging-tool} Go binary is publicly available in link:https://quay.io/openshift-kni/telco-ran-tools:latest[the {rds-first} tools container image]. The {factory-prestaging-tool} Go binary in the container image is executed on the server running an {op-system} live image using `podman`. If you are working in a disconnected environment or have a private registry, you need to copy the image there so you can download the image to the server. @@ -27,9 +28,9 @@ If you are working in a disconnected environment or have a private registry, you ---- # podman run quay.io/openshift-kni/telco-ran-tools:latest -- factory-precaching-cli -v ---- - + -.Example output +The following is example output: ++ [source,terminal] ---- factory-precaching-cli version 20221018.120852+main.feecf17 diff --git a/modules/ztp-precaching-partitioning.adoc b/modules/ztp-precaching-partitioning.adoc index 3d56af56fff0..b4eb4346f546 100644 --- a/modules/ztp-precaching-partitioning.adoc +++ b/modules/ztp-precaching-partitioning.adoc @@ -6,6 +6,7 @@ [id="ztp-partitioning_{context}"] = Partitioning the disk +[role="_abstract"] To run the full pre-caching process, you have to boot from a live ISO and use the {factory-prestaging-tool} from a container image to partition and pre-cache all the artifacts required. A live ISO or {op-system} live ISO is required because the disk must not be in use when the operating system ({op-system}) is written to the device during the provisioning. @@ -25,9 +26,9 @@ Single-disk servers can also be enabled with this procedure. ---- # lsblk ---- - + -.Example output +The following is example output: ++ [source,terminal] ---- NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT @@ -43,9 +44,9 @@ nvme0n1 259:1 0 1.5T 0 disk ---- # wipefs -a /dev/nvme0n1 ---- - + -.Example output +The following is example output: ++ [source,terminal] ---- /dev/nvme0n1: 8 bytes were erased at offset 0x00000200 (gpt): 45 46 49 20 50 41 52 54 @@ -85,13 +86,16 @@ In the following example, the size of the partition is 250 GiB due to allow pre- ---- # podman run -v /dev:/dev --privileged \ --rm quay.io/openshift-kni/telco-ran-tools:latest -- \ -factory-precaching-cli partition \ <1> --d /dev/nvme0n1 \ <2> --s 250 <3> +factory-precaching-cli partition \ +-d /dev/nvme0n1 \ +-s 250 ---- -<1> Specifies the partitioning function of the {factory-prestaging-tool}. -<2> Defines the root directory on the disk. -<3> Defines the size of the disk in GB. ++ +Where: ++ +** `factory-precaching-cli partition` specifies the partitioning function of the {factory-prestaging-tool}. +** `-d /dev/nvme0n1` specifies the root directory on the disk. +** `-s 250` specifies the size of the disk in GB. . Check the storage information: + @@ -99,9 +103,9 @@ factory-precaching-cli partition \ <1> ---- # lsblk ---- - + -.Example output +The following is example output: ++ [source,terminal] ---- NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT @@ -127,7 +131,8 @@ Query the disk status to verify that the disk is partitioned as expected: # gdisk -l /dev/nvme0n1 ---- -.Example output +The following is example output: + [source,terminal] ---- GPT fdisk (gdisk) version 1.0.3 @@ -169,9 +174,9 @@ It is recommended to mount the device into `/mnt` because that mounting point is ---- # lsblk -f /dev/nvme0n1 ---- - + -.Example output +The following is example output: ++ [source,terminal] ---- NAME FSTYPE LABEL UUID MOUNTPOINT @@ -194,9 +199,9 @@ nvme0n1 ---- # lsblk ---- - + -.Example output +The following is example output. The mount point is `/var/mnt` because the `/mnt` folder in {op-system} is a link to `/var/mnt`. ++ [source,terminal] ---- NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT @@ -204,6 +209,5 @@ loop0 7:0 0 93.8G 0 loop /run/ephemeral loop1 7:1 0 897.3M 1 loop /sysroot sr0 11:0 1 999M 0 rom /run/media/iso nvme0n1 259:1 0 1.5T 0 disk -└─nvme0n1p1 259:2 0 250G 0 part /var/mnt <1> +└─nvme0n1p1 259:2 0 250G 0 part /var/mnt ---- -<1> The mount point is `/var/mnt` because the `/mnt` folder in {op-system} is a link to `/var/mnt`. diff --git a/modules/ztp-precaching-preparing-ocp-images.adoc b/modules/ztp-precaching-preparing-ocp-images.adoc new file mode 100644 index 000000000000..eab52b4c825e --- /dev/null +++ b/modules/ztp-precaching-preparing-ocp-images.adoc @@ -0,0 +1,73 @@ +// Module included in the following assemblies: +// +// * scalability_and_performance/ztp_far_edge/ztp-precaching-tool.adoc + +:_mod-docs-content-type: PROCEDURE +[id="ztp-preparing-ocp-images_{context}"] += Preparing to download the {product-title} images + +[role="_abstract"] +To download {product-title} container images, you need to know the multicluster engine version. When you use the `--du-profile` flag, you also need to specify the {rh-rhacm-first} version running in the hub cluster that is going to provision the {sno}. + +.Prerequisites + +* You have {rh-rhacm} and the {mce-short} installed. +* You partitioned the storage device. +* You have enough space for the images on the partitioned device. +* You connected the bare-metal server to the Internet. +* You have a valid pull secret. + +.Procedure + +. Check the {rh-rhacm} version and the multicluster engine version by running the following commands in the hub cluster: ++ +[source,terminal] +---- +$ oc get csv -A | grep -i advanced-cluster-management +---- ++ +The following is example output: ++ +[source,terminal] +---- +open-cluster-management advanced-cluster-management.v2.6.3 Advanced Cluster Management for Kubernetes 2.6.3 advanced-cluster-management.v2.6.3 Succeeded +---- ++ +[source,terminal] +---- +$ oc get csv -A | grep -i multicluster-engine +---- ++ +The following is example output: ++ +[source,terminal] +---- +multicluster-engine cluster-group-upgrades-operator.v0.0.3 cluster-group-upgrades-operator 0.0.3 Pending +multicluster-engine multicluster-engine.v2.1.4 multicluster engine for Kubernetes 2.1.4 multicluster-engine.v2.0.3 Succeeded +multicluster-engine openshift-gitops-operator.v1.5.7 Red Hat OpenShift GitOps 1.5.7 openshift-gitops-operator.v1.5.6-0.1664915551.p Succeeded +multicluster-engine openshift-pipelines-operator-rh.v1.6.4 Red Hat OpenShift Pipelines 1.6.4 openshift-pipelines-operator-rh.v1.6.3 Succeeded +---- + +. To access the container registry, copy a valid pull secret on the server to be installed: + +.. Create the `.docker` folder: ++ +[source,terminal] +---- +$ mkdir /root/.docker +---- + +.. Copy the valid pull in the `config.json` file to the previously created `.docker/` folder: ++ +[source,terminal] +---- +$ cp config.json /root/.docker/config.json +---- ++ +`/root/.docker/config.json` is the default path where `podman` checks for the login credentials for the registry. ++ +[NOTE] +==== +If you use a different registry to pull the required artifacts, you need to copy the proper pull secret. +If the local registry uses TLS, you need to include the certificates from the registry as well. +==== diff --git a/modules/ztp-precaching-troubleshooting.adoc b/modules/ztp-precaching-troubleshooting.adoc index 9d8346de3a72..c73f17eff1ab 100644 --- a/modules/ztp-precaching-troubleshooting.adoc +++ b/modules/ztp-precaching-troubleshooting.adoc @@ -6,6 +6,7 @@ [id="ztp-pre-staging-troubleshooting_{context}"] = Troubleshooting a "Rendered catalog is invalid" error +[role="_abstract"] When you download images by using a local or disconnected registry, you might see the `The rendered catalog is invalid` error. This means that you are missing certificates of the new registry you want to pull content from. [NOTE] @@ -13,7 +14,8 @@ When you download images by using a local or disconnected registry, you might se The {factory-prestaging-tool} image is built on a UBI {op-system-base} image. Certificate paths and locations are the same on {op-system}. ==== -.Example error +The following is an example of this error: + [source,terminal] ---- Generating list of pre-cached artifacts... diff --git a/modules/ztp-precaching-ztp-config.adoc b/modules/ztp-precaching-ztp-config.adoc index 91edebd43c72..46fdeabc8b5f 100644 --- a/modules/ztp-precaching-ztp-config.adoc +++ b/modules/ztp-precaching-ztp-config.adoc @@ -6,6 +6,7 @@ [id="ztp-pre-caching-config-con_{context}"] = Pre-caching images in {ztp} +[role="_abstract"] The `SiteConfig` manifest defines how an OpenShift cluster is to be installed and configured. In the {ztp-first} provisioning workflow, the {factory-prestaging-tool} requires the following additional fields in the `SiteConfig` manifest: @@ -15,7 +16,8 @@ In the {ztp-first} provisioning workflow, the {factory-prestaging-tool} requires include::snippets/siteconfig-deprecation-notice.adoc[] -.Example SiteConfig with additional fields +The following example shows a `SiteConfig` with the additional fields: + [source,yaml] ---- apiVersion: ran.openshift.io/v1 @@ -27,11 +29,11 @@ spec: baseDomain: "example.domain.redhat.com" pullSecretRef: name: "assisted-deployment-pull-secret" - clusterImageSetNameRef: "img4.9.10-x86-64-appsub" <1> + clusterImageSetNameRef: "img4.9.10-x86-64-appsub" sshPublicKey: "ssh-rsa ..." clusters: - clusterName: "sno-worker-0" - clusterImageSetNameRef: "eko4-img4.11.5-x86-64-appsub" <2> + clusterImageSetNameRef: "eko4-img4.11.5-x86-64-appsub" clusterLabels: group-du-sno: "" common-411: true @@ -155,8 +157,11 @@ spec: - name: "ens1f0" macAddress: "AA:BB:CC:11:22:33" ---- -<1> Specifies the cluster image set used for deployment, unless you specify a different image set in the `spec.clusters.clusterImageSetNameRef` field. -<2> Specifies the cluster image set used to deploy an individual cluster. If defined, it overrides the `spec.clusterImageSetNameRef` at the site level. + +Where: + +** `spec.clusterImageSetNameRef` specifies the cluster image set used for deployment, unless you specify a different image set in the `spec.clusters.clusterImageSetNameRef` field. +** `spec.clusters.clusterImageSetNameRef` specifies the cluster image set used to deploy an individual cluster. If defined, it overrides the `spec.clusterImageSetNameRef` at the site level. [id="ztp-pre-caching-config-clusters-ignitionconfigoverride_{context}"] == Understanding the clusters.ignitionConfigOverride field