OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Configuring the Samples Operator

The Samples Operator, which operates in the openshift namespace, installs and updates the Red Hat Enterprise Linux (RHEL)-based OpenShift Container Platform imagestreams and OpenShift Container Platform templates.

Prerequisites

  • Deploy an OpenShift Container Platform cluster.

Understanding the Samples Operator

During installation, the Operator creates the default configuration object for itself and then creates the sample imagestreams and templates, including quickstart templates.

The Samples Operator copies the pull secret that is captured by the installation program into the openshift namespace and names the secret, samples-registry-credentials, to facilitate imagestream imports from registry.redhat.io. Additionally, 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 to facilitate image import.

The Samples Operator configuration is a cluster-wide resource, and the deployment is contained within the openshift-cluster-samples-operator namespace.

The image for the Samples Operator contains imagestream and template definitions for the associated OpenShift Container Platform release. When each sample is created or updated, the 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, will be reverted automatically.

The Jenkins images are part of the image payload from installation and are tagged into the imagestreams directly.

The Samples Operator configuration resource includes a finalizer which cleans up the following upon deletion:

  • Operator managed imagestreams.

  • Operator managed templates.

  • Operator generated configuration resources.

  • Cluster status resources.

  • The samples-registry-credentials secret.

Upon deletion of the samples resource, the Samples Operator recreates the resource using the default configuration.

Samples Operator’s use of management state

The Samples Operator is bootstrapped as Managed by default or if global proxy is configured. In the Managed state, the 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.

Certain circumstances will result in the Samples Operator bootstrapping itself as Removed including:

  • If the Samples Operator cannot reach registry.redhat.io after three minutes on initial start-up after a clean installation.

  • If the Samples Operator detects it is on an IPv6 network.

  • If the Samples Operator detects it is installed on ppc64le and S390x.

IPv6 installations are not currently supported by registry.redhat.io. The Samples Operator pulls most of the sample imagestreams and images from registry.redhat.io.

If the Samples Operator is removed during installation, you can use the Samples Operator with an alternate registry.

Samples Operator configuration parameters

The samples resource offers the following configuration fields:

Parameter Description

managementState

Managed: The Samples Operator updates the samples as the configuration dictates.

Unmanaged: The Cluster Samples Operator ignores updates to its configuration resource object and any imagestreams or templates in the openshift namespace.

Removed: The Cluster Samples Operator removes the set of Managed imagestreams and templates in the openshift namespace. It ignores new samples created by the cluster administrator or any samples in the skipped lists. After the removals are complete, the Samples Operator works like it is in the Unmanaged state and ignores any watch events on the sample resources, imagestreams, or templates.

Neither deletion nor setting the Management State to Removed are completed while imagestream imports are still in progress. Once progress has completed, either in success or in error, the deletion or removal commences.

Secret, imagestream, and template watch events are ignored once deletion or removal has started.

samplesRegistry

Overrides the registry from which images are imported.

Creation or update of RHEL content does not commence if the secret for pull access is not in place when either Samples Registry is not explicitly set (i.e., the empty string), or when it is set to registry.redhat.io. In both cases, image imports will work off of registry.redhat.io, which requires credentials.

Creation or update of RHEL content is not gated by the existence of the pull secret if the Samples Registry is overridden to a value other than the empty string or registry.redhat.io.

architectures

Placeholder to choose an architecture type. Currently only x86 is supported.

skippedImagestreams

Imagestreams that are in the Samples Operator’s inventory but that the cluster administrator wants the Operator to ignore or not manage. You can add a list of imagestream names to this parameter. For example, ["httpd","perl"].

skippedTemplates

Templates that are in the Samples Operator’s inventory, but that the cluster administrator wants the Operator to ignore or not manage.

Secret, imagestream, and template watch events can come in before the initial samples resource object is created, the Samples Operator detects and re-queues the event.

Configuration restrictions

When the Samples Operator starts supporting multiple architectures, the architecture list is not allowed to be changed while in the Managed state.

In order 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 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 (though 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 before switching is not required).

Conditions

The samples resource maintains the following conditions in its status:

Condition Description

SamplesExists

Indicates the samples are created in the openshift namespace.

ImageChangesInProgress

True when imagestreams are created or updated, but not all of the tag spec generations and tag status generations match.

False when all of the generations match, or unrecoverable errors occurred during import, the last seen error is in the message field. The list of pending imagestreams is in the reason field.

ImportCredentialsExist

A samples-registry-credentials secret is copied into the OpenShift namespace.

ConfigurationValid

True or False based on whether any of the restricted changes noted previously are submitted.

RemovePending

Indicator that there is a Management State: Removed setting pending, but are waiting for in progress imagestreams to complete.

ImportImageErrorsExist

Indicator of which imagestreams had errors during the image import phase for one of their tags.

True when an error has occurred. The list of imagestreams with an error is in the reason field. The details of each error reported are in the message field.

MigrationInProgress

True when the Samples Operator detects that the version is different than the Samples Operator version with which the current samples set are installed.

Accessing the Samples Operator configuration

You can configure the Samples Operator by editing the file with the provided parameters.

Prerequisites

  • Install the OpenShift CLI (oc).

Procedure

  • Access the Samples Operator configuration:

    $ oc get configs.samples.operator.openshift.io/cluster -o yaml

    The Samples Operator configuration resembles the following example:

    apiVersion: samples.operator.openshift.io/v1
kind: Config
projectName: cluster-samples-operator
...