Makes changes to image books as a result of ADV errors

modules/images-add-tags-to-imagestreams.adoc

@@ -5,22 +5,22 @@
 [id="images-add-tags-to-imagestreams_{context}"]
 = Adding tags to image streams
 
-An image stream in {product-title} comprises zero or more container images identified by tags.
+[role="_abstract"]
+You can add tags to image streams using the `oc tag` command.
+You can add tags to organize images and create aliases for specific versions.
 
-There are different types of tags available. The default behavior uses a `permanent` tag, which points to a specific image in time. If the `permanent` tag is in use and the source changes, the tag does not change for the destination.
-
-A `tracking` tag means the destination tag's metadata is updated during the import of the source tag.
+An image stream in {product-title} comprises zero or more container images identified by tags. There are different types of tags available. The default behavior uses a Permanent tag, which points to a specific image in time. If the Permanent tag is in use and the source changes, the tag does not change for the destination. A Tracking tag means that the destination tag's metadata is updated during the import of the source tag.
 
 .Procedure
 
-* You can add tags to an image stream using the `oc tag` command:
+* Add a tag to an image stream by entering the following command. The default behavior creates a Permanent Tag that is pinned to an image ID:
 +
 [source,terminal]
 ----
-$ oc tag <source> <destination>
+$ oc tag <source_reference> <destination_image_stream>:<destination_tag>
 ----
 +
-For example, to configure the `ruby` image stream `static-2.0` tag to always refer to the current image for the `ruby` image stream `2.0` tag:
+For example, to configure the `ruby` image stream `static-2.0` tag to always refer to the specific image that the `ruby:2.0` tag points to right now, enter the following command:
 +
 [source,terminal]
 ----
@@ -29,22 +29,35 @@ $ oc tag ruby:2.0 ruby:static-2.0
 +
 This creates a new image stream tag named `static-2.0` in the `ruby` image stream. The new tag directly references the image id that the `ruby:2.0` image stream tag pointed to at the time `oc tag` was run, and the image it points to never changes.
 
-* To ensure the destination tag is updated when the source tag changes, use the `--alias=true` flag:
+* Use the `--alias=true` flag to create a Tracking Tag. This ensures the destination tag automatically updates (tracks) when the source tag changes to point to a new image. For example, to ensure that the `ruby:latest` tag always reflects whatever image is currently tagged as `ruby:2.0`, enter the following command:
 +
 [source,terminal]
 ----
-$ oc tag --alias=true <source> <destination>
+$ oc tag --alias=true ruby:2.0 ruby:latest
 ----
-
++
 [NOTE]
 ====
-Use a tracking tag for creating permanent aliases, for example, `latest` or `stable`. The tag only works correctly within a single image stream. Trying to create a cross-image stream alias produces an error.
+A Tracking Tag created with `--alias=true` automatically updates its image ID whenever the source tag changes. Use tracking tags for creating common, long-lived aliases, such as latest or stable. This tracking behavior only works correctly within a single image stream. Trying to create a cross-image stream alias produces an error.
 ====
 
-* You can also add the `--scheduled=true` flag to have the destination tag be
-refreshed, or re-imported, periodically. The period is configured globally at
-the system level.
+* Optional: Use the `--scheduled=true` flag to have the destination tag be refreshed, or re-imported, periodically. The period is configured globally at the system level. For example:
++
+[source,terminal]
+----
+$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --scheduled=true
+----
 
-* The `--reference` flag creates an image stream tag that is not imported. The tag points to the source location, permanently.
+* Optional: Use the `--reference` flag to create an image stream tag that is not imported. The tag permanently points to the source location, regardless of changes to the source image. For example:
 +
-If you want to instruct {product-title} to always fetch the tagged image from the integrated registry, use `--reference-policy=local`. The registry uses the pull-through feature to serve the image to the client. By default, the image blobs are mirrored locally by the registry. As a result, they can be pulled more quickly the next time they are needed. The flag also allows for pulling from insecure registries without a need to supply `--insecure-registry` to the container runtime as long as the image stream has an insecure annotation or the tag has an insecure import policy.
+[source,terminal]
+----
+$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference
+----
+
+* Optional: Use the `--reference-policy=local` flag to instruct {product-title} to always fetch the tagged image from the integrated registry. The registry uses the pull-through feature to serve the image to the client. By default, the image blobs are mirrored locally by the registry. As a result, they can be pulled more quickly the next time they are needed. The flag also allows for pulling from insecure registries without a need to supply `--insecure-registry` to the container runtime as long as the image stream has an insecure annotation or the tag has an insecure import policy. For example:
++
+[source,terminal]
+----
+$ oc tag <source_reference> <destination_image_stream>:<destination_tag> --reference-policy=local
+----

modules/images-image-pull-policy-overview.adoc

@@ -5,7 +5,10 @@
 [id="images-image-pull-policy-overview_{context}"]
 = Image pull policy overview
 
-When {product-title} creates containers, it uses the container `imagePullPolicy` to determine if the image should be pulled prior to starting the container. There are three possible values for `imagePullPolicy`:
+[role="_abstract"]
+The container's `imagePullPolicy` parameter dictates how {product-title} manages image retrieval when starting a container. This policy determines if the container image must be pulled from a registry or if a locally cached copy can be used.
+
+There are three possible values for `imagePullPolicy`:
 
 .`imagePullPolicy` values
 [width="50%",options="header"]
@@ -22,8 +25,33 @@ When {product-title} creates containers, it uses the container `imagePullPolicy`
 |Never pull the image.
 |===
 
-
-If a container `imagePullPolicy` parameter is not specified, {product-title} sets it based on the image tag:
-
-. If the tag is `latest`, {product-title} defaults `imagePullPolicy` to `Always`.
-. Otherwise, {product-title} defaults `imagePullPolicy` to `IfNotPresent`.
+If you omit the `imagePullPolicy` parameter from your YAML file, {product-title} automatically sets it based on the image tag:
+
+* If the tag is `latest`, the default policy is `Always`. This ensures that the container always uses the latest version of the image.
+
+* If the image tag is anything other than `latest`, for example, `:v1.2.3`, the default policy is `IfNotPresent`. This ensures that the container uses the locally cached version of the image if it exists, avoiding unnecessary pulls from the registry.
+
+.Example `imagePullPolicy` configuration
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+# ...
+spec:
+  # ...
+  template:
+    spec:
+      containers:
+      - name: my-app-container
+        image: registry.example.com/myapp:v1.2.3
+        imagePullPolicy: IfNotPresent
+        ports:
+        - containerPort: 8080
+----
+
+--
+where:
+
+`image`:: Specifies is the image to use. In this example, the image tag is explicitly set to `v1.2.3`.
+`imagePullPolicy`:: Specifies the policy to use. In this example, the policy is set to `IfNotPresent` because the image tag is not `latest`.
+--

modules/images-imagestream-reference-types.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+// * openshift_images/tagging-images
+
+:_mod-docs-content-type: REFERENCE
+[id="images-imagestream-reference-types_{context}"]
+= Understanding image stream reference types
+
+[role="_abstract"]
+Image streams in {product-title} allow you to reference container images using different reference types. These reference types define which specific image version your builds and deployments utilize.
+
+`ImageStreamImage` objects are automatically created in {product-title} when you import or tag an image into the image stream. You never have to explicitly define an `ImageStreamImage` object in any image stream definition that you use to create image streams.
+
+[NOTE]
+====
+Example image stream definitions often contain definitions of `ImageStreamTag` and references to `DockerImage`, but never contain definitions of `ImageStreamImage`.
+====
+
+.Imagestream reference types
+[width="50%",options="header"]
+|===
+| Reference Type | Description | Syntax Examples |
+| `ImageStreamTag` | References or retrieves an image for a given image stream and human-readable tag. | `image_stream_name:tag` 
+| `ImageStreamImage` | References or retrieves an image for a given image stream and immutable SHA ID (digest). | `image_stream_name@id` 
+| `DockerImage` | References or retrieves an image from an external registry. Uses the standard `docker pull` specification. | `openshift/ruby-20-centos7:2.0`<br>`registry.redhat.io/rhel7:latest`<br>`centos/ruby-22-centos7@sha256:3a335d7d...` 
+|===

modules/images-referencing-images-imagestreams.adoc

@@ -3,65 +3,75 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="images-referencing-images-imagestreams_{context}"]
-= Referencing images in imagestreams
+= Using image stream reference syntax
 
-You can use tags to reference images in image streams using the following reference types.
-
-.Imagestream reference types
-[width="50%",options="header"]
-|===
-|Reference type |Description
-
-|`ImageStreamTag`
-|An `ImageStreamTag` is used to reference or retrieve an image for a given image stream and tag.
-
-|`ImageStreamImage`
-|An `ImageStreamImage` is used to reference or retrieve an image for a given image stream and image `sha` ID.
-
-|`DockerImage`
-|A `DockerImage` is used to reference or retrieve an image for a given external registry. It uses standard Docker `pull specification` for its name.
-|===
-
-When viewing example image stream definitions you may notice they contain definitions of `ImageStreamTag` and references to `DockerImage`, but nothing related to `ImageStreamImage`.
-
-This is because the `ImageStreamImage` objects are automatically created in {product-title} when you import or tag an image into the image stream. You should never have to explicitly define an `ImageStreamImage` object in any image stream definition that you use to create image streams.
+[role="_abstract"]
+To ensure your builds or deployments use the correct image, you must apply the appropriate reference syntax based on whether you are referencing an image stream, a tag, a specific ID, or an external registry.
 
 .Procedure
 
-* To reference an image for a given image stream and tag, use `ImageStreamTag`:
+* To reference an image by a mutable tag (`ImageStreamTag`) from an image stream within your cluster, use the `<image_stream_name>:<tag>` format in your build or deployment configuration. For example:
 +
+[source,yaml]
 ----
-<image_stream_name>:<tag>
+# ...
+spec:
+  containers:
+    - name: my-app
+      image: <image_stream_name>:<tag>
 ----
++
+--
+where:
 
-* To reference an image for a given image stream and image `sha` ID, use `ImageStreamImage`:
+`image`:: Specifies the image to use from the image stream. For example, `ruby:2.0`.
+--
+
+* To reference a specific, immutable image ID, or digest, within an image stream, use the `<image_stream_name>@<image_id>` format in your build or deployment configuration. For example:
 +
+[source,yaml]
 ----
-<image_stream_name>@<id>
+# ...
+spec:
+  containers:
+    - name: my-app
+      image: <image_stream_name>@<image_id>
 ----
 +
-The `<id>` is an immutable identifier for a specific image, also called a
-digest.
+--
+where:
 
-* To reference or retrieve an image for a given external registry, use `DockerImage`:
-+
-----
-openshift/ruby-20-centos7:2.0
-----
+`image`:: Specifies the image to use from the image stream. For example, `ruby@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e`.
+--
 +
 [NOTE]
 ====
-When no tag is specified, it is assumed the `latest` tag is used.
+Using the image ID with the `@id` syntax ensures your configuration always uses the exact same image, even if the tag is later updated to point to a different image.
 ====
+
+* To reference an image from an external registry by using the DockerImage format, use the standard Docker pull specification: `<registry>/<namespace>/<image_name>:<tag>`. For example:
 +
-You can also reference a third-party registry:
-+
+[source,yaml]
 ----
-registry.redhat.io/rhel7:latest
+# ...
+spec:
+  source:
+    type: Dockerfile
+  strategy:
+    type: Docker
+    dockerStrategy:
+      from:
+        kind: DockerImage
+        name: <registry>/<namespace>/<image_name>:<tag>
 ----
 +
-Or an image with a digest:
+--
+where:
+
+`image`:: Specifies the image to use from the external registry. For example, `registry.redhat.io/rhel7:latest`.
+--
 +
-----
-centos/ruby-22-centos7@sha256:3a335d7d8a452970c5b4054ad7118ff134b3a6b50a2bb6d0c07c746e8986b28e
-----
+[NOTE]
+====
+When no tag is specified in a `DockerImage` reference, the `latest` tag is assumed.
+====

modules/images-tag.adoc

@@ -18,4 +18,4 @@ registry.access.redhat.com/openshift3/jenkins-2-rhel7:v3.11.59-2
 
 You can add additional tags to an image. For example, an image might be assigned the tags `:v3.11.59-2` and `:latest`.
 
-{product-title} provides the `oc tag` command, which is similar to the `docker tag` command, but operates on image streams instead of directly on images.
+{product-title} provides the `oc tag` command, which is similar to the `docker tag` command, but operates on image streams instead of directly on images.

openshift_images/managing_images/image-pull-policy.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-Each container in a pod has a container image. After you have created an image and pushed it to a registry, you can then refer to it in the pod.
+[role="_abstract"]
+Image pull policy controls when {product-title} pulls container images from registries.
+You configure image pull policy to manage image updates and optimize pod startup performance.
 
-include::modules/images-image-pull-policy-overview.adoc[leveloffset=+1]
+include::modules/images-image-pull-policy-overview.adoc[leveloffset=+1]

openshift_images/managing_images/managing-images-overview.adoc

@@ -6,6 +6,15 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-With {product-title} you can interact with images and set up image streams, depending on where the registries of the images are located, any authentication requirements around those registries, and how you want your builds and deployments to behave.
+[role="_abstract"]
+With {product-title}, you interact with images (the static container definitions) and image streams (a layer of abstraction over those images). This interaction is based on where the container registries are located, any necessary authentication, and how you want your builds and deployments to behave.
 
-include::modules/images-managing-overview.adoc[leveloffset=+1]
+An image stream is a resource that comprises any number of container images, each identified by a specific tag, such as `v1.0` or `latest`. It provides a single virtual view of related images, similar to a container image repository, without containing the actual image data itself.
+
+The primary benefit of using image streams is automation:
+
+* Builds and deployments can watch an image stream.
+
+* They receive notifications when new images are added to the stream or when a tag is modified to point to a new image.
+
+* They can then automatically react by performing a new build or a new deployment, respectively.

openshift_images/managing_images/tagging-images.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-The following sections provide an overview and instructions for using image tags in the context of container images for working with {product-title} image streams and their tags.
+[role="_abstract"]
+Image tags identify specific versions of container images in image streams. You can use image tags to organize images and control which versions your builds and deployments use.
 
 include::modules/images-tag.adoc[leveloffset=+1]
 
@@ -18,6 +19,7 @@ include::modules/images-remove-tag-imagestream.adoc[leveloffset=+1]
 
 include::modules/images-referencing-images-imagestreams.adoc[leveloffset=+1]
 
+include::modules/images-imagestream-reference-types.adoc[leveloffset=+1]
 
 ////
 == Additional information