Merge pull request #17565 from bmcelvee/osdocs-715

OSDOCS-715 pull secret doc improvements

Author: bmcelvee

installing/install_config/customizations.adoc

@@ -157,6 +157,7 @@ xref:../../installing/installing_aws/installing-aws-network-customizations.adoc#
 
 |===
 
+include::modules/images-update-global-pull-secret.adoc[leveloffset=+1]
 
 ////
 [id="default-crds_{context}"]

modules/builds-creating-secrets.adoc

@@ -1,7 +1,6 @@
 // Module included in the following assemblies:
 // * builds/creating-build-inputs.adoc
 
-
 [id="builds-creating-secrets_{context}"]
 = Creating secrets
 

modules/images-allow-pods-to-reference-images-from-secure-registries.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 // * openshift_images/using-image-pull-secrets
 // * virt/virtual_machines/importing_vms/virt-importing-vmware-vm.adoc
+// * openshift_images/managing-image-streams.adoc
 
 [id="images-allow-pods-to-reference-images-from-secure-registries_{context}"]
 = Allowing pods to reference images from other secured registries

modules/images-imagestream-import-images-private-registry.adoc

@@ -0,0 +1,30 @@
+// Module included in the following assemblies:
+// * assembly/openshift_images/managing-image-streams.adoc
+
+[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 procedures applies if you change the registry that the Cluster Samples Operator uses to pull content from to something other than link:registry.redhat.io[registry.redhat.io].
+
+[NOTE]
+====
+When importing from insecure or secure registries, the registry URL defined in the secret must include the `:80` port suffix or the secret is not used when attempting to import from the registry.
+====
+
+.Procedure
+
+. You must create a `secret` object that is used to store your credentials by entering the following command:
++
+[source,terminal]
+----
+$ oc create secret generic <secret_name> --from-file=.dockerconfigjson=<file_absolute_path> --type=kubernetes.io/dockerconfigjson
+----
++
+. After the secret is configured, create the new image stream or enter the `oc import-image` command:
++
+[source,terminal]
+----
+$ oc import-image <imagestreamtag> --from=<image> --confirm
+----
++
+During the import process, {product-title} picks up the secrets and provides them to the remote party.

modules/images-update-global-pull-secret.adoc

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 // * openshift_images/using-image-pull-secrets
+// * installing/install_config/customizations.adoc
 
 [id="images-update-global-pull-secret_{context}"]
 = Updating the global cluster pull secret
@@ -11,14 +12,19 @@ You can update the global pull secret for your cluster.
 Cluster resources must adjust to the new pull secret, which can temporarily limit the usability of the cluster.
 ====
 
+[WARNING]
+====
+Updating the global pull secret will cause node reboots while the Machine Config Operator (MCO) syncs the changes.
+====
+
 .Prerequisites
 
 * You have a new or modified pull secret file to upload.
 * You have access to the cluster as a user with the `cluster-admin` role.
 
 .Procedure
 
-* Run the following command to update the global pull secret for your cluster:
+* Enter the following command to update the global pull secret for your cluster:
 +
 [source,terminal]
 ----
@@ -27,3 +33,5 @@ $ oc set data secret/pull-secret -n openshift-config --from-file=.dockerconfigjs
 <1> Provide the path to the new pull secret file.
 
 This update is rolled out to all nodes, which can take some time depending on the size of your cluster. During this time, nodes are drained and pods are rescheduled on the remaining nodes.
+
+//Also referred to as the cluster-wide pull secret.

modules/samples-operator-overview.adoc

@@ -7,17 +7,16 @@
 = Understanding the Cluster Samples Operator
 
 During installation, the Operator creates the default configuration object for
-itself and then creates the sample imagestreams and templates, including
-quickstart templates.
+itself and then creates the sample image streams and templates, including quickstart templates.
 
 [NOTE]
 ====
-To facilitate imagestream imports from other registries that require credentials, a cluster administrator can create any additional secrets that contain the content of a Docker `config.json` file in the `openshift` namespace needed for image import.
+To facilitate image stream imports from other registries that require credentials, a cluster administrator can create any additional secrets that contain the content of a Docker `config.json` file in the `openshift` namespace needed for image import.
 ====
 
 The Cluster Samples Operator configuration is a cluster-wide resource, and the deployment is contained within the `openshift-cluster-samples-operator` namespace.
 
-The image for the Cluster Samples Operator contains imagestream and template definitions
+The image for the Cluster Samples Operator contains image stream and template definitions
 for the associated {product-title} release. When each sample is created or updated,
 the Cluster Samples Operator includes an annotation that denotes the version of
 {product-title}. The Operator uses this annotation to ensure that each sample
@@ -29,13 +28,13 @@ automatically.
 [NOTE]
 ====
 The Jenkins images are part of the image payload from
-installation and are tagged into the imagestreams directly.
+installation and are tagged into the image streams directly.
 ====
 
 The Cluster Samples Operator configuration resource includes a finalizer which cleans up
 the following upon deletion:
 
-* Operator managed imagestreams.
+* Operator managed image streams.
 * Operator managed templates.
 * Operator generated configuration resources.
 * Cluster status resources.
@@ -46,7 +45,7 @@ resource using the default configuration.
 [id="samples-operator-bootstrapped"]
 == Cluster Samples Operator's use of management state
 
-The Cluster Samples Operator is bootstrapped as `Managed` by default or if global proxy is configured. In the `Managed` state, the Cluster Samples Operator is actively managing its resources and keeping the component active in order to pull sample imagestreams and images from the registry and ensure that the requisite sample templates are installed.
+The Cluster Samples Operator is bootstrapped as `Managed` by default or if global proxy is configured. In the `Managed` state, the Cluster Samples Operator is actively managing its resources and keeping the component active in order to pull sample image streams and images from the registry and ensure that the requisite sample templates are installed.
 
 Certain circumstances result in the Cluster Samples Operator bootstrapping itself as `Removed` including:
 
@@ -57,13 +56,13 @@ However, if the Cluster Samples Operator also detects an {product-title} global
 
 [IMPORTANT]
 ====
-IPv6 installations are not currently supported by link:https://registry.redhat.io[registry.redhat.io]. The Cluster Samples Operator pulls most of the sample imagestreams and images from link:https://registry.redhat.io[registry.redhat.io].
+IPv6 installations are not currently supported by link:https://registry.redhat.io[registry.redhat.io]. The Cluster Samples Operator pulls most of the sample image streams and images from link:https://registry.redhat.io[registry.redhat.io].
 ====
 
 [id="samples-operator-restricted-network-install"]
 === Restricted network installation
 
-Boostrapping as `Removed` when unable to access `registry.redhat.io` facilitates restricted network installations when the network restriction is already in place. Bootstrapping as `Removed` when network access is restricted allows the cluster administrator more time to decide if samples are desired, because the Cluster Samples Operator does not submit alerts that sample imagestream imports are failing when the management state is set to `Removed`. When the Cluster Samples Operator comes up as `Managed` and attempts to install sample imagestreams, it starts alerting two hours after initial installation if there are failing imports.
+Boostrapping as `Removed` when unable to access `registry.redhat.io` facilitates restricted network installations when the network restriction is already in place. Bootstrapping as `Removed` when network access is restricted allows the cluster administrator more time to decide if samples are desired, because the Cluster Samples Operator does not submit alerts that sample image stream imports are failing when the management state is set to `Removed`. When the Cluster Samples Operator comes up as `Managed` and attempts to install sample image streams, it starts alerting two hours after initial installation if there are failing imports.
 
 [id="samples-operator-restricted-network-install-with-access"]
 === Restricted network installation with initial network access
@@ -86,9 +85,9 @@ spec:
 ----
 
 [id="samples-operator-retries"]
-== Cluster Samples Operator's tracking and error recovery of imagestream imports
+== Cluster Samples Operator's tracking and error recovery of image stream imports
 
-After creation or update of a samples imagestream, the Cluster Samples Operator monitors the progress of each imagestreamtag's image import.
+After creation or update of a samples image stream, the Cluster Samples Operator monitors the progress of each image stream tag's image import.
 
-If an import fails, the Cluster Samples Operator retries the import through the imagestream image import API, which is the same API used by the `oc import-image` command, approximately every 15 minutes until it sees the import succeed, or if
-the Cluster Samples Operator's configuration is changed such that either the imagestream is added to the `skippedImagestreams` list, or the management state is changed to `Removed`.
+If an import fails, the Cluster Samples Operator retries the import through the image stream image import API, which is the same API used by the `oc import-image` command, approximately every 15 minutes until it sees the import succeed, or if
+the Cluster Samples Operator's configuration is changed such that either the image stream is added to the `skippedImagestreams` list, or the management state is changed to `Removed`.

openshift_images/configuring-samples-operator.adoc

@@ -24,3 +24,8 @@ include::modules/samples-operator-overview.adoc[leveloffset=+1]
 include::modules/samples-operator-configuration.adoc[leveloffset=+1]
 
 include::modules/samples-operator-crd.adoc[leveloffset=+1]
+
+[discrete]
+== Additional resources
+
+For more information about configuring credentials, see xref:../openshift_images/managing_images/using-image-pull-secrets.adoc#using-image-pull-secrets[Using image pull secrets].

openshift_images/image-streams-manage.adoc

@@ -30,3 +30,6 @@ include::modules/images-imagestream-external-image-tags.adoc[leveloffset=+2]
 include::modules/images-imagestream-update-tag.adoc[leveloffset=+2]
 include::modules/images-imagestream-remove-tag.adoc[leveloffset=+2]
 include::modules/images-imagestream-import.adoc[leveloffset=+2]
+
+include::modules/images-imagestream-import-images-private-registry.adoc[leveloffset=+1]
+include::modules/images-allow-pods-to-reference-images-from-secure-registries.adoc[leveloffset=+2]

openshift_images/managing_images/using-image-pull-secrets.adoc

@@ -6,14 +6,35 @@ include::modules/common-attributes.adoc[]
 toc::[]
 
 If you are using {product-title}'s internal registry and are pulling from
-imagestreams located in the same project, then your Pod's service account should
+image streams located in the same project, then your pod's 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.
 
+You can obtain the image pull secret, `pullSecret`, from the link:https://cloud.redhat.com/openshift/install/pull-secret[Pull Secret] page on the {cloud-redhat-com} site.
+
+You use this pull secret to authenticate with the services that are provided by the included authorities, including link:quay.io[Quay.io] and link:registry.redhat.io[registry.redhat.io], which serve the container images for {product-title} components.
+
+.Example `config.json` file
+[source,json]
+----
+{
+   "auths":{
+      "cloud.openshift.com":{
+         "auth":"b3Blb=",
+         "email":"[email protected]"
+      },
+      "quay.io":{
+         "auth":"b3Blb=",
+         "email":"[email protected]"
+      }
+   }
+}
+----
+
 include::modules/images-allow-pods-to-reference-images-across-projects.adoc[leveloffset=+1]
 
 include::modules/images-allow-pods-to-reference-images-from-secure-registries.adoc[leveloffset=+1]