From 938b8f71b9d96408597c4f4d254c88d9cbddda0e Mon Sep 17 00:00:00 2001 From: Sebastian Kopacz Date: Tue, 4 Aug 2026 15:01:21 -0400 Subject: [PATCH] OSDOCS-17058: mirroring content CQA --- .../about-installing-oc-mirror-v2.adoc | 32 +++-------- .../installing-mirroring-disconnected.adoc | 54 +++++++------------ ...talling-mirroring-installation-images.adoc | 4 +- .../oc-mirror-migration-v1-to-v2.adoc | 3 +- ...nstalling-mirroring-disconnected-full.adoc | 6 +++ ...ring-disconnected-mirroring-image-set.adoc | 8 +++ ...alling-mirroring-disconnected-partial.adoc | 6 +++ ...irroring-disconnected-preparing-hosts.adoc | 10 ++++ ...-mirroring-disconnected-prerequisites.adoc | 17 ++++++ modules/oc-mirror-v2-mirroring-image-set.adoc | 6 +++ modules/oc-mirror-v2-prerequisites.adoc | 23 ++++++++ 11 files changed, 107 insertions(+), 62 deletions(-) create mode 100644 modules/installing-mirroring-disconnected-full.adoc create mode 100644 modules/installing-mirroring-disconnected-mirroring-image-set.adoc create mode 100644 modules/installing-mirroring-disconnected-partial.adoc create mode 100644 modules/installing-mirroring-disconnected-preparing-hosts.adoc create mode 100644 modules/installing-mirroring-disconnected-prerequisites.adoc create mode 100644 modules/oc-mirror-v2-mirroring-image-set.adoc create mode 100644 modules/oc-mirror-v2-prerequisites.adoc diff --git a/disconnected/about-installing-oc-mirror-v2.adoc b/disconnected/about-installing-oc-mirror-v2.adoc index 43a71878d168..171372469d6f 100644 --- a/disconnected/about-installing-oc-mirror-v2.adoc +++ b/disconnected/about-installing-oc-mirror-v2.adoc @@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] You can run your cluster in a disconnected environment if you install the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever your cluster is running. You can use oc-mirror plugin v2 to mirror images to a mirror registry in your fully or partially disconnected environments. To download the required images from the official Red{nbsp}Hat registries, you must run oc-mirror plugin v2 from a system with internet connectivity. @@ -16,19 +17,7 @@ include::modules/oc-mirror-v2-about.adoc[leveloffset=+1] // oc-mirror compatibility and support include::modules/oc-mirror-v2-support.adoc[leveloffset=+2] -[id="prerequisites_oc-mirror-v2_{context}"] -== Prerequisites - -* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker V2-2] in the location that hosts the {product-title} cluster, such as {quay}. -+ -[NOTE] -==== -* If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red{nbsp}Hat Quay Operator on {product-title} (Red{nbsp}Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red{nbsp}Hat Support. - -* If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red{nbsp}Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations. -==== - -* Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation, might fail. Mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters. +include::modules/oc-mirror-v2-prerequisites.adoc[leveloffset=+1] //Preparing your mirror hosts include::modules/oc-mirror-preparing-mirror-hosts.adoc[leveloffset=+1] @@ -39,10 +28,8 @@ include::modules/oc-mirror-installing-plugin.adoc[leveloffset=+2] //Configuring credentials that enable image mirroring include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2] -[id="using-oc-mirror_{context}"] -== Mirroring an image set to a mirror registry - -Mirroring an image set to a mirror registry ensures that the required images are available in a secure and controlled environment, facilitating smoother deployments, updates, and maintenance tasks. +// Mirroring an image set to a mirror registry +include::modules/oc-mirror-v2-mirroring-image-set.adoc[leveloffset=+1] //Creating the image set configuration include::modules/oc-mirror-building-image-set-config-v2.adoc[leveloffset=+2] @@ -84,8 +71,6 @@ include::modules/oc-mirror-restricted-fields.adoc[leveloffset=+2] // Configuring your cluster to use the resources generated by oc-mirror include::modules/oc-mirror-updating-cluster-manifests-v2.adoc[leveloffset=+2] -After your cluster is configured to use the resources generated by oc-mirror plugin v2, see xref:../disconnected/about-installing-oc-mirror-v2.adoc#next-steps_about-installing-oc-mirror-v2[Next steps] for information about tasks that you can perform using your mirrored images. - [role="_additional-resources"] .Additional resources @@ -152,13 +137,8 @@ include::modules/oc-mirror-command-reference-v2-delete.adoc[leveloffset=+2] include::modules/oc-mirror-about-cache-and-workspace-dirs.adoc[leveloffset=+2] [role="_additional-resources"] -.Additional resources -* xref:../disconnected/about-installing-oc-mirror-v2.adoc#oc-mirror-updating-cluster-manifests-v2_about-installing-oc-mirror-v2[Configuring your cluster to use the resources generated by oc-mirror] - -[id="next-steps_{context}"] -== Next steps - -After you mirror images to your disconnected environment using oc-mirror plugin v2, you can perform any of the following actions: +[id="additional-resources_{context}"] +== Additional resources * xref:../disconnected/installing.adoc#installing-disconnected-environments[Installing a cluster in a disconnected environment] * xref:../disconnected/using-olm.adoc#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments] diff --git a/disconnected/installing-mirroring-disconnected.adoc b/disconnected/installing-mirroring-disconnected.adoc index 0818ba28f12f..524a67179208 100644 --- a/disconnected/installing-mirroring-disconnected.adoc +++ b/disconnected/installing-mirroring-disconnected.adoc @@ -6,13 +6,16 @@ include::_attributes/common-attributes.adoc[] toc::[] -Running your cluster in a restricted network without direct internet connectivity is possible by installing the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running at all times as long as the cluster is running. See the xref:../disconnected/installing-mirroring-disconnected.adoc#prerequisites_installing-mirroring-disconnected[Prerequisites] section for more information. +[role="_abstract"] +You can run your cluster in a restricted network by installing from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever the cluster is running. You can use the oc-mirror OpenShift CLI (`oc`) plugin to mirror images to a mirror registry in your fully or partially disconnected environments. You must run oc-mirror from a system with internet connectivity in order to download the required images from the official Red Hat registries. [IMPORTANT] ==== -The oc-mirror v1 plugin is deprecated. Specify the `--v1` flag to continue using the v1 plugin, or migrate to the supported v2 plugin and use the `--v2` flag. Transition to the xref:../disconnected/about-installing-oc-mirror-v2.adoc#installation-oc-mirror-v2-about_about-installing-oc-mirror-v2[oc-mirror v2 plugin] for continued support and improvements. +The oc-mirror v1 plugin is deprecated. Specify the `--v1` flag to continue using the v1 plugin, or migrate to the supported v2 plugin and use the `--v2` flag. Transition to the oc-mirror v2 plugin for continued support and improvements. + +For more information, see "Mirroring images for a disconnected installation" using oc-mirror plugin v2. ==== // About the oc-mirror plugin @@ -24,7 +27,7 @@ include::modules/oc-mirror-support.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* For information on updating oc-mirror, see xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source]. +* xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source] // About the mirror registry include::modules/installation-about-mirror-registry.adoc[leveloffset=+1] @@ -32,24 +35,13 @@ include::modules/installation-about-mirror-registry.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source]. - -[id="prerequisites_installing-mirroring-disconnected"] -== Prerequisites - -* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2] in the location that will host the {product-title} cluster, such as {quay}. -+ -[NOTE] -==== -If you use {quay}, you must use version 3.6 or later with the oc-mirror plugin. If you have an entitlement to {quay}, see the documentation on deploying {quay} link:https://docs.redhat.com/en/documentation/red_hat_quay/3/html/proof_of_concept_-_deploying_red_hat_quay/index[for proof-of-concept purposes] or link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[by using the {quay} Operator]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support. -==== -+ -If you do not already have an existing solution for a container image registry, subscribers of {product-title} are provided a xref:../disconnected/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[mirror registry for Red Hat OpenShift]. The _mirror registry for Red{nbsp}Hat OpenShift_ is included with your subscription and is a small-scale container registry that can be used to mirror the required container images of {product-title} in disconnected installations. +* xref:../installing/validation_and_troubleshooting/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source] -[id="mirroring-preparing-your-hosts"] -== Preparing your mirror hosts +// Prerequisites +include::modules/installing-mirroring-disconnected-prerequisites.adoc[leveloffset=+1] -Before you can use the oc-mirror plugin to mirror images, you must install the plugin and create a container image registry credentials file to allow the mirroring from Red Hat to your mirror. +// Preparing your mirror hosts +include::modules/installing-mirroring-disconnected-preparing-hosts.adoc[leveloffset=+1] // Installing the oc-mirror OpenShift CLI plugin include::modules/oc-mirror-installing-plugin.adoc[leveloffset=+2] @@ -72,25 +64,17 @@ include::modules/oc-mirror-creating-image-set-config.adoc[leveloffset=+1] * xref:../disconnected/installing-mirroring-disconnected.adoc#oc-mirror-image-set-examples_installing-mirroring-disconnected[Image set configuration examples] * xref:../disconnected/updating/disconnected-update-osus.adoc#updating-disconnected-cluster-osus[Using the OpenShift Update Service in a disconnected environment] -[id="mirroring-image-set"] -== Mirroring an image set to a mirror registry +// Mirroring an image set to a mirror registry +include::modules/installing-mirroring-disconnected-mirroring-image-set.adoc[leveloffset=+1] -You can use the oc-mirror CLI plugin to mirror images to a mirror registry in a xref:../disconnected/installing-mirroring-disconnected.adoc#mirroring-image-set-partial[partially disconnected environment] or in a xref:../disconnected/installing-mirroring-disconnected.adoc#mirroring-image-set-full[fully disconnected environment]. - -These procedures assume that you already have your mirror registry set up. - -[id="mirroring-image-set-partial"] -=== Mirroring an image set in a partially disconnected environment - -In a partially disconnected environment, you can mirror an image set directly to the target mirror registry. +// Mirroring an image set in a partially disconnected environment +include::modules/installing-mirroring-disconnected-partial.adoc[leveloffset=+2] // Mirroring from mirror to mirror include::modules/oc-mirror-mirror-to-mirror.adoc[leveloffset=+3] -[id="mirroring-image-set-full"] -=== Mirroring an image set in a fully disconnected environment - -To mirror an image set in a fully disconnected environment, you must first xref:../disconnected/installing-mirroring-disconnected.adoc#oc-mirror-mirror-to-disk_installing-mirroring-disconnected[mirror the image set to disk], then xref:../disconnected/installing-mirroring-disconnected.adoc#oc-mirror-disk-to-mirror_installing-mirroring-disconnected[mirror the image set file on disk to a mirror]. +// Mirroring an image set in a partially disconnected environment +include::modules/installing-mirroring-disconnected-full.adoc[leveloffset=+2] // Mirroring from mirror to disk include::modules/oc-mirror-mirror-to-disk.adoc[leveloffset=+3] @@ -104,7 +88,7 @@ include::modules/oc-mirror-updating-cluster-manifests.adoc[leveloffset=+1] [role="_additional-resources"] .Additional resources -* xref:../extensions/catalogs/managing-catalogs.adoc#olmv1-adding-a-catalog-to-a-cluster_managing-catalogs[Adding a catalog to a cluster] in "Extensions" +* xref:../extensions/catalogs/managing-catalogs.adoc#olmv1-adding-a-catalog-to-a-cluster_managing-catalogs[Adding a catalog to a cluster] // About updating your mirror registry content include::modules/oc-mirror-updating-registry-about.adoc[leveloffset=+1] @@ -144,4 +128,6 @@ include::modules/oc-mirror-command-reference.adoc[leveloffset=+1] [id="additional-resources_installing-mirroring-disconnected"] == Additional resources +* xref:../disconnected/about-installing-oc-mirror-v2.adoc#about-installing-oc-mirror-v2[Mirroring images for a disconnected installation using oc-mirror plugin v2] + * xref:../disconnected/updating/index.adoc#about-disconnected-updates[About cluster updates in a disconnected environment] diff --git a/disconnected/installing-mirroring-installation-images.adoc b/disconnected/installing-mirroring-installation-images.adoc index 5468f491f332..0ddec96e5bc7 100644 --- a/disconnected/installing-mirroring-installation-images.adoc +++ b/disconnected/installing-mirroring-installation-images.adoc @@ -7,7 +7,9 @@ include::_attributes/common-attributes.adoc[] toc::[] [role="_abstract"] -You can ensure your clusters only use container images that satisfy your organizational controls on external content. Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. By using the `oc adm` command, you can mirror release and catalog images in OpenShift. To mirror container images, you must have a registry for mirroring. +You can ensure your clusters only use container images that satisfy your organizational controls on external content. Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. + +By using the `oc adm` command, you can mirror release and catalog images in OpenShift. To mirror container images, you must have a registry for mirroring. // Note to CQA assignee: this deprecation notice is in 4.22+ docs, this should not be backported to 4.20 and 4.21 docs while cherry picking CQAs. diff --git a/disconnected/oc-mirror-migration-v1-to-v2.adoc b/disconnected/oc-mirror-migration-v1-to-v2.adoc index a2d5092f2926..456145e524d7 100644 --- a/disconnected/oc-mirror-migration-v1-to-v2.adoc +++ b/disconnected/oc-mirror-migration-v1-to-v2.adoc @@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[] toc::[] -The oc-mirror v2 plugin introduces major changes to image mirroring workflows. This guide provides step-by-step instructions for migration while ensuring compatibility with oc-mirror plugin v2. +[role="_abstract"] +The oc-mirror v2 plugin introduces major changes to image mirroring workflows. Understand the migration process and check for compatibility with oc-mirror plugin v2 to ensure a successful migration. [IMPORTANT] ==== diff --git a/modules/installing-mirroring-disconnected-full.adoc b/modules/installing-mirroring-disconnected-full.adoc new file mode 100644 index 000000000000..df9c3215c972 --- /dev/null +++ b/modules/installing-mirroring-disconnected-full.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT +[id="mirroring-image-set-full"] += Mirroring an image set in a fully disconnected environment + +[role="_abstract"] +To mirror an image set in a fully disconnected environment, you must first mirror the image set to a disk, then mirror the image set file on the disk to a mirror. \ No newline at end of file diff --git a/modules/installing-mirroring-disconnected-mirroring-image-set.adoc b/modules/installing-mirroring-disconnected-mirroring-image-set.adoc new file mode 100644 index 000000000000..b3e701c5ad63 --- /dev/null +++ b/modules/installing-mirroring-disconnected-mirroring-image-set.adoc @@ -0,0 +1,8 @@ +:_mod-docs-content-type: CONCEPT +[id="mirroring-image-set"] += Mirroring an image set to a mirror registry + +[role="_abstract"] +You can use the oc-mirror CLI plugin to mirror images to a mirror registry in a partially disconnected environment or in a fully disconnected environment. + +These procedures assume that you already have your mirror registry set up. \ No newline at end of file diff --git a/modules/installing-mirroring-disconnected-partial.adoc b/modules/installing-mirroring-disconnected-partial.adoc new file mode 100644 index 000000000000..60f0ebc1f960 --- /dev/null +++ b/modules/installing-mirroring-disconnected-partial.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT +[id="mirroring-image-set-partial"] += Mirroring an image set in a partially disconnected environment + +[role="_abstract"] +In a partially disconnected environment, you can mirror an image set directly to the target mirror registry. \ No newline at end of file diff --git a/modules/installing-mirroring-disconnected-preparing-hosts.adoc b/modules/installing-mirroring-disconnected-preparing-hosts.adoc new file mode 100644 index 000000000000..ba0cae674fa9 --- /dev/null +++ b/modules/installing-mirroring-disconnected-preparing-hosts.adoc @@ -0,0 +1,10 @@ +// Module included in the following assemblies: +// +// * disconnected/about-installing-oc-mirror-v2.adoc + +:_mod-docs-content-type: CONCEPT +[id="mirroring-preparing-your-hosts"] += Preparing your mirror hosts + +[role="_abstract"] +Before you can use the oc-mirror plugin to mirror images, you must install the plugin and create a container image registry credentials file to allow the mirroring from Red Hat to your mirror. \ No newline at end of file diff --git a/modules/installing-mirroring-disconnected-prerequisites.adoc b/modules/installing-mirroring-disconnected-prerequisites.adoc new file mode 100644 index 000000000000..40fdfb4cbe0c --- /dev/null +++ b/modules/installing-mirroring-disconnected-prerequisites.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: REFERENCE +[id="prerequisites_installing-mirroring-disconnected"] += Prerequisites + +[role="_abstract"] +Before you can mirror images using the oc-mirror plugin, you must meet several prerequisites. + +The following prerequisites must be met: + +* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2] in the location that will host the {product-title} cluster, such as {quay}. ++ +[NOTE] +==== +If you use {quay}, you must use version 3.6 or later with the oc-mirror plugin. If you have an entitlement to {quay}, see the documentation on deploying {quay} link:https://docs.redhat.com/en/documentation/red_hat_quay/3/html/proof_of_concept_-_deploying_red_hat_quay/index[for proof-of-concept purposes] or link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[by using the {quay} Operator]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support. +==== ++ +If you do not already have an existing solution for a container image registry, subscribers of {product-title} are provided a xref:../disconnected/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[mirror registry for Red Hat OpenShift]. The _mirror registry for Red{nbsp}Hat OpenShift_ is included with your subscription and is a small-scale container registry that can be used to mirror the required container images of {product-title} in disconnected installations. \ No newline at end of file diff --git a/modules/oc-mirror-v2-mirroring-image-set.adoc b/modules/oc-mirror-v2-mirroring-image-set.adoc new file mode 100644 index 000000000000..cbcc77833fcd --- /dev/null +++ b/modules/oc-mirror-v2-mirroring-image-set.adoc @@ -0,0 +1,6 @@ +:_mod-docs-content-type: CONCEPT +[id="using-oc-mirror_{context}"] += Mirroring an image set to a mirror registry + +[role="_abstract"] +Mirroring an image set to a mirror registry ensures that the required images are available in a secure and controlled environment, facilitating smoother deployments, updates, and maintenance tasks. \ No newline at end of file diff --git a/modules/oc-mirror-v2-prerequisites.adoc b/modules/oc-mirror-v2-prerequisites.adoc new file mode 100644 index 000000000000..812ef764d2a4 --- /dev/null +++ b/modules/oc-mirror-v2-prerequisites.adoc @@ -0,0 +1,23 @@ +// Module included in the following assemblies: +// +// * disconnected/about-installing-oc-mirror-v2.adoc + +:_mod-docs-content-type: REFERENCE +[id="prerequisites_oc-mirror-v2_{context}"] += Prerequisites + +[role="_abstract"] +Before you can mirror images with the oc-mirror plugin v2, you must meet several prerequisites. + +The following prerequisites must be met: + +* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker V2-2] in the location that hosts the {product-title} cluster, such as {quay}. ++ +[NOTE] +==== +* If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red{nbsp}Hat Quay Operator on {product-title} (Red{nbsp}Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red{nbsp}Hat Support. + +* If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red{nbsp}Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations. +==== + +* Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation, might fail. Mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters. \ No newline at end of file