[OSDOCS-12036]ROSA-HCP - Image registry mirror config to customers

modules/images-registry-mirroring.adoc

@@ -0,0 +1,300 @@
+// Module included in the following assemblies:
+//
+// * openshift_images/image-configuration-hcp.adoc
+:_mod-docs-content-type: CONCEPT
+
+[id="images-registry-mirroring_{context}"]
+=  Image registry mirroring for {product-title}
+
+You can configure an existing {product-title} cluster to pull images from a mirrored registry by using the `ImageDigestMirrorSet (IDMS)` object.
+
+[IMPORTANT]
+====
+The image mirror configuration feature operates exclusively with image references by digest, meaning that image mirroring will only activate when an image is pulled using its unique and immutable ID. Any image references using a mutable tag are currently not supported by this functionality.
+====
+
+IDMS defines a set of cluster-wide policies for registry mirroring that makes image downloads faster, more reliable and more secure. It works by intercepting any image pull request that identifies an image by its unique, content-addressable digest. Based on these policies, the IDMS transparently redirects the pull operation from its specified source registry to one or more designated mirror registries. For the developer, this means their request—still pointing to the original source—is automatically fulfilled by a faster, closer mirror, significantly improving deployment speed without requiring any changes to their workflow.
+
+.Prerequisites
+
+To configure an existing {product-title} cluster to pull images from a mirrored registry by using the `ImageDigestMirrorSet (IDMS)` object, you must meet the following prerequisites:
+
+** You have installed and configured the latest {rosa-cli-first} on your installation host.
+** You have installed a {product-title} cluster.
+** The {product-title} cluster must be in a **Ready** state to create, edit, list, or delete image mirrors.
+** You have access to the mirror registries you want to configure.
+** You have the required IAM permissions to manage cluster configurations. For more information, see "About IAM resources" in the _Additional resources_ section.
+
+The benefits of configuring your {product-title} cluster to pull images from a mirrored registry using IDMS include:
+
+** *Enhanced Security*: By forcing image pulls from a private, mirrored registry, you can scan and approve all images for vulnerabilities before they ever enter your cluster.
+
+** *Improved Cluster Reliability*: A local mirror guarantees stable and predictable cluster performance by eliminating reliance on public internet pathways.
+
+** *Guaranteed Image Consistency*: IDMS uses image digests to reference images, which ensures that every node in the cluster pulls the same version of an image, preventing inconsistencies which could lead to deployment failures.
+
+[id="create-image-mirroring_{context}"]
+==  Creating an image mirror configuration
+
+.Procedure
+
+To create an image mirror configuration for a {product-title} cluster, run the following command:
+
+[IMPORTANT]
+====
+The source registry cannot be modified after creation. You must delete and recreate the image mirror to change the source.
+====
+
+.Syntax
+[source,terminal]
+----
+$ rosa create image-mirror [arguments]
+----
+
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+a|--cluster
+|Required: The name or ID of the cluster the mirror configuration will be applied to.
+
+|--source
+|Required: The source registry that will be mirrored.
+
+|--mirrors
+|Required: List of mirror registries. Mirror registries must be comma-separated.
+
+|--type=digest
+|Optional: Type of image mirror. The `digest` type is set by default and the only available `type` option.
+
+|--profile
+|Optional: Specifies an AWS profile (string) from your credentials file.
+
+|--region
+|Optional:Specifies an AWS region, overriding the AWS_REGION environment variable.
+|===
+
+.Examples
+Creates an image mirror configuration for a cluster named `mycluster`.
+
+
+[source,terminal]
+----
+$ rosa create image-mirror --cluster=mycluster \
+  --source=registry.example.com/team \
+  --mirrors=mirror.corp.com/team,backup.corp.com/team
+----
+.Example Output
+
+[source,terminal]
+----
+I: Image mirror with ID 'abc123def456' has been created on cluster 'mycluster'
+I: Source: registry.example.com/team
+I: Mirrors: [mirror.corp.com/team backup.corp.com/team]
+----
+[NOTE]
+====
+An ID is automatically generated and assigned to an image mirror during image mirror configuration creation.
+====
+
+Creates an image mirror configuration with a specific type.
+
+[NOTE]
+====
+The `digest` type is set by default and the only available `type` option.
+====
+
+[source,terminal]
+----
+$ rosa create image-mirror --cluster=mycluster \
+  --type=digest --source=docker.io/library \
+  --mirrors=internal-registry.company.com/dockerhub
+----
+
+Creating a single image mirror configuration with multiple mirrors for a cluster.
+
+[source,terminal]
+----
+$ rosa create image-mirror --cluster=mycluster \
+  --source=quay.io/openshift \
+  --mirrors=mirror1.company.com/openshift,mirror2.company.com/openshift,mirror3.company.com/openshift
+----
+
+[id="edit-image-mirroring_{context}"]
+==  Editing an image mirroring configuration
+
+.Procedure
+
+To edit an image mirror configuration for a {product-title} cluster, run the following command:
+
+[NOTE]
+====
+When editing an image mirror configuration, the new mirrors list completely replaces the existing mirrors list.
+====
+
+.Syntax
+[source,terminal]
+----
+$ rosa edit image-mirror [arguments]
+----
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--cluster
+|Required: The name or ID (string) of the cluster to which the image mirror configuration applies.
+
+|--mirrors
+|Required: New list of mirror registries that replaces current mirror registries. Mirror registries must be comma-separated.
+
+|--id
+|Required: ID of the image mirror configuration to edit.
+
+|--profile
+|Optional: Use a specific AWS profile from your credential file.
+
+|--region
+|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
+|===
+
+.Examples
+// Based on conversation with PM, these are not necessary b/c we are going to include examples only with the ID to keep things unambiguous.
+// Edits an image mirror configuration with a positional argument.
+
+// [source,terminal]
+// ----
+// $ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
+//   --mirrors=mirror.corp.com/team,backup.corp.com/team,new-mirror.corp.com/team
+// ----
+
+// Edits an image mirror configuration using the `--id` flag.
+
+// [source,terminal]
+// ----
+// $ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
+//   --mirrors=mirror.corp.com/team,backup.corp.com/team,new-mirror.corp.com/team
+// ----
+
+Replaces a single mirror on an image mirror configuration.
+
+[source,terminal]
+----
+$ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
+  --mirrors=single-mirror.company.com/team
+----
+.Example Output
+[source,terminal]
+----
+I: Image mirror 'abc123def456' has been updated on cluster 'mycluster'
+I: Source: registry.example.com/team
+I: Updated mirrors: [mirror.corp.com/team backup.corp.com/team new-mirror.corp.com/team]
+----
+
+Replaces all mirrors on an image mirror configuration.
+
+[source,terminal]
+----
+$ rosa edit image-mirror --cluster=mycluster --id=abc123def456 \
+  --mirrors=new-primary.company.com/team,new-secondary.company.com/team
+----
+
+
+[id="list-image-mirroring_{context}"]
+==  Listing all image mirror configurations
+.Procedure
+
+To list all image mirror  configurations for a {product-title} cluster, run the following command:
+
+.Syntax
+[source,terminal]
+----
+$ rosa list image-mirrors [arguments]
+----
+
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--cluster
+|Required: Name or ID of the cluster.
+|--output
+|Optional: Output format. Allowed formats are `json`, `yaml`
+|--profile
+|Optional: Use a specific AWS profile from your credential file.
+|--region
+|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
+|===
+
+.Example
+
+Lists all image mirror configurations for a cluster.
+
+[source,terminal]
+----
+$ rosa list image-mirrors --cluster=mycluster
+----
+.Example Outputs
+[source,terminal]
+----
+ID              TYPE    SOURCE                    MIRRORS
+abc123def456    digest  registry.example.com/team mirror.corp.com/team, backup.corp.com/
+----
+
+[id="delete-image-mirroring_{context}"]
+==  Deleting an image mirror configuration
+[NOTE]
+====
+Delete operations require confirmation unless the `--yes` or `--y` argument is used.
+====
+
+.Procedure
+
+To delete an image mirror configuration from a {product-title} cluster, run the following command:
+
+.Syntax
+[source,terminal]
+----
+$ rosa delete image-mirror [arguments]
+----
+
+.Arguments
+[cols="30,70"]
+|===
+|Option |Definition
+
+|--cluster
+|Required: The name or ID (string) of the cluster that the image mirror configuration will be deleted from.
+|--id
+|Required: ID of the image mirror configuration to delete.
+|`--yes`, `-y`
+|Optional: Automatically answers "yes" to confirm deletion.
+|--profile
+|Optional: Use a specific AWS profile from your credential file.
+|--region
+|Optional: Use a specific AWS region, overriding the AWS_REGION environment variable.
+
+|===
+.Examples
+Deletes an image mirror configuration without a confirmation prompt.
+
+[source,terminal]
+----
+$ rosa delete image-mirror --cluster=mycluster abc123def456 --yes
+----
+
+.Example Output
+[source,terminal]
+----
+I: Image mirror 'abc123def456' has been deleted from cluster 'mycluster'
+----
+
+Deletes an image mirror configuration with a confirmation prompt.
+
+[source,terminal]
+----
+$ rosa delete image-mirror --cluster=mycluster --id=abc123def456
+----
+