openshift/openshift-docs
1
0
Fork 0
mirror of https://github.com/openshift/openshift-docs.git synced 2026-02-05 21:46:22 +01:00
Code Issues Releases Activity

Revert "Merge pull request #76555 from subhtk/ocm-v1"

Browse Source 
This reverts commit 690b892098, reversing
changes made to c136038fb4.

Conflicts:
  modules/oc-mirror-imageset-config-params.adoc

Resolved conflicts by keeping the "4.16" version bump that happened via PR 76649, but set back the commas instead of colons to their pre-76555 state.
This commit is contained in:
Alex Dellapenta
2024-06-14 09:50:58 -06:00
committed by openshift-cherrypick-robot
parent 5b22bbe21d
commit 7fa9252b28
20 changed files with 273 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
installing/disconnected_install/installing-mirroring-disconnected.adoc
View File

@@ -1,12 +1,14 @@
:_mod-docs-content-type: ASSEMBLY
[id="installing-mirroring-disconnected_{context}"]
= Mirroring images for a disconnected installation using the oc-mirror plugin v1
[id="installing-mirroring-disconnected"]
= Mirroring images for a disconnected installation using the oc-mirror plugin
include::_attributes/common-attributes.adoc[]
:context: installing-mirroring-disconnected
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 "Prerequisites" section for more information.
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:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#prerequisites_installing-mirroring-disconnected[Prerequisites] section for more information.
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.
// About the oc-mirror plugin
include::modules/oc-mirror-about.adoc[leveloffset=+1]
@@ -14,68 +16,76 @@ include::modules/oc-mirror-about.adoc[leveloffset=+1]
// oc-mirror compatibility and support
include::modules/oc-mirror-support.adoc[leveloffset=+1]
[id="prerequisites_installing-mirroring-disconnected_{context}"]
== Prerequisites
[role="_additional-resources"]
.Additional resources
* You must have a container image registry, which is referred as the mirror 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}, 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://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploy_red_hat_quay_for_proof-of-concept_non-production_purposes/[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 Red Hat 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 mirror registry, the subscribers of {product-title} are provided in "Creating a mirror registry with mirror registry for Red Hat OpenShift".
* For information on updating oc-mirror, see xref:../../installing/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source].
* The mirror registry must be reachable by every machine in the clusters that you provision. If the registry is unreachable, installation, updating, or normal operations such as workload relocation might fail. For this reason, you must run mirror registries ensuring highly availability. The mirror registries must meet or exceed the production availability of your {product-title} clusters.
* You have set the umask parameter to `0022` on the operating system that uses oc-mirror plugin v1.
// About the mirror registry
include::modules/installation-about-mirror-registry.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../installing/disconnected_install/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[Creating a mirror registry with mirror registry for Red Hat OpenShift]
* For information about viewing the CRI-O logs to view the image source, see xref:../../installing/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source].
[id="mirroring-preparing-your-hosts_{context}"]
[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 Red Hat Quay.
+
[NOTE]
====
If you use Red Hat Quay, you must use version 3.6 or later with the oc-mirror plugin. If you have an entitlement to Red Hat Quay, see the documentation on deploying Red Hat Quay link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploy_red_hat_quay_for_proof-of-concept_non-production_purposes/[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 Red Hat 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:../../installing/disconnected_install/installing-mirroring-creating-registry.adoc#installing-mirroring-creating-registry[mirror registry for Red Hat OpenShift]. The _mirror registry for Red 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.
[id="mirroring-preparing-your-hosts"]
== Preparing your mirror hosts
To use the oc-mirror plugin v1 to mirror images, you need to install the plugin and create a container image registry credentials file to enable mirroring from Red Hat to your mirror.
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.
// Installing the oc-mirror OpenShift CLI plugin v1
// Installing the oc-mirror OpenShift CLI plugin
include::modules/oc-mirror-installing-plugin.adoc[leveloffset=+2]
[role="_additional-resources"]
.Additional resources
* xref:../../cli_reference/openshift_cli/extending-cli-plugins.adoc#cli-installing-plugins_cli-extend-plugins[Installing and using CLI plugins]
// Configuring credentials that allow images to be mirrored
include::modules/installation-adding-registry-pull-secret.adoc[leveloffset=+2]
// About Image set configuration
include::modules/oc-mirror-about-image-set-config.adoc[leveloffset=+1]
// Creating the image set configuration
include::modules/oc-mirror-creating-image-set-config.adoc[leveloffset=+2]
// Image set configuration parameters
include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+2]
// Image set configuration examples
include::modules/oc-mirror-image-set-config-examples.adoc[leveloffset=+2]
// Setting up for incremental mirroring
include::modules/oc-mirror-setting-incremental-mirroring.adoc[leveloffset=+1]
include::modules/oc-mirror-creating-image-set-config.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc#update-service-overview_updating-restricted-network-cluster-osus[Updating a cluster in a disconnected environment using the OpenShift Update Service]
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-imageset-config-params_installing-mirroring-disconnected[Image set configuration parameters]
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-image-set-examples_installing-mirroring-disconnected[Image set configuration examples]
* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.adoc#update-service-overview_updating-restricted-network-cluster-osus[Using the OpenShift Update Service in a disconnected environment]
* xref:../../cli_reference/openshift_cli/extending-cli-plugins.adoc#cli-installing-plugins_cli-extend-plugins[Extending the OpenShift CLI with plugins]
[id="mirroring-image-set"]
== Mirroring an image set to a mirror registry
// Mirroring an image set to a mirror registry
include::modules/oc-mirror-mirroring-image-set.adoc[leveloffset=+1]
You can use the oc-mirror CLI plugin to mirror images to a mirror registry in a xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#mirroring-image-set-partial[partially disconnected environment] or in a xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#mirroring-image-set-full[fully disconnected environment].
// Mirroring from partially disconnected environment:mirror to mirror
include::modules/oc-mirror-mirror-to-mirror.adoc[leveloffset=+2]
These procedures assume that you already have your mirror registry set up.
// Mirroring from fully disconnected environment
include::modules/oc-mirror-fully-disconnected.adoc[leveloffset=+2]
[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 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:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-mirror-to-disk_installing-mirroring-disconnected[mirror the image set to disk], then xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-disk-to-mirror_installing-mirroring-disconnected[mirror the image set file on disk to a mirror].
// Mirroring from mirror to disk
include::modules/oc-mirror-mirror-to-disk.adoc[leveloffset=+3]
@@ -86,34 +96,42 @@ include::modules/oc-mirror-disk-to-mirror.adoc[leveloffset=+3]
// Configuring your cluster to use the resources generated by oc-mirror
include::modules/oc-mirror-updating-cluster-manifests.adoc[leveloffset=+1]
[role="_additional-resources"]
.Additional resources
* xref:../../updating/understanding_updates/intro-to-updates.adoc#update-service-about_understanding-openshift-updates[About the OpenShift Update Service]
// About updating your mirror registry content
include::modules/oc-mirror-updating-registry-about.adoc[leveloffset=+1]
// Use-cases
include::modules/oc-mirror-updating-use-cases.adoc[leveloffset=+2]
[role="_additional-resources"]
.Additional resources
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-image-set-examples_installing-mirroring-disconnected[Image set configuration examples]
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#mirroring-image-set-partial[Mirroring an image set in a partially disconnected environment]
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#mirroring-image-set-full[Mirroring an image set in a fully disconnected environment]
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-updating-cluster-manifests_installing-mirroring-disconnected[Configuring your cluster to use the resources generated by oc-mirror]
// Performing a dry run
include::modules/oc-mirror-dry-run.adoc[leveloffset=+1]
// Including local OCI Operator catalogs
include::modules/oc-mirror-oci-format.adoc[leveloffset=+1]
// Additional resources
[role="_additional-resources"]
.Additional resources
// TODO: This title might need to update per sebastian's PR
// Configuring your cluster to use the resources generated by oc-mirror
* xref:../../installing/disconnected_install/installing-mirroring-disconnected.adoc#oc-mirror-updating-cluster-manifests_installing-mirroring-disconnected[Configuring your cluster to use the resources generated by oc-mirror]
// Image set configuration parameters
include::modules/oc-mirror-imageset-config-params.adoc[leveloffset=+1]
// Image set configuration examples
include::modules/oc-mirror-image-set-config-examples.adoc[leveloffset=+1]
// Command reference for oc-mirror
include::modules/oc-mirror-command-reference.adoc[leveloffset=+1]
[role="_additional-resources"]
[id="additional-resources_installing-mirroring-disconnected"]
== Additional resources
* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/index.adoc#about-restricted-network-updates[About cluster updates in a disconnected environment]
* xref:../../installing/validating-an-installation.adoc#viewing-the-image-pull-source_validating-an-installation[Viewing the image pull source]

13
modules/installation-adding-registry-pull-secret.adoc
View File

@@ -22,18 +22,23 @@ endif::[]
:_mod-docs-content-type: PROCEDURE
[id="installation-adding-registry-pull-secret_{context}"]
= Configuring credentials to enable mirroring images
= Configuring credentials that allow images to be mirrored
Follow the procedure to create a container image registry credentials file for mirroring images from Red Hat to your mirror registry.
Create a container image registry credentials file that allows mirroring
images from Red Hat to your mirror.
ifdef::restricted[]
[WARNING]
====
Do not use this image registry credentials file as the pull secret when installing a cluster. Using this file will grant write access to your mirror registry for all machines in the cluster.
Do not use this image registry credentials file as the pull secret when you install a cluster. If you provide this file when you install cluster, all of the machines in the cluster will have write access to your mirror registry.
====
endif::restricted[]
ifdef::restricted[]
[WARNING]
====
This process requires that you have write access to a container image registry on the mirror registry and adds the credentials to a registry pull secret.
====
endif::restricted[]
@@ -47,8 +52,6 @@ endif::openshift-rosa,openshift-dedicated[]
ifdef::restricted[]
* You identified an image repository location on your mirror registry to mirror images into.
* You provisioned a mirror registry account that allows images to be uploaded to that image repository.
* You have write access to the mirror registry.
* You included the credentials in the registry pull secret.
endif::restricted[]
.Procedure

33
modules/oc-mirror-about-image-set-config.adoc
View File

@@ -1,33 +0,0 @@
// Module included in the following assemblies:
//
// * installing/disconnected_install/installing-mirroring-disconnected.adoc
// * updating/updating_a_cluster/updating_disconnected_cluster/mirroring-image-repository.adoc
:_mod-docs-content-type: CONCEPT
[id="oc-mirror-about-image-set-config_{context}"]
= About the Image Set Configuration
An `ImageSetConfiguration` (ISC) file is a collection of container images for mirroring. The ISC specifies the images, their versions, and any additional configuration needed for mirroring. ISCs provide a structured way to manage image mirroring tasks, allowing users to easily define, organize, and execute mirroring operations within their {product-title} environment.
[id="oc-mirror-possibile-deployment-scenarios_{context}"]
== Possible deployment scenarios
[id="oc-mirror-getting-image-set-config-specific-release_{context}"]
=== Scenario 1: Obtaining the `ImageSetConfiguration` file for a specific release
To obtain the `ImageSetConfiguration` file for a specific release, follow one of these methods:
* Set `minVersion` at the channel level to your target deployment version.
* Alternatively, set `minVersion` to the latest version in the default channel and keep it unchanged.
* Set the `maxVersion` to limit versions being mirrored.
* Use the same version for both `minVersion` and `maxVersion` to mirror only one version.
When you run the `oc-mirror` plugin v1 with the `ImageSetConfiguration` file, it evaluates the latest release of the `stable-<latest-_version>` channel.
[id="oc-mirror-image-set-config-local-storage-shortest-path_{context}"]
=== Scenario 2: Using local storage and including all {product-title} versions with the shortest update path
When using local storage and including all {product-title} versions with the shortest update path, consider the following options:
* Set `maxVersion` to a valid version that exists in the channel you are setting it on, or include a different channel that has this version.
* If `minVersion` and `maxVersion` are not the same, the default behavior is to mirror the shortest valid upgrade path between them.

15
modules/oc-mirror-about.adoc
View File

@@ -5,7 +5,7 @@
:_mod-docs-content-type: CONCEPT
[id="installation-oc-mirror-about_{context}"]
= About the oc-mirror plugin v1
= About the oc-mirror plugin
You can use the oc-mirror OpenShift CLI (`oc`) plugin to mirror all required {product-title} content and other images to your mirror registry by using a single tool. It provides the following features:
@@ -21,28 +21,27 @@ You can use the oc-mirror OpenShift CLI (`oc`) plugin to mirror all required {pr
* Optionally generates supporting artifacts for OpenShift Update Service (OSUS) usage.
When using the oc-mirror plugin v1, you specify the content to mirror in an image set configuration file. This YAML file allows you to configure which {product-title} releases and Operators your cluster requires, reducing the amount of data to download and transfer. The plugin can also mirror helm charts and additional container images to facilitate workload synchronization onto mirror registries.
When using the oc-mirror plugin, you specify which content to mirror in an image set configuration file. In this YAML file, you can fine-tune the configuration to only include the {product-title} releases and Operators that your cluster needs. This reduces the amount of data that you need to download and transfer. The oc-mirror plugin can also mirror arbitrary helm charts and additional container images to assist users in seamlessly synchronizing their workloads onto mirror registries.
The first time you run the oc-mirror plugin v1, it populates your mirror registry with the necessary content for your disconnected cluster installation or update. To continue receiving updates, it's essential to keep your mirror registry updated. Running the oc-mirror plugin v1 with the same configuration as the initial run allows for referencing metadata from the storage backend and downloading only the releases since the last run, providing update paths for {product-title} and Operators, and performing necessary dependency resolution.
The first time you run the oc-mirror plugin, it populates your mirror registry with the required content to perform your disconnected cluster installation or update. In order for your disconnected cluster to continue receiving updates, you must keep your mirror registry updated. To update your mirror registry, you run the oc-mirror plugin using the same configuration as the first time you ran it. The oc-mirror plugin references the metadata from the storage backend and only downloads what has been released since the last time you ran the tool. This provides update paths for {product-title} and Operators and performs dependency resolution as required.
[id="installation-oc-mirror-workflow_{context}"]
== High level workflow
The following steps outline the high-level workflow on how to use the oc-mirror plugin v1 to mirror images to a mirror registry:
The following steps outline the high-level workflow on how to use the oc-mirror plugin to mirror images to a mirror registry:
. Create an image set configuration file.
. Mirror the image set to the target mirror registry by using one of the following workflows:
. Mirror the image set to the target mirror registry by using one of the following methods:
** Mirror an image set directly to the target mirror registry.
** Mirror an image set to disk, transfer the image set to the target environment, then upload the image set to the target mirror registry.
. Configure your cluster to use the resources generated by the oc-mirror plugin v1.
. Configure your cluster to use the resources generated by the oc-mirror plugin.
. Repeat these steps to update your target mirror registry as necessary.
[IMPORTANT]
====
When using the oc-mirror CLI plugin to populate a mirror registry, any further updates to the target mirror registry must be made by using the oc-mirror plugin v1.
When using the oc-mirror CLI plugin to populate a mirror registry, any further updates to the target mirror registry must be made by using the oc-mirror plugin.
====

41
modules/oc-mirror-creating-image-set-config.adoc
View File

@@ -7,11 +7,18 @@
[id="oc-mirror-creating-image-set-config_{context}"]
= Creating the image set configuration
In order to use the oc-mirror plugin v1 to mirror image sets, you must create an image set configuration file that specifies the {product-title} releases, Operators, and additional images for mirroring, along with various configuration parameters for the oc-mirror plugin v1.
Before you can use the oc-mirror plugin to mirror image sets, you must create an image set configuration file. This image set configuration file defines which {product-title} releases, Operators, and other images to mirror, along with other configuration settings for the oc-mirror plugin.
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]
====
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.
====
.Prerequisites
* You have created a container image registry credentials file. For instructions, see "Configuring credentials that allow images to be mirrored".
* You have created a container image registry credentials file. For instructions, see _Configuring credentials that allow images to be mirrored_.
.Procedure
@@ -21,7 +28,7 @@ In order to use the oc-mirror plugin v1 to mirror image sets, you must create an
----
$ oc mirror init --registry example.com/mirror/oc-mirror-metadata > imageset-config.yaml <1>
----
<1> Replace `example.com/mirror/oc-mirror-metadata` with the location you have created for the storage backend image of oc-mirror on your mirror registry.
<1> Replace `example.com/mirror/oc-mirror-metadata` with the location of your registry for the storage backend.
. Edit the file and adjust the settings as necessary:
+
@@ -29,37 +36,35 @@ $ oc mirror init --registry example.com/mirror/oc-mirror-metadata > imageset-con
----
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
archiveSize: 4 #<1>
archiveSize: 4 <1>
storageConfig: <2>
registry:
imageURL: example.com/mirror/oc-mirror-metadata #<3>
imageURL: example.com/mirror/oc-mirror-metadata <3>
skipTLS: false
mirror:
platform:
channels:
- name: stable-{product-version} #<4>
- name: stable-{product-version} <4>
type: ocp
graph: true #<5>
graph: true <5>
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} #<6>
- catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version} <6>
packages:
- name: serverless-operator #<7>
- name: serverless-operator <7>
channels:
- name: stable #<8>
- name: stable <8>
additionalImages:
- name: registry.redhat.io/ubi9/ubi:latest #<9>
- name: registry.redhat.io/ubi9/ubi:latest <9>
helm: {}
----
<1> Add `archiveSize` to set the maximum size, in GiB, of each archive generated. This setup is only valid when mirroring to a fully disconnected environment.
<1> Add `archiveSize` to set the maximum size, in GiB, of each file within the image set.
<2> Set the back-end location to save the image set metadata to. This location can be a registry or local directory. It is required to specify `storageConfig` values.
<3> Set the registry URL for the storage backend.
<4> Set the channel to retrieve the {product-title} images from.
<5> Add `graph: true` to build and push the graph-data image to the mirror registry. The graph-data image is required to create OpenShift Update Service (OSUS). The `graph: true` field also generates the `UpdateService` custom resource manifest. The `oc` command-line interface (CLI) can use the `UpdateService` custom resource manifest to create OSUS. For more information, see "About the OpenShift Update Service".
<6> Set the Operator catalog to retrieve the {product-title} images from; retrieves the latest version of all Operators of this catalog.
<5> Add `graph: true` to build and push the graph-data image to the mirror registry. The graph-data image is required to create OpenShift Update Service (OSUS). The `graph: true` field also generates the `UpdateService` custom resource manifest. The `oc` command-line interface (CLI) can use the `UpdateService` custom resource manifest to create OSUS. For more information, see _About the OpenShift Update Service_.
<6> Set the Operator catalog to retrieve the {product-title} images from.
<7> Specify only certain Operator packages to include in the image set. Remove this field to retrieve all packages in the catalog.
<8> 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=<catalog_name> --package=<package_name>`.
<8> 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=<catalog_name> --package=<package_name>`.
<9> Specify any additional images to include in image set.
+
[NOTE]
@@ -67,7 +72,7 @@ You can find the default channel by running the following command:
The `graph: true` field also mirrors the `ubi-micro` image along with other mirrored images.
====
+
See "Image set configuration parameters" for the full list of parameters and "Image set configuration examples" for various mirroring use cases.
See _Image set configuration parameters_ for the full list of parameters and _Image set configuration examples_ for various mirroring use cases.
. Save the updated file.
+

17
modules/oc-mirror-disk-to-mirror.adoc
View File

@@ -5,18 +5,16 @@
:_mod-docs-content-type: PROCEDURE
[id="oc-mirror-disk-to-mirror_{context}"]
= Mirroring from disk-to-mirror
= Mirroring from disk to mirror
You can use the oc-mirror plugin v1 to mirror the contents of a generated image set to the target mirror registry.
You can use the oc-mirror plugin to mirror the contents of a generated image set to the target mirror registry.
.Prerequisites
* You have installed the OpenShift CLI (`oc`) in the disconnected environment.
* You have installed the `oc-mirror` CLI plugin v1 in the disconnected environment.
* You have installed the `oc-mirror` CLI plugin in the disconnected environment.
* You have generated the image set file by using the `oc mirror` command.
* You have access to the target mirror registry.
* You have transferred the image set file to the disconnected environment.
* You have set the umask parameter to `0022` on the operating system that uses oc-mirror plugin v1.
// TODO: Confirm prereq about not needing a cluster, but need pull secret misc
.Procedure
@@ -28,14 +26,9 @@ You can use the oc-mirror plugin v1 to mirror the contents of a generated image
$ oc mirror --from=./mirror_seq1_000000.tar \// <1>
docker://registry.example:5000 <2>
----
<1> Pass in the image set `.tar` file to mirror, named `mirror_seq1_000000.tar` in this example. If an `archiveSize` value was specified in the image set configuration file, the image set might be broken up into multiple `.tar` files. In this situation, you can pass in a directory that contains the image set `.tar` files.
<1> Pass in the image set .tar file to mirror, named `mirror_seq1_000000.tar` in this example. If an `archiveSize` value was specified in the image set configuration file, the image set might be broken up into multiple .tar files. In this situation, you can pass in a directory that contains the image set .tar files.
<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.
+
[NOTE]
====
The generated image sets follow a sequential order and must be pushed to the target mirror registry accordingly. You can determine the sequence number from the file name of the generated image set archive file.
====
+
This command updates the mirror registry with the image set and generates the `ImageContentSourcePolicy` and `CatalogSource` resources.
.Verification
@@ -52,5 +45,5 @@ This command updates the mirror registry with the image set and generates the `I
.Troubleshooting
* link:https://access.redhat.com/solutions/7032017[What to do when encountering "manifest unknown error: unable to retrieve source image" while using oc-mirror?]
* link:https://access.redhat.com/solutions/7032017[Unable to retrieve source image].

6
modules/oc-mirror-dry-run.adoc
View File

@@ -8,13 +8,13 @@
[id="oc-mirror-dry-run_{context}"]
= Performing a dry run
You can use oc-mirror plugin v1 to perform a dry run, without actually mirroring any images. This allows you to review the list of images that would be mirrored, as well as any images that would be pruned from the mirror registry. A dry run also allows you to catch any errors with your image set configuration early or use the generated list of images with other tools to carry out the mirroring operation.
You can use oc-mirror to perform a dry run, without actually mirroring any images. This allows you to review the list of images that would be mirrored, as well as any images that would be pruned from the mirror registry. A dry run also allows you to catch any errors with your image set configuration early or use the generated list of images with other tools to carry out the mirroring operation.
.Prerequisites
* You have access to the internet to obtain the necessary container images.
* You have installed the OpenShift CLI (`oc`).
* You have installed the `oc-mirror` CLI plugin v1.
* You have installed the `oc-mirror` CLI plugin.
* You have created the image set configuration file.
.Procedure
@@ -66,5 +66,5 @@ This file contains a list of all images that would be pruned from the mirror reg
+
[NOTE]
====
The `pruning-plan.json` file is only generated if your oc-mirror plugin v1 command points to your mirror registry and there are images to be pruned.
The `pruning-plan.json` file is only generated if your oc-mirror command points to your mirror registry and there are images to be pruned.
====

11
modules/oc-mirror-fully-disconnected.adoc
View File

@@ -1,11 +0,0 @@
// Module included in the following assemblies:
//
// * 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: CONCEPT
[id="oc-mirror-fully-disconnected_{context}"]
= Mirroring an image set in a fully disconnected environment
To mirror an image set in a fully disconnected environment, you must first mirror the image set to disk, then mirror the image set file on disk to a mirror.

132
modules/oc-mirror-image-set-config-examples.adoc
View File

@@ -5,21 +5,16 @@
:_mod-docs-content-type: REFERENCE
[id="oc-mirror-image-set-examples_{context}"]
= Optimizing the image set configuration
= Image set configuration examples
The following `ImageSetConfiguration` file examples show the configuration for various mirroring use cases.
[id="oc-mirror-image-set-example-specific-ocp-release_{context}"]
== Use case: Preparing for installing a specific {product-title} release
// Moved to first; unchanged
[discrete]
[id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
== Use case: Including the shortest {product-title} update path
See "About ImageSetConfiguration" for further information.
[NOTE]
====
Regularly running oc-mirror plugin v1 facilitates the automatic retrieval of the latest {product-title} releases.
====
The following example `ImageSetConfiguration` file uses a local storage backend, including all {product-title} versions from the minimum version of 4.15.13:
The following `ImageSetConfiguration` file uses a local storage backend and includes all {product-title} versions along the shortest update path from the minimum version of `4.11.37` to the maximum version of `4.12.15`.
.Example `ImageSetConfiguration` file
[source,yaml]
@@ -32,19 +27,20 @@ storageConfig:
mirror:
platform:
channels:
- name: stable-4.15
minVersion: 4.15.13
- name: stable-4.12
minVersion: 4.11.37
maxVersion: 4.12.15
shortestPath: true
----
[id="oc-mirror-image-set-example-multi-architecture_{context}"]
== Use case: Preparing for installing for multiple architectures
// Moved to second; unchanged
[discrete]
[id="oc-mirror-image-set-examples-minimum-to-latest_{context}"]
== Use case: Including all versions of {product-title} from a minimum to the latest version for multi-architecture releases
If you set the architectures to `multi` in the `imageSetConfiguration` file, it implies that the images in the set support multiple architectures.
The following `ImageSetConfiguration` file uses a registry storage backend and includes all {product-title} versions starting at a minimum version of `4.13.4` to the latest version in the channel. On every invocation of oc-mirror with this image set configuration, the latest release of the `stable-4.13` channel is evaluated, so running oc-mirror at regular intervals ensures that you automatically receive the latest releases of {product-title} images.
[NOTE]
====
The `multi` value only supports the {product-title} releases and not the Operators.
====
By setting the value of `platform.architectures` to `multi`, you can ensure that the mirroring is supported for multi-architecture releases.
.Example `ImageSetConfiguration` file
[source,yaml]
@@ -60,47 +56,25 @@ mirror:
architectures:
- "multi"
channels:
- name: stable-4.15
minVersion: 4.15.13
- name: stable-4.13
minVersion: 4.13.4
maxVersion: 4.13.6
----
[id="oc-mirror-image-set-examples-shortest-upgrade-path_{context}"]
== Use case: Preparing for an {product-title} upgrade including the shortest update path
The following `ImageSetConfiguration` file uses a local storage backend and includes all {product-title} versions along with the shortest update path from the minimum version of 4.14.25 to the maximum version of 4.15.13:
.Example `ImageSetConfiguration` file
[source,yaml]
----
apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration
storageConfig:
local:
path: /home/user/metadata
mirror:
platform:
channels:
- name: stable-4.15
minVersion: 4.14.25
maxVersion: 4.15.13
shortestPath: true
----
[IMPORTANT]
====
When using EUS channels and more than one channel is specified in the `imagesetconfig`, you might need to include non-EUS channels to make sure that all required intermediate versions are included in the `imageset`. See link:https://access.redhat.com/labs/ocpupgradegraph/update_path[Red Hat OpenShift Container Platform Update Graph] to check all versions forming the upgrade graph.
====
// Updated:
// - Added a note below about the maxVersion
// - Added a note about not necessarily getting all versions in the range
[discrete]
[id="oc-mirror-image-set-examples-operator-versions_{context}"]
== Use case: Including Operator versions from a minimum to the latest
The following `ImageSetConfiguration` file uses a local storage backend and includes only the Red Hat Advanced Cluster Security for Kubernetes Operator, versions starting at 4.0.1 and later regardless of the channel.
The following `ImageSetConfiguration` file uses a local storage backend and includes only the Red Hat Advanced Cluster Security for Kubernetes Operator, versions starting at 4.0.1 and later in the `stable` channel.
[NOTE]
====
When you specify a minimum or maximum version range, you might not receive all Operator versions in that range.
By default, oc-mirror plugin v1 excludes any versions that are skipped or replaced by a newer version in the Operator Lifecycle Manager (OLM) specification. Operator versions that are skipped might be affected by a CVE or contain bugs. Use a newer version instead. For more information on skipped and replaced versions, see link:https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/[Creating an update graph with OLM].
By default, oc-mirror excludes any versions that are skipped or replaced by a newer version in the Operator Lifecycle Manager (OLM) specification. Operator versions that are skipped might be affected by a CVE or contain bugs. Use a newer version instead. For more information on skipped and replaced versions, see link:https://olm.operatorframework.io/docs/concepts/olm-architecture/operator-catalog/creating-an-update-graph/[Creating an update graph with OLM].
To receive all Operator versions in a specified range, you can set the `mirror.operators.full` field to `true`.
====
@@ -118,15 +92,11 @@ mirror:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
packages:
- name: rhacs-operator
- minVersion: 4.0.1
channels:
- name: stable
minVersion: 4.0.1
----
In this example, if you set the `minVersion` to the latest possible version and omit the `maxVersion`, no additional versions are mirrored.
The oc-mirror plugin v1 automatically evaluates the latest Operator version with each use. Running the oc-mirror plugin v1 regularly ensures automatic updates to receive the latest versions of the Red Hat Advanced Cluster Security for Kubernetes Operator.
When selecting channels for your package, consider their suitability. Enabling all channels within `minVersion` and `maxVersion` or specifying only `minVersion` allows for gradual updates with minimal configuration changes.
[NOTE]
====
To specify a maximum version instead of the latest, set the `mirror.operators.packages.channels.maxVersion` field.
@@ -135,7 +105,6 @@ To specify a maximum version instead of the latest, set the `mirror.operators.pa
[discrete]
[id="oc-mirror-image-set-examples-nutanix-operator_{context}"]
== Use case: Including the Nutanix CSI Operator
The following `ImageSetConfiguration` file uses a local storage backend and includes the Nutanix CSI Operator, the OpenShift Update Service (OSUS) graph image, and an additional Red Hat Universal Base Image (UBI).
.Example `ImageSetConfiguration` file
@@ -163,12 +132,12 @@ mirror:
- name: registry.redhat.io/ubi9/ubi:latest
----
// New example; including the default channel
[discrete]
[id="oc-mirror-image-set-examples-default-channel_{context}"]
== Use case: Including an Operator version that is not available in the default channel
== Use case: Including the default Operator channel
To include an Operator version not available in the default channel, consider installing `aws-load-balancer-operator`, specifically version 0.2.0.
In the `ImageSetConfiguration` file, include the `stable-v0.2` and `stable-v1` channels for the AWS Load Balancer Operator. Even if only the packages from the `stable-v0.2` channel are needed, you must include the `stable-v1` channel in the `ImageSetConfiguration` file, as it is the default channel for the Operator. It's important to always include the default channel for the Operator package, even if you do not use the bundles in that channel.
The following `ImageSetConfiguration` file includes the `stable-5.7` and `stable` channels for the OpenShift Elasticsearch Operator. Even if only the packages from the `stable-5.7` channel are needed, the `stable` channel must also be included in the `ImageSetConfiguration` file, because it is the default channel for the Operator. You must always include the default channel for the Operator package even if you do not use the bundles in that channel.
[TIP]
====
@@ -186,22 +155,23 @@ storageConfig:
skipTLS: false
mirror:
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version}
- catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
packages:
- name: aws-load-balancer-operator
- name: elasticsearch-operator
channels:
- name: stable-v0.2
- name: stable-v1
- name: stable-5.7
- name: stable
----
[id="oc-mirror-image-set-examples-default-channel-alternative_{context}"]
== Use case: Alternative example to include an Operator version that is not available in the default channel
// New example; Entire catalog; all versions
[discrete]
[id="oc-mirror-image-set-examples-entire-catalog-full_{context}"]
== Use case: Including an entire catalog (all versions)
Another possibility is to redefine the default channel as follows:
The following `ImageSetConfiguration` file sets the `mirror.operators.full` field to `true` to include all versions for an entire Operator catalog.
.Example `ImageSetConfiguration` file
[source,yaml]
[source,yaml,subs=attributes+]
----
apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration
@@ -211,21 +181,19 @@ storageConfig:
skipTLS: false
mirror:
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version}
packages:
- name: aws-load-balancer-operator
defaultChannel: stable-v0.2 <1>
channels:
- name: stable-v0.2
- catalog: registry.redhat.io/redhat/redhat-operator-index:v{product-version}
full: true
----
<1> The value for `defaultChannel` must be specified in the `channels` list.
[id="oc-mirror-image-set-examples-entire-catalog-full_{context}"]
// New example; Entire catalog; heads only
// - Included 'targetCatalog' in example
[discrete]
[id="oc-mirror-image-set-examples-entire-catalog-heads_{context}"]
== Use case: Including an entire catalog (channel heads only)
The following `ImageSetConfiguration` file includes the channel heads for an entire Operator catalog.
By default, for each Operator in the catalog, oc-mirror plugin v1 includes the latest Operator version (channel head) from the default channel. If you want to mirror all Operator versions, and not just the channel heads, you must set the `mirror.operators.full` field to `true`.
By default, for each Operator in the catalog, oc-mirror includes the latest Operator version (channel head) from the default channel. If you want to mirror all Operator versions, and not just the channel heads, you must set the `mirror.operators.full` field to `true`.
This example also uses the `targetCatalog` field to specify an alternative namespace and name to mirror the catalog as.
@@ -244,6 +212,8 @@ mirror:
targetCatalog: my-namespace/my-operator-catalog
----
// Moved to last; unchanged
[discrete]
[id="oc-mirror-image-set-examples-helm_{context}"]
== Use case: Including arbitrary images and helm charts

85
modules/oc-mirror-imageset-config-params.adoc
View File

@@ -8,7 +8,7 @@
[id="oc-mirror-imageset-config-params_{context}"]
= Image set configuration parameters
The oc-mirror plugin v1 requires an image set configuration file that defines what images to mirror. The following table lists the available parameters for the `ImageSetConfiguration` resource.
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
@@ -21,13 +21,13 @@ The oc-mirror plugin v1 requires an image set configuration file that defines wh
|`apiVersion`
|The API version for the `ImageSetConfiguration` content.
|String. For example, `mirror.openshift.io/v1alpha2`.
|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`
|Integer. For example: `4`
endif::microshift[]
@@ -37,7 +37,7 @@ endif::microshift[]
|`mirror.additionalImages`
|The additional images configuration of the image set.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml]
----
@@ -47,11 +47,11 @@ additionalImages:
|`mirror.additionalImages.name`
|The tag or digest of the image to mirror.
|String. For example, `registry.redhat.io/ubi8/ubi:latest`
|String. For example: `registry.redhat.io/ubi8/ubi:latest`
|`mirror.blockedImages`
|The full tag, digest, or pattern of images to block from mirroring.
|Array of strings. For example, `docker.io/library/alpine`
|Array of strings. For example: `docker.io/library/alpine`
ifndef::microshift[]
@@ -61,7 +61,7 @@ ifndef::microshift[]
|`mirror.helm.local`
|The local helm charts to mirror.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml]
----
@@ -72,15 +72,15 @@ local:
|`mirror.helm.local.name`
|The name of the local helm chart to mirror.
|String. For example, `podinfo`.
|String. For example: `podinfo`.
|`mirror.helm.local.path`
|The path of the local helm chart to mirror.
|String. For example, `/test/podinfo-5.0.0.tar.gz`.
|String. For example: `/test/podinfo-5.0.0.tar.gz`.
|`mirror.helm.repositories`
|The remote helm repositories to mirror from.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml]
----
@@ -94,11 +94,11 @@ repositories:
|`mirror.helm.repositories.name`
|The name of the helm repository to mirror from.
|String. For example, `podinfo`.
|String. For example: `podinfo`.
|`mirror.helm.repositories.url`
|The URL of the helm repository to mirror from.
|String. For example, [x-]`https://example.github.io/podinfo`.
|String. For example: [x-]`https://example.github.io/podinfo`.
|`mirror.helm.repositories.charts`
|The remote helm charts to mirror.
@@ -106,17 +106,17 @@ repositories:
|`mirror.helm.repositories.charts.name`
|The name of the helm chart to mirror.
|String. For example, `podinfo`.
|String. For example: `podinfo`.
|`mirror.helm.repositories.charts.version`
|The version of the named helm chart to mirror.
|String. For example, `5.0.0`.
|String. For example: `5.0.0`.
endif::microshift[]
|`mirror.operators`
|The Operators configuration of the image set.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml,subs="attributes+"]
----
@@ -129,7 +129,7 @@ operators:
|`mirror.operators.catalog`
|The Operator catalog to include in the image set.
|String. For example, `registry.redhat.io/redhat/redhat-operator-index:v4.16`.
|String. For example: `registry.redhat.io/redhat/redhat-operator-index:v4.16`.
|`mirror.operators.full`
|When `true`, downloads the full catalog, Operator package, or Operator channel.
@@ -137,7 +137,7 @@ operators:
|`mirror.operators.packages`
|The Operator packages configuration.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml,subs="attributes+"]
----
@@ -150,7 +150,7 @@ operators:
|`mirror.operators.packages.name`
|The Operator package name to include in the image set
|String. For example, `elasticsearch-operator`.
|String. For example: `elasticsearch-operator`.
|`mirror.operators.packages.channels`
|The Operator package channel configuration.
@@ -158,32 +158,27 @@ operators:
|`mirror.operators.packages.channels.name`
|The Operator channel name, unique within a package, to include in the image set.
|String. For example, `fast` or `stable-v4.16`.
|String. For example: `fast` or `stable-v4.16`.
|`mirror.operators.packages.channels.maxVersion`
|The highest version of the Operator mirror across all channels in which it exists. See the note that follows the table for further information.
|String. For example, `5.2.3-31`
|The highest version of the Operator mirror across all channels in which it exists. See the following note for further information.
|String. For example: `5.2.3-31`
|`mirror.operators.packages.channels.minBundle`
|The name of the minimum bundle to include, plus all bundles in the update graph to the channel head. Set this field only if the named bundle has no semantic version metadata.
|String. For example, `bundleName`
|String. For example: `bundleName`
|`mirror.operators.packages.channels.minVersion`
|The lowest version of the Operator to mirror across all channels in which it exists. See the note that follows the table for further information.
|String. For example, `5.2.3-31`
|`mirrors.operators.packages.defaultChannel`
|The `defaultChannel` overrides the channel that is selected as default for this Operator in the catalog.
|String. For example, `stable-5.8`.
See "Use case: Including an operator version that is not available in the default channel" for an example.
|The lowest version of the Operator to mirror across all channels in which it exists. See the following note for further information.
|String. For example: `5.2.3-31`
|`mirror.operators.packages.maxVersion`
|The highest version of the Operator to mirror in this channel. See the following note for further information.
|String. For example, `5.2.3-31`.
|The highest version of the Operator to mirror across all channels in which it exists. See the following note for further information.
|String. For example: `5.2.3-31`.
|`mirror.operators.packages.minVersion`
|The lowest version of the Operator to mirror in this channel. See the note that follows the table for further information.
|String. For example, `5.2.3-31`.
|The lowest version of the Operator to mirror across all channels in which it exists. See the following note for further information.
|String. For example: `5.2.3-31`.
|`mirror.operators.skipDependencies`
|If `true`, dependencies of bundles are not included.
@@ -191,18 +186,18 @@ See "Use case: Including an operator version that is not available in the defaul
|`mirror.operators.targetCatalog`
|An alternative name and optional namespace hierarchy to mirror the referenced catalog as.
|String. For example, `my-namespace/my-operator-catalog`
|String. For example: `my-namespace/my-operator-catalog`
|`mirror.operators.targetName`
|An alternative name to mirror the referenced catalog as.
The `targetName` parameter is deprecated. Use the `targetCatalog` parameter instead.
|String. For example, `my-operator-catalog`
|String. For example: `my-operator-catalog`
|`mirror.operators.targetTag`
|An alternative tag to append to the `targetName` or `targetCatalog`.
|String. For example, `v1`
|String. For example: `v1`
ifndef::microshift[]
@@ -212,7 +207,7 @@ ifndef::microshift[]
|`mirror.platform.architectures`
|The architecture of the platform release payload to mirror.
|Array of strings. For example,
|Array of strings. For example:
[source,yaml]
----
@@ -228,7 +223,7 @@ The default value is `amd64`. The value `multi` ensures that the mirroring is su
|`mirror.platform.channels`
|The platform channel configuration of the image set.
|Array of objects. For example,
|Array of objects. For example:
[source,yaml,subs="attributes+"]
----
@@ -243,15 +238,15 @@ channels:
|`mirror.platform.channels.name`
|The name of the release channel.
|String. For example, `stable-4.16`
|String. For example: `stable-4.16`
|`mirror.platform.channels.minVersion`
|The minimum version of the referenced platform to be mirrored.
|String. For example, `4.12.6`
|String. For example: `4.12.6`
|`mirror.platform.channels.maxVersion`
|The highest version of the referenced platform to be mirrored.
|String. For example, `4.16.1`
|String. For example: `4.16.1`
|`mirror.platform.channels.shortestPath`
|Toggles shortest path mirroring or full range mirroring.
@@ -259,7 +254,7 @@ channels:
|`mirror.platform.channels.type`
|The type of the platform to be mirrored.
|String. For example, `ocp` or `okd`. The default is `ocp`.
|String. For example: `ocp` or `okd`. The default is `ocp`.
|`mirror.platform.graph`
|Indicates whether the OSUS graph is added to the image set and subsequently published to the mirror.
@@ -277,7 +272,7 @@ endif::microshift[]
|`storageConfig.local.path`
|The path of the directory to contain the image set metadata.
|String. For example, `./path/to/dir/`.
|String. For example: `./path/to/dir/`.
|`storageConfig.registry`
|The registry back-end configuration of the image set.
@@ -285,7 +280,7 @@ endif::microshift[]
|`storageConfig.registry.imageURL`
|The back-end registry URI. Can optionally include a namespace reference in the URI.
|String. For example, `quay.io/myuser/imageset:metadata`.
|String. For example: `quay.io/myuser/imageset:metadata`.
|`storageConfig.registry.skipTLS`
|Optionally skip TLS verification of the referenced back-end registry.
@@ -297,7 +292,7 @@ endif::microshift[]
====
Using the `minVersion` and `maxVersion` properties to filter for a specific Operator version range can result in a multiple channel heads error. The error message states that there are `multiple channel heads`. This is because when the filter is applied, the update graph of the Operator is truncated.
Operator Lifecycle Manager [OLM] requires that every Operator channel contains versions that form an update graph with exactly one end point, that is, the latest version of the Operator. When the filter range is applied, that graph can turn into two or more separate graphs or a graph that has more than one end point.
Operator Lifecycle Manager requires that every Operator channel contains versions that form an update graph with exactly one end point, that is, the latest version of the Operator. When the filter range is applied, that graph can turn into two or more separate graphs or a graph that has more than one end point.
To avoid this error, do not filter out the latest version of an Operator. If you still run into the error, depending on the Operator, either the `maxVersion` property must be increased or the `minVersion` property must be decreased. Because every Operator graph can be different, you might need to adjust these values until the error resolves.
====

15
modules/oc-mirror-installing-plugin.adoc
View File

@@ -11,23 +11,22 @@
* You have installed the OpenShift CLI (`oc`). If you are mirroring image sets in a fully disconnected environment, ensure the following:
** You have installed the oc-mirror plugin v1 on the host that has internet access.
** You have installed the oc-mirror plugin on the host that has internet access.
** The host in the disconnected environment has access to the target mirror registry.
* You have set the `umask` parameter to `0022` on the operating system that uses oc-mirror.
* You have installed the correct binary for the {op-system-base} version that you are using.
.Procedure
. Download the oc-mirror CLI plugin v1:
. Download the oc-mirror CLI plugin.
.. Navigate to the link:https://console.redhat.com/openshift/downloads[Downloads] page of the {cluster-manager-url}.
.. Under the *OpenShift disconnected installation tools* section, follow the steps to save the file:
* Select your operating system and architecture type:
** Choose *{op-system-base-full} 9* for FIPS compliance.
* Click *Download* to get the oc-mirror plugin v1 and save the file.
.. Under the *OpenShift disconnected installation tools* section, click *Download* for *OpenShift Client (oc) mirror plugin* and save the file.
. Extract the archive:
+
@@ -36,7 +35,7 @@
$ tar xvzf oc-mirror.tar.gz
----
. If necessary, update the oc-mirror plugin v1 file to be executable:
. If necessary, update the plugin file to be executable:
+
[source,terminal]
----
@@ -57,7 +56,7 @@ $ sudo mv oc-mirror /usr/local/bin/.
.Verification
* Run the `oc mirror help` command to verify that the oc-mirror plugin v1 was successfully installed:
* Run `oc mirror help` to verify that the plugin was successfully installed:
+
[source,terminal]
----

16
modules/oc-mirror-mirror-to-disk.adoc
View File

@@ -5,31 +5,30 @@
:_mod-docs-content-type: PROCEDURE
[id="oc-mirror-mirror-to-disk_{context}"]
= Mirroring from mirror-to-disk
= Mirroring from mirror to disk
You can use the oc-mirror plugin v1 to generate an image set and save the contents to disk. The generated image set can then be transferred to the disconnected environment and mirrored to the target registry.
You can use the oc-mirror plugin to generate an image set and save the contents to disk. The generated image set can then be transferred to the disconnected environment and mirrored to the target registry.
[IMPORTANT]
====
Depending on the configuration specified in the image set configuration file, using oc-mirror to mirror images might download several hundreds of gigabytes of data to disk.
When configuring the mirror registry, the initial image set tends to be the largest. Subsequent uses of the oc-mirror plugin v1 result in smaller downloads, as only the changed images are retrieved since the last execution.
The initial image set download when you populate the mirror registry is often the largest. Because you only download the images that changed since the last time you ran the command, when you run the oc-mirror plugin again, the generated image set is often smaller.
====
You must specify a storage backend in the image set configuration file. See "Setting up incremental mirroring".
You are required to specify a storage backend in the image set configuration file. This storage backend can be a local directory or a docker v2 registry. The oc-mirror plugin stores metadata in this storage backend during image set creation.
[IMPORTANT]
====
Do not delete or modify the metadata that is generated by the oc-mirror plugin v1. You must use the same storage backend every time you run the oc-mirror plugin v1 for the same mirror registry.
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.
====
.Prerequisites
* You have access to the internet to obtain the necessary container images.
* You have installed the OpenShift CLI (`oc`).
* You have installed the `oc-mirror` CLI plugin v1.
* You have installed the `oc-mirror` CLI plugin.
* You have created the image set configuration file.
* You have set the umask parameter to `0022` on the operating system that uses oc-mirror plugin v1.
// TODO: Don't need a running cluster, but need some pull secrets. Sync w/ team on this
.Procedure
@@ -72,4 +71,5 @@ mirror_seq1_000000.tar
.Troubleshooting
* link:https://access.redhat.com/solutions/7032017[What to do when encountering "manifest unknown error: unable to retrieve source image" while using oc-mirror?]
* link:https://access.redhat.com/solutions/7032017[Unable to retrieve source image].

19
modules/oc-mirror-mirror-to-mirror.adoc
View File

@@ -6,28 +6,23 @@
:_mod-docs-content-type: PROCEDURE
[id="oc-mirror-mirror-to-mirror_{context}"]
= Mirroring an image set in a partially disconnected environment:
= Mirroring from mirror to mirror
You can use the oc-mirror plugin v1 to mirror an image set directly to a target mirror registry that is accessible during image set creation.
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.
[NOTE]
====
You must specify a storage backend in the image set configuration file. See "Setting up incremental mirroring".
====
You are required to specify a storage backend in the image set configuration file. This storage backend can be a local directory or a Docker v2 registry. The oc-mirror plugin stores metadata in this storage backend during image set creation.
[IMPORTANT]
====
Do not delete or modify the metadata that is generated by the oc-mirror plugin v1. You must use the same storage backend every time you run the oc-mirror plugin v1 for the same mirror registry.
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.
====
.Prerequisites
* You have access to the internet to get the necessary container images.
* You have access to the target mirror registry.
* You have installed the OpenShift CLI (`oc`).
* You have installed the `oc-mirror` CLI plugin v1.
* You have installed the `oc-mirror` CLI plugin.
* You have created the image set configuration file.
* You have set the umask parameter to `0022` on the underlying operating system that uses oc-mirror plugin v1.
.Procedure
@@ -75,8 +70,8 @@ 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 the oc-mirror plugin. See "Configuring your cluster to use the resources generated by oc-mirror".
* Configure your cluster to use the resources generated by oc-mirror.
.Troubleshooting
* link:https://access.redhat.com/solutions/7032017[What to do when encountering "manifest unknown error: unable to retrieve source image" while using oc-mirror?]
* link:https://access.redhat.com/solutions/7032017[Unable to retrieve source image].

15
modules/oc-mirror-mirroring-image-set.adoc
View File

@@ -1,15 +0,0 @@
// Module included in the following assemblies:
//
// * 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: CONCEPT
[id="mirroring-image-set_{context}"]
= Mirroring an image set to a mirror registry
To populate your mirror registry with {product-title} images, you can use one of the following scenarios:
* *Partially disconnected environment*: The host can access both the internet and your mirror registry, but not your cluster nodes. This setup enables you to mirror content directly from the host machine.
* *Fully disconnected environment*: The host cannot access the internet, your mirror registry, or the cluster nodes. In this setup, you must mirror the images to a file system and then bring that host or removable media into your restricted environment.

11
modules/oc-mirror-oci-format.adoc
View File

@@ -15,16 +15,21 @@ The local catalog and its contents are mirrored to your target mirror registry b
====
When mirroring local OCI catalogs, any {product-title} releases or additional images that you want to mirror along with the local OCI-formatted catalog must be pulled from a registry.
You cannot mirror OCI catalogs along with an oc-mirror plugin v1 image set file on disk.
You cannot mirror OCI catalogs along with an oc-mirror image set file on disk.
====
One example use case for using the OCI feature is if you have a CI/CD system building an OCI catalog to a location on disk, and you want to mirror that OCI catalog along with an {product-title} release to your mirror registry.
[NOTE]
====
If you used the Technology Preview OCI local catalogs feature for the oc-mirror plugin for {product-title} 4.12, you can no longer use the OCI local catalogs feature of the oc-mirror plugin to copy a catalog locally and convert it to OCI format as a first step to mirroring to a fully disconnected cluster.
====
.Prerequisites
* You have access to the internet to obtain the necessary container images.
* You have installed the OpenShift CLI (`oc`).
* You have installed the `oc-mirror` CLI plugin v1.
* You have installed the `oc-mirror` CLI plugin.
.Procedure
@@ -95,4 +100,4 @@ Optionally, you can specify other flags to adjust the behavior of the OCI featur
.Next steps
* Configure your cluster to use the resources generated by oc-mirror plugin v1.
* Configure your cluster to use the resources generated by oc-mirror.

53
modules/oc-mirror-setting-incremental-mirroring.adoc
View File

@@ -1,53 +0,0 @@
// Module included in the following assemblies:
//
// * installing/disconnected_install/installing-mirroring-disconnected.adoc
:_mod-docs-content-type: PROCEDURE
[id="setting-incremental-mirroring_{context}"]
= Setting up for incremental mirroring
You mirror images to install, upgrade, and maintain {product-title} in a disconnected environment. Because the volume of the image set needed to install or upgrade {product-title} can be substantial, oc-mirror plugin v1 stores the metadata of the previously mirrored images in its storage backend thus reducing the volume of the image sets to the recent images only.
You can specify the following storage backends:
* A local directory
+
[NOTE]
====
Using a local directory is not recommended for enterprise scenarios because it does not scale effectively. This method is suitable only for small-scale environments or testing purposes.
====
+
.Example `ImageSetConfiguration` file
[source,terminal]
----
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
storageConfig:
local:
path: <oc_mirror_workspace> <1>
----
<1> Specify your target workspace path.
* A registry that supports Docker v2-2
+
.Example `ImageSetConfiguration` file
[source,terminal]
----
kind: ImageSetConfiguration
apiVersion: mirror.openshift.io/v1alpha2
storageConfig:
registry:
imageURL: <storage_backend> <1>
skipTLS: false
----
<1> Specifies the location of your storage backend, such as `example.com/mirror/oc-mirror-metadata`.
When mirroring content with the oc-mirror plugin v1, consider the following:
* Ensure you always use the same storage backend and the same image set configuration for a given mirror registry location, so that the metadata remains consistent.
* Do not attempt to push or prune images of that mirror registry location manually, without using oc-mirror plugin v1.
* Do not delete or modify the metadata that is generated by the oc-mirror plugin v1.
* Keep a backup of the storage backend when mirroring content to a given location on your mirror registry with the oc-mirror plugin v1.

4
modules/oc-mirror-support.adoc
View File

@@ -7,11 +7,11 @@
[id="oc-mirror-support_{context}"]
= oc-mirror compatibility and support
The oc-mirror plugin v1 supports mirroring {product-title} payload images and Operator catalogs for {product-title} versions 4.12 and later.
The oc-mirror plugin supports mirroring {product-title} payload images and Operator catalogs for {product-title} versions 4.10 and later.
[NOTE]
====
On `aarch64`, `ppc64le`, and `s390x` architectures the oc-mirror plugin v1 is only supported for {product-title} versions 4.14 and later.
On `aarch64`, `ppc64le`, and `s390x` architectures the oc-mirror plugin is only supported for {product-title} versions 4.14 and later.
====
Use the latest available version of the oc-mirror plugin regardless of which versions of {product-title} you need to mirror.

4
modules/oc-mirror-updating-cluster-manifests.adoc
View File

@@ -9,9 +9,7 @@
After you have mirrored your image set to the mirror registry, you must apply the generated `ImageContentSourcePolicy`, `CatalogSource`, and release image signature resources into the cluster.
If you set `graph:true` in your `ImageSetConfiguration` file, the oc-mirror plugin v1 generates an `UpdateService.yaml` file. The `UpdateService` resource can be used to configure the OSUS service on the cluster side. See "About the OpenShift Update Service" for more information.
The `ImageContentSourcePolicy` resource associates the mirror registry with the source registry and redirects image pull requests from the online registries to the mirror registry. The `CatalogSource` resource is used by OLM to retrieve information about the available Operators in the mirror registry. The release image signatures are used to verify the mirrored release images.
The `ImageContentSourcePolicy` resource associates the mirror registry with the source registry and redirects image pull requests from the online registries to the mirror registry. The `CatalogSource` resource is used by Operator Lifecycle Manager (OLM) to retrieve information about the available Operators in the mirror registry. The release image signatures are used to verify the mirrored release images.
.Prerequisites

20
modules/oc-mirror-updating-registry-about.adoc
View File

@@ -7,24 +7,24 @@
[id="oc-mirror-updating-registry-about_{context}"]
= Updating your mirror registry content
In order to upgrade your disconnected {product-title} cluster, you must update your mirror registry content with updated content from the Red Hat registries.
You can update your registry content by updating the image set configuration file and mirroring the image set to the mirror registry. Every time you run the oc-mirror plugin v1, an image set is generated that only contains new and updated images since the previous execution.
You can update your mirror registry content by updating the image set configuration file and mirroring the image set to the mirror registry. The next time that you run the oc-mirror plugin, an image set is generated that only contains new and updated images since the previous execution.
While updating the mirror registry, you must take into account the following considerations:
* Images are pruned from the target mirror registry if they are no longer included in the latest image set that was generated and mirrored. Therefore, ensure that you are updating images for the same combination of the following key components:
* Images are pruned from the target mirror registry if they are no longer included in the latest image set that was generated and mirrored. Therefore, ensure that you are updating images for the same combination of the following key components so that only a differential image set is created and mirrored:
** Image set configuration: Modify your existing `ImageSetConfiguration` file to update channels and version selections to align with the desired content in your disconnected registry after completing the mirror operation.
** Image set configuration
** Target mirror registry: If you specified a top-level namespace for the mirror registry during the initial image set creation, use the same namespace every time you run the oc-mirror plugin v1 for that mirror registry.
** Destination registry
** Storage configuration: Retain the exact metadata, either container image or file directory, from your `storageConfig` across runs on the connected side.
** Storage configuration
* The images can be pruned during the disk-to-mirror or mirror-to-mirror workflow.
* The images can be pruned in case of disk to mirror or mirror to mirror workflow.
* The generated image sets must be pushed to the target mirror registry in sequence. You can derive the sequence number from the file name of the generated image set archive file.
* Do not delete or modify the metadata image that is generated by the oc-mirror plugin v1.
* Do not delete or modify the metadata image that is generated by the oc-mirror plugin.
For more information about the workflow to update the mirror registry content, see "High level workflow" section.
* If you specified a top-level namespace for the mirror registry during the initial image set creation, then you must use this same namespace every time you run the oc-mirror plugin for the same mirror registry.
For more information about the workflow to update the mirror registry content, see the "High level workflow" section.

90
modules/oc-mirror-updating-use-cases.adoc
View File

@@ -6,9 +6,10 @@
[id="oc-mirror-image-set-examples-add-images_{context}"]
= Mirror registry update examples
This section covers the use cases for updating the mirror registry by using the disk-to-mirror workflows.
This section covers the use cases for updating the mirror registry from disk to mirror.
.Example `ImageSetConfiguration` file that was previously used for mirroring:
.Example `ImageSetConfiguration` file that was previously used for mirroring
[source, yaml]
----
apiVersion: mirror.openshift.io/v1alpha2
@@ -28,15 +29,13 @@ mirror:
- name: rhacs-operator
channels:
- name: stable
minVersion: 1.0.1
----
[id="mirror-latest-version-upgrading_{context}"]
== Upgrading to the latest {product-title} version
[discrete]
== Mirroring a specific {product-title} version by pruning the existing images
You can upgrade to the latest {product-title} version by running the mirroring workflow without changing the `ImageSetConfiguration` file.
.Updated `ImageSetConfiguration` file:
.Updated `ImageSetConfiguration` file
[source,yaml]
----
apiVersion: mirror.openshift.io/v1alpha2
@@ -47,60 +46,21 @@ storageConfig:
mirror:
platform:
channels:
- name: stable-4.12
minVersion: 4.12.1
maxVersion: 4.12.1
- name: stable-4.14
- name: stable-4.13 #<1>
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.14
packages:
- name: rhacs-operator
channels:
- name: stable
minVersion: 1.0.1
----
<1> Replacing by `stable-4.13` prunes all the images of `stable-4.12`.
This image set configuration mirrors all the necessary {product-title} releases for upgrading the cluster from version 4.12.1 to the latest version in the `stable-4.14` channel.
[discrete]
== Updating to the latest version of an Operator by pruning the existing images
When adding `stable-4.14` alongside 4.12.1 while you are still using 4.12.1, note that a cluster reboot may occur after a mirror refresh, but before an upgrade, due to routine operations. It is crucial to ensure that you have the images you are currently using.
.Updated `ImageSetConfiguration` file:
[id="mirror-specific-version-prune-existing_{context}"]
== Mirroring a specific {product-title} version and pruning the existing images
You can mirror a specific {product-title} version while pruning images from an older version. In this scenario, you remove the images of {product-title} 4.12.1, as the cluster was previously upgraded to 4.14.25 during the prior mirroring process.
.Updated `ImageSetConfiguration` file
[source,yaml]
----
apiVersion: mirror.openshift.io/v1alpha2
kind: ImageSetConfiguration
storageConfig:
local:
path: /home/user/metadata
mirror:
platform:
channels:
- name: stable-4.14 <1>
minVersion: 4.14.25
- name: stable-4.15
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.14
packages:
- name: rhacs-operator
channels:
- name: stable
minVersion: 1.0.1
----
<1> Replacing `stable-4.12` with `stable-4.14` prunes all the images of `stable-4.12`.
[id="mirror-latest-version-prune-existing_{context}"]
== Updating to the latest version of an Operator and pruning the existing images
You can update to the latest version of an Operator while pruning existing images using an updated `ImageSetConfiguration` file. By following this method, you ensure that only the necessary images for the specific upgrade path are retained.
If the initial `ImageSetConfiguration` file contains only a specified `minVersion`, oc-mirror plugin v1 includes these versions and valid upgrade paths in its processing. To ensure only the latest versions are mirrored, and oc-mirror plugin v1 retains only the images necessary for the specific upgrade path, avoid specifying any `minVersion`.
.Updated `ImageSetConfiguration` file
[source,yaml,subs=attributes+]
----
apiVersion: mirror.openshift.io/v1alpha2
@@ -119,15 +79,17 @@ mirror:
packages:
- name: rhacs-operator
channels:
- name: stable
- name: stable #<1>
----
<1> Using the same channel without specifying a version prunes the existing images and updates with the latest version of images.
[discrete]
[id="oc-mirror-image-set-examples-operator-pruning-versions_{context}"]
== Mirroring a new Operator and pruning the existing Operator
== Mirroring a new Operator by pruning the existing Operator
You can mirror a new Operator and prune an existing one using an `ImageSetConfiguration` file.
.Updated `ImageSetConfiguration` file:
.Updated `ImageSetConfiguration` file
[source,yaml,subs=attributes+]
----
apiVersion: mirror.openshift.io/v1alpha2
@@ -148,15 +110,13 @@ mirror:
channels:
- name: stable
----
<1> Replacing `rhacs-operator` with `<new_operator_name>` prunes the Red Hat Advanced Cluster Security for Kubernetes Operator.
<1> Replacing `rhacs-operator` with `new_operator_name` prunes the Red Hat Advanced Cluster Security for Kubernetes Operator.
[discrete]
== Pruning all the {product-title} images
[id="mirror-non-ideal-practice-pruning_{context}"]
== Pruning All {product-title} Images
.Updated `ImageSetConfiguration` file:
You can prune all {product-title} images by running the mirroring workflow without altering the `ImageSetConfiguration` file.
.Updated `ImageSetConfiguration` file
[source,yaml,subs=attributes+]
----
apiVersion: mirror.openshift.io/v1alpha2
@@ -165,11 +125,9 @@ storageConfig:
local:
path: /home/user/metadata
mirror:
platform:
channels:
operators:
- catalog: registry.redhat.io/redhat/redhat-operator-index:v4.14
packages:
----
If you remove the platform section from your `ImageSetConfiguration` file, the `oc-mirror` plugin v1 removes all {product-title} images from the mirror registry. This action may disrupt the cluster's functionality, especially during a cluster reboot due to a `MachineConfiguration` change or other routine tasks.
To avoid unintended disruptions, use the `--dry-run` flag with the mirror-to-mirror or disk-to-mirror workflows. Running `--dry-run` allows you to verify the intended actions and ensure they do not negatively impact any disconnected clusters, even if you choose to skip pruning during the actual workflow.
----