TELCODOCS-2762: Apply DITA formatting and split downloading module for enterprise-4.20

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]

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:
 

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
+----