Chapter 2. Configuring the Cluster Samples Operator
The Cluster Samples Operator, which operates in the openshift
namespace, installs and updates the Red Hat Enterprise Linux (RHEL)-based OpenShift Container Platform image streams and OpenShift Container Platform templates.
Starting from OpenShift Container Platform 4.16, the Cluster Samples Operator is deprecated. No new templates, samples, or non-Source-to-Image (Non-S2I) image streams will be added to the Cluster Samples Operator. However, the existing S2I builder image streams and templates will continue to receive updates until the Cluster Samples Operator is removed in a future release. S2I image streams and templates include:
- Ruby
- Python
- Node.js
- Perl
- PHP
- HTTPD
- Nginx
- EAP
- Java
- Webserver
- .NET
- Go
- The Cluster Samples Operator will stop managing and providing support to the non-S2I samples (image streams and templates). You can contact the image stream or template owner for any requirements and future plans. In addition, refer to the list of the repositories hosting the image stream or templates.
2.1. 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.
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 image stream and template definitions for the associated OpenShift Container Platform release. When each sample is created or updated, the Cluster Samples Operator includes an annotation that denotes the version of OpenShift Container Platform. 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 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:
- 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.
2.1.1. 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 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.
-
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 the
samplesRegistry
setting.
For OpenShift Container Platform, the default image registry is registry.redhat.io
.
However, if the Cluster Samples Operator detects that it is on an IPv6 network and an OpenShift Container Platform global proxy is configured, then IPv6 check supersedes all the checks. As a result, the Cluster Samples Operator bootstraps itself as Removed
.
IPv6 installations are not currently supported by registry.redhat.io. The Cluster Samples Operator pulls most of the sample image streams and images from registry.redhat.io.
2.1.1.1. 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.
2.1.1.2. 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
:
Example Cluster Samples Operator YAML file with managementState: Removed
apiVersion: samples.operator.openshift.io/v1 kind: Config metadata: name: cluster spec: architectures: - x86_64 managementState: Removed
2.1.2. Cluster Samples Operator’s tracking and error recovery of image stream imports
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 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
.
Additional resources
-
If the Cluster Samples Operator is removed during installation, you can use the Cluster Samples Operator with an alternate registry so content can be imported, and then set the Cluster Samples Operator to
Managed
to get the samples. To ensure the Cluster Samples Operator bootstraps as
Removed
in a restricted network installation with initial network access to defer samples installation until you have decided which samples are desired, follow the instructions for customizing nodes to override the Cluster Samples Operator default configuration and initially come up asRemoved
.- To host samples in your disconnected environment, follow the instructions for using the Cluster Samples Operator with an alternate registry.
2.1.3. Cluster Samples Operator assistance for mirroring
During installation, OpenShift Container Platform 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>
.
During a disconnected installation of OpenShift Container Platform, the status of the Cluster Samples Operator is set to Removed
. If you choose to change it to Managed
, it installs samples.
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.
You can use this config map as a reference for which images need to be mirrored 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.
-
Add any of the image streams you did not mirror to the
skippedImagestreams
list of the Cluster Samples Operator configuration object. -
Set
samplesRegistry
of the Cluster Samples Operator configuration object to the mirrored registry. -
Then set the Cluster Samples Operator to
Managed
to install the image streams you have mirrored.
See Using Cluster Samples Operator image streams with alternate or mirrored registries for a detailed procedure.
2.2. Cluster Samples Operator configuration parameters
The samples resource offers the following configuration fields:
Parameter | Description |
---|---|
|
|
|
Allows you to specify which registry is accessed by image streams for their image content. Note
Creation or update of RHEL content does not commence if the secret for pull access is not in place when either
Creation or update of RHEL content is not gated by the existence of the pull secret if the |
| Placeholder to choose an architecture type. |
|
Image streams that are in the Cluster Samples Operator’s inventory but that the cluster administrator wants the Operator to ignore or not manage. You can add a list of image stream names to this parameter. For example, |
| Templates that are in the Cluster Samples Operator’s inventory, but that the cluster administrator wants the Operator to ignore or not manage. |
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.
2.2.1. 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.
To change the architectures values, a cluster administrator must:
-
Mark the
Management State
asRemoved
, saving the change. -
In a subsequent change, edit the architecture and change the
Management State
back toManaged
.
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.
2.2.2. Conditions
The samples resource maintains the following conditions in its status:
Condition | Description |
---|---|
|
Indicates the samples are created in the |
|
This condition is deprecated in OpenShift Container Platform. |
|
|
|
Indicator that there is a |
| Indicator of which image streams had errors during the image import phase for one of their tags.
|
|
This condition is deprecated in OpenShift Container Platform. |
2.3. Accessing the Cluster Samples Operator configuration
You can configure the Cluster Samples Operator by editing the file with the provided parameters.
Prerequisites
-
Install the OpenShift CLI (
oc
).
Procedure
Access the Cluster Samples Operator configuration:
$ oc edit configs.samples.operator.openshift.io/cluster
The Cluster Samples Operator configuration resembles the following example:
apiVersion: samples.operator.openshift.io/v1 kind: Config # ...
2.4. Removing deprecated image stream tags from the Cluster Samples Operator
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.
Deprecated image stream tags that the samples providers have removed from their image streams are not included on initial installations.
Prerequisites
-
You installed the
oc
CLI.
Procedure
Remove deprecated image stream tags by editing the image stream with the
oc tag
command.$ oc tag -d <image_stream_name:tag>
Example output
Deleted tag default/<image_stream_name:tag>.
Additional resources
- For more information about configuring credentials, see Using image pull secrets.