From 9d4b9c588ddd08d25ea277d00636297d24f5fa72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9CShauna=20Diaz=E2=80=9D?= Date: Mon, 4 Aug 2025 07:56:03 -0400 Subject: [PATCH] OSDOCS-13626: updates oc mirror to v2 --- ...hift-operators-oc-mirror-disconnected.adoc | 3 +- .../microshift-operators-oc-mirror.adoc | 62 ++++++------- .../microshift-operators-olm.adoc | 4 +- modules/microshift-oc-mirror-about-con.adoc | 32 +------ .../microshift-oc-mirror-connectivity.adoc | 25 ++++++ ...ft-oc-mirror-creating-imageset-config.adoc | 89 ++++++------------- modules/microshift-oc-mirror-dry-run.adoc | 65 ++++++++++++++ ...-oc-mirror-embed-ops-disconnected-use.adoc | 72 ++++++++------- ...ift-oc-mirror-install-catalog-cluster.adoc | 52 ++++++----- ...icroshift-oc-mirror-list-ops-catalogs.adoc | 22 ++--- modules/microshift-oc-mirror-to-mirror.adoc | 59 ++++++++++++ ...-oc-mirror-transform-imageset-to-crio.adoc | 41 ++++----- modules/microshift-olm-rh-ops-mirror.adoc | 14 +++ modules/oc-mirror-dry-run.adoc | 1 - ...-mirror-imageset-config-parameters-v2.adoc | 20 +++-- modules/oc-mirror-imageset-config-params.adoc | 10 +-- modules/oc-mirror-mirror-to-mirror.adoc | 29 +----- 17 files changed, 342 insertions(+), 258 deletions(-) create mode 100644 modules/microshift-oc-mirror-connectivity.adoc create mode 100644 modules/microshift-oc-mirror-dry-run.adoc create mode 100644 modules/microshift-oc-mirror-to-mirror.adoc create mode 100644 modules/microshift-olm-rh-ops-mirror.adoc diff --git a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc index 0ea06d98129a..b63f55017d6e 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror-disconnected.adoc @@ -18,8 +18,7 @@ include::modules/microshift-olm-deploy-op-disconnected-con.adoc[leveloffset=+1] * xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use] * xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-networking-disconnected-hosts[Configuring network settings for fully disconnected hosts] -//OCP module, edit with conditionals and care -include::modules/oc-mirror-dry-run.adoc[leveloffset=+2] +include::modules/microshift-oc-mirror-dry-run.adoc[leveloffset=+2] include::modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc[leveloffset=+2] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc index e0b29647c833..a18c7b7c4983 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc @@ -1,57 +1,49 @@ :_mod-docs-content-type: ASSEMBLY [id="microshift-operators-oc-mirror"] -= Creating custom catalogs using the oc-mirror plugin += Creating custom Operator catalogs using the oc-mirror plugin include::_attributes/attributes-microshift.adoc[] :context: microshift-operators-oc-mirror toc::[] -You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror OpenShift CLI (oc) plugin. +You can create custom catalogs with widely available Operators and mirror them by using the oc-mirror {oc-first} plugin. -[id="microshift-olm-red-hat-ops-mirror_{context}"] -== Using Red Hat-provided Operator catalogs and mirror registries -You can filter and prune catalogs to get specific Operators and mirror them by using the oc-mirror OpenShift CLI (oc) plugin. You can also use Operators in disconnected settings or embedded in {op-system-ostree-first} images. To read more details about how to configure your systems for mirroring, use the links in the following "Additional resources" section. If you are ready to deploy Operators from Red Hat-provided Operator catalogs, mirror them, or to embed them in {op-system-ostree} images, start with the following section, "Inspecting catalog contents by using the oc-mirror plugin." - -//additional resources for deploying operators in disconnected environments -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager on restricted networks] -* xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access] -* xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] -* xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-get-mirror-reg-container-image-list_microshift-deploy-with-mirror-registry[Getting the mirror registry container image list] -* xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-in-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use] +include::modules/microshift-olm-rh-ops-mirror.adoc[leveloffset=+1] include::modules/microshift-oc-mirror-about-con.adoc[leveloffset=+1] -//additional resources for preqeq to using oc mirror -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#prerequisites_installing-mirroring-disconnected[Installing the oc mirror plugin] +include::modules/microshift-oc-mirror-connectivity.adoc[leveloffset=+2] -include::modules/microshift-oc-mirror-list-ops-catalogs.adoc[leveloffset=+2] +include::modules/microshift-oc-mirror-list-ops-catalogs.adoc[leveloffset=+1] //First, make the image sets -include::modules/microshift-oc-mirror-creating-imageset-config.adoc[leveloffset=+2] +include::modules/microshift-oc-mirror-creating-imageset-config.adoc[leveloffset=+1] //OCP module, reference for valid imageset parameters for microshift; see conditionals -include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+3] +include::modules/oc-mirror-imageset-config-parameters-v2.adoc[leveloffset=+2] -//additional resources for creating image sets -[role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#oc-mirror-image-set-examples_installing-mirroring-disconnected[Imageset configuration examples] +//mirroring from mirror to mirror +include::modules/microshift-oc-mirror-to-mirror.adoc[leveloffset=+1] -// OCP module, mirroring from mirror to mirror -include::modules/oc-mirror-mirror-to-mirror.adoc[leveloffset=+2] +//Convert the imageset file and add configuration to CRI-O +include::modules/microshift-oc-mirror-transform-imageset-to-crio.adoc[leveloffset=+1] -//additional resources for microshift mirror to mirror module +//Apply changes to cluster so it can use Operators +include::modules/microshift-oc-mirror-install-catalog-cluster.adoc[leveloffset=+1] + +[id="Additional-resources_microshift-operators-oc-mirror_{context}"] [role="_additional-resources"] -.Additional resources -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#mirroring-image-set-partial[Mirroring an image set in a partially disconnected environment] -* link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/installing/disconnected-installation-mirroring#mirroring-image-set-full[Mirroring an image set in a fully disconnected environment] +== Additional resources -//Convert the imageset file and add configuration to CRI-O -include::modules/microshift-oc-mirror-transform-imageset-to-crio.adoc[leveloffset=+2] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/disconnected_environments/mirroring-in-disconnected-environments#installation-oc-mirror-installing-plugin_about-installing-oc-mirror-v2[Installing the oc mirror plugin] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/disconnected_environments/mirroring-in-disconnected-environments#oc-mirror-migration-v1-to-v2[Migrating from oc-mirror plugin v1 to v2] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/disconnected_environments/mirroring-in-disconnected-environments#oc-mirror-custom-resources-v2_about-installing-oc-mirror-v2[About custom resources generated by oc-mirror plugin v2] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/disconnected_environments/mirroring-in-disconnected-environments#oc-mirror-about-cache-and-workspace-dirs_about-installing-oc-mirror-v2[About the --cache-dir and --workspace flags] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/operators/administrator-tasks#olm-restricted-networks[Using Operator Lifecycle Manager in disconnected environments] +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/disconnected_environments/mirroring-in-disconnected-environments#oc-mirror-procedure-delete-v2_about-installing-oc-mirror-v2[Deleting images from a disconnected environment] -//Apply changes to cluster so it can use Operators -include::modules/microshift-oc-mirror-install-catalog-cluster.adoc[leveloffset=+2] \ No newline at end of file +{microshift-short} links:: +* xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-configuring-hosts-for-mirror_microshift-deployment-mirror[Configuring hosts for mirror registry access] +* xref:../../microshift_networking/microshift-disconnected-network-config.adoc#microshift-disconnected-network-config[Configuring network settings for fully disconnected hosts] +* xref:../../microshift_install_get_ready/microshift-deploy-with-mirror-registry.adoc#microshift-deploy-with-mirror-registry[Mirroring container images for disconnected installations] +* xref:../../microshift_install_rpm_ostree/microshift-embed-in-rpm-ostree-offline-use.adoc#microshift-embed-in-rpm-ostree-offline-use[Embedding in a {op-system-ostree} image for offline use] diff --git a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc index a92358e67c19..d45d5e383808 100644 --- a/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +++ b/microshift_running_apps/microshift_operators/microshift-operators-olm.adoc @@ -6,7 +6,9 @@ include::_attributes/attributes-microshift.adoc[] toc::[] -The Operator Lifecycle Manager (OLM) package manager is used in {microshift-short} for installing and running optional link:https://access.redhat.com/documentation/en-us/openshift_container_platform/{ocp-version}/html/architecture/control-plane#olm-operators_control-plane[add-on Operators]. +Operator Lifecycle Manager (OLM) is used in {microshift-short} for installing and running optional add-on Operators. See the following link for more information: + +* link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/operators/understanding-operators#operator-lifecycle-manager-olm[Operator Lifecycle Manager] [id="microshift-olm-considerations_{context}"] == Considerations for using OLM with {microshift-short} diff --git a/modules/microshift-oc-mirror-about-con.adoc b/modules/microshift-oc-mirror-about-con.adoc index 7c27f59e3ec4..72c325c0cfbf 100644 --- a/modules/microshift-oc-mirror-about-con.adoc +++ b/modules/microshift-oc-mirror-about-con.adoc @@ -1,37 +1,11 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: CONCEPT [id="microshift-using-oc-mirror_{context}"] = About the oc-mirror plugin for creating a mirror registry -You can use the oc-mirror OpenShift CLI (oc) plugin with {microshift-short} to filter and prune Operator catalogs. You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments with {op-system-ostree}. +You can use the oc-mirror OpenShift CLI (oc) plugin with {microshift-short} to filter and delete images from Operator catalogs. You can then mirror the filtered catalog contents to a mirror registry or use the container images in disconnected or offline deployments. -[NOTE] -==== -{microshift-short} uses the generally available version (1) of the oc-mirror plugin. Do not use the following procedures with the Technical Preview version (2) of oc-mirror plugin. -==== - -You can mirror the container images required by the desired Operators locally or to a container mirror registry that supports link:https://docs.docker.com/registry/[Docker v2-2], such as {quay}. The procedure to mirror content from Red Hat-hosted registries connected to the internet to a disconnected image registry is the same, independent of the registry you choose. After you mirror the contents of your catalog, configure each cluster to retrieve this content from your mirror registry. - -[id="microshift-populate-mirror-registry-connectivity_{context}"] -== Connectivity considerations when populating a mirror registry - -When you populate your registry, you can use one of following connectivity scenarios: - -Connected mirroring:: -If you have a host that can access both the internet and your mirror registry, but not your cluster node, you can directly mirror the content from that machine. - -Disconnected mirroring:: -If you do not have a host that can access both the internet and your mirror registry, you must mirror the images to a file system and then bring that host or removable media into your disconnected environment. -+ -[IMPORTANT] -==== -A container registry must be reachable by every machine in the clusters that you provision. Installing, updating, and other operations, such as relocating workloads, might fail if the registry is unreachable. -==== - -To avoid problems caused by an unreachable registry, use the following standard practices: - -* Run mirror registries in a highly available way. -* Ensure that the mirror registry at least matches the production availability of your clusters. \ No newline at end of file +The procedure to mirror content from Red Hat-hosted registries connected to the internet to a disconnected image registry is the same, independent of the registry you select. After you mirror the contents of your catalog, configure each cluster to retrieve this content from your mirror registry. diff --git a/modules/microshift-oc-mirror-connectivity.adoc b/modules/microshift-oc-mirror-connectivity.adoc new file mode 100644 index 000000000000..89b827d1f8f9 --- /dev/null +++ b/modules/microshift-oc-mirror-connectivity.adoc @@ -0,0 +1,25 @@ +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-connectivity-considerations_{context}"] += Connectivity considerations when populating a mirror registry + +When you populate your registry, you can use one of following connectivity scenarios: + +Connected mirroring:: +If you have a host that can access both the internet and your mirror registry, but not your cluster node, you can directly mirror the content from that machine. + +Disconnected mirroring:: +If you do not have a host that can access both the internet and your mirror registry, you must mirror the images to a file system and then bring that host or removable media into your disconnected environment. ++ +[IMPORTANT] +==== +A container registry must be reachable by every machine in the cluster that you provision. Installing, updating, and other operations, such as relocating workloads, fail if the registry is unreachable. +==== + +To avoid problems caused by an unreachable registry, use the following standard practices: + +* Run mirror registries in a highly available way. +* Ensure that the mirror registry at least matches the production availability of your clusters. diff --git a/modules/microshift-oc-mirror-creating-imageset-config.adoc b/modules/microshift-oc-mirror-creating-imageset-config.adoc index 56e3c61877f8..aa84c2f4341b 100644 --- a/modules/microshift-oc-mirror-creating-imageset-config.adoc +++ b/modules/microshift-oc-mirror-creating-imageset-config.adoc @@ -1,92 +1,59 @@ // Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-creating-imageset-config_{context}"] = Creating an image set configuration file -You must create an image set configuration file to mirror catalog contents with the oc-mirror plugin. The image set configuration file defines which Operators to mirror along with other configuration settings for the oc-mirror plugin. After generating a default image set file, you must edit the contents so that remaining entries are compatible with both {microshift-short} and the Operator you plan to use. +You must create an `ImageSetConfiguration` YAML file. This image set configuration file specifies both the Operators to mirror and the configuration settings for the oc-mirror plugin. Edit the contents of the image set configuration file so that the entries are compatible with both {microshift-short} and the Operator you plan to use. -You must specify a storage backend in the image set configuration file. This storage backend can be a local directory or a registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker v2-2]. The oc-mirror plugin stores metadata in this storage backend during image set creation. - -[IMPORTANT] +[NOTE] ==== -Do not delete or modify the metadata that is generated by the oc-mirror plugin. You must use the same storage backend every time you run the oc-mirror plugin for the same mirror registry. +oc mirror v2 uses a cache system instead of metadata. The cache system prevents the need to start the entire mirroring process over when a single step fails. Instead, you can troubleshoot the failed step and the process does not re-mirror images that existed before the failure. ==== .Prerequisites -* You have created a container image registry credentials file. See link:https://docs.openshift.com/container-platform/{ocp-version}/installing/disconnected_install/installing-mirroring-disconnected.html#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored]. +* You created a container image registry credentials file. For more information, see the following reference: -.Procedure +** link:https://docs.redhat.com/en/documentation/openshift_container_platform/4.19/html/disconnected_environments/mirroring-in-disconnected-environments#installation-adding-registry-pull-secret_installing-mirroring-disconnected[Configuring credentials that allow images to be mirrored] -. Use the `oc mirror init` command to create a template for the image set configuration and save it to a file called `imageset-config.yaml`: -+ --- -[source,terminal] ----- -$ oc mirror init --registry > imageset-config.yaml <1> ----- -<1> Specifies the location of your storage backend, such as `example.com/mirror/oc-mirror-metadata`. --- -+ -.Example default image set configuration file -[source,yaml] ----- -kind: ImageSetConfiguration -apiVersion: mirror.openshift.io/v1alpha2 -storageConfig: - registry: - imageURL: registry.example.com/oc-mirror - skipTLS: false -mirror: - platform: # <1> - channels: - - name: stable-4.20 - type: ocp - operators: - - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.20 - packages: - - name: serverless-operator - channels: - - name: stable - additionalImages: # <2> - - name: registry.redhat.io/ubi8/ubi:latest - helm: {} # <3> ----- -<1> The `platform` field and related fields are not supported by {microshift-short} and must be deleted. -<2> Specify any additional images to include in the image set. If you do not need to specify additional images, delete this field. -<3> Helm is not supported by {microshift-short} and must be deleted. +.Procedure -. Edit the values of your image set configuration file to meet the requirements of both {microshift-short} and the Operator you want to mirror, like the following example: +. Create and edit the `ImageSetConfiguration` YAML for {microshift-short} by using the following example as a guide: + .Example edited {microshift-short} image set configuration file [source,yaml,subs="attributes+"] ---- kind: ImageSetConfiguration -apiVersion: mirror.openshift.io/v1alpha2 -storageConfig: <1> - registry: - imageURL: <2> - skipTLS: false +apiVersion: mirror.openshift.io/v2alpha1 mirror: operators: - - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.20 <3> + - catalog: registry.redhat.io/redhat/redhat-operator-index:v{ocp-version} <1> packages: - - name: amq-broker-rhel8 <4> + - name: amq-broker-rhel9 <2> channels: - - name: 7.11.x <5> + - name: 7.13.x <3> + additionalImages: <4> + - name: quay.io/rh_ee_aguidi/multi-platform-container:latest + - name: quay.io/rh_ee_aguidi/empty-image:latest ---- -<1> Set the backend location where the image set metadata is saved. This location can be a registry or local directory. It is required to specify `storageConfig` values. -<2> Set the registry URL for the storage backend, such as ` Set the Operator catalog to retrieve images from. -<4> Specify the Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog. -<5> Specify only certain channels of the Operator packages to include in the image set. You must always include the default channel for the Operator package even if you do not use the bundles in that channel. You can find the default channel by running the following command: `oc mirror list operators --catalog= --package=`. +<1> Set the Operator catalog to retrieve images from. +<2> Specify the Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog. +<3> Specify only certain channels of the Operator packages to include in the image set. You must always include the default channel for the Operator package even if you do not use the bundles in that channel. You can find the default channel by running the following command: `oc mirror list operators --catalog= --package=`. +<4> Specify any additional images to include in the image set. If you do not need to specify additional images, delete this field. ++ +-- +[IMPORTANT] +==== +The `platform` field, related fields, and Helm are not supported by {microshift-short}. +==== +-- -. Save the updated file. +. Save the updated file as `ImageSetConfiguration.yaml`. .Next steps * Use the oc-mirror plugin to mirror an image set directly to a target mirror registry. * Configure CRI-O. -* Apply the catalog sources to your clusters. \ No newline at end of file +* Apply the catalog sources to your clusters. diff --git a/modules/microshift-oc-mirror-dry-run.adoc b/modules/microshift-oc-mirror-dry-run.adoc new file mode 100644 index 000000000000..16d3574c8e63 --- /dev/null +++ b/modules/microshift-oc-mirror-dry-run.adoc @@ -0,0 +1,65 @@ +// Module included in the following assemblies: +// +// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-oc-mirror-dry-run_{context}"] += Performing a dry run + +You can use oc-mirror to perform a dry run, without actually mirroring any images. A dry run means you can review the list of images to be mirrored. You can catch any errors with your image set configuration early by using a dry run, or use the generated list of images with other tools to conduct mirroring. + +.Prerequisites + +* You have access to the internet to obtain the necessary container images. +* You installed the {oc-first}. +* You installed the oc-mirror CLI plugin. +* You created the image set configuration file. + +.Procedure + +. Run the `oc mirror` command with the `--dry-run` flag to perform a dry run: ++ +[source,terminal,subs="+quotes"] +---- +$ oc-mirror --config __ docker://localhost:5000 --workspace file://__ --dry-run --v2 +---- +where: + +`ImageSetConfig.yaml`:: Specifies the name of the image set configuration file that you created. +`docker://localhost:5000`:: Specifies the mirror registry. Nothing is mirrored to this registry when you use the `--dry-run` flag. +`--workspace file://__`:: Insert the address of the workspace path. +`--dry-run`:: The dry run flag generates the dry run artifacts and not an actual image set file. +`--v2`:: Specifies oc mirror v2. ++ +.Example output +[source,terminal] +---- +2025/08/25 15:50:44 [INFO] : 👋 Hello, welcome to oc-mirror +2025/08/25 15:50:44 [INFO] : ⚙ setting up the environment for you... +2025/08/25 15:50:44 [INFO] : 🔀 workflow mode: mirrorToMirror +2025/08/25 15:50:44 [INFO] : 🕵 going to discover the necessary images... +2025/08/25 15:50:44 [INFO] : 🔍 collecting release images... +2025/08/25 15:50:44 [INFO] : 🔍 collecting operator images... + ✓ (1m30s) Collecting catalog registry.redhat.io/redhat/redhat-operator-index:v4.20 +2025/08/25 15:52:14 [INFO] : 🔍 collecting additional images... +2025/08/25 15:52:14 [INFO] : 📄 list of all images for mirroring in : wspace/working-dir/dry-run/mapping.txt +2025/08/25 15:52:14 [INFO] : mirror time : 1m30.399585837s +2025/08/25 15:52:14 [INFO] : 👋 Goodbye, thank you for using oc-mirror +---- + +. Review the `mapping.txt` file that was generated by running the following command: ++ +[source,terminal] +---- +$ cat wspace/working-dir/dry-run/mapping.txt +---- ++ +.Example output +[source,terminal] +---- +docker://registry.redhat.io/amq8/amq-broker-rhel9@sha256:47fd4ce2533496828aba37bd1f9715e2164d5c90bd0fc6b25e7e0786d723bf01=docker://mirror.com/amq8/amq-broker-rhel9:sha256-47fd4ce2533496828aba37bd1f9715e2164d5c90bd0fc6b25e7e0786d723bf01 +docker://registry.redhat.io/amq8/amq-broker-init-rhel9@sha256:9cc48eecf1442ae04b8543fa5d4381a13bc2831390850828834d387006d1342b=docker://mirror.com/amq7/amq-broker-init-rhel9:sha256-9cc48eecf1442ae04b8543fa5d4381a13bc2831390850828834d387006d1342b +docker://registry.redhat.io/amq8/amq-broker-rhel9@sha256:bb6fbd68475a7852b4d99eea6c4ab313f9267da7963162f0d75375d7063409e7=docker://mirror.com/amq8/amq-broker-rhel9:sha256-bb6fbd68475a7852b4d99eea6c4ab313f9267da7963162f0d75375d7063409e7 +docker://registry.redhat.io/amq8/amq-broker-rhel9@sha256:d42d713da0ce6806fdc6492b6342586783e6865a82a8647d3c4288439b1751ee=docker://mirror.com/amq8/amq-broker-rhel9:sha256-d42d713da0ce6806fdc6492b6342586783e6865a82a8647d3c4288439b1751ee +docker://registry.redhat.io/amq8/amq-broker-init-rhel9@sha256:ffffa9875f0379e9373f89f05eb06e5a193273bb04bc3aa5f85b044357b79098=docker://mirror.com/amq8/amq-broker-init-rhel9:sha256-ffffa9875f0379e9373f89f05eb06e5a193273bb04bc3aa5f85b044357b79098 +---- diff --git a/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc b/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc index dd5d958d37f5..0b12bd82d385 100644 --- a/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc +++ b/modules/microshift-oc-mirror-embed-ops-disconnected-use.adoc @@ -4,37 +4,38 @@ :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-prep-ops-cat-images-disconnected-use_{context}"] -= Getting catalogs and Operator container image references to use with RHEL for Edge in disconnected environments += Getting catalogs and Operator container image references -After performing a dry run with the oc-mirror plugin to review the list of images that you want to mirror, you must get all of the container image references, then format the output for adding to an Image Builder blueprint. +After performing a dry run with the oc-mirror plugin to review the list of images that you want to mirror, you must get all of the container image references, then format the output for adding to an image builder blueprint. [NOTE] ==== -For catalogs made for proprietary Operators, you can format image references for the Image Builder blueprint without using the following procedure. +For catalogs made for proprietary Operators, you can format image references for the image builder blueprint without using the following procedure. ==== .Prerequisites + * You have a catalog index for the Operators you want to use. * You have installed the `jq` CLI tool. -* You are familiar with Image Builder blueprint files. -* You have an Image Builder blueprint TOML file. +* You are familiar with image builder blueprint files. +* You have an image builder blueprint TOML file. .Procedure -. Parse the catalog `index.json` file to get the image references that you need to include in the Image Builder blueprint. You can use either the unfiltered catalog or you can filter out images that cannot be mirrored: +. Parse the catalog `index.json` file to get the image references that you need to include in the image builder blueprint. You can use either the unfiltered catalog or you can filter out images that cannot be mirrored: .. Parse the unfiltered catalog `index.json` file to get the image references by running the following command: + -[source,terminal] +[source,terminal,subs="attributes+"] ---- -jq -r --slurp '.[] | select(.relatedImages != null) | "[[containers]]\nsource = \"" + .relatedImages[].image + "\"\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.17/index/index.json +jq -r --slurp '.[] | select(.relatedImages != null) | "[[containers]]\nsource = \"" + .relatedImages[].image + "\"\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v{product-version}/index/index.json ---- .. If you want to filter out images that cannot be mirrored, filter and parse the catalog `index.json` file by running the following command: + -[source,terminal] +[source,terminal,subs="attributes+"] ---- -$ jq -r --slurp '.[] | select(.relatedImages != null) | .relatedImages[] | select(.name | contains("ppc") or contains("s390x") | not) | "[[containers]]\\nsource = \\"" + .image + "\\"\\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v4.17/index/index.json +$ jq -r --slurp '.[] | select(.relatedImages != null) | .relatedImages[] | select(.name | contains("ppc") or contains("s390x") | not) | "[[containers]]\\nsource = \\"" + .image + "\\"\\n"' ./oc-mirror-workspace/src/catalogs/registry.redhat.io/redhat/redhat-operator-index/v{product-version}/index/index.json ---- + [NOTE] @@ -46,18 +47,18 @@ This step uses the AMQ Broker Operator as an example. You can add other criteria [source,terminal] ---- [[containers]] -source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0b2126cfb6054fdf428c1f43b69e36e93a09a49ce15350e9273c98cc08c6598b" +source = "registry.redhat.io/amq8/amq-broker-init-rhel9@sha256:0b2126cfb6054fdf428c1f43b69e36e93a09a49ce15350e9273c98cc08c6598b" [[containers]] -source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" +source = "registry.redhat.io/amq8/amq-broker-init-rhel9@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" ... ... [[containers]] -source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" +source = "registry.redhat.io/amq8/amq-broker-rhel9@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" [[containers]] -source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" +source = "registry.redhat.io/amq8/amq-broker-rhel9@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" … EOF ---- @@ -75,59 +76,56 @@ $ cat imageset-config.yaml ---- + .Example output -[source,terminal] +[source,yaml,subs="attributes+"] ---- kind: ImageSetConfiguration -apiVersion: mirror.openshift.io/v1alpha2 -storageConfig: - registry: - imageURL: registry.example.com/microshift-mirror +apiVersion: mirror.openshift.io/v2alpha1 mirror: operators: - - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.17 <1> + - catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} <1> packages: - - name: amq-broker-rhel8 + - name: amq-broker-rhel9 channels: - - name: 7.11.x + - name: 7.13.x ---- -<1> Use the value in the `mirror.catalog` catalog image reference for the follwing `jq` command to get the image digest. In this example, __. +<1> Use the value in the `mirror.catalog` catalog image reference for the following `jq` command to get the image digest. In this example, __. . Get the SHA of the catalog index image by running the following command: + -[source,terminal] +[source,terminal,subs="attributes+",subs="+quotes"] ---- -$ skopeo inspect docker:// | jq `.Digest` <1> +$ skopeo inspect docker://__ | jq `.Digest` <1> ---- -<1> Use the value in the `mirror.catalog` catalog image reference for the `jq` command to get the image digest. In this example, __. +<1> Use the value in the `mirror.catalog` catalog image reference for the `jq` command to get the image digest. In this example, __. + .Example output -[source,terminal] +[source,text] ---- "sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6" ---- -. To get ready to add the image references to your Image Builder blueprint file, format the catalog image reference by using the following example: +. To get ready to add the image references to your image builder blueprint file, format the catalog image reference by using the following example: + -[source,terminal] +[source,text] ---- [[containers]] source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a839035eb6e896d54ebd63668bb37b82040692141ba39ab4c539bc6" ---- -. Add the image references from all the previous steps to the Image Builder blueprint. +. Add the image references from all of the previous steps to the image builder blueprint. + -.Generated Image Builder blueprint example snippet -[source,text] +.Generated image builder blueprint example snippet +[source,text,subs="attributes+"] ---- name = "microshift_blueprint" -description = "MicroShift 4.17.1 on x86_64 platform" +description = "MicroShift {product-version}.1 on x86_64 platform" version = "0.0.1" modules = [] groups = [] [[packages]] <1> name = "microshift" -version = "4.17.1" +version = "{product-version}.1" ... ... @@ -153,15 +151,15 @@ source = "registry.redhat.io/redhat/redhat-operator-index@sha256:7a76c0880a83903 ... [[containers]] -source = "registry.redhat.io/amq7/amq-broker-init-rhel8@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" +source = "registry.redhat.io/amq8/amq-broker-init-rhel9@sha256:0dde839c2dce7cb684094bf26523c8e16677de03149a0fff468b8c3f106e1f4f" ... ... [[containers]] -source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" +source = "registry.redhat.io/amq8/amq-broker-rhel9@sha256:e8fa2a00e576ecb95561ffbdbf87b1c82d479c8791ab2c6ce741dd0d0b496d15" [[containers]] -source = "registry.redhat.io/amq7/amq-broker-rhel8@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" +source = "registry.redhat.io/amq8/amq-broker-rhel9@sha256:ff6fefad518a6c997d4c5a6e475ba89640260167f0bc27715daf3cc30116fad1" … EOF ---- diff --git a/modules/microshift-oc-mirror-install-catalog-cluster.adoc b/modules/microshift-oc-mirror-install-catalog-cluster.adoc index 00e6e0e1d194..7d00727d20a3 100644 --- a/modules/microshift-oc-mirror-install-catalog-cluster.adoc +++ b/modules/microshift-oc-mirror-install-catalog-cluster.adoc @@ -1,12 +1,12 @@ //Module included in the following assemblies: // -// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-install-catalog-in-cluster_{context}"] = Installing a custom catalog created with the oc-mirror plugin -After you mirror your image set to the mirror registry, you must apply the generated `CatalogSource` custom resource (CR) into the cluster. The `CatalogSource` CR is used by Operator Lifecycle Manager (OLM) to retrieve information about the available Operators in the mirror registry. You must then create and apply a subscription CR to subscribe to your custom catalog. +After you mirror your image set to the mirror registry, you must apply the generated `CatalogSource` custom resource (CR) into the cluster. Operator Lifecycle Manager (OLM) uses the `CatalogSource` CR to retrieve information about the available Operators in the mirror registry. You must then create and apply a subscription CR to subscribe to your custom catalog. .Prerequisites @@ -17,41 +17,53 @@ After you mirror your image set to the mirror registry, you must apply the gener . Apply the catalog source configuration file from the results directory to create the catalog source object by running the following command: + +[source,terminal,subs="+quotes"] +---- +$ oc apply -f ./__/working-dir/cluster-resources/catalogSource-cs-redhat-catalog.yaml <1> +---- +<1> Replace __ with the directory you used to store custom resources for the mirroring process. ++ +.Example output [source,terminal] ---- -$ oc apply -f ./oc-mirror-workspace/results-1708508014/catalogSource-cs-redhat-operator-index.yaml +catalogsource.operators.coreos.com/cs-redhat-catalog created ---- + +. For reference, see the following example file: + .Example catalog source configuration file -[source,yaml] +[source,yaml,subs="+attributes"] ---- -apiVersion: operators.coreos.com/v1alpha1 +apiVersion: operators.coreos.com/v2alpha1 kind: CatalogSource metadata: name: redhat-catalog namespace: openshift-marketplace <1> spec: sourceType: grpc - image: registry.example.com/redhat/redhat-operator-index:v4.17 + image: registry.example.com/redhat/redhat-catalog:v{ocp-version} updateStrategy: registryPoll: interval: 60m ---- <1> Specifies the global namespace. Setting the `metadata.namespace` to `openshift-marketplace` enables the catalog to reference catalogs in all namespaces. Subscriptions in any namespace can reference catalogs created in the `openshift-marketplace` namespace. + +. Verify that the `CatalogSource` resources were successfully installed by running the following command: + -.Example output [source,terminal] ---- -catalogsource.operators.coreos.com/cs-redhat-operator-index created +$ oc get catalogsource --all-namespaces ---- - -. Verify that the `CatalogSource` resources were successfully installed by running the following command: + +.Example output [source,terminal] ---- -$ oc get catalogsource --all-namespaces +NAMESPACE NAME DISPLAY TYPE PUBLISHER AGE +openshift-marketplace certified-operators Certified Operators grpc Red Hat 37m +openshift-marketplace community-operators Community Operators grpc Red Hat 37m +openshift-marketplace redhat-marketplace Red Hat Marketplace grpc Red Hat 37m +openshift-marketplace redhat-catalog Red Hat Catalog grpc Red Hat 37m ---- -//add example output . Verify that the catalog source is running by using the following command: + @@ -64,7 +76,7 @@ $ oc get pods -n openshift-marketplace [source,terminal] ---- NAME READY STATUS RESTARTS AGE -cs-redhat-operator-index-4227b 2/2 Running 0 2m5s +cs-redhat-catalog-4227b 2/2 Running 0 2m5s ---- . Create a `Subscription` CR, similar to the following example: @@ -72,25 +84,25 @@ cs-redhat-operator-index-4227b 2/2 Running 0 2m5s .Example `Subscription` CR [source,yaml] ---- -apiVersion: operators.coreos.com/v1alpha1 +apiVersion: operators.coreos.com/v2alpha1 kind: Subscription metadata: name: amq-broker namespace: openshift-operators spec: - channel: 7.11.x - name: amq-broker-rhel8 - source: cs-redhat-operator-index + channel: 7.13.x + name: amq-broker-rhel9 + source: cs-redhat-catalog sourceNamespace: openshift-marketplace ---- . Apply the Subscription CR configuration by running the following command: + -[source,terminal] +[source,terminal,subs="+quotes"] ---- -$ oc apply -f ./ <1> +$ oc apply -f ./__ <1> ---- -<1> Specify the name of your subscription, such as `my-subscription-cr.yaml`. +<1> Specify the name of your subscription in __, for example `amq--broker-subscription-cr.yaml`. + .Example output [source,terminal] diff --git a/modules/microshift-oc-mirror-list-ops-catalogs.adoc b/modules/microshift-oc-mirror-list-ops-catalogs.adoc index 249558766781..3d7a3d004f31 100644 --- a/modules/microshift-oc-mirror-list-ops-catalogs.adoc +++ b/modules/microshift-oc-mirror-list-ops-catalogs.adoc @@ -1,12 +1,12 @@ //Module included in the following assemblies: // -//* microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-list-operators-catalogs_{context}"] = Inspecting catalog contents by using the oc-mirror plugin -Use the following example procedure to select a catalog and list Operators from available {OCP} content to add to your oc-mirror plugin image set configuration file. +Use the following example procedure to select a catalog and list {OCP} Operators to add to your oc-mirror plugin image set configuration file. You must use oc mirror v1 to selecting a catalog and listing Operators. [NOTE] ==== @@ -14,9 +14,9 @@ If you use your own catalogs and Operators, you can push the images directly to ==== .Prerequisites -* The {oc-first} is installed. -* Operator Lifecycle Manager (OLM) is installed. -* The oc-mirror OpenShift CLI (oc) plugin is installed. +* You uninstalled {oc-first}. +* You installed the Operator Lifecycle Manager (OLM). +* You installed the oc-mirror plugin. .Procedure . Get a list of available Red{nbsp}Hat-provided Operator catalogs to filter by running the following command: @@ -26,7 +26,7 @@ If you use your own catalogs and Operators, you can push the images directly to $ oc mirror list operators --version {product-version} --catalogs ---- -. Get a list of Operators in the Red{nbsp}Hat Operators catalog by running the following command: +. Get a list of Operators in the Red Hat Operators catalog by running the following command: + [source,terminal] ---- @@ -34,21 +34,21 @@ $ oc mirror list operators <--catalog=> <1> ---- <1> Specifies your catalog source, such as `registry.redhat.io/redhat/redhat-operator-index:v{product-version}` or `quay.io/operatorhubio/catalog:latest`. -. Select an Operator. For this example, `amq-broker-rhel8` is selected. +. Select an Operator. This example uses the `amq-broker-rhel9` Operator. . Optional: To inspect the channels and versions of the Operator you want to filter, enter the following commands: .. Get a list of channels by running the following command: + -[source,terminal] +[source,terminal,subs="attributes+"] ---- -$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.17 --package=amq-broker-rhel8 +$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v{product-version} --package=amq-broker-rhel9 ---- .. Get a list of versions within a channel by running the following command: + -[source,terminal] +[source,terminal,subs="attributes+"] ---- -$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v4.17 --package=amq-broker-rhel8 --channel=7.11.x +$ oc mirror list operators --catalog=registry.redhat.io/redhat/redhat-operator-index:v{product-version} --package=amq-broker-rhel9 --channel=7.13.x ---- .Next steps diff --git a/modules/microshift-oc-mirror-to-mirror.adoc b/modules/microshift-oc-mirror-to-mirror.adoc new file mode 100644 index 000000000000..050c74f8815e --- /dev/null +++ b/modules/microshift-oc-mirror-to-mirror.adoc @@ -0,0 +1,59 @@ +// Module included in the following assemblies: +// +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc + +:_mod-docs-content-type: PROCEDURE +[id="microshift-oc-mirror-mirror-to-mirror_{context}"] += Mirroring from mirror to mirror + +You can use the oc-mirror plugin to mirror an image set directly to a target mirror registry that is accessible during image set creation. + +.Prerequisites + +* You have access to the internet to get the required container images. +* You installed the {oc-first}. +* You installed the `oc-mirror` CLI plugin. +* You created the image set configuration file. + +.Procedure + +* Mirror the images from the specified image set configuration to a specified registry by running the following command: ++ +[source,terminal,subs="quotes+"] +---- +$ oc-mirror --config imageset-config.yaml --workspace file://__ \// <1> + docker://__ --v2 <2> +---- +<1> You must use the `--workspace` flag for the mirror-to-mirror process. Replace __ with the directory you want to use to store custom resources for the mirroring process. +<2> Replace __ with the name of the registry to mirror the image set file to. The registry must start with `docker://`. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on later executions. ++ +.Example output +[source,terminal] +---- +Rendering catalog image "registry.example.com/redhat/redhat-operator-index:v{ocp-version}" with file-based catalog +---- ++ +-- +[IMPORTANT] +==== +You must use the `ImageDigestMirrorSet` YAML file as reference content for manual configuration of CRI-O in {microshift-short}. You cannot apply the resource directly into a {microshift-short} cluster. +==== +-- + +.Verification +. List the contents of the `cluster-resources` subdirectory by running the following command: ++ +[source,terminal,subs="+quotes"] +---- +$ ls __/working-dir/cluster-resources/ <1> +---- +<1> Replace __ with the directory you used to store custom resources for the mirroring process. + +.Next steps + +* Convert the `ImageDigestMirrorSet` YAML content for use in manually configuring CRI-O. +* If required, mirror the images from mirror to disk for disconnected or offline use. + +.Troubleshooting + +* link:https://access.redhat.com/solutions/7032017[Unable to retrieve source image]. diff --git a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc index b3cf59d29ca9..246f3983cf09 100644 --- a/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc +++ b/modules/microshift-oc-mirror-transform-imageset-to-crio.adoc @@ -1,57 +1,58 @@ //Module included in the following assemblies: // -// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="microshift-oc-mirror-transform-imageset-to-crio_{context}"] = Configuring CRI-O for using a registry mirror for Operators -You must transform the `imageContentSourcePolicy.yaml` file created with the oc-mirror plugin into a format that is compatible with the CRI-O container runtime configuration used by {microshift-short}. +You must transform the `ImageDigestMirrorSet` YAML file created with the oc-mirror plugin into a format that is compatible with the CRI-O container runtime configuration used by {microshift-short}. .Prerequisites + * The {oc-first} is installed. -* Operator Lifecycle Manager (OLM) is installed. -* The oc-mirror OpenShift CLI (oc) plugin is installed. -* The `yq` binary is installed. -* `ImageContentSourcePolicy` and `CatalogSource` YAML files are available in the `oc-mirror-workspace/results-*` directory. +* You installed Operator Lifecycle Manager (OLM). +* You installed the oc-mirror plugin. +* You installed the `yq` binary. +* The `ImageDigestMirrorSet` and `CatalogSource` YAML files are available in the `cluster-resources` subdirectory. .Procedure -. Confirm the contents of the `imageContentSourcePolicy.yaml` file by running the following command: +. Confirm the contents of the `ImageDigestMirrorSet` YAML file by running the following command: + -[source,terminal] +[source,terminal,subs="+quotes"] ---- -$ cat oc-mirror-workspace//imageContentSourcePolicy.yaml <1> +$ cat __/working-dir/cluster-resources/imagedigestmirrorset.yaml <1> ---- -<1> Specify the `results` directory name, such as ``. +<1> Replace __ with the directory name that you used when you generated mirroring resources. + .Example output -[source,terminal] +[source,yaml] ---- -apiVersion: operator.openshift.io/v1alpha1 -kind: ImageContentSourcePolicy +apiVersion: config.openshift.io/v1 +kind: ImageDigestMirrorSet metadata: labels: operators.openshift.org/catalog: "true" name: operator-0 spec: - repositoryDigestMirrors: + imageDigestMirrors: - mirrors: - - registry./amq7 + - registry.example.com/amq7 source: registry.redhat.io/amq7 ---- -. Transform the `imageContentSourcePolicy.yaml` into a format ready for CRI-O configuration by running the following command: +. Transform the `imagedigestmirrorset.yaml` into a format ready for CRI-O configuration by running the following command: + [source,terminal] ---- -yq '.spec.repositoryDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.mirrors[], "source": ($item | .source)}]) | .[] | +yq '.spec.imageDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.mirrors[], "source": ($item | .source)}]) | .[] | "[[registry]] prefix = \"" + .source + "\" location = \"" + .mirror + "\" mirror-by-digest-only = true insecure = true - "' ./icsp.yaml + "' ./mirror1/working-dir/cluster-resources/imagedigestmirrorset.yaml ---- + .Example output @@ -83,11 +84,11 @@ yq '.spec.repositoryDigestMirrors[] as $item ireduce([]; . + [{"mirror": $item.m location = ":" <1> insecure = false ---- -<1> Specify the host name and port of your mirror registry server, for example `microshift-quay:8443`. +<1> Specify the hostname and port of your mirror registry server, for example `microshift-quay:8443`. . Apply the CRI-O configuration changes by restarting {microshift-short} with the following command: + [source,terminal] ---- $ sudo systemctl restart crio ----- \ No newline at end of file +---- diff --git a/modules/microshift-olm-rh-ops-mirror.adoc b/modules/microshift-olm-rh-ops-mirror.adoc new file mode 100644 index 000000000000..195558c72633 --- /dev/null +++ b/modules/microshift-olm-rh-ops-mirror.adoc @@ -0,0 +1,14 @@ + +//Module included in the following assemblies: +// +//* microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc + +:_mod-docs-content-type: CONCEPT +[id="microshift-olm-rh-ops-mirror_{context}"] += Using Red Hat-provided Operator catalogs and mirror registries + +You can filter catalogs and delete images to get specific Operators and mirror them by using the oc-mirror {oc-first} plugin. You can also use Operators in disconnected settings or embedded in a {op-system-base-full} image. + +* To understand more about how to configure your systems for mirroring, follow the links in the following "Additional resources" section. + +* If you are ready to deploy Operators from Red Hat-provided Operator catalogs, mirror them, or to embed them in a {op-system-base} image, start with the following section, "Inspecting catalog contents by using the oc-mirror plugin." diff --git a/modules/oc-mirror-dry-run.adoc b/modules/oc-mirror-dry-run.adoc index 65b2d368741f..8b13a22514c3 100644 --- a/modules/oc-mirror-dry-run.adoc +++ b/modules/oc-mirror-dry-run.adoc @@ -2,7 +2,6 @@ // // * installing/disconnected_install/installing-mirroring-disconnected.adoc // * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc -// * microshift_running_apps/microshift_operators/microshift-operators-olm.adoc :_mod-docs-content-type: PROCEDURE [id="oc-mirror-dry-run_{context}"] diff --git a/modules/oc-mirror-imageset-config-parameters-v2.adoc b/modules/oc-mirror-imageset-config-parameters-v2.adoc index 320c0050ad39..32b814381e8e 100644 --- a/modules/oc-mirror-imageset-config-parameters-v2.adoc +++ b/modules/oc-mirror-imageset-config-parameters-v2.adoc @@ -2,10 +2,11 @@ // Module included in the following assemblies: // // * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc +// * microshift_running_apps/microshift_operators//microshift-operators-oc-mirror.com :_mod-docs-content-type: REFERENCE [id="oc-mirror-imageset-config-parameters-v2_{context}"] -= `ImageSet` configuration parameters for oc-mirror plugin v2 += ImageSet configuration parameters for oc-mirror plugin v2 The oc-mirror plugin v2 requires an image set configuration file that defines what images to mirror. The following table lists the available parameters for the `ImageSetConfiguration` resource. @@ -30,6 +31,7 @@ To avoid this error, do not filter out the latest version of an Operator. If you |String Example: `mirror.openshift.io/v2alpha1` +ifndef::microshift[] |`archiveSize` |The maximum size, in GiB, of each archive file within the image set. |Integer @@ -51,6 +53,7 @@ mirror: maxVersion: 4.16.0 kubeVirtContainer: true ---- +endif::microshift[] |`mirror` |The configuration of the image set. @@ -77,6 +80,7 @@ Example: `registry.redhat.io/ubi8/ubi:latest` |Array of strings Example: `docker.io/library/alpine` +ifndef::microshift[] |`mirror.helm` |The helm configuration of the image set. The oc-mirror plugin does not support helm charts with manually modified `values.yaml` files. |Object @@ -140,6 +144,7 @@ repositories: `oc-mirror` detects and mirrors container images from the helm chart by searching well-known paths. You can also specify custom paths using this field. ==== |Array of string. For example: `"- {.spec.template.spec.custom[*].image}"`. +endif::microshift[] |`mirror.operators` |The Operators configuration of the image set. @@ -243,6 +248,7 @@ spec: |String Example: `v1` +ifndef::microshift[] |`mirror.platform` |The platform configuration of the image set. |Object @@ -324,14 +330,13 @@ The default value is `false` channels: - name: fast ---- - +endif::microshift[] |=== +[id="delete-imagset-config-parameters_{context}"] +== DeleteImageSetConfiguration parameters -[id="delete-imagset-config-parameters"] -== Delete `ImageSet` Configuration parameters - -To use the oc-mirror plugin v2, you must have delete image set configuration file that defines which images to delete from the mirror registry. The following table lists the available parameters for the `DeleteImageSetConfiguration` resource. +To use remove images with the oc-mirror plugin v2, you must use a `DeleteImageSetConfiguration.yaml` configuration file that defines which images to delete from the mirror registry. The following table lists the available parameters for the `DeleteImageSetConfiguration` resource. .`DeleteImageSetConfiguration` parameters [cols="2,2a,1a",options="header"] @@ -434,6 +439,7 @@ Example: `5.2.3-31` |String Example: `5.2.3-31` +ifndef::microshift[] |`delete.platform` |The platform configuration of the image set |Object @@ -501,5 +507,5 @@ The default is `ocp` |Determines whether the OSUS graph is deleted as well on the mirror registry as well. |Boolean The default value is `false` - +endif::microshift[] |=== diff --git a/modules/oc-mirror-imageset-config-params.adoc b/modules/oc-mirror-imageset-config-params.adoc index b5b56ce227d6..ec96126c5d3e 100644 --- a/modules/oc-mirror-imageset-config-params.adoc +++ b/modules/oc-mirror-imageset-config-params.adoc @@ -2,7 +2,7 @@ // // * installing/disconnected_install/installing-mirroring-disconnected.adoc // * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc -// * microshift_running_apps/microshift_operators//microshift-operators-olm.com +// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.com :_mod-docs-content-type: REFERENCE [id="oc-mirror-imageset-config-params_{context}"] @@ -10,8 +10,6 @@ The oc-mirror plugin requires an image set configuration file that defines what images to mirror. The following table lists the available parameters for the `ImageSetConfiguration` resource. -// TODO: Consider adding examples for the general "Object" params - .`ImageSetConfiguration` parameters [cols="2,2a,1a",options="header"] |=== @@ -24,11 +22,9 @@ The oc-mirror plugin requires an image set configuration file that defines what |String. For example: `mirror.openshift.io/v1alpha2`. ifndef::microshift[] - |`archiveSize` |The maximum size, in GiB, of each archive file within the image set. |Integer. For example: `4` - endif::microshift[] |`mirror` @@ -54,7 +50,6 @@ additionalImages: |Array of strings. For example: `docker.io/library/alpine` ifndef::microshift[] - |`mirror.helm` |The helm configuration of the image set. Note that the oc-mirror plugin supports only helm charts that do not require user input when rendered. |Object @@ -111,7 +106,6 @@ repositories: |`mirror.helm.repositories.charts.version` |The version of the named helm chart to mirror. |String. For example: `5.0.0`. - endif::microshift[] |`mirror.operators` @@ -200,7 +194,6 @@ The `targetName` parameter is deprecated. Use the `targetCatalog` parameter inst |String. For example: `v1` ifndef::microshift[] - |`mirror.platform` |The platform configuration of the image set. |Object @@ -259,7 +252,6 @@ channels: |`mirror.platform.graph` |Indicates whether the OSUS graph is added to the image set and subsequently published to the mirror. |Boolean. The default value is `false`. - endif::microshift[] |`storageConfig` diff --git a/modules/oc-mirror-mirror-to-mirror.adoc b/modules/oc-mirror-mirror-to-mirror.adoc index 0dd49bc8a967..20e71ac92e0a 100644 --- a/modules/oc-mirror-mirror-to-mirror.adoc +++ b/modules/oc-mirror-mirror-to-mirror.adoc @@ -2,7 +2,6 @@ // // * installing/disconnected_install/installing-mirroring-disconnected.adoc // * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc -// * microshift_running_apps/microshift_operators/microshift-operators-oc-mirror.adoc :_mod-docs-content-type: PROCEDURE [id="oc-mirror-mirror-to-mirror_{context}"] @@ -19,10 +18,10 @@ Do not delete or modify the metadata that is generated by the oc-mirror plugin. .Prerequisites -* You have access to the internet to get the necessary container images. -* You have installed the OpenShift CLI (`oc`). -* You have installed the oc-mirror CLI plugin. -* You have created the image set configuration file. +* You have access to the internet to get the required container images. +* You installed the {oc-first}. +* You installed the oc-mirror CLI plugin. +* You created the image set configuration file. .Procedure @@ -36,40 +35,20 @@ $ oc mirror --config=./ \// <1> <1> Specify the image set configuration file that you created. For example, `imageset-config.yaml`. <2> Specify the registry to mirror the image set file to. The registry must start with `docker://`. If you specify a top-level namespace for the mirror registry, you must also use this same namespace on subsequent executions. -ifdef::microshift[] -.Example output -[source,terminal] ----- -Rendering catalog image "registry.example.com/redhat/redhat-operator-index:v{ocp-version}" with file-based catalog ----- -endif::microshift[] - .Verification . Navigate into the `oc-mirror-workspace/` directory that was generated. . Navigate into the results directory, for example, `results-1639608409/`. . Verify that YAML files are present for the `ImageContentSourcePolicy` and `CatalogSource` resources. -ifndef::microshift[] [NOTE] ==== The `repositoryDigestMirrors` section of the `ImageContentSourcePolicy` YAML file is used for the `install-config.yaml` file during installation. ==== -endif::microshift[] -// TODO: Test and get some better wording/example output. - -ifdef::microshift[] -[IMPORTANT] -==== -The `ImageContentSourcePolicy` YAML file is used as reference content for manual configuration of CRI-O in {microshift-short}. You cannot apply the resource directly into a {microshift-short} cluster. -==== -endif::microshift[] .Next steps -ifdef::microshift[] * Convert the `ImageContentSourcePolicy` YAML content for use in manually configuring CRI-O. * If required, mirror the images from mirror to disk for disconnected or offline use. -endif::microshift[] * Configure your cluster to use the resources generated by oc-mirror. .Troubleshooting