Merge pull request #47645 from bergerhoffer/OSDOCS-3567

OSDOCS-3567: Updating docs for oc-mirror GA

Author: bergerhoffer

installing/disconnected_install/installing-mirroring-disconnected.adoc

@@ -6,25 +6,16 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-////
-General to do list:
-* Confirm that no new content was added since I did the reorg of the disconnected install assemblies (up to date as of 2/13)
-* Add info about mirroring to a namespace
-* Test and get some actual example output
-* Use cases for changing image set config between runs
-////
+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 ensure your clusters only use container images that satisfy your organizational controls on external content. Before you install a cluster on infrastructure that you provision in a restricted network, you must mirror the required container images into that environment. To mirror container images, you must have a registry for mirroring.
-
-You can use the oc-mirror OpenShift CLI (`oc`) plug-in to mirror images to a mirror registry in your fully or partially disconnected environments.
-
-:FeatureName: Mirroring images for disconnected environments using the oc-mirror plug-in
-include::snippets/technology-preview.adoc[leveloffset=+1]
+You can use the oc-mirror OpenShift CLI (`oc`) plug-in 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.
 
 The following steps outline the high-level workflow on how to use the oc-mirror plug-in to mirror images to a mirror registry:
 
 . Create an image set configuration file.
-. Mirror the image set to the mirror registry.
+. Mirror the image set to the mirror registry by using one of the following methods:
+** Mirror an image set directly to the 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.
 . Install the `ImageContentSourcePolicy` and `CatalogSource` resources that were generated by oc-mirror into the cluster.
 . Repeat these steps to update your mirror registry as necessary.
 
@@ -76,6 +67,7 @@ include::modules/oc-mirror-creating-image-set-config.adoc[leveloffset=+1]
 
 * 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-restricted-network-cluster.adoc#update-service-overview_updating-restricted-network-cluster[About the OpenShift Update Service]
 
 [id="mirroring-image-set"]
 == Mirroring an image set to a mirror registry
@@ -109,20 +101,35 @@ include::modules/oc-mirror-updating-cluster-manifests.adoc[leveloffset=+1]
 // TODO: Consider whether we want any sort of reference module on how to use `oc mirror` (the 3 ways etc)
 // Maybe consider adding the blurb just to the beginning of the procedure modules (the combo of params?)
 
-// Updating your mirror registry with differential updates
-include::modules/oc-mirror-differential-updates.adoc[leveloffset=+1]
+[id="updating-mirror-registry-content"]
+== Keeping your mirror registry content updated
+
+After your target mirror registry is populated with the initial image set, be sure to update it regularly so that it has the latest content. You can optionally set up a cron job, if possible, so that the mirror registry is updated on a regular basis.
+
+Ensure that you update your image set configuration to add or remove {product-title} and Operator releases as necessary. Any images that are removed are pruned from the mirror registry.
+
+// About updating your mirror registry content
+include::modules/oc-mirror-updating-registry-about.adoc[leveloffset=+2]
+
+// Updating your mirror registry content
+include::modules/oc-mirror-differential-updates.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[Installing the ImageContentSourcePolicy and CatalogSource resources into the cluster]
 
+// Performing a dry run
+include::modules/oc-mirror-dry-run.adoc[leveloffset=+1]
+
 // 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]
 
-// TODO: Add an additional resources section to link to the non-TP assembly?
+// Command reference for oc-mirror
+include::modules/oc-mirror-command-reference.adoc[leveloffset=+1]

modules/oc-mirror-about.adoc

@@ -12,6 +12,8 @@ You can use the oc-mirror OpenShift CLI (`oc`) plug-in to mirror all required {p
 * Maintains update paths for {product-title} and Operators.
 * Uses a declarative image set configuration file to include only the {product-title} releases, Operators, and images that your cluster needs.
 * Performs incremental mirroring, which reduces the size of future image sets.
+* Prunes images from the target mirror registry that were excluded from the image set configuration since the previous execution.
+* Optionally generates supporting artifacts for OpenShift Update Service (OSUS) usage.
 
 When using the oc-mirror plug-in, 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 plug-in can also mirror arbitrary helm charts and additional container images to assist users in seamlessly synchronizing their workloads onto mirror registries.
 

modules/oc-mirror-command-reference.adoc

@@ -0,0 +1,97 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected.adoc
+
+:_content-type: REFERENCE
+[id="oc-mirror-command-reference_{context}"]
+= Command reference for oc-mirror
+
+The following tables describe the `oc mirror` subcommands and flags:
+
+.oc mirror subcommands
+[cols="1,2",options="header"]
+|===
+|Subcommand
+|Description
+
+|`completion`
+|Generate the autocompletion script for the specified shell.
+
+|`describe`
+|Output the contents of an image set.
+
+|`help`
+|Show help about any subcommand.
+
+|`init`
+|Output an initial image set configuration template.
+
+|`list`
+|List available platform and Operator content and their version.
+
+|`version`
+|Output the oc-mirror version.
+
+|===
+
+.oc mirror flags
+[cols="1,2",options="header"]
+|===
+|Flag
+|Description
+
+|`-c`, `--config` `<string>`
+|Specify the path to an image set configuration file.
+
+|`--continue-on-error`
+|If any non image-pull related error occurs, continue and attempt to mirror as much as possible.
+
+|`--dest-skip-tls`
+|Disable TLS validation for the target registry.
+
+|`--dest-use-http`
+|Use plain HTTP for the target registry.
+
+|`--dry-run`
+|Print actions without mirroring images. Generates `mapping.txt` and `pruning-plan.json` files.
+
+|`--from <string>`
+|Specify the path to an image set archive that was generated by an execution of oc-mirror to load into a target registry.
+
+|`-h`, `--help`
+|Show the help.
+
+|`--ignore-history`
+|Ignore past mirrors when downloading images and packing layers. Disables incremental mirroring and might download more data.
+
+|`--manifests-only`
+|Generate manifests for `ImageContentSourcePolicy` and `CatalogSource` objects to configure a cluster to use the mirror registry, but do not actually mirror any images.
+
+|`--max-per-registry <int>`
+|Specify the number of concurrent requests allowed per registry. The default is `6`.
+
+|`--skip-cleanup`
+|Skip removal of artifact directories.
+
+|`--skip-image-pin`
+|Do not replace image tags with digest pins in Operator catalogs.
+
+|`--skip-metadata-check`
+|Skip metadata when publishing an image set. This is only recommended when the image set was created with `--ignore-history`.
+
+|`--skip-missing`
+|If an image is not found, skip it instead of reporting an error and aborting execution. Does not apply to custom images explicitly specified in the image set configuration.
+
+|`--skip-verification`
+|Skip digest verification.
+
+|`--source-skip-tls`
+|Disable TLS validation for the source registry.
+
+|`--source-use-http`
+|Use plain HTTP for the source registry.
+
+|`-v`, `--verbose` `<int>`
+|Specify the number for the log level verbosity. Valid values are `0` - `9`. The default is `0`.
+
+|===

modules/oc-mirror-creating-image-set-config.adoc

@@ -15,32 +15,58 @@ You must specify a storage backend in the image set configuration file. This sto
 Do not delete or modify the metadata that is generated by the oc-mirror plug-in. You must use the same storage backend every time you run the oc-mirror plug-in 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_.
+
 .Procedure
 
-. Create an `ImageSetConfiguration` resource that specifies the necessary configuration details:
+. Use the `oc mirror init` command to create a template for the image set configuration and save it to a file called `imageset-config.yaml`:
++
+[source,terminal]
+----
+$ oc mirror init --registry example.com/mirror/oc-mirror-metadata > imageset-config.yaml <1>
+----
+<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:
 +
-.Example `ImageSetConfiguration` file
 [source,yaml]
 ----
-apiVersion: mirror.openshift.io/v1alpha1
 kind: ImageSetConfiguration
-archiveSize: 4 <1>
+apiVersion: mirror.openshift.io/v1alpha2
+archiveSize: 4                                                      <1>
+storageConfig:                                                      <2>
+  registry:
+    imageURL: example.com/mirror/oc-mirror-metadata                 <3>
+    skipTLS: false
 mirror:
- ocp:
-   channels:
-     - name: stable-4.9 <2>
- operators:
-   - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.9 <3>
-storageConfig: <4>
- registry:
-   imageURL: example.com/example/oc-mirror <5>
+  platform:
+    channels:
+    - name: stable-4.11                                             <4>
+      type: ocp
+    graph: true                                                     <5>
+  operators:
+  - catalog: registry.redhat.io/redhat/redhat-operator-index:v4.11  <6>
+    packages:
+    - name: serverless-operator                                     <7>
+      channels:
+      - name: stable
+  additionalImages:
+  - name: registry.redhat.io/ubi8/ubi:latest                        <8>
+  helm: {}
 ----
-<1> The maximum size, in GiB, of each file within the image set.
-<2> The channel to retrieve the {product-title} images from.
-<3> The Operator catalog to retrieve the {product-title} images from.
-<4> 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.
-<5> The registry URL for the storage backend.
+<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 generate the OpenShift Update Service (OSUS) graph image to allow for an improved cluster update experience when using the web console. 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 and channels to include in the image set. Remove this field to retrieve all packages in the catalog.
+<8> Specify any additional images to include in image set.
 +
-This example pulls images from the `stable-4.9` channel for the `registry.redhat.io/redhat/redhat-operator-index:v4.9` operator catalog and saves the image set metadata to the `example.com/example/oc-mirror` registry.
+See _Image set configuration parameters_ for the full list of parameters and _Image set configuration examples_ for various mirroring use cases.
 
-. Save the file as `imageset-config.yaml`. This file is required by the `oc mirror` command when mirroring content.
+. Save the updated file.
++
+This image set configuration file is required by the `oc mirror` command when mirroring content.

modules/oc-mirror-differential-updates.adoc

@@ -4,32 +4,27 @@
 
 :_content-type: PROCEDURE
 [id="oc-mirror-differential-updates_{context}"]
-= Updating your mirror registry
+= Updating your mirror registry content
 
-After you publish a full image set to the mirror registry, you can use the oc-mirror plug-in to update the mirror registry with updated images.
+After you publish the initial image set to the mirror registry, you can use the oc-mirror plug-in to keep your disconnected clusters updated.
 
-When you run the oc-mirror plug-in again, it generates an image set that only contains new and updated images since the previous execution.
-
-[NOTE]
-====
-You must use the same storage backend as the initial execution of oc-mirror for the same mirror registry. Do not delete or modify the metadata that is generated by the oc-mirror plug-in.
-====
-
-Because it only pulls in the differences since the previous image set was created, the generated image set is often smaller and faster to process than the initial image set.
-
-[IMPORTANT]
-====
-Generated image sets are sequential and must be synchronized to the target mirror registry in order.
-====
+Depending on your image set configuration, oc-mirror automatically detects newer releases of {product-title} and your selected Operators that have been released after you completed the inital mirror. It is recommended to run oc-mirror at regular intervals, for example in a nightly cron job, to receive product and security updates on a timely basis.
 
 .Prerequisites
 
 * You have used the oc-mirror plug-in to mirror the initial image set to your mirror registry.
 * You have access to the storage backend that was used for the initial execution of the oc-mirror plug-in.
++
+[NOTE]
+====
+You must use the same storage backend as the initial execution of oc-mirror for the same mirror registry. Do not delete or modify the metadata image that is generated by the oc-mirror plug-in.
+====
 
 .Procedure
 
-. Follow the same steps that you used to create the initial image set and mirror it to the mirror registry. For instructions, see _Mirroring an image set in a partially disconnected environment_ or _Mirroring an image set in a fully disconnected environment_.
+. If necessary, update your image set configuration file to pick up new {product-title} and Operator versions. See _Image set configuration examples_ for example mirroring use cases.
+
+. Follow the same steps that you used to mirror your initial image set to the mirror registry. For instructions, see _Mirroring an image set in a partially disconnected environment_ or _Mirroring an image set in a fully disconnected environment_.
 +
 [IMPORTANT]
 ====

modules/oc-mirror-disk-to-mirror.adoc

@@ -22,8 +22,8 @@ You can use the oc-mirror plug-in to mirror the contents of a generated image se
 +
 [source,terminal]
 ----
-$ oc mirror --from=./mirror_seq1_000000.tar \ <1>
-  docker://registry.example:5000              <2>
+$ 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.
 <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.

modules/oc-mirror-dry-run.adoc

@@ -0,0 +1,68 @@
+// Module included in the following assemblies:
+//
+// * installing/disconnected_install/installing-mirroring-disconnected.adoc
+
+:_content-type: PROCEDURE
+[id="oc-mirror-dry-run_{context}"]
+= Performing a dry run
+
+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. It 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 plug-in.
+* You have created the image set configuration file.
+
+.Procedure
+
+. Run the `oc mirror` command with the `--dry-run` flag to perform a dry run:
++
+[source,terminal]
+----
+$ oc mirror --config=./imageset-config.yaml \// <1>
+  docker://registry.example:5000            \// <2>
+  --dry-run                                  <3>
+----
+<1> Pass in the image set configuration file that was created. This procedure assumes that it is named `imageset-config.yaml`.
+<2> Specify the mirror registry. Nothing is mirrored to this registry as long as you use the `--dry-run` flag.
+<3> Use the `--dry-run` flag to generate the dry run artifacts and not an actual image set file.
++
+.Example output
+[source,terminal]
+----
+Checking push permissions for registry.example:5000
+Creating directory: oc-mirror-workspace/src/publish
+Creating directory: oc-mirror-workspace/src/v2
+Creating directory: oc-mirror-workspace/src/charts
+Creating directory: oc-mirror-workspace/src/release-signatures
+No metadata detected, creating new workspace
+wrote mirroring manifests to oc-mirror-workspace/operators.1658342351/manifests-redhat-operator-index
+
+...
+
+info: Planning completed in 31.48s
+info: Dry run complete
+Writing image mapping to oc-mirror-workspace/mapping.txt
+----
+
+. Navigate into the workspace directory that was generated:
++
+[source,terminal]
+----
+$ cd oc-mirror-workspace/
+----
+
+. Review the `mapping.txt` file that was generated.
++
+This file contains a list of all images that would be mirrored.
+
+. Review the `pruning-plan.json` file that was generated.
++
+This file contains a list of all images that would be pruned from the mirror registry when the image set is published.
++
+[NOTE]
+====
+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.
+====