From 61d178a1989f5680a41a4a0bccc5b6f8a875c6e4 Mon Sep 17 00:00:00 2001 From: Jesse Dohmann Date: Wed, 3 Dec 2025 13:41:49 -0800 Subject: [PATCH] update with CQA DITA compliance --- ...ference-images-from-secure-registries.adoc | 7 ++++-- ...mages-getting-info-about-imagestreams.adoc | 5 ++-- modules/images-imagestream-adding-tags.adoc | 3 ++- modules/images-imagestream-configure.adoc | 24 +++++++++++-------- ...mages-imagestream-external-image-tags.adoc | 3 ++- ...stream-import-images-private-registry.adoc | 3 ++- ...images-imagestream-import-import-mode.adoc | 17 ++++--------- modules/images-imagestream-import.adoc | 5 ++-- modules/images-imagestream-mapping.adoc | 3 ++- ...ages-imagestream-periodic-import-list.adoc | 5 ++-- modules/images-imagestream-remove-tag.adoc | 3 ++- ...ages-imagestream-specify-architecture.adoc | 5 ++-- .../images-imagestream-ssl-import-list.adoc | 9 +++---- modules/images-imagestream-update-tag.adoc | 3 ++- ...ges-using-imagestream-change-triggers.adoc | 4 ++-- modules/images-using-imagestream-images.adoc | 3 +++ modules/images-using-imagestream-tags.adoc | 3 +++ modules/importmode-configuration-fields.adoc | 5 +++- 18 files changed, 65 insertions(+), 45 deletions(-) diff --git a/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc b/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc index a70b510893fc..85b01296b487 100644 --- a/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc +++ b/modules/images-allow-pods-to-reference-images-from-secure-registries.adoc @@ -6,7 +6,10 @@ [id="images-allow-pods-to-reference-images-from-secure-registries_{context}"] = Allowing pods to reference images from other secured registries -To pull a secured container from other private or secured registries, you must create a pull secret from your container client credentials, such as Docker or Podman, and add it to your service account. +[role="_abstract"] +To ensure reliable application deployment on {product-title}, configure image pull secrets. This allows your resources, such as pods and deployments, to authenticate and pull container images successfully from private registries. + +To pull a secured container from other private or secured registries, you must create a pull secret from your container client credentials, such as Docker or Podman, and add it to your service account. Both Docker and Podman use a configuration file to store authentication details to log in to secured or insecure registry: @@ -55,4 +58,4 @@ metadata: resourceVersion: "37676" uid: e2851531-01bc-48ba-878c-de96cfe31020 type: Opaque ----- \ No newline at end of file +---- diff --git a/modules/images-getting-info-about-imagestreams.adoc b/modules/images-getting-info-about-imagestreams.adoc index 22b64752bcf6..27e346ce8cd1 100644 --- a/modules/images-getting-info-about-imagestreams.adoc +++ b/modules/images-getting-info-about-imagestreams.adoc @@ -5,7 +5,8 @@ [id="images-getting-info-about-imagestreams_{context}"] = Getting information about image streams -You can get general information about the image stream and detailed information about all the tags it is pointing to. +[role="_abstract"] +To efficiently manage and monitor your image streams in {product-title}, retrieve information about their versions. You can get general information about the image stream and detailed information about all the tags it is pointing to, ensuring your deployed applications rely on the correct image versions. .Procedure @@ -106,4 +107,4 @@ linux/mips64le linux/ppc64le linux/riscv64 linux/s390x ----- \ No newline at end of file +---- diff --git a/modules/images-imagestream-adding-tags.adoc b/modules/images-imagestream-adding-tags.adoc index fb501d3e938b..f824fb126947 100644 --- a/modules/images-imagestream-adding-tags.adoc +++ b/modules/images-imagestream-adding-tags.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-adding-tags_{context}"] = Adding tags to an image stream -You can add additional tags to image streams. +[role="_abstract"] +To accurately manage and track specific versions of your container images, add tags to your image streams within {product-title}, This ensures reliable referencing and deployment throughout your environment. .Procedure diff --git a/modules/images-imagestream-configure.adoc b/modules/images-imagestream-configure.adoc index 679f5fecae5e..e8c3093968df 100644 --- a/modules/images-imagestream-configure.adoc +++ b/modules/images-imagestream-configure.adoc @@ -5,6 +5,9 @@ [id="images-imagestream-configure_{context}"] = Configuring image streams +[role="_abstract"] +To customize image retrieval and security policies for your applications, configure image streams within {product-title}. This process lets you define image pull specifications, manage tags, and control access permissions necessary for reliable application deployment. + An `ImageStream` object file contains the following elements. [id="image-stream-object-definition_{context}"] @@ -20,26 +23,27 @@ metadata: labels: app: ruby-sample-build template: application-template-stibuild - name: origin-ruby-sample <1> + name: origin-ruby-sample namespace: test spec: {} status: - dockerImageRepository: 172.30.56.218:5000/test/origin-ruby-sample <2> + dockerImageRepository: 172.30.56.218:5000/test/origin-ruby-sample tags: - items: - created: 2017-09-02T10:15:09Z - dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d <3> + dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d generation: 2 - image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 <4> + image: sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 - created: 2017-09-01T13:40:11Z dockerImageReference: 172.30.56.218:5000/test/origin-ruby-sample@sha256:909de62d1f609a717ec433cc25ca5cf00941545c83a01fb31527771e1fab3fc5 generation: 1 image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d - tag: latest <5> + tag: latest ---- +where -<1> The name of the image stream. -<2> Docker repository path where new images can be pushed to add or update them in this image stream. -<3> The SHA identifier that this image stream tag currently references. Resources that reference this image stream tag use this identifier. -<4> The SHA identifier that this image stream tag previously referenced. Can be used to rollback to an older image. -<5> The image stream tag name. +`name`:: Specifies the name of the image stream +`ruby-sample`:: Specifies the Docker repository path where new images can be pushed to add or update them in this image stream. +`dockerImageReference`:: Specifies the SHA identifier that this image stream tag currently references. Resources that reference this image stream tag use this identifier +`image`:: Specifies the SHA identifier that this image stream tag previously referenced. You can use it to rollback to an older image. +`tag`:: Specifies the image stream tag name. diff --git a/modules/images-imagestream-external-image-tags.adoc b/modules/images-imagestream-external-image-tags.adoc index 26761257f2f2..e47c1e03337d 100644 --- a/modules/images-imagestream-external-image-tags.adoc +++ b/modules/images-imagestream-external-image-tags.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-external-image-tags_{context}"] = Adding tags for an external image -You can add tags for external images. +[role="_abstract"] +To enable {product-title} resources to track and consume container images sourced from external registries, add tags to the corresponding image streams. This action integrates external image content securely into your cluster's local image management system. .Procedure diff --git a/modules/images-imagestream-import-images-private-registry.adoc b/modules/images-imagestream-import-images-private-registry.adoc index 24a1ef55f539..856bb78314ee 100644 --- a/modules/images-imagestream-import-images-private-registry.adoc +++ b/modules/images-imagestream-import-images-private-registry.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-import-images-private-registry_{context}"] = Importing images and image streams from private registries -An image stream can be configured to import tag and image metadata from private image registries requiring authentication. This procedure applies if you change the registry that the Cluster Samples Operator uses to pull content from to something other than link:https://registry.redhat.io[registry.redhat.io]. +[role="_abstract"] +To securely manage content from external sources, configure your image streams to import tag and image metadata from private registries requiring authentication. This procedure is essential if you change the registry that the Cluster Samples Operator uses for pulling content to something other than the default link:https://registry.redhat.io[registry.redhat.io]. [NOTE] ==== diff --git a/modules/images-imagestream-import-import-mode.adoc b/modules/images-imagestream-import-import-mode.adoc index d460d7d0cf4b..0e953149bde2 100644 --- a/modules/images-imagestream-import-import-mode.adoc +++ b/modules/images-imagestream-import-import-mode.adoc @@ -5,9 +5,12 @@ [id="images-imagestream-import-import-mode_{context}"] = Working with manifest lists -You can import a single sub-manifest, or all manifests, of a manifest list when using `oc import-image` or `oc tag` CLI commands by adding the `--import-mode` flag. +[role="_abstract"] +To precisely manage multi-architecture or variant images contained within a manifest list, use the `--import-mode` flag with `oc import-image` or `oc tag` CLI commands. This functionality allows you to import a single sub-manifest, or all manifests, of a manifest list, providing fine-grained control over your image stream content. -Refer to the commands below to create an image stream that includes a single sub-manifest or multi-architecture images. +In some cases, users might want to use sub-manifests directly. When `oc adm prune images` is run, or the `CronJob` pruner runs, they cannot detect when a sub-manifest list is used. As a result, an administrator using `oc adm prune images`, or the `CronJob` pruner, might delete entire manifest lists, including sub-manifests. + +To avoid this limitation, you can use the manifest list by tag or by digest instead. .Procedure @@ -43,13 +46,3 @@ $ oc import-image --from=/ ==== The `--import-mode=` default value is `Legacy`. Excluding this value, or failing to specify either `Legacy` or `PreserveOriginal`, imports a single sub-manifest. An invalid import mode returns the following error: `error: valid ImportMode values are Legacy or PreserveOriginal`. ==== - - -[id="images-imagestream-import-import-mode-limitations"] -== Limitations - -Working with manifest lists has the following limitations: - -* In some cases, users might want to use sub-manifests directly. When `oc adm prune images` is run, or the `CronJob` pruner runs, they cannot detect when a sub-manifest list is used. As a result, an administrator using `oc adm prune images`, or the `CronJob` pruner, might delete entire manifest lists, including sub-manifests. -+ -To avoid this limitation, you can use the manifest list by tag or by digest instead. diff --git a/modules/images-imagestream-import.adoc b/modules/images-imagestream-import.adoc index ef3ceb06b42a..a179f7deb81f 100644 --- a/modules/images-imagestream-import.adoc +++ b/modules/images-imagestream-import.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-import_{context}"] = Configuring periodic importing of image stream tags -When working with an external container image registry, to periodically re-import an image, for example to get latest security updates, you can use the `--scheduled` flag. +[role="_abstract"] +To maintain up-to-date image definitions from an external container image registry, configure periodic importing of image stream tags. This process allows you to quickly re-import images for critical security updates by using the `--scheduled` flag. .Procedure @@ -36,4 +37,4 @@ This command causes {product-title} to periodically update this particular image [source,terminal] ---- $ oc tag ----- \ No newline at end of file +---- diff --git a/modules/images-imagestream-mapping.adoc b/modules/images-imagestream-mapping.adoc index f4e7760df7f2..c746f35c2c52 100644 --- a/modules/images-imagestream-mapping.adoc +++ b/modules/images-imagestream-mapping.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-mapping_{context}"] = Image stream mapping -When the integrated registry receives a new image, it creates and sends an image stream mapping to {product-title}, providing the image's project, name, tag, and image metadata. +[role="_abstract"] +Manage how {product-title} tracks newly uploaded images by understanding image stream mapping. When the integrated registry receives a new image, it automatically creates and sends an image stream mapping, providing the image's crucial project, name, tag, and metadata. [NOTE] ==== diff --git a/modules/images-imagestream-periodic-import-list.adoc b/modules/images-imagestream-periodic-import-list.adoc index fef883b64ae1..33c054c97bd6 100644 --- a/modules/images-imagestream-periodic-import-list.adoc +++ b/modules/images-imagestream-periodic-import-list.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-periodic-import-list_{context}"] = Configuring periodic importing of manifest lists -To periodically re-import a manifest list, you can use the `--scheduled` flag. +[role="_abstract"] +To maintain up-to-date image references for complex, multi-architecture images, configure periodic importing of manifest lists. To periodically re-import a manifest list, you can use the `--scheduled` flag, ensuring your image stream tracks the latest versions from external registries. .Procedure @@ -15,4 +16,4 @@ To periodically re-import a manifest list, you can use the `--scheduled` flag. ---- $ oc import-image --from=// \ --import-mode='PreserveOriginal' --scheduled=true ----- \ No newline at end of file +---- diff --git a/modules/images-imagestream-remove-tag.adoc b/modules/images-imagestream-remove-tag.adoc index d964f521578e..4dfe09b4a183 100644 --- a/modules/images-imagestream-remove-tag.adoc +++ b/modules/images-imagestream-remove-tag.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-remove-tag_{context}"] = Removing image stream tags -You can remove old tags from an image stream. +[role="_abstract"] +To maintain control over your image history and simplify management within {product-title}, you can remove old tags from an image stream. This action helps ensure that your resources track only the current and necessary image references. .Procedure diff --git a/modules/images-imagestream-specify-architecture.adoc b/modules/images-imagestream-specify-architecture.adoc index d7c6d9c9cfe4..ef63719cc1e4 100644 --- a/modules/images-imagestream-specify-architecture.adoc +++ b/modules/images-imagestream-specify-architecture.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-specify-architecture_{context}"] = Specifying architecture for --import-mode -You can swap your imported image stream between multi-architecture and single architecture by excluding or including the `--import-mode=` flag +[role="_abstract"] +To control the architecture of your imported images and ensure proper deployment, use the `--import-mode=` flag. You can swap your imported image stream between multi-architecture and single architecture by excluding or including the `--import-mode=` flag as needed. .Procedure @@ -20,4 +21,4 @@ $ oc import-image --from=// + -- include::snippets/update-image-stream-to-multi-arch.adoc[] --- \ No newline at end of file +-- diff --git a/modules/images-imagestream-ssl-import-list.adoc b/modules/images-imagestream-ssl-import-list.adoc index ef455374c25b..e3172be42010 100644 --- a/modules/images-imagestream-ssl-import-list.adoc +++ b/modules/images-imagestream-ssl-import-list.adoc @@ -3,16 +3,17 @@ :_mod-docs-content-type: PROCEDURE [id="images-imagestream-ssl-import-list_{context}"] -= Configuring SSL/TSL when importing manifest lists += Configuring SSL/TLS when importing manifest lists -To configure SSL/TSL when importing a manifest list, you can use the `--insecure` flag. +[role="_abstract"] +To control connection security and access policies for manifest lists sourced from external repositories, configure SSL/TLS settings during image importing. To configure SSL/TLS when importing a manifest list, you can use the `--insecure` flag to bypass standard certificate validation requirements if necessary. .Procedure -* Set `--insecure=true` so that importing a manifest list skips SSL/TSL verification. For example: +* Set `--insecure=true` so that importing a manifest list skips SSL/TLS verification. For example: + [source,terminal] ---- $ oc import-image --from=// \ --import-mode='PreserveOriginal' --insecure=true ----- \ No newline at end of file +---- diff --git a/modules/images-imagestream-update-tag.adoc b/modules/images-imagestream-update-tag.adoc index 15bf1e82a9ca..4277d643cda8 100644 --- a/modules/images-imagestream-update-tag.adoc +++ b/modules/images-imagestream-update-tag.adoc @@ -5,7 +5,8 @@ [id="images-imagestream-update-tag_{context}"] = Updating image stream tags -You can update a tag to reflect another tag in an image stream. +[role="_abstract"] +To maintain flexibility and consistency in deployment definitions, update an image stream tag to reflect a different tag in {product-title}. Specifically, you can update a tag to reflect another tag in an image stream, which is essential for managing image versions effectively. .Procedure diff --git a/modules/images-using-imagestream-change-triggers.adoc b/modules/images-using-imagestream-change-triggers.adoc index fa4eb203bdac..136260ae2387 100644 --- a/modules/images-using-imagestream-change-triggers.adoc +++ b/modules/images-using-imagestream-change-triggers.adoc @@ -5,8 +5,8 @@ [id="images-using-imagestream-change-triggers_{context}"] = Image stream change triggers -Image stream triggers allow your builds and deployments to be automatically -invoked when a new version of an upstream image is available. +[role="_abstract"] +To automate your application lifecycle and ensure they use the latest code, configure image stream triggers in {product-title}. Image stream triggers allow your builds and deployments to be automatically invoked when a new version of an upstream image is available. //from FAQ diff --git a/modules/images-using-imagestream-images.adoc b/modules/images-using-imagestream-images.adoc index 899c0c172025..c9faf44a4d36 100644 --- a/modules/images-using-imagestream-images.adoc +++ b/modules/images-using-imagestream-images.adoc @@ -5,6 +5,9 @@ [id="images-using-imagestream-images_{context}"] = Image stream images +[role="_abstract"] +To precisely identify and manage the actual image content associated with a specific tag, reference and use image stream images in {product-title}. This ensures your application deployments reliably target immutable image definitions. + An image stream image points from within an image stream to a particular image ID. Image stream images allow you to retrieve metadata about an image from a particular image stream where it is tagged. diff --git a/modules/images-using-imagestream-tags.adoc b/modules/images-using-imagestream-tags.adoc index b4530e732c74..aec50f4b0594 100644 --- a/modules/images-using-imagestream-tags.adoc +++ b/modules/images-using-imagestream-tags.adoc @@ -5,6 +5,9 @@ [id="images-using-imagestream-tags_{context}"] = Image stream tags +[role="_abstract"] +To maintain human-readable references to immutable images, utilize image stream tags within {product-title}. These tags are essential because they enable your builds and deployments to accurately target specific, stable image content. + An image stream tag is a named pointer to an image in an image stream. It is abbreviated as `istag`. An image stream tag is used to reference or retrieve an image for a given image stream and tag. Image stream tags can reference any local or externally managed image. It contains a history of images represented as a stack of all images the tag ever pointed to. Whenever a new or existing image is tagged under a particular image stream tag, it is placed at the first position in the history stack. The image previously occupying the top position is available at the second position. This allows for easy rollbacks to make tags point to historical images again. diff --git a/modules/importmode-configuration-fields.adoc b/modules/importmode-configuration-fields.adoc index dc6b2b09887e..7b676c355595 100644 --- a/modules/importmode-configuration-fields.adoc +++ b/modules/importmode-configuration-fields.adoc @@ -5,6 +5,9 @@ [id="importmode-configuration-fields_{context}"] = Configuration fields for --import-mode +[role="_abstract"] +To implement multi-architecture image management using the `--import-mode` flag, reference the necessary configuration fields. These fields define precise parameters for selecting and importing specific manifests into your {product-title} cluster. + The following table describes the options available for the `--import-mode=` flag: [cols="3a,8a",options="header"] @@ -20,4 +23,4 @@ The following table describes the options available for the `--import-mode=` fla | *PreserveOriginal* | When specified, the original manifest is preserved. For manifest lists, the manifest list and all of its sub-manifests are imported. -|=== \ No newline at end of file +|===