Merge pull request #24589 from openshift-cherrypick-robot/cherry-pick…

…-24562-to-enterprise-4.6

[enterprise-4.6] OSDOCS-1348: Separating command and output for Registry docs

modules/images-configuration-cas.adoc

@@ -8,7 +8,7 @@
 
 The `image.config.openshift.io/cluster` resource can contain a reference
 to a ConfigMap that contains additional certificate authorities to be trusted
-during image registry access.  
+during image registry access.
 
 .Prerequisites
 * The CAs must be PEM-encoded.
@@ -46,9 +46,18 @@ You can configure additional CAs with the following procedure.
 
 . To configure an additional CA:
 +
+[source,terminal]
 ----
 $ oc create configmap registry-config --from-file=<external_registry_address>=ca.crt -n openshift-config
+----
++
+[source,terminal]
+----
 $ oc edit image.config.openshift.io cluster
+----
++
+[source,yaml]
+----
 spec:
   additionalTrustedCA:
     name: registry-config

modules/registry-accessing-directly.adoc

@@ -15,13 +15,19 @@ Access the registry from the cluster by using internal routes:
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
 . Access the node by getting the node's address:
 +
+[source,terminal]
 ----
 $ oc get nodes
+----
++
+[source,terminal]
+----
 $ oc debug nodes/<node_address>
 ----
 
-. In order to have access to tools such as `oc` and `podman` on the node, run the following command:
+. To enable access to tools such as `oc` and `podman` on the node, run the following command:
 +
+[source,terminal]
 ----
 sh-4.2# chroot /host
 ----
@@ -31,19 +37,29 @@ endif::[]
 . Log in to the container image registry by using your access token:
 +
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
+[source,terminal]
 ----
 sh-4.2# oc login -u kubeadmin -p <password_from_install_log> https://api-int.<cluster_name>.<base_domain>:6443
+----
++
+[source,terminal]
+----
 sh-4.2# podman login -u kubeadmin -p $(oc whoami -t) image-registry.openshift-image-registry.svc:5000
 ----
 endif::[]
+
++
 ifdef::openshift-dedicated[]
+[source,terminal]
 ----
 $ podman login -u $(oc whoami) -p $(oc whoami -t) $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}')
 ----
 endif::[]
+
 +
 You should see a message confirming login, such as:
 +
+[source,terminal]
 ----
 Login Succeeded!
 ----
@@ -96,6 +112,7 @@ endif::[]
 
 .. Pull an arbitrary image:
 +
+[source,terminal]
 ----
 $ podman pull name.io/image
 ----
@@ -105,6 +122,7 @@ ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
 The project name must appear in this pull specification for {product-title} to
 correctly place and later access the image in the registry:
 +
+[source,terminal]
 ----
 $ podman tag name.io/image image-registry.openshift-image-registry.svc:5000/openshift/image
 ----
@@ -114,6 +132,7 @@ ifdef::openshift-dedicated[]
 The project name must appear in this pull specification for {product-title} to
 correctly place and later access the image in the registry:
 +
+[source,terminal]
 ----
 $ podman tag name.io/image $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}')/openshift/image
 ----
@@ -127,14 +146,16 @@ project, which allows the user to write or push an image. Otherwise, the
 to push the image.
 ====
 
-.. Push the newly-tagged image to your registry:
+.. Push the newly tagged image to your registry:
 +
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
+[source,terminal]
 ----
 $ podman push image-registry.openshift-image-registry.svc:5000/openshift/image
 ----
 endif::[]
 ifdef::openshift-dedicated[]
+[source,terminal]
 ----
 $ podman push $(oc -n openshift-image-registry get route default-route -o jsonpath='{.spec.host}')/openshift/image
 ----

modules/registry-accessing-metrics.adoc

@@ -24,9 +24,15 @@ or using the cluster role.
 
 . Run a metrics query, for example:
 +
+[source,terminal]
 ----
 $ curl --insecure -s -u <user>:<secret> \ <1>
     https://image-registry.openshift-image-registry.svc:5000/extensions/v2/metrics | grep imageregistry | head -n 20
+----
++
+.Example output
+[source,terminal]
+----
 # HELP imageregistry_build_info A metric with a constant '1' value labeled by major, minor, git commit & git version from which the image registry was built.
 # TYPE imageregistry_build_info gauge
 imageregistry_build_info{gitCommit="9f72191",gitVersion="v3.11.0+9f72191-135-dirty",major="3",minor="11+"} 1
@@ -55,8 +61,9 @@ registry configuration.
 
 . Create a cluster role if you do not already have one to access the metrics:
 +
+[source,terminal]
 ----
-$ cat <<EOF |
+$ cat <<EOF | oc create -f -
 apiVersion: rbac.authorization.k8s.io/v1
 kind: ClusterRole
 metadata:
@@ -69,18 +76,19 @@ rules:
   verbs:
   - get
 EOF
-$ oc create -f -
 ----
 
 . Add this role to a user, run the following command:
 +
+[source,terminal]
 ----
 $ oc adm policy add-cluster-role-to-user prometheus-scraper <username>
 ----
 
 . Access the metrics using cluster role. The part of
 the configuration file responsible for metrics should look like this:
 +
+[source,yaml]
 ----
 openshift:
   version: 1.0

modules/registry-configuring-storage-aws-user-infra.adoc

@@ -7,7 +7,7 @@
 [id="registry-configuring-storage-aws-user-infra_{context}"]
 = Configuring registry storage for AWS with user-provisioned infrastructure
 
-During installation, your cloud credentials are sufficient to create an S3 bucket
+During installation, your cloud credentials are sufficient to create an Amazon S3 bucket
 and the Registry Operator will automatically configure storage.
 
 If the Registry Operator cannot create an S3 bucket, and automatically configure
@@ -17,7 +17,7 @@ procedure.
 .Prerequisites
 
 * A cluster on AWS with user-provisioned infrastructure.
-* For S3 on AWS storage the secret is expected to contain two keys:
+* For Amazon S3 storage, the secret is expected to contain two keys:
 ** `REGISTRY_STORAGE_S3_ACCESSKEY`
 ** `REGISTRY_STORAGE_S3_SECRETKEY`
 
@@ -38,7 +38,7 @@ $ oc edit configs.imageregistry.operator.openshift.io/cluster
 ----
 +
 .Example configuration
-[source,terminal]
+[source,yaml]
 ----
 storage:
   s3:

modules/registry-configuring-storage-azure-user-infra.adoc

@@ -28,7 +28,7 @@ $ oc edit configs.imageregistry.operator.openshift.io/cluster
 ----
 +
 .Example configuration
-[source,terminal]
+[source,yaml]
 ----
 storage:
   azure:

modules/registry-configuring-storage-baremetal.adoc

@@ -16,7 +16,7 @@ registry to use storage.
 
 * Cluster administrator permissions.
 * A cluster on bare metal.
-* Provision persistent storage
+* Provisioned persistent storage
 for your cluster, such as Red Hat OpenShift Container Storage. To deploy a private image registry, your storage must provide
 ReadWriteMany access mode.
 * Must have "100Gi" capacity.
@@ -74,7 +74,7 @@ $ oc edit configs.imageregistry.operator.openshift.io
 ----
 +
 .Example registry configuration
-[source,terminal]
+[source,yaml]
 ----
 storage:
   pvc:

modules/registry-configuring-storage-gcp-user-infra.adoc

@@ -6,14 +6,14 @@
 = Registry storage for GCP with user-provisioned infrastructure
 
 You must set up the storage medium manually and configure the settings in the
-registry CRD.
+registry custom resource (CR).
 
 .Prerequisites
 
 * A cluster on GCP with user-provisioned infrastructure.
 * To configure registry storage for GCP, you need to provide Registry Operator
 cloud credentials.
-* For GCS on GCP storage the secret is expected to contain one key whose value is the
+* For GCS on GCP storage, the secret is expected to contain one key whose value is the
 contents of a credentials file provided by GCP:
 ** `REGISTRY_STORAGE_GCS_KEYFILE`
 

modules/registry-configuring-storage-openstack-user-infra.adoc

@@ -6,14 +6,14 @@
 = Registry storage for {rh-openstack} with user-provisioned infrastructure
 
 You must set up the storage medium manually and configure the settings in the
-registry CRD.
+registry custom resource (CR).
 
 .Prerequisites
 
 * A cluster on {rh-openstack-first} with user-provisioned infrastructure.
 * To configure registry storage for {rh-openstack}, you need to provide Registry Operator
 cloud credentials.
-* For Swift on {rh-openstack} storage the secret is expected to contain the following two keys:
+* For Swift on {rh-openstack} storage, the secret is expected to contain the following two keys:
 
 ** `REGISTRY_STORAGE_SWIFT_USER`
 ** `REGISTRY_STORAGE_SWIFT_PASSWORD`

modules/registry-configuring-storage-vsphere.adoc

@@ -82,7 +82,7 @@ $ oc edit configs.imageregistry.operator.openshift.io
 ----
 +
 .Example registry configuration
-[source,terminal]
+[source,yaml]
 ----
 storage:
   pvc:

modules/registry-exposing-secure-registry-manually.adoc

@@ -26,14 +26,20 @@ To expose the registry using `DefaultRoute`:
 
 . Set `DefaultRoute` to `True`:
 +
+[source,terminal]
 ----
 $ oc patch configs.imageregistry.operator.openshift.io/cluster --patch '{"spec":{"defaultRoute":true}}' --type=merge
 ----
 +
 . Log in with Podman:
 +
+[source,terminal]
 ----
 $ HOST=$(oc get route default-route -n openshift-image-registry --template='{{ .spec.host }}')
+----
++
+[source,terminal]
+----
 $ podman login -u $(oc whoami) -p $(oc whoami -t) --tls-verify=false $HOST <1>
 ----
 <1> `--tls-verify=false` is needed if the cluster's default certificate for routes
@@ -45,6 +51,7 @@ To expose the registry using custom routes:
 
 . Create a secret with your route's TLS keys:
 +
+[source,terminal]
 ----
 $ oc create secret tls public-route-tls \
     -n openshift-image-registry \
@@ -57,6 +64,7 @@ default TLS configuration from the Ingress Operator.
 +
 . On the Registry Operator:
 +
+[source,yaml]
 ----
 spec:
   routes:

modules/registry-integrated-openshift-registry.adoc

@@ -6,43 +6,43 @@
 [id="registry-integrated-openshift-registry_{context}"]
 = Integrated {product-title} registry
 ifdef::openshift-enterprise,openshift-webscale,openshift-origin[]
-{product-title} provides a built in container image registry which runs as a
+{product-title} provides a built-in container image registry that runs as a
 standard workload on the cluster. The registry is configured and managed by an
-infrastructure operator. It provides an out of the box solution for users to
+infrastructure Operator. It provides an out-of-the-box solution for users to
 manage the images that run their workloads, and runs on top of the existing
 cluster infrastructure. This registry can be scaled up or down like any other
 cluster workload and does not require specific infrastructure provisioning. In
 addition, it is integrated into the cluster user authentication and
-authorization system which means that access to create and retrieve images is
+authorization system, which means that access to create and retrieve images is
 controlled by defining user permissions on the image resources.
 
 The registry is typically used as a publication target for images built on the
-cluster as well as a source of images for workloads running on the cluster.
+cluster, as well as being a source of images for workloads running on the cluster.
 When a new image is pushed to the registry, the cluster is notified of the
 new image and other components can react to and consume the updated image.
 
 Image data is stored in two locations. The actual image data is stored in a
-configurable storage location such as cloud storage or a filesystem volume. The
+configurable storage location, such as cloud storage or a filesystem volume. The
 image metadata, which is exposed by the standard cluster APIs and is used to
 perform access control, is stored as standard API resources, specifically images
 and imagestreams.
 endif::[]
 
 ifdef::openshift-dedicated[]
-{product-title} provides a built in container image registry which runs as a
+{product-title} provides a built-in container image registry that runs as a
 standard workload on the cluster. The registry is configured and managed by an
-infrastructure operator. It provides an out of the box solution for users to
+infrastructure Operator. It provides an out-of-the-box solution for users to
 manage the images that run their workloads, and runs on top of the existing
 cluster infrastructure. In addition, it is integrated into the cluster user
-authentication and authorization system which means that access to create and
+authentication and authorization system, which means that access to create and
 retrieve images is controlled by defining user permissions on the image resources.
 
 The registry is typically used as a publication target for images built on the
-cluster as well as a source of images for workloads running on the cluster.
+cluster, as well as being a source of images for workloads running on the cluster.
 When a new image is pushed to the registry, the cluster is notified of the
 new image and other components can react to and consume the updated image.
 
-The actual image data is stored in a Red Hat managed s3 bucket. The
+The actual image data is stored in a Red Hat-managed Amazon S3 bucket. The
 image metadata, which is exposed by the standard cluster APIs and is used to
 perform access control, is stored as standard API resources, specifically images
 and imagestreams.

modules/registry-operator-config-resources-secret-aws.adoc

@@ -13,7 +13,7 @@ The `image-registry-private-configuration-user` secret provides
 credentials needed for storage access and management. It overrides the default
 credentials used by the Operator, if default credentials were found.
 
-For S3 on AWS storage the secret is expected to contain two keys:
+For S3 on AWS storage, the secret is expected to contain two keys:
 
 * REGISTRY_STORAGE_S3_ACCESSKEY
 * REGISTRY_STORAGE_S3_SECRETKEY
@@ -22,6 +22,7 @@ For S3 on AWS storage the secret is expected to contain two keys:
 
 * Create an {product-title} secret that contains the required keys.
 +
+[source,terminal]
 ----
 $ oc create secret generic image-registry-private-configuration-user --from-literal=REGISTRY_STORAGE_S3_ACCESSKEY=myaccesskey --from-literal=REGISTRY_STORAGE_S3_SECRETKEY=mysecretkey --namespace openshift-image-registry
 ----

modules/registry-operator-config-resources-secret-azure.adoc

@@ -14,7 +14,7 @@ The `image-registry-private-configuration-user` secret provides
 credentials needed for storage access and management. It overrides the default
 credentials used by the Operator, if default credentials were found.
 
-For Azure registry storage the secret is expected to contain one key whose value is the
+For Azure registry storage, the secret is expected to contain one key whose value is the
 contents of a credentials file provided by Azure:
 
 * REGISTRY_STORAGE_AZURE_ACCOUNTKEY
@@ -24,6 +24,7 @@ contents of a credentials file provided by Azure:
 
 * Create an {product-title} secret that contains the required key.
 +
+[source,terminal]
 ----
 $ oc create secret generic image-registry-private-configuration-user --from-literal=REGISTRY_STORAGE_AZURE_ACCOUNTKEY=<accountkey> --namespace openshift-image-registry
 ----