Images docs fixes during ROSA review

Michael Burke · Michael Burke · commit 73849903d7f7 · 2023-11-07T09:18:29.000-05:00
diff --git a/modules/cli-installing-cli.adoc b/modules/cli-installing-cli.adoc
@@ -133,8 +133,10 @@ To check your `PATH`, execute the following command:
 $ echo $PATH
 ----
 
-After you install the OpenShift CLI, it is available using the `oc` command:
+.Verification
 
+* After you install the OpenShift CLI, it is available using the `oc` command:
++
 [source,terminal]
 ----
 $ oc <command>
@@ -177,8 +179,10 @@ To check your `PATH`, open the command prompt and execute the following command:
 C:\> path
 ----
 
-After you install the OpenShift CLI, it is available using the `oc` command:
+.Verification
 
+* After you install the OpenShift CLI, it is available using the `oc` command:
++
 [source,terminal]
 ----
 C:\> oc <command>
@@ -226,8 +230,10 @@ To check your `PATH`, open a terminal and execute the following command:
 $ echo $PATH
 ----
 
-After you install the OpenShift CLI, it is available using the `oc` command:
+.Verification
 
+* After you install the OpenShift CLI, it is available using the `oc` command:
++
 [source,terminal]
 ----
 $ oc <command>
diff --git a/modules/images-configuration-allowed.adoc b/modules/images-configuration-allowed.adoc
@@ -18,12 +18,7 @@ When the `allowedRegistries` parameter is defined, all registries, including the
 
 .Procedure
 
-ifndef::openshift-rosa,openshift-dedicated[]
-. Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
-ifdef::openshift-rosa,openshift-dedicated[]
 * Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
 +
 [source,terminal]
 ----
@@ -67,8 +62,9 @@ Either the `allowedRegistries` parameter or the `blockedRegistries` parameter ca
 The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, the allowed registries list is used to update the image signature policy in the `/host/etc/containers/policy.json` file on each node.
 
 ifndef::openshift-rosa,openshift-dedicated[]
-. To check that the registries have been added to the policy file, use the following command on a node:
-// cannot create resource "namespaces"
+.Verification
+
+* To check that the registries have been added to the policy file, use the following command on a node:
 +
 [source,terminal]
 ----
diff --git a/modules/images-configuration-blocked.adoc b/modules/images-configuration-blocked.adoc
@@ -18,12 +18,7 @@ To prevent pod failure, do not add the `registry.redhat.io` and `quay.io` regist
 
 .Procedure
 
-ifndef::openshift-rosa,openshift-dedicated[]
-. Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
-ifdef::openshift-rosa,openshift-dedicated[]
 * Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
 +
 [source,terminal]
 ----
@@ -64,7 +59,9 @@ Either the `blockedRegistries` registry or the `allowedRegistries` registry can
 The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` resource for any changes to the registries. When the MCO detects a change, it drains the nodes, applies the change, and uncordons the nodes. After the nodes return to the `Ready` state, changes to the blocked registries appear in the `/etc/containers/registries.conf` file on each node.
 
 ifndef::openshift-rosa,openshift-dedicated[]
-. To check that the registries have been added to the policy file, use the following command on a node:
+.Verification
+
+* To check that the registries have been added to the policy file, use the following command on a node:
 // cannot create resource "namespaces"
 +
 [source,terminal]
diff --git a/modules/images-configuration-insecure.adoc b/modules/images-configuration-insecure.adoc
@@ -18,12 +18,7 @@ Insecure external registries should be avoided to reduce possible security risks
 
 .Procedure
 
-ifndef::openshift-rosa,openshift-dedicated[]
-. Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
-ifdef::openshift-rosa,openshift-dedicated[]
 * Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
 +
 [source,terminal]
 ----
@@ -72,8 +67,9 @@ When the `allowedRegistries` parameter is defined, all registries, including the
 The Machine Config Operator (MCO) watches the `image.config.openshift.io/cluster` CR for any changes to the registries, then drains and uncordons the nodes when it detects changes. After the nodes return to the `Ready` state, changes to the insecure and blocked registries appear in the `/etc/containers/registries.conf` file on each node.
 
 ifndef::openshift-rosa,openshift-dedicated[]
-. To check that the registries have been added to the policy file, use the following command on a node:
-// cannot create resource "namespaces"
+.Verification
+
+* To check that the registries have been added to the policy file, use the following command on a node:
 +
 [source,terminal]
 ----
diff --git a/modules/images-configuration-shortname.adoc b/modules/images-configuration-shortname.adoc
@@ -37,12 +37,7 @@ The `containerRuntimeSearchRegistries` parameter works only with the Podman and
 
 .Procedure
 
-ifndef::openshift-rosa,openshift-dedicated[]
-. Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
-ifdef::openshift-rosa,openshift-dedicated[]
 * Edit the `image.config.openshift.io/cluster` custom resource:
-endif::openshift-rosa,openshift-dedicated[]
 +
 [source,terminal]
 ----
@@ -96,7 +91,9 @@ When the `allowedRegistries` parameter is defined, all registries, including the
 ====
 
 ifndef::openshift-rosa,openshift-dedicated[]
-. To check that the registries have been added, when a node returns to the `Ready` state, use the following command on the node:
+.Verification
+
+* To check that the registries have been added, when a node returns to the `Ready` state, use the following command on the node:
 +
 [source,terminal]
 ----
diff --git a/modules/images-create-guide-general.adoc b/modules/images-create-guide-general.adoc
@@ -16,9 +16,9 @@ In addition, use tags in the `FROM` instruction, for example, `rhel:rhel7`, to m
 [discrete]
 == Maintain compatibility within tags
 
-When tagging your own images, try to maintain backwards compatibility within a tag. For example, if you provide an image named `foo` and it currently includes version `1.0`, you might provide a tag of `foo:v1`. When you update the image, as long as it continues to be compatible with the original image, you can continue to tag the new image `foo:v1`, and downstream consumers of this tag are able to get updates without being broken.
+When tagging your own images, try to maintain backwards compatibility within a tag. For example, if you provide an image named `image` and it currently includes version `1.0`, you might provide a tag of `image:v1`. When you update the image, as long as it continues to be compatible with the original image, you can continue to tag the new image `image:v1`, and downstream consumers of this tag are able to get updates without being broken.
 
-If you later release an incompatible update, then switch to a new tag, for example `foo:v2`. This allows downstream consumers to move up to the new version at will, but not be inadvertently broken by the new incompatible image. Any downstream consumer using `foo:latest` takes on the risk of any incompatible changes being introduced.
+If you later release an incompatible update, then switch to a new tag, for example `image:v2`. This allows downstream consumers to move up to the new version at will, but not be inadvertently broken by the new incompatible image. Any downstream consumer using `image:latest` takes on the risk of any incompatible changes being introduced.
 
 [discrete]
 == Avoid multiple processes
diff --git a/modules/images-imagestream-remove-tag.adoc b/modules/images-imagestream-remove-tag.adoc
@@ -20,11 +20,11 @@ For example:
 +
 [source,terminal]
 ----
-$ oc tag -d python:3.5
+$ oc tag -d python:3.6
 ----
 +
 .Example output
 [source,terminal]
 ----
-Deleted tag default/python:3.5.
+Deleted tag default/python:3.6
 ----
diff --git a/modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc b/modules/images-triggering-updates-imagestream-changes-kubernetes-about.adoc
@@ -12,25 +12,29 @@ The annotation is defined as follows:
 
 [source,yaml]
 ----
-Key: image.openshift.io/triggers
-Value:
-[
- {
-   "from": {
-     "kind": "ImageStreamTag", <1>
-     "name": "example:latest", <2>
-     "namespace": "myapp" <3>
-   },
-   "fieldPath": "spec.template.spec.containers[?(@.name==\"web\")].image", <4>
-   "paused": false <5>
- },
- ...
-]
+apiVersion: v1
+kind: Pod
+metadata:
+  annotations:
+    image.openshift.io/triggers:
+      [
+       {
+         "from": {
+           "kind": "ImageStreamTag", <1>
+           "name": "example:latest", <2>
+           "namespace": "myapp" <3>
+         },
+         "fieldPath": "spec.template.spec.containers[?(@.name==\"web\")].image", <4>
+         "paused": false <5>
+       },
+      # ...
+      ]
+# ...
 ----
 <1> Required: `kind` is the resource to trigger from must be `ImageStreamTag`.
 <2> Required: `name` must be the name of an image stream tag.
 <3> Optional: `namespace` defaults to the namespace of the object.
-<4> Required: `fieldPath` is the JSON path to change. This field is limited and accepts only a JSON path expression that precisely matches a container by ID or index. For pods, the JSON path is  "spec.containers[?(@.name='web')].image".
+<4> Required: `fieldPath` is the JSON path to change. This field is limited and accepts only a JSON path expression that precisely matches a container by ID or index. For pods, the JSON path is `spec.containers[?(@.name='web')].image`.
 <5> Optional: `paused` is whether or not the trigger is paused, and the default value is `false`. Set `paused` to `true` to temporarily disable this trigger.
 
 When one of the core Kubernetes resources contains both a pod template and this annotation, {product-title} attempts to update the object by using the image currently associated with the image stream tag that is referenced by trigger. The update is performed against the `fieldPath` specified.
diff --git a/modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc b/modules/images-triggering-updates-imagestream-changes-kubernetes-cli.adoc
@@ -17,5 +17,17 @@ When adding an image trigger to deployments, you can use the `oc set triggers` c
 ----
 $ oc set triggers deploy/example --from-image=example:latest -c web
 ----
-
++
+.Example deployment with trigger annotation
++
+[source,yaml]
+----
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  annotations:
+    image.openshift.io/triggers: '[{"from":{"kind":"ImageStreamTag","name":"example:latest"},"fieldPath":"spec.template.spec.containers[?(@.name==\"container\")].image"}]'
+# ...
+----
++
 Unless the deployment is paused, this pod template update automatically causes a deployment to occur with the new image value.
diff --git a/modules/images-using-imagestream-tags.adoc b/modules/images-using-imagestream-tags.adoc
@@ -14,6 +14,11 @@ The following image stream tag is from an `ImageStream` object:
 
 [source,yaml]
 ----
+kind: ImageStream
+apiVersion: image.openshift.io/v1
+metadata:
+  name: my-image-stream
+# ...  
   tags:
   - items:
     - created: 2017-09-02T10:15:09Z
@@ -25,6 +30,7 @@ The following image stream tag is from an `ImageStream` object:
       generation: 1
       image: sha256:47463d94eb5c049b2d23b03a9530bf944f8f967a0fe79147dd6b9135bf7dd13d
     tag: latest
+# ...
 ----
 
 Image stream tags can be permanent tags or tracking tags.
diff --git a/modules/samples-operator-crd.adoc b/modules/samples-operator-crd.adoc
@@ -28,5 +28,5 @@ The Cluster Samples Operator configuration resembles the following example:
 ----
 apiVersion: samples.operator.openshift.io/v1
 kind: Config
-...
+# ...
 ----
diff --git a/modules/templates-creating-from-console.adoc b/modules/templates-creating-from-console.adoc
@@ -4,15 +4,20 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="templates-creating-from-console_{context}"]
-= Creating an application by using the web console
+= Creating an application by using the web console 
 
 You can use the web console to create an application from a template.
 
 .Procedure
 
-. While in the desired project, click *Add to Project*.
+. Select *Developer* from the context selector at the top of the web console
+navigation menu.
 
-. Select either a builder image from the list of images in your project, or from the service catalog.
+. While in the desired project, click *+Add*
+
+. Click *All services* in the *Developer Catalog* tile.
+
+. Click *Builder Images* under *Type* to see the available builder images.
 +
 [NOTE]
 ====
@@ -28,16 +33,16 @@ metadata:
   name: "ruby"
   creationTimestamp: null
 spec:
-  dockerImageRepository: "registry.redhat.io/rhscl/ruby-26-rhel7"
+# ...
   tags:
-    -
-      name: "2.6"
+    - name: "2.6"
       annotations:
         description: "Build and run Ruby 2.6 applications"
         iconClass: "icon-ruby"
         tags: "builder,ruby" <1>
         supports: "ruby:2.6,ruby"
         version: "2.6"
+# ...
 ----
 <1> Including `builder` here ensures this image stream tag appears in the
 web console as a builder.
diff --git a/modules/templates-uploading.adoc b/modules/templates-uploading.adoc
@@ -6,18 +6,20 @@
 [id="templates-uploading_{context}"]
 = Uploading a template
 
-If you have a JSON or YAML file that defines a template, for example as seen in this example, you can upload the template to projects using the CLI. This saves the template to the project for repeated use by any user with appropriate access to that project. Instructions on writing your own templates are provided later in this topic.
+If you have a JSON or YAML file that defines a template, you can upload the template to projects using the CLI. This saves the template to the project for repeated use by any user with appropriate access to that project. Instructions about writing your own templates are provided later in this topic.
 
 .Procedure
 
-* Upload a template to your current project's template library, pass the JSON or YAML file with the following command:
+* Upload a template using one of the following methods:
+
+** Upload a template to your current project's template library, pass the JSON or YAML file with the following command:
 +
 [source,terminal]
 ----
 $ oc create -f <filename>
 ----
 
-* Upload a template to a different project using the `-n` option with the name of the project:
+** Upload a template to a different project using the `-n` option with the name of the project:
 +
 [source,terminal]
 ----
diff --git a/openshift_images/managing_images/using-image-pull-secrets.adoc b/openshift_images/managing_images/using-image-pull-secrets.adoc
@@ -8,7 +8,7 @@ toc::[]
 
 If you are using the {product-registry} and are pulling from image streams located in the same project, then your pod service account should already have the correct permissions and no additional action should be required.
 
-However, for other scenarios, such as referencing images across {product-title} projects or from secured registries, then additional configuration steps are required.
+However, for other scenarios, such as referencing images across {product-title} projects or from secured registries, additional configuration steps are required.
 
 You can obtain the image {cluster-manager-url-pull}. This pull secret is called `pullSecret`.
 
diff --git a/openshift_images/using_images/using-s21-images.adoc b/openshift_images/using_images/using-s21-images.adoc
@@ -23,9 +23,9 @@ S2I images are available for you to use directly from the {product-title} web co
 
 . Log in to the {product-title} web console using your login credentials. The default view for the {product-title} web console is the *Administrator* perspective.
 . Use the perspective switcher to switch to the *Developer* perspective.
-. In the *+Add* view, select an existing project from the list or use the *Project* drop-down list to create a new project.
-. Choose *All services* under the tile *Developer Catalog*.
-. Select the Type *Builder Images* then can see the available S2I images.
+. In the *+Add* view, use the *Project* drop-down list to select an existing project or create a new project.
+. Click *All services* in the *Developer Catalog* tile.
+. Click *Builder Images* under *Type* to see the available S2I images.
 
 S2I images are also available though the xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Cluster Samples Operator].
 
@@ -35,10 +35,11 @@ include::modules/images-s2i-build-process-overview.adoc[leveloffset=+1]
 [id="additional-resources_using-s21-images"]
 == Additional resources
 
-* For instructions on using the Cluster Samples Operator, see the xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator].
+* xref:../../openshift_images/configuring-samples-operator.adoc#configuring-samples-operator[Configuring the Cluster Samples Operator]
 ifndef::openshift-rosa,openshift-dedicated[]
-* For more information on S2I builds, see the xref:../../cicd/builds/build-strategies.adoc#builds-strategy-s2i-build_build-strategies[builds strategy documentation on S2I builds].
-* For troubleshooting assistance for the S2I process, see xref:../../support/troubleshooting/troubleshooting-s2i.adoc#troubleshooting-s2i[Troubleshooting the Source-to-Image process].
+* xref:../../cicd/builds/build-strategies.adoc#builds-strategy-s2i-build_build-strategies[Using build strategies]
+* xref:../../support/troubleshooting/troubleshooting-s2i.adoc#troubleshooting-s2i[Troubleshooting the Source-to-Image process]
 endif::openshift-rosa,openshift-dedicated[]
-* For an overview of creating images with S2I, see xref:../../openshift_images/create-images.adoc#images-create-s2i_create-images[Creating images from source code with source-to-image].
-* For an overview of testing S2I images, see xref:../../openshift_images/create-images.adoc#images-test-s2i_create-images[About testing S2I images].
+* xref:../../openshift_images/create-images.adoc#images-create-s2i_create-images[Creating images from source code with source-to-image]
+* xref:../../openshift_images/create-images.adoc#images-test-s2i_create-images[About testing source-to-image images]
+* xref:../../openshift_images/create-images.adoc#images-create-s2i_create-images[Creating images from source code with source-to-image]

Original file line number	Diff line number	Diff line change
`@@ -20,11 +20,11 @@ For example:`
`20`	`20`	`+`
`21`	`21`	`[source,terminal]`
`22`	`22`	`----`
`23`		`-$ oc tag -d python:3.5`
	`23`	`+$ oc tag -d python:3.6`
`24`	`24`	`----`
`25`	`25`	`+`
`26`	`26`	`.Example output`
`27`	`27`	`[source,terminal]`
`28`	`28`	`----`
`29`		`-Deleted tag default/python:3.5.`
	`29`	`+Deleted tag default/python:3.6`
`30`	`30`	`----`