OSDOCS-16880: CQA Image Configuration and Advanced Features

Author: ShaunaDiaz

modules/images-samples-operator-deprecated-image-stream.adoc

@@ -8,6 +8,7 @@
 [id="images-samples-operator-deprecated-image-stream_{context}"]
 = Removing deprecated image stream tags from the Cluster Samples Operator
 
+[role="_abstract"]
 The Cluster Samples Operator leaves deprecated image stream tags in an image stream because users can have deployments that use the deprecated image stream tags.
 
 You can remove deprecated image stream tags by editing the image stream with the  `oc tag` command.
@@ -19,11 +20,11 @@ Deprecated image stream tags that the samples providers have removed from their
 
 .Prerequisites
 
-* You installed the `oc` CLI.
+* You installed the {oc-first}.
 
 .Procedure
 
-* Remove deprecated image stream tags by editing the image stream with the  `oc tag` command.
+* Remove deprecated image stream tags by editing the image stream with the following `oc tag` command:
 +
 [source,terminal]
 ----

modules/installation-images-samples-disconnected-mirroring-assist.adoc

@@ -8,19 +8,22 @@
 [id="installation-images-samples-disconnected-mirroring-assist_{context}"]
 = Cluster Samples Operator assistance for mirroring
 
-During installation, {product-title} creates a config map named `imagestreamtag-to-image` in the `openshift-cluster-samples-operator` namespace. The `imagestreamtag-to-image` config map contains an entry, the populating image, for each image stream tag.
+[role="_abstract"]
+During installation, {product-title} creates a config map named `imagestreamtag-to-image` in the `openshift-cluster-samples-operator` namespace.
+
+The `imagestreamtag-to-image` config map contains an entry, the populating image, for each image stream tag.
 
 The format of the key for each entry in the data field in the config map is `<image_stream_name>_<image_stream_tag_name>`.
 
 ifndef::openshift-rosa;openshift-dedicated[]
 During a disconnected installation of {product-title}, the status of the Cluster Samples Operator is set to `Removed`. If you choose to change it to `Managed`, it installs samples.
 [NOTE]
 ====
-The use of samples in a network-restricted or discontinued environment may require access to services external to your network. Some example services include: Github, Maven Central, npm, RubyGems, PyPi and others. There might be additional steps to take that allow the cluster samples operators's objects to reach the services they require.
+The use of samples in a network-restricted or discontinued environment might require access to services external to your network. Some example services include: Github, Maven Central, npm, RubyGems, PyPi and others. There might be additional steps to take that allow the Cluster Samples Operators objects to reach the services they require.
 ====
 endif::openshift-rosa;openshift-dedicated[]
 
-You can use this config map as a reference for which images need to be mirrored for your image streams to import.
+Use the following principles to determine which images you need to mirror for your image streams to import:
 
 * While the Cluster Samples Operator is set to `Removed`, you can create your mirrored registry, or determine which existing mirrored registry you want to use.
 * Mirror the samples you want to the mirrored registry using the new config map as your guide.

modules/samples-operator-bootstrapped.adoc

@@ -0,0 +1,48 @@
+// Module included in the following assemblies:
+//
+// * openshift_images/configuring_samples_operator.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="samples-operator-bootstrapped_{context}"]
+= Cluster Samples Operator use of management state
+
+[role="_abstract"]
+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 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:
+
+* If the Cluster Samples Operator cannot reach the registry after three minutes on initial startup after a clean installation.
+* If the Cluster Samples Operator detects that it is on an IPv6 network.
+// cannot configure the Samples Operator
+ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+* If the image controller configuration parameters prevent the creation of image streams by using the default image registry, or by using the image registry specified by `samplesRegistry` setting. For more information, see the following links:
+
+** link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/images/image-configuration-classic#images-configuration-parameters_image-configuration[Image controller configuration parameters]
+** link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/images/configuring-samples-operator#samples-operator-configuration_configuring-samples-operator[Cluster Samples Operator configuration parameters]
+endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
+
+[NOTE]
+====
+For {product-title}, the default image registry is
+ifdef::openshift-enterprise[]
+`registry.redhat.io`.
+endif::[]
+ifdef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp,openshift-origin[]
+`registry.access.redhat.com` or `quay.io`.
+endif::[]
+====
+
+ifdef::openshift-enterprise,openshift-dedicated,openshift-origin[]
+However, if the Cluster Samples Operator detects that it is on an IPv6 network and an {product-title}
+endif::[]
+ifdef::openshift-rosa,openshift-rosa-hcp[]
+However, if the Cluster Samples Operator detects that it is on an IPv6 network and a {product-title}
+endif::[]
+global proxy is configured, then the IPv6 check supersedes all the checks. As a result, the Cluster Samples Operator bootstraps itself as `Removed`.
+
+[IMPORTANT]
+====
+IPv6 installations are not currently supported by the registry. The Cluster Samples Operator pulls most of the sample image streams and images from the registry.
+====

modules/samples-operator-configuration.adoc

@@ -6,6 +6,7 @@
 [id="samples-operator-configuration_{context}"]
 = Cluster Samples Operator configuration parameters
 
+[role="_abstract"]
 The samples resource offers the following configuration fields:
 
 [cols="3a,8a",options="header"]
@@ -42,18 +43,20 @@ Creation or update of RHEL content is not gated by the existence of the pull sec
 
 Secret, image stream, and template watch events can come in before the initial samples resource object is created, the Cluster Samples Operator detects and re-queues the event.
 
+[id="samples-operator-config-restrictions_{context}"]
 == Configuration restrictions
 
-When the Cluster Samples Operator starts supporting multiple architectures, the architecture list is not allowed to be changed while in the `Managed` state.
+When the Cluster Samples Operator starts supporting multiple architectures, you cannot change the architecture list while the Operator is in the `Managed` state.
 
 To change the architectures values, a cluster administrator must:
 
 * Mark the `Management State` as `Removed`, saving the change.
 * In a subsequent change, edit the architecture and change the `Management State` back to `Managed`.
 
-The Cluster Samples Operator still processes secrets while in `Removed` state. You can create the secret before switching to `Removed`, while in `Removed` before switching to `Managed`, or after switching to `Managed` state. There are delays in creating the samples until the secret event is processed if you create the secret after switching to `Managed`. This helps facilitate the changing of the registry, where you choose to remove all the samples before switching to insure a clean slate. Removing all samples before switching is not required.
+The Cluster Samples Operator still processes secrets while in `Removed` state. You can create the secret before switching to `Removed`, while in `Removed` before switching to `Managed`, or after switching to `Managed` state. There are delays in creating the samples until the secret event is processed if you create the secret after switching to `Managed`. This helps facilitate the changing of the registry, where you choose to remove all the samples before switching to ensure a clean slate. Removing all samples before switching is not required.
 
-== Conditions
+[id="samples-operator-conditions_{context}"]
+== Samples resource conditions
 
 The samples resource maintains the following conditions in its status:
 
@@ -81,6 +84,6 @@ The samples resource maintains the following conditions in its status:
 `True` when an error has occurred. The list of image streams with an error is in the reason field. The details of each error reported are in the message field.
 
 |`MigrationInProgress`
-|`True` when the Cluster Samples Operator detects that the version is different than the Cluster Samples Operator version with which the current samples set are installed.
+|`True` when the Cluster Samples Operator detects that the version is different from the Cluster Samples Operator version with which the current samples set are installed.
 
 |===

modules/samples-operator-crd.adoc

@@ -7,15 +7,16 @@
 [id="samples-operator-crd_{context}"]
 = Accessing the Cluster Samples Operator configuration
 
+[role="_abstract"]
 You can configure the Cluster Samples Operator by editing the file with the provided parameters.
 
 .Prerequisites
 
-* Install the OpenShift CLI (`oc`).
+* You installed the {oc-first}.
 
 .Procedure
 
-*  Access the  Cluster Samples Operator configuration:
+*  Access the Cluster Samples Operator configuration by running the following command:
 +
 [source,terminal]
 ----

modules/samples-operator-overview.adoc

@@ -1,113 +1,41 @@
 // Module included in the following assemblies:
 //
 // * openshift_images/configuring_samples_operator.adoc
-// * openshift_images/configuring-samples-operator.adoc
-
 
 :_mod-docs-content-type: CONCEPT
 [id="samples-operator-overview_{context}"]
 = Understanding the Cluster Samples Operator
 
-During installation, the Operator creates the default configuration object for
-itself and then creates the sample image streams and templates, including quick start templates.
+[role="_abstract"]
+During installation, the Operator creates the default configuration object for itself and then creates the sample image streams and templates, including quick start templates.
 
 [NOTE]
 ====
 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 Cluster Samples Operator configuration is a cluster-wide resource. The deployment of the Operator is within the `openshift-cluster-samples-operator` namespace.
 
-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
-matches the release version. Samples outside of its inventory are ignored, as
-are skipped samples. Modifications to any samples that are managed by the
-Operator, where that version annotation is modified or deleted, are reverted
-automatically.
+The image for the Cluster Samples Operator has 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 matches the release version. Samples outside of its inventory are ignored, as are skipped samples. Modifications to any samples that are managed by the Operator, where that version annotation is modified or deleted, are reverted automatically.
 
 [NOTE]
 ====
-The Jenkins images are part of the image payload from
-installation and are tagged into the image streams directly.
+The Jenkins images are part of the image payload from 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:
+The Cluster Samples Operator configuration resource includes a finalizer which cleans up the following upon deletion:
 
 * Operator managed image streams.
 * Operator managed templates.
 * Operator generated configuration resources.
 * Cluster status resources.
 
-Upon deletion of the samples resource, the Cluster Samples Operator recreates the
-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 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:
-
-* If the Cluster Samples Operator cannot reach link:https://registry.redhat.io[registry.redhat.io] after three minutes on initial startup after a clean installation.
-* If the Cluster Samples Operator detects it is on an IPv6 network.
-// cannot configure the Samples Operator
-ifndef::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-* If the xref:../openshift_images/image-configuration.adoc#images-configuration-parameters_image-configuration[image controller configuration parameters] prevent the creation of image streams by using the default image registry, or by using the image registry specified by the xref:../openshift_images/configuring-samples-operator.adoc#samples-operator-configuration_configuring-samples-operator[`samplesRegistry` setting].
-endif::openshift-rosa,openshift-rosa-hcp,openshift-dedicated[]
-
-[NOTE]
-====
-For {product-title}, the default image registry is
-ifdef::openshift-enterprise[]
-`registry.redhat.io`.
-endif::[]
-ifdef::openshift-rosa,openshift-dedicated,openshift-rosa-hcp,openshift-origin[]
-`registry.access.redhat.com` or `quay.io`.
-endif::[]
-====
-
-However, if the Cluster Samples Operator detects that it is on an IPv6 network and an {product-title} global proxy is configured, then IPv6 check supersedes all the checks. As a result, the Cluster Samples Operator bootstraps itself as `Removed`.
-
-[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 image streams and images from link:https://registry.redhat.io[registry.redhat.io].
-====
-
-// Restricted network not supported ROSA/OSD
-ifndef::openshift-rosa,openshift-dedicated[]
-[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 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
-
-Conversely, if a cluster that is intended to be a restricted network or disconnected cluster is first installed while network access exists, the Cluster Samples Operator installs the content from `registry.redhat.io` since it can access it. If you want the Cluster Samples Operator to still bootstrap as `Removed` in order to defer samples installation until you have decided which samples are desired, set up image mirrors, and so on, then follow the instructions for using the Samples Operator with an alternate registry and customizing nodes, both linked in the additional resources section, to override the Cluster Samples Operator default configuration and initially come up as `Removed`.
-
-You must put the following additional YAML file in the `openshift` directory created by `openshift-install create manifest`:
+Upon deletion of the samples resource, the Cluster Samples Operator recreates the resource by using the default configuration.
 
-.Example Cluster Samples Operator YAML file with `managementState: Removed`
-[source,yaml]
-----
-apiVersion: samples.operator.openshift.io/v1
-kind: Config
-metadata:
-  name: cluster
-spec:
-  architectures:
-  - x86_64
-  managementState: Removed
-----
-endif::openshift-rosa,openshift-dedicated[]
+If the Cluster Samples Operator is removed during installation, you can use the Cluster Samples Operator with an alternate registry so that content can be imported. Then you can set the Cluster Samples Operator to `Managed` to get the samples. Use the following instructions:
 
-[id="samples-operator-retries"]
-== Cluster Samples Operator's tracking and error recovery of image stream imports
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/images/samples-operator-alt-registry[Using the Cluster Samples Operator with an alternate registry]
 
-After creation or update of a samples image stream, the Cluster Samples Operator monitors the progress of each image stream tag's image import.
+For more information about configuring credentials, see the following link:
 
-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`.
+* link:https://docs.redhat.com/en/documentation/openshift_container_platform/{product-version}/html/images/managing-images#using-image-pull-secrets[Using image pull secrets]

modules/samples-operator-restricted-network-install.adoc

@@ -0,0 +1,12 @@
+// Module included in the following assemblies:
+//
+// * openshift_images/configuring_samples_operator.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="samples-operator-restricted-network-install-con_{context}"]
+= Restricted network installation
+
+[role="_abstract"]
+The Cluster Samples Operator boostrapping itself as `Removed` when unable to access `registry.redhat.io` facilitates restricted network installations when the network restriction is already in place.
+
+As a cluster administrator, you have more time to decide if samples are needed when the Operator is boostrapped `Removed`. This is because the Cluster Samples Operator does not submit alerts that sample image stream imports are failing when the management state is `Removed`. When the Cluster Samples Operator management state is `Managed`, and the Operator attempts to install sample image streams, failing-import alerts start two hours after initial installation.