Red Hat OpenShift Container Platform

Install from the software catalog by using the CLI

To install an Operator from the software catalog without using the web console, you can create or update a Subscription object by using the oc command in Red Hat OpenShift Container Platform.

For SingleNamespace install mode, you must also ensure an appropriate Operator group exists in the related namespace. An Operator group, defined by an OperatorGroup object, selects target namespaces in which to generate required RBAC access for all Operators in the same namespace as the Operator group.

In most cases, the web console method of this procedure is preferred because it automates tasks in the background, such as handling the creation of OperatorGroup and Subscription objects automatically when choosing SingleNamespace mode.

Prerequisites

Access to your Red Hat OpenShift Container Platform cluster using an account with cluster-admin permissions.
You have installed the OpenShift CLI (oc).

Procedure

View the list of Operators available to the cluster from the software catalog:

$ oc get packagemanifests -n openshift-marketplace

Example output

NAME                               CATALOG               AGE
3scale-operator                    Red Hat Operators     91m
advanced-cluster-management        Red Hat Operators     91m
amq7-cert-manager                  Red Hat Operators     91m
# ...
couchbase-enterprise-certified     Certified Operators   91m
crunchy-postgres-operator          Certified Operators   91m
mongodb-enterprise                 Certified Operators   91m
# ...
etcd                               Community Operators   91m
jaeger                             Community Operators   91m
kubefed                            Community Operators   91m
# ...

Note the catalog for your desired Operator.

Inspect your desired Operator to verify its supported install modes and available channels:

$ oc describe packagemanifests <operator_name> -n openshift-marketplace

Example output

# ...
Kind:         PackageManifest
# ...
      Install Modes:
        Supported:  true
        Type:       OwnNamespace
        Supported:  true
        Type:       SingleNamespace
        Supported:  false
        Type:       MultiNamespace
        Supported:  true
        Type:       AllNamespaces
# ...
    Entries:
      Name:       example-operator.v3.7.11
      Version:    3.7.11
      Name:       example-operator.v3.7.10
      Version:    3.7.10
    Name:         stable-3.7
# ...
   Entries:
      Name:         example-operator.v3.8.5
      Version:      3.8.5
      Name:         example-operator.v3.8.4
      Version:      3.8.4
    Name:           stable-3.8
  Default Channel:  stable-3.8

In the example output, Install Modes indicates which install modes are supported; Name shows example channel names; and Default Channel is the channel selected by default if one is not specified.

You can print an Operator’s version and channel information in YAML format by running the following command:

$ oc get packagemanifests <operator_name> -n <catalog_namespace> -o yaml

If more than one catalog is installed in a namespace, run the following command to look up the available versions and channels of an Operator from a specific catalog:

$ oc get packagemanifest \
   --selector=catalog=<catalogsource_name> \
   --field-selector metadata.name=<operator_name> \
   -n <catalog_namespace> -o yaml

If you do not specify the Operator’s catalog, running the oc get packagemanifest and oc describe packagemanifest commands might return a package from an unexpected catalog if the following conditions are met:

Multiple catalogs are installed in the same namespace.
The catalogs contain the same Operators or Operators with the same name.

If the Operator you intend to install supports the AllNamespaces install mode, and you choose to use this mode, skip this step, because the openshift-operators namespace already has an appropriate Operator group in place by default, called global-operators.

If the Operator you intend to install supports the SingleNamespace install mode, and you choose to use this mode, you must ensure an appropriate Operator group exists in the related namespace. If one does not exist, you can create create one by following these steps:

You can only have one Operator group per namespace. For more information, see "Operator groups".
1. Create an OperatorGroup object YAML file, for example operatorgroup.yaml, for SingleNamespace install mode:
  Example OperatorGroup object for SingleNamespace install mode
  apiVersion: operators.coreos.com/v1 kind: OperatorGroup metadata: name: <operatorgroup_name> namespace: <namespace> spec: targetNamespaces: - <namespace>
  For SingleNamespace install mode, use the same <namespace> value for both the metadata.namespace and spec.targetNamespaces fields.
2. Create the OperatorGroup object:
  $ oc apply -f operatorgroup.yaml

Create a Subscription object to subscribe a namespace to an Operator:

Create a YAML file for the Subscription object, for example subscription.yaml:

If you want to subscribe to a specific version of an Operator, set the startingCSV field to the desired version and set the installPlanApproval field to Manual to prevent the Operator from automatically upgrading if a later version exists in the catalog. For details, see the following "Example Subscription object with a specific starting Operator version".

Example Subscription object

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: <subscription_name>
  namespace: <namespace_per_install_mode>
spec:
  channel: <channel_name>
  name: <operator_name>
  source: <catalog_name>
  sourceNamespace: <catalog_source_namespace>
  config:
    env:
    - name: ARGS
      value: "-v=10"
    envFrom:
    - secretRef:
        name: license-secret
    volumes:
    - name: <volume_name>
      configMap:
        name: <configmap_name>
    volumeMounts:
    - mountPath: <directory_name>
      name: <volume_name>
    tolerations:
    - operator: "Exists"
    resources:
      requests:
        memory: "64Mi"
        cpu: "250m"
      limits:
        memory: "128Mi"
        cpu: "500m"
    nodeSelector:
      foo: bar

where:

<namespace_per_install_mode>

Specifies the namespace for your chosen install mode. For default AllNamespaces install mode usage, specify the openshift-operators namespace. Alternatively, you can specify a custom global namespace, if you have created one. For SingleNamespace install mode usage, specify the relevant single namespace.

<channel_name>

Specifies the name of the channel to subscribe to.

<operator_name>

Specifies the name of the Operator to subscribe to.

<catalog_name>

Specifies the name of the catalog source that provides the Operator.

<catalog_source_namespace>

Specifies the namespace of the catalog source. Use openshift-marketplace for the default software catalog sources.

config.env

Specifies a list of environment variables that must exist in all containers in the pod created by OLM.

config.envFrom

Specifies a list of sources to populate environment variables in the container.

config.volumes

Specifies a list of volumes that must exist on the pod created by OLM.

config.volumeMounts

Specifies a list of volume mounts that must exist in all containers in the pod created by OLM. If a volumeMount references a volume that does not exist, OLM fails to deploy the Operator.

config.tolerations

Specifies a list of tolerations for the pod created by OLM.

config.resources

Specifies resource constraints for all the containers in the pod created by OLM.

config.nodeSelector

Specifies a NodeSelector for the pod created by OLM.

Example Subscription object with a specific starting Operator version

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: example-operator
  namespace: example-operator
spec:
  channel: stable-3.7
  installPlanApproval: Manual
  name: example-operator
  source: custom-operators
  sourceNamespace: openshift-marketplace
  startingCSV: example-operator.v3.7.10

where:

installPlanApproval

Specifies the approval strategy. Set to Manual in case your specified version is superseded by a later version in the catalog. This plan prevents an automatic upgrade to a later version and requires manual approval before the starting CSV can complete the installation.

startingCSV

Specifies a specific version of an Operator CSV.

For clusters on cloud providers with token authentication enabled, such as Amazon Web Services (AWS) Security Token Service (STS), Microsoft Entra Workload ID, or Google Cloud Platform Workload Identity, configure your Subscription object by following these steps:
1. Ensure the Subscription object is set to manual update approvals:
  Example Subscription object with manual update approvals
  kind: Subscription # ... spec: installPlanApproval: Manual
  Set the spec.installPlanApproval parameter to Manual. Subscriptions with manual approvals for updates ensure that administrators have the opportunity to verify the permissions of the later version, take any necessary steps, and then update. Subscriptions with automatic approvals for updates are not recommended because there might be permission changes to make before updating.
2. Include the relevant cloud provider-specific fields in the Subscription object’s config section:
  
  If the cluster is in AWS STS mode, include the following fields:
  Example Subscription object with AWS STS variables
  kind: Subscription # ... spec: config: env: - name: ROLEARN value: "<role_arn>"
  - ROLEARN is the Amazon Resource Name (ARN) of the role that the Operator assumes.
    
    If the cluster is in Workload ID mode, include the following fields:
    
    Example Subscription object with Workload ID variables
    
    kind: Subscription # ... spec: config: env: - name: CLIENTID value: "<client_id>" - name: TENANTID value: "<tenant_id>" - name: SUBSCRIPTIONID value: "<subscription_id>"
    
    where:
    
    <client_id>
    
    Specifies the client ID.
    
    <tenant_id>
    
    Specifies the tenant ID.
    
    <subscription_id>
    
    Specifies the subscription ID.
    
    If the cluster is in GCP Workload Identity mode, include the following fields:
    
    Example Subscription object with GCP Workload Identity variables
    
    kind: Subscription # ... spec: config: env: - name: AUDIENCE value: "<audience_url>" - name: SERVICE_ACCOUNT_EMAIL value: "<service_account_email>"
    
    where:
    
    <audience_url>
    
    Created in Google Cloud by the administrator when they set up GCP Workload Identity, the AUDIENCE value must be a preformatted URL in the following format:
    
    //iam.googleapis.com/projects/<project_number>/locations/global/workloadIdentityPools/<pool_id>/providers/<provider_id>
    
    <service_account_email>
    
    Specifies a Google Cloud service account email that is impersonated during Operator operation, for example:
    
    <service_account_name>@<project_id>.iam.gserviceaccount.com
Create the Subscription object by running the following command:
```
$ oc apply -f subscription.yaml
```

If you set the installPlanApproval field to Manual, manually approve the pending install plan to complete the Operator installation. For more information, see "Manually approving a pending Operator update".

Verification

At this point, OLM is now aware of the selected Operator. A cluster service version (CSV) for the Operator should appear in the target namespace, and APIs provided by the Operator should be available for creation.

Check the status of the Subscription object for your installed Operator by running the following command:
```
$ oc describe subscription <subscription_name> -n <namespace>
```
If you created an Operator group for SingleNamespace install mode, check the status of the OperatorGroup object by running the following command:
```
$ oc describe operatorgroup <operatorgroup_name> -n <namespace>
```