diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 3177c8514853..d6bcf854af5d 100644 --- a/_topic_maps/_topic_map.yml +++ b/_topic_maps/_topic_map.yml @@ -130,9 +130,9 @@ Topics: File: installing-mirroring-creating-registry - Name: Mirroring images for a disconnected installation File: installing-mirroring-installation-images - - Name: Mirroring images for a disconnected installation using the oc-mirror plugin + - Name: Mirroring images for a disconnected installation using the oc-mirror plugin v1 File: installing-mirroring-disconnected - - Name: Mirroring images for a disconnected installation using oc-mirror V2 + - Name: Mirroring images for a disconnected installation using oc-mirror plugin v2 File: about-installing-oc-mirror-v2 - Name: Installing on Alibaba Dir: installing_alibaba diff --git a/installing/disconnected_install/about-installing-oc-mirror-v2.adoc b/installing/disconnected_install/about-installing-oc-mirror-v2.adoc index 39f43e65608c..512982d3a09a 100644 --- a/installing/disconnected_install/about-installing-oc-mirror-v2.adoc +++ b/installing/disconnected_install/about-installing-oc-mirror-v2.adoc @@ -1,21 +1,36 @@ :_mod-docs-content-type: ASSEMBLY [id="about-installing-oc-mirror-v2"] -= Mirroring images for a disconnected installation using the version 2 += Mirroring images for a disconnected installation by using the oc-mirror plugin v2 include::_attributes/common-attributes.adoc[] :context: installing-mirroring-disconnected toc::[] -:FeatureName: oc-mirror version 2 +You can run your cluster in a restricted network without direct internet connectivity if you install the cluster from a mirrored set of {product-title} container images in a private registry. This registry must be running whenever your cluster is running. + +Just as you can use the `oc-mirror` OpenShift CLI (`oc`) plugin, you can also use oc-mirror plugin v2 to mirror images to a mirror registry in your fully or partially disconnected environments. To download the required images from the official Red Hat registries, you must run oc-mirror plugin v2 from a system with internet connectivity. + +:FeatureName: oc-mirror plugin v2 include::snippets/technology-preview.adoc[] -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 provided that the cluster is running. See "Prerequisites" section for more information. +[id="prerequisites_oc-mirror-v2_{context}"] +== Prerequisites -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. +* You must have a container image registry that supports link:https://docs.docker.com/registry/spec/manifest-v2-2[Docker V2-2] in the location that hosts the {product-title} cluster, such as {quay}. ++ +[NOTE] +==== +If you use {quay}, use version 3.6 or later with the oc-mirror plugin. See the documentation on link:https://access.redhat.com/documentation/en-us/red_hat_quay/3/html/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index[Deploying the Red Hat Quay Operator on OpenShift Container Platform (Red Hat Quay documentation)]. If you need additional assistance selecting and installing a registry, contact your sales representative or Red Hat Support. +==== + +[Optional] +* If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry. You can use this registry to mirror the necessary container images of {product-title} for disconnected installations. + +* Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation, might fail. Mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters. .High level workflow -The following steps outline the high-level workflow on how to use the oc-mirror plugin to mirror images to a mirror registry: +The following steps outline the high-level workflow on how to mirror images to a mirror registry by using the oc-mirror plugin v2: . Create an image set configuration file. @@ -23,31 +38,48 @@ The following steps outline the high-level workflow on how to use the oc-mirror ** Mirror an image set directly to the target mirror registry (Mirror-to-Mirror). -** Mirror an image set to disk (Mirror-to-Disk), transfer the tar file to the target environment, then mirror the image set to the target mirror registry (Disk-to-Mirror). +** Mirror an image set to disk (Mirror-to-Disk), transfer the `tar` file to the target environment, then mirror the image set to the target mirror registry (Disk-to-Mirror). -. Configure your cluster to use the resources generated by the oc-mirror. +. Configure your cluster to use the resources generated by the oc-mirror plugin v2. . Repeat these steps to update your target mirror registry as necessary. -// AboutVv2 + +// About oc-mirror plugin v2 include::modules/oc-mirror-v2-about.adoc[leveloffset=+1] // oc-mirror compatibility and support -include::modules/oc-mirror-v2-support.adoc[leveloffset=+1] +include::modules/oc-mirror-v2-support.adoc[leveloffset=+2] +//Delete Feature +// workflows of delete feature +include::modules/oc-mirror-workflows-delete-v2.adoc[leveloffset=+1] -[id="prerequisites_oc-mirror-v2_{context}"] -== Prerequisites +// procedure for delete feature +include::modules/oc-mirror-procedure-delete-v2.adoc[leveloffset=+2] -* 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. -==== +// About dry-run +include::modules/oc-mirror-v2-about-dry-run.adoc[leveloffset=+1] + +// Performing Dry-run for V2 +include::modules/oc-mirror-dry-run-v2.adoc[leveloffset=+2] + +//oc-mirror-enclave-support-about +include::modules//oc-mirror-enclave-support-about.adoc[leveloffset=+1] + +// How to mirror to an Enclave +include::modules/oc-mirror-enclave-support.adoc[leveloffset=+2] + +[id="additional-resources"] +== Additional resources + +* xref:../../updating/updating_a_cluster/updating_disconnected_cluster/disconnected-update-osus.html[Updating a cluster in a disconnected environment using the OpenShift Update Service]. -If you do not have an existing solution for a container image registry, {product-title} subscribers receive a mirror registry for Red Hat OpenShift. This mirror registry is included with your subscription and serves as a small-scale container registry that can be used to mirror the necessary container images of {product-title} for disconnected installations. +//operator catalog filtering +include::modules/oc-mirror-operator-catalog-filtering.adoc[leveloffset=+1] -* Every machine in the provisioned clusters must have access to the mirror registry. If the registry is unreachable, tasks like installation, updating, or routine operations such as workload relocation may fail. Therefore, mirror registries must be operated in a highly available manner, ensuring their availability aligns with the production availability of your {product-title} clusters. +//Image set configuration parameters +include::modules/oc-mirror-imageset-config-parameters-v2.adoc[leveloffset=+1] -* You have set the umask parameter to `0022` on the operating system that uses oc-mirror. \ No newline at end of file +// Command reference for oc-mirror v2 +include::modules/oc-mirror-command-reference-v2.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/oc-mirror-command-reference-v2.adoc b/modules/oc-mirror-command-reference-v2.adoc new file mode 100644 index 000000000000..e63c74e7404b --- /dev/null +++ b/modules/oc-mirror-command-reference-v2.adoc @@ -0,0 +1,80 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + + +:_mod-docs-content-type: REFERENCE +[id="oc-mirror-command-reference-v2_{context}"] += Command reference for oc-mirror plugin v2 + +The following tables describe the `oc mirror` subcommands and flags for oc-mirror plugin v2: + +.Subcommands and flags for the oc-mirror plugin v2: +[cols="1,2",options="header"] +|=== +|Subcommand +|Description + +|`help` +|Show help about any subcommand + +|`version` +|Output the oc-mirror version + +|`delete` +|Deletes images in remote registry and local cache. + +|=== + +.oc mirror flags +[cols="1,2",options="header"] +|=== +|Flag +|Description + +|`--authfile` +|Displays the string path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`. + +|`-c`, `--config` `` +|Specifies the path to an image set configuration file. + +|`--dest-tls-verify` +|Requires HTTPS and verifies certificates when accessing the container registry or daemon. + +|`--dry-run` +|Prints actions without mirroring images + +|`--from ` +|Specifies the path to an image set archive that was generated by executing oc-mirror plugin v2 to load a target registry. + +|`-h`, `--help` +|Displays help + +|`--loglevel` +|Displays string log levels. Supported values include info, debug, trace, error. The default is `info`. + +|`-p`, `--port` +|Determines the HTTP port used by oc-mirror plugin v2 local storage instance. The default is `55000`. + +|`--max-nested-paths ` +|Specifies the maximum number of nested paths for destination registries that limit nested paths. The default is `0`. + +|`--secure-policy` +|Default value is `false`. If you set a non-default value, the command enables signature verification, which is the secure policy for signature verification. + +|`--since` +|Includes all new content since a specified date (format: `yyyy-mm-dd`). When not provided, new content since previous mirroring is mirrored. + +|`--src-tls-verify` +|Requires HTTPS and verifies certificates when accessing the container registry or daemon. + +|`--strict-archive` +|Default value is `false`. If you set a value, the command generates archives that are strictly less than the `archiveSize` that was set in the `imageSetConfig` custom resource (CR). Mirroring exist in error if a file being archived exceeds `archiveSize` (GB). + +|`-v`, `--version` +|Displays the version for oc-mirror plugin v2. + +|`--workspace` +|Determines string oc-mirror plugin v2 workspace where resources and internal artifacts are generated. + +|=== \ No newline at end of file diff --git a/modules/oc-mirror-dry-run-v2.adoc b/modules/oc-mirror-dry-run-v2.adoc new file mode 100644 index 000000000000..8c1c6de9648d --- /dev/null +++ b/modules/oc-mirror-dry-run-v2.adoc @@ -0,0 +1,55 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + + +:_mod-docs-content-type: PROCEDURE +[id="oc-mirror-dry-run-v2_{context}"] += Performing dry run for oc-mirror plugin v2 + +To perform a dry run and verify your image set configuration without mirroring any images, follow the procedure. + +.Procedure + +* To perform a test run, run the `oc mirror` command and append the `--dry-run` argument to the command: ++ +[source,terminal] +---- +$ oc mirror -c --from file:// docker:// --dry-run --v2 +---- +Where: +- ``: Use the image set configuration file that you just created. +- ``: Insert the address of the workspace path. +- ``: Insert the URL or address of the remote container registry from which images will be deleted. ++ +.Example output +[source,terminal] +---- +$ oc mirror --config /tmp/isc_dryrun.yaml file:// --dry-run --v2 + +[INFO] : :warning: --v2 flag identified, flow redirected to the oc-mirror v2 version. This is Tech Preview, it is still under development and it is not production ready. +[INFO] : :wave: Hello, welcome to oc-mirror +[INFO] : :gear: setting up the environment for you... +[INFO] : :twisted_rightwards_arrows: workflow mode: mirrorToDisk +[INFO] : :sleuth_or_spy: going to discover the necessary images... +[INFO] : :mag: collecting release images... +[INFO] : :mag: collecting operator images... +[INFO] : :mag: collecting additional images... +[WARN] : :warning: 54/54 images necessary for mirroring are not available in the cache. +[WARN] : List of missing images in : CLID-19/working-dir/dry-run/missing.txt. +please re-run the mirror to disk process +[INFO] : :page_facing_up: list of all images for mirroring in : CLID-19/working-dir/dry-run/mapping.txt +[INFO] : mirror time : 9.641091076s +[INFO] : :wave: Goodbye, thank you for using oc-mirror +---- + +.Verification + +. Navigate to the workspace directory that was generated: ++ +[source,terminal] +---- +$ cd +---- + +. Review the `mapping.txt` and `missing.txt` files that were generated. These files contain a list of all images that would be mirrored. \ No newline at end of file diff --git a/modules/oc-mirror-enclave-support-about.adoc b/modules/oc-mirror-enclave-support-about.adoc new file mode 100644 index 000000000000..adb551a9eb7a --- /dev/null +++ b/modules/oc-mirror-enclave-support-about.adoc @@ -0,0 +1,22 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-mirror-enclave-support-about_{context}"] += Benefits of enclave support + +Enclave support restricts internal access to a specific part of a network. Unlike a demilitarized zone (DMZ) network, which allows inbound and outbound traffic access through firewall boundaries, enclaves do not cross firewall boundaries. + +:FeatureName: Enclave Support +include::snippets/technology-preview.adoc[] + +The new enclave support functionality is for scenarios where mirroring is needed for multiple enclaves that are secured behind at least one intermediate disconnected network. + +Enclave support has the following benefits: + +* You can mirror content for multiple enclaves and centralize it in a single internal registry. Because some customers want to run security checks on the mirrored content, with this setup they can run these checks all at once. The content is then vetted before being mirrored to downstream enclaves. + +* You can mirror content directly from the centralized internal registry to enclaves without restarting the mirroring process from the internet for each enclave. + +* You can minimize data transfer between network stages, so to ensure that a blob or image is transferred only once from one stage to another. \ No newline at end of file diff --git a/modules/oc-mirror-enclave-support.adoc b/modules/oc-mirror-enclave-support.adoc new file mode 100644 index 000000000000..09f3dc821f68 --- /dev/null +++ b/modules/oc-mirror-enclave-support.adoc @@ -0,0 +1,128 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: Procedure +[id="oc-mirror-enclave-support_{context}"] += Mirroring to an enclave + +When you mirror to an enclave, you must first transfer the necessary images from one or more enclaves into the enterprise central registry. + +The central registry is situated within a secure network, specifically a disconnected environment, and is not directly linked to the public internet. But the user must execute `oc mirror` in an environment with access to the public internet. + +.Procedure + +. Before running oc-mirror plugin v2 in the disconnected environment, create a `registries.conf` file. The TOML format of the file is described in this specification: ++ +[NOTE] +==== +It is recommended to store the file under `$HOME/.config/containers/registries.conf` or `/etc/containers/registries.conf`. +==== ++ +.Example `registries.conf` +[source,toml] +---- +[[registry]] +location="registry.redhat.io" +[[registry.mirror]] +location="" + +[[registry]] +location="quay.io" +[[registry.mirror]] +location="" +---- + +. Generate a mirror archive. + +.. To collect all the {product-title} content into an archive on the disk under `/enterprise-content`, run the following command: ++ +[source,terminal] +---- +$ oc mirror --v2 -c isc.yaml file:///enterprise-content +---- ++ +.Example of isc.yaml: +[source,yaml] +---- +apiVersion: mirror.openshift.io/v2alpha1 +kind: ImageSetConfiguration +mirror: + platform: + architectures: + - "amd64" + channels: + - name: stable-4.15 + minVersion: 4.15.0 + maxVersion: 4.15.3 +---- ++ +After the archive is generated, it is transferred to the disconnected environment. The transport mechanism is not part of oc-mirror plugin v2. The enterprise network administrators determine the transfer strategy. ++ +In some cases, the transfer is done manually, in that the disk is physically unplugged from one location, and plugged to another computer in the disconnected environment. In other cases, the Secure File Transfer Protocol (SFTP) or other protocols are used. + +. After the transfer of the archive is done, you can execute oc-mirror plugin v2 again in order to mirror the relevant archive contents to the registry (`entrerpise_registry.in` in the example) as demonstrated in the following example: ++ +[source,terminal] +---- +$ oc mirror --v2 -c isc.yaml --from file:///enterprise-content docker:/// +---- +Where: +- `--from` points to the folder containing the archive. It starts with the `file://`. +- `docker://` is the destination of the mirroring is the final argument. Because it is a docker registry. +- `-c` (`--config`) is a mandatory argument. It enables oc-mirror plugin v2 to eventually mirror only sub-parts of the archive to the registry. One archive might contain several {product-title} releases, but the disconnected environment or an enclave might mirror only a few. + +. Prepare the `imageSetConfig` YAML file, which describes the content to mirror to the enclave: ++ +.Example isc-enclave.yaml +[source,yaml] +---- +apiVersion: mirror.openshift.io/v2alpha1 +kind: ImageSetConfiguration +mirror: + platform: + architectures: + - "amd64" + channels: + - name: stable-4.15 + minVersion: 4.15.2 + maxVersion: 4.15.2 +---- ++ +You must run oc-mirror plugin v2 on a machine with access to the disconnected registry. In the previous example, the disconnected environment, `enterprise-registry.in`, is accessible. + +. Update the graph URL ++ +If you are using `graph:true`, oc-mirror plugin v2 attempts to reach the `cincinnati` API endpoint. Because this environment is disconnected, be sure to export the environment variable `UPDATE_URL_OVERRIDE` to refer to the URL for the OpenShift Update Service (OSUS): ++ +[source,terminal] +---- +$ export UPDATE_URL_OVERRIDE=https:///graph +---- ++ +For more information on setting up OSUS on an OpenShift cluster, see "Updating a cluster in a disconnected environment using the OpenShift Update Service". + +. Generate a mirror archive from the enterprise registry for the enclave. ++ +To prepare an archive for the `enclave1`, the user executes oc-mirror plugin v2 in the enterprise disconnected environment by using the `imageSetConfiguration` specific for that enclave. This ensures that only images needed by that enclave are mirrored: ++ +[source,terminal] +---- +$ oc mirror --v2 -c isc-enclave.yaml +file:///disk-enc1/ +---- ++ +This action collects all the {product-title} content into an archive and generates an archive on disk. + +. After the archive is generated, it will be transferred to the `enclave1` network. The transport mechanism is not the responsibility of oc-mirror plugin v2. + +. Mirror contents to the enclave registry ++ +After the transfer of the archive is done, the user can execute oc-mirror plugin v2 again in order to mirror the relevant archive contents to the registry. ++ +[source,terminal] +---- +$ oc mirror --v2 -c isc-enclave.yaml --from file://local-disk docker://registry.enc1.in +---- ++ +The administrators of the {product-title} cluster in `enclave1` are now ready to install or upgrade that cluster. \ No newline at end of file diff --git a/modules/oc-mirror-imageset-config-parameters-v2.adoc b/modules/oc-mirror-imageset-config-parameters-v2.adoc new file mode 100644 index 000000000000..de0330ac043c --- /dev/null +++ b/modules/oc-mirror-imageset-config-parameters-v2.adoc @@ -0,0 +1,450 @@ + +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: REFERENCE +[id="oc-mirror-imageset-config-parameters-v2_{context}"] += `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. + +[NOTE] +==== +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. + +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. + +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. +==== + +.`ImageSetConfiguration` parameters +[cols="2,2a,1a",options="header"] +|=== +|Parameter +|Description +|Values + +|`apiVersion` +|The API version of the `ImageSetConfiguration` content. +|String +Example: `mirror.openshift.io/v2alpha1` + +|`archiveSize` +|The maximum size, in GiB, of each archive file within the image set. +|Integer +Example: `4` + +|`mirror` +|The configuration of the image set. +|Object + +|`mirror.additionalImages` +|The additional images configuration of the image set. +|Array of objects + +Example: +[source,yaml] +---- +additionalImages: + - name: registry.redhat.io/ubi8/ubi:latest +---- + +|`mirror.additionalImages.name` +|The tag or digest of the image to mirror. +|String +Example: `registry.redhat.io/ubi8/ubi:latest` + +|`mirror.blockedImages` +|The full tag, digest, or pattern of images to block from mirroring. +|Array of strings +Example: `docker.io/library/alpine` + +|`mirror.operators` +|The Operators configuration of the image set. +|Array of objects + +Example: +[source,yaml,subs="attributes+"] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: elasticsearch-operator + minVersion: '2.4.0' +---- + +|`mirror.operators.catalog` +|The Operator catalog to include in the image set. +|String +Example: `registry.redhat.io/redhat/redhat-operator-index:v4.15` + +|`mirror.operators.full` +|When `true`, downloads the full catalog, Operator package, or Operator channel. +|Boolean +The default value is `false`. + +|`mirror.operators.packages` +|The Operator packages configuration. +|Array of objects + +Example: +[source,yaml,subs="attributes+"] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: elasticsearch-operator + minVersion: '5.2.3-31' +---- + +|`mirror.operators.packages.name` +|The Operator package name to include in the image set. +|String +Example: `elasticsearch-operator` + +|`mirror.operators.packages.channels` +|Operator package channel configuration +|Object + +|`mirror.operators.packages.channels.name` +|The Operator channel name, unique within a package, to include in the image set. +|String +Eample: `fast` or `stable-v4.15` + +|`mirror.operators.packages.channels.maxVersion` +|The highest version of the Operator mirror across all channels in which it exists. +|String +Example: `5.2.3-31` + +|`mirror.operators.packages.channels.minVersion` +|The lowest version of the Operator to mirror across all channels in which it exists +|String +Example: `5.2.3-31` + +|`mirror.operators.packages.maxVersion` +|The highest version of the Operator to mirror across all channels in which it exists. +|String +Example: `5.2.3-31` + +|`mirror.operators.packages.minVersion` +|The lowest version of the Operator to mirror across all channels in which it exists. +|String +Example: `5.2.3-31` + +|`mirror.operators.packages.bundles` +|Selected bundles configuration +|Array of objects + +Example: +[source,yaml,subs="attributes+"] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: 3scale-operator + bundles: + - name: 3scale-operator.v0.10.0-mas +---- + +|`mirror.operators.packages.bundles.name` +|Name of the bundle selected for mirror (as it appears in the catalog). +|String +Example : `3scale-operator.v0.10.0-mas` + +|`mirror.operators.targetCatalog` +|An alternative name and optional namespace hierarchy to mirror the referenced catalog as +|String +Example: `my-namespace/my-operator-catalog` + +|`mirror.operators.targetCatalogSourceTemplate` +|Path on disk for a template to use to complete catalogSource custom resource generated by oc-mirror plugin v2. +|String +Example: `/tmp/catalog-source_template.yaml` +Example of a template file: +[source,yaml] +---- +apiVersion: operators.coreos.com/v2alpha1 +kind: CatalogSource +metadata: + name: discarded + namespace: openshift-marketplace +spec: + image: discarded + sourceType: grpc + updateStrategy: +registryPoll: +interval: 30m0s +---- + +|`mirror.operators.targetTag` +|An alternative tag to append to the `targetName` or `targetCatalog`. +|String +Example: `v1` + +|`mirror.platform` +|The platform configuration of the image set. +|Object + +|`mirror.platform.architectures` +|The architecture of the platform release payload to mirror. +|Array of strings +Example: +[source,yaml] +---- +architectures: + - amd64 + - arm64 + - multi + - ppc64le + - s390x +---- + +The default value is `amd64`. The value `multi` ensures that the mirroring is supported for all available architectures, eliminating the need to specify individual architectures + +|`mirror.platform.channels` +|The platform channel configuration of the image set. +|Array of objects +Example: +[source,yaml,subs="attributes+"] +---- +channels: + - name: stable-4.12 + - name: stable-{product-version} +---- + +|`mirror.platform.channels.full` +|When `true`, sets the `minVersion` to the first release in the channel and the `maxVersion` to the last release in the channel. +|Boolean +The default value is `false` + +|`mirror.platform.channels.name` +|Name of the release channel +|String +Example: `stable-4.15` + +|`mirror.platform.channels.minVersion` +|The minimum version of the referenced platform to be mirrored. +|String +Example: `4.12.6` + +|`mirror.platform.channels.maxVersion` +|The highest version of the referenced platform to be mirrored. +|String +Example: `4.15.1` + +|`mirror.platform.channels.shortestPath` +|Toggles shortest path mirroring or full range mirroring. +|Boolean +The default value is `false` + +|`mirror.platform.channels.type` +|Type of the platform to be mirrored +|String +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. +|Boolean +The default value is `false` + +|=== + + +[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. + +.`DeleteImageSetConfiguration` parameters +[cols="2,2a,1a",options="header"] +|=== +|Parameter +|Description +|Values + +|`apiVersion` +|The API version for the `DeleteImageSetConfiguration` content. +|String +Example: `mirror.openshift.io/v2alpha1` + +|`delete` +|The configuration of the image set to delete. +|Object + +|`delete.additionalImages` +|The additional images configuration of the delete image set. +|Array of objects +Example: +[source,yaml] +---- +additionalImages: + - name: registry.redhat.io/ubi8/ubi:latest +---- + +|`delete.additionalImages.name` +|The tag or digest of the image to delete. +|String +Example: `registry.redhat.io/ubi8/ubi:latest` + +|`delete.operators` +|The Operators configuration of the delete image set. +|Array of objects +Example: +[source,yaml] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: elasticsearch-operator + minVersion: '2.4.0' +---- + +|`delete.operators.catalog` +|The Operator catalog to include in the delete image set. +|String +Example: `registry.redhat.io/redhat/redhat-operator-index:v4.15` + +|`delete.operators.full` +|When true, deletes the full catalog, Operator package, or Operator channel. +|Boolean +The default value is `false` + +|`delete.operators.packages` +|Operator packages configuration +|Array of objects +Example: +[source,yaml] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: elasticsearch-operator + minVersion: '5.2.3-31' +---- + +|`delete.operators.packages.name` +|The Operator package name to include in the delete image set. +|String +Example: `elasticsearch-operator` + +|`delete.operators.packages.channels` +|Operator package channel configuration +|Object + +|`delete.operators.packages.channels.name` +|The Operator channel name, unique within a package, to include in the delete image set. +|String +Example: `fast` or `stable-v4.15` + +|`delete.operators.packages.channels.maxVersion` +|The highest version of the Operator to delete within the selected channel. +|String +Example: `5.2.3-31` + +|`delete.operators.packages.channels.minVersion` +|The lowest version of the Operator to delete within the selection in which it exists. +|String +Example: `5.2.3-31` + +|`delete.operators.packages.maxVersion` +|The highest version of the Operator to delete across all channels in which it exists. +|String +Example: `5.2.3-31` + +|`delete.operators.packages.minVersion` +|The lowest version of the Operator to delete across all channels in which it exists. +|String +Example: `5.2.3-31` + +|`delete.operators.packages.bundles` +|The selected bundles configuration +|Array of objects + +You cannot choose both channels and bundles for the same operator. + +Example: +[source,yaml] +---- +operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:{product-version} + packages: + - name: 3scale-operator + bundles: + - name: 3scale-operator.v0.10.0-mas +---- + +|`delete.operators.packages.bundles.name` +|Name of the bundle selected to delete (as it is displayed in the catalog) +|String +Example : `3scale-operator.v0.10.0-mas` + +|`delete.platform` +|The platform configuration of the image set +|Object + +|`delete.platform.architectures` +|The architecture of the platform release payload to delete. +|Array of strings +Example: +[source,yaml] +---- +architectures: + - amd64 + - arm64 + - multi + - ppc64le + - s390x +---- + +The default value is `amd64` + +|`delete.platform.channels` +|The platform channel configuration of the image set. +|Array of objects + +Example: +[source,yaml,subs="attributes+"] +---- +channels: + - name: stable-4.12 + - name: stable-{product-version} +---- + +|`delete.platform.channels.full` +|When `true`, sets the `minVersion` to the first release in the channel and the `maxVersion` to the last release in the channel. +|Boolean +The default value is `false` + +|`delete.platform.channels.name` +|Name of the release channel +|String +Example: `stable-4.15` + +|`delete.platform.channels.minVersion` +|The minimum version of the referenced platform to be deleted. +|String +Example: `4.12.6` + +|`delete.platform.channels.maxVersion` +|The highest version of the referenced platform to be deleted. +|String +Example: `4.15.1` + +|`delete.platform.channels.shortestPath` +|Toggles between deleting the shortest path and deleting the full range. +|Boolean +The default value is `false` + +|`delete.platform.channels.type` +|Type of the platform to be deleted +|String +Example: `ocp` or `okd` +The default is `ocp` + +|`delete.platform.graph` +|Determines whether the OSUS graph is deleted as well on the mirror registry as well. +|Boolean +The default value is `false` + +|=== \ No newline at end of file diff --git a/modules/oc-mirror-operator-catalog-filtering.adoc b/modules/oc-mirror-operator-catalog-filtering.adoc new file mode 100644 index 000000000000..cd5a0479e231 --- /dev/null +++ b/modules/oc-mirror-operator-catalog-filtering.adoc @@ -0,0 +1,268 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: REFERENCE +[id="oc-mirror-operator-catalog-filtering_{context}"] += How filtering works in the operator catalog + +oc-mirror plugin v2 selects the list of bundles for mirroring by processing the information in `imageSetConfig`. + +When oc-mirror plugin v2 selects bundles for mirroring, it does not infer Group Version Kind (GVK) or bundle dependencies, omitting them from the mirroring set. Instead, it strictly adheres to the user instructions. You must explicitly specify any required dependent packages and their versions. + +Bundle versions typically use semantic versioning standards (SemVer), and you can sort bundles within a channel by version. You can select buncles that fall within a specific range in the `ImageSetConfig`. + +This selection algorithm ensures consistent outcomes compared to oc-mirror plugin v1. However, it does not include upgrade graph details, such as `replaces`, `skip`, and `skipRange`. This approach differs from the OLM algorithm. It might mirror more bundles than necessary for upgrading a cluster because of potentially shorter upgrade paths between the `minVersion` and `maxVersion`. + +.Use the following table to see what bundle versions are included in different scenarios: +[cols="1,2",options="header"] + +|=== + +|ImageSetConfig operator filtering +|Expected bundle versions + + +a|Scenario 1 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10 +---- +|For each package in the catalog, 1 bundle, corresponding to the head version of the default channel for that package. + +a|Scenario 2 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10 + full: true +---- +|All bundles of all channels of the specified catalog + +a|Scenario 3 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10 + packages: + - name: compliance-operator +---- +|One bundle, corresponding to the head version of the default channel for that package + +a|Scenario 4 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10 + full: true + - packages: + - name: elasticsearch-operator +---- +|All bundles of all channels for the packages specified + +a|Scenario 5 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + minVersion: 5.6.0 +---- +|All bundles in the default channel, from the `minVersion`, up to the channel head for that package that do not rely on the shortest path from upgrade the graph. + +a|Scenario 6 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + maxVersion: 6.0.0 +---- +|All bundles in the default channel that are lower than the `maxVersion` for that package. + +a|Scenario 7 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + minVersion: 5.6.0 + maxVersion: 6.0.0 +---- +|All bundles in the default channel, between the `minVersion` and `maxVersion` for that package. The head of the channel is not included, even if multiple channels are included in the filtering. + +a|Scenario 8 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable +---- +|The head bundle for the selected channel of that package. + +a|Scenario 9 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.10 + full: true + - packages: + - name: elasticsearch-operator + channels: + - name: 'stable-v0' +---- +|All bundles for the specified packages and channels. + +a|Scenario 10 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + - name: stable-5.5 +---- +|The head bundle for each selected channel of that package. + +a|Scenario 11 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + minVersion: 5.6.0 +---- +|Within the selected channel of that package, all versions starting with the `minVersion` up to the channel head. This scenario does not relyon the shortest path from the upgrade graph. + +a|Scenario 12 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + maxVersion: 6.0.0 +---- +|Within the selected channel of that package, all versions up to the `maxVersion` (not relying on the shortest path from the upgrade graph). The head of the channel is not included, even if multiple channels are included in the filtering. + +a|Scenario 13 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + minVersion: 5.6.0 + maxVersion: 6.0.0 +---- +|Within the selected channel of that package, all versions between the `minVersion` and `maxVersion`, not relying on the shortest path from the upgrade graph. The head of the channel is not included, even if multiple channels are included in the filtering. + +a|Scenario 14 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.14 + packages: + - name: aws-load-balancer-operator + bundles: + - name: aws-load-balancer-operator.v1.1.0 + - name: 3scale-operator + bundles: + - name: 3scale-operator.v0.10.0-mas +---- +|Only the bundles specified for each package are included in the filtering. + +a|Scenario 15 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + minVersion: 5.6.0 + maxVersion: 6.0.0 +---- +|Do not use this scenario. filtering by channel and by package with a `minVersion` or `maxVersion` is not allowed. + +a|Scenario 16 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + packages: + - name: compliance-operator + channels + - name: stable + minVersion: 5.6.0 + maxVersion: 6.0.0 +---- +|Do not use this scenario. You cannot filter using `full:true` and the `minVersion` or `maxVersion`. + +a|Scenario 17 + +[source,yaml] +---- +mirror: + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.15 + full: true + packages: + - name: compliance-operator + channels + - name: stable + minVersion: 5.6.0 + maxVersion: 6.0.0 +---- +|Do not use this scenario. You cannot filter using `full:true` and the `minVersion` or `maxVersion`. + +|=== \ No newline at end of file diff --git a/modules/oc-mirror-procedure-delete-v2.adoc b/modules/oc-mirror-procedure-delete-v2.adoc new file mode 100644 index 000000000000..9c2729fe889f --- /dev/null +++ b/modules/oc-mirror-procedure-delete-v2.adoc @@ -0,0 +1,41 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: PROCEDURE +[id="oc-mirror-procedure-delete-v2_{context}"] += Deleting the images from disconnected environment + +To delete images from a disconnected environment using the oc-mirror plugin v2, follow the procedure. + +.Procedure + +. Create a YAML file that deletes previous images: ++ +[source,terminal] +---- +$ oc mirror delete --config delete-image-set-config.yaml --workspace file:// --v2 --generate docker:// +---- +Where: +- ``: Use the directory where images were previously mirrored or stored during the mirroring process. +- ``: Insert the URL or address of the remote container registry from which images will be deleted. + +. Go to the `/delete directory` that was created. + +. Verify that the `delete-images.yaml` file has been generated. + +. Manually ensure that each image listed in the file is no longer needed by the cluster and can be safely removed from the registry. + +. After you generate the `delete` YAML file, delete the images from the remote registry: ++ +[source,terminal] +---- +$ oc mirror delete --v2 --delete-yaml-file /delete/delete-images.yaml docker:/ +---- +Where: +- ``: Specify your previously mirrored work folder. ++ +[IMPORTANT] +==== +When using the mirror-to-mirror procedure, images are not cached locally, so you cannot delete images from a local cache. +==== \ No newline at end of file diff --git a/modules/oc-mirror-v2-about-dry-run.adoc b/modules/oc-mirror-v2-about-dry-run.adoc new file mode 100644 index 000000000000..3baf4e819ea0 --- /dev/null +++ b/modules/oc-mirror-v2-about-dry-run.adoc @@ -0,0 +1,9 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-mirror-v2-about-dry-run_{context}"] += Verifying your selected images for mirroring + +You can use oc-mirror plugin v2 to perform a test run (dry run) that does not actually mirror any images. This enables you to review the list of images that would be mirrored. You can also use a dry run to catch any errors with your image set configuration early. When running a dry run on a mirror-to-disk workflow, the oc-mirror plugin v2 checks if all the images within the image set are available in its cache. Any missing images are listed in the `missing.txt` file. When a dry run is performed before mirroring, both `missing.txt` and `mapping.txt` files contain the same list of images. \ No newline at end of file diff --git a/modules/oc-mirror-v2-about.adoc b/modules/oc-mirror-v2-about.adoc index 00fc8dee7902..d7bda5d2290f 100644 --- a/modules/oc-mirror-v2-about.adoc +++ b/modules/oc-mirror-v2-about.adoc @@ -5,12 +5,13 @@ :_mod-docs-content-type: CONCEPT [id="installation-oc-mirror-v2-about_{context}"] -= About oc-mirror plugin version 2 -You can use the oc-mirror OpenShift CLI (`oc`) plugin as a single tool to mirror all required {product-title} content and other images to your mirror registry. += About oc-mirror plugin v2 -To use oc-mirror, add the `--v2` flag to the oc-mirror command line. The new tool is is available as a Tech Preview feature. +The oc-mirror OpenShift CLI (`oc`) plugin is a single tool that mirrors all required {product-title} content and other images to your mirror registry. -oc-mirror version 2 (V2) provides the following features: +To use the new Technology Preview version of oc-mirror, add the `--v2` flag to the oc-mirror plugin v2 command line. + +oc-mirror plugin v2 has the following features: * Verifies that the complete image set specified in the image set config is mirrored to the mirrored registry, regardless of whether the images were previously mirrored or not. @@ -18,12 +19,12 @@ oc-mirror version 2 (V2) provides the following features: * Maintains minimal archive sizes by incorporating only new images into the archive. -* Generate mirroring archives with content selected by mirroring date. +* Generates mirroring archives with content selected by mirroring date. -* Can generate IDMS and ITMS (instead of ICSP) for the full image set, rather than just the incremental changes. +* Can generate `ImageDigestMirrorSet` (IDMS), `ImageTagMirrorSet` (ITMS), instead of `ImageContentSourcePolicy` (ICSP) for the full image set, rather than just for the incremental changes. -* Filter Operator versions by bundle name. +* Saves filter Operator versions by bundle name. -* Does not perform automatic pruning; instead, it introduces a `Delete` feature, granting users more control over the image deletion. +* Does not perform automatic pruning. V2 now has a `Delete` feature, which grants users more control over deleting images. -* Introduces support for `registries.conf`, facilitating mirroring to multiple enclaves using the same cache. \ No newline at end of file +* Introduces support for `registries.conf`. This change facilitates mirroring to multiple enclaves while using the same cache. \ No newline at end of file diff --git a/modules/oc-mirror-v2-support.adoc b/modules/oc-mirror-v2-support.adoc index b5fddd96726a..ea2c1ad9dcb5 100644 --- a/modules/oc-mirror-v2-support.adoc +++ b/modules/oc-mirror-v2-support.adoc @@ -6,13 +6,13 @@ :_mod-docs-content-type: CONCEPT [id="oc-mirror-v2-support_{context}"] -= oc-mirror V2 compatibility and support += oc-mirror plugin v2 compatibility and support -The oc-mirror plugin V2 supports mirroring {product-title} payload images and Operator catalogs for {product-title} versions 4.12 and later. +The oc-mirror plugin v2 is supported for {product-title}. [NOTE] ==== -On `aarch64`, `ppc64le`, and `s390x` architectures the oc-mirror plugin is only supported for {product-title} versions 4.14 and later. +On `aarch64`, `ppc64le`, and `s390x` architectures the oc-mirror plugin v2 is supported only 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. \ No newline at end of file +Use the latest available version of the oc-mirror plugin v2 regardless of which versions of {product-title} you need to mirror. \ No newline at end of file diff --git a/modules/oc-mirror-workflows-delete-v2.adoc b/modules/oc-mirror-workflows-delete-v2.adoc new file mode 100644 index 000000000000..cbb9ce2b9a44 --- /dev/null +++ b/modules/oc-mirror-workflows-delete-v2.adoc @@ -0,0 +1,50 @@ +// Module included in the following assemblies: +// +// * installing/disconnected_install/installing-mirroring-disconnected-v2.adoc + +:_mod-docs-content-type: CONCEPT +[id="oc-mirror-workflows-delete-v2_{context}"] += Deletion of images from your disconnected environment + +Before you can use oc-mirror plugin v2, you must delete previously deployed images. oc-mirror plugin v2 no longer performs automatic pruning. + +You must create the `DeleteImageSetConfiguration` file to delete image configuration when using oc-mirror plugin v2. This prevents accidentally deleting necessary or deployed images when making changes with `ImageSetConfig.yaml`. + + +In the following example, `DeleteImageSetConfiguration` removes the following: + +* All images of {product-title} release 4.13.3. +* The catalog image `redhat-operator-index` `v4.12`. +* The `aws-load-balancer-operator` v0.0.1 bundle and all its related images. +* The additional images `ubi` and `ubi-minimal` referenced by their corresponding digests. + +.Example: `DeleteImageSetConfig` +[source,yaml] +---- +apiVersion: mirror.openshift.io/v2alpha1 +kind: DeleteImageSetConfiguration +delete: + platform: + channels: + - name: stable-4.13 + minVersion: 4.13.3 + maxVersion: 4.13.3 + operators: + - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.12 + packages: + - name: aws-load-balancer-operator + minVersion: 0.0.1 + maxVersion: 0.0.1 + additionalImages: + - name: registry.redhat.io/ubi8/ubi@sha256:bce7e9f69fb7d4533447232478fd825811c760288f87a35699f9c8f030f2c1a6 + - name: registry.redhat.io/ubi8/ubi-minimal@sha256:8bedbe742f140108897fb3532068e8316900d9814f399d676ac78b46e740e34e +---- + +[IMPORTANT] +==== +Consider using the mirror-to-disk and disk-to-mirror workflows to reduce mirroring issues. +==== + +In the image delete workflow, oc-mirror plugin v2 deletes only the manifests of the images, which does not reduce the storage occupied in the registry. + +To free up storage space from unnecessary images, such as those with deleted manifests, you must enable the garbage collector on your container registry. With the garbage collector enabled, the registry will delete the image blobs that no longer have references to any manifests, thereby reducing the storage previously occupied by the deleted blobs. Enabling the garbage collector differs depending on your container registry.