If a cluster administrator has delegated Operator installation permissions to your account, you can install and subscribe an Operator to your namespace in a self-service manner.
A cluster administrator must add certain permissions to your OKD user account to allow self-service Operator installation to a namespace. See Allowing non-cluster administrators to install Operators for details.
Ensure that you have downloaded the pull secret from Red Hat OpenShift Cluster Manager as shown in Obtaining the installation program in the installation documentation for your platform.
If you have the pull secret, add the redhat-operators
catalog to the OperatorHub
custom resource (CR) as shown in Configuring OKD to use Red Hat Operators.
OperatorHub is a user interface for discovering Operators; it works in conjunction with Operator Lifecycle Manager (OLM), which installs and manages Operators on a cluster.
As a user with the proper permissions, you can install an Operator from OperatorHub by using the OKD web console or CLI.
During installation, you must determine the following initial settings for the Operator:
Choose a specific namespace in which to install the Operator.
If an Operator is available through multiple channels, you can choose which channel you want to subscribe to. For example, to deploy from the stable channel, if available, select it from the list.
You can choose automatic or manual updates.
If you choose automatic updates for an installed Operator, when a new version of that Operator is available in the selected channel, Operator Lifecycle Manager (OLM) automatically upgrades the running instance of your Operator without human intervention.
If you select manual updates, when a newer version of an Operator is available, OLM creates an update request. As a cluster administrator, you must then manually approve that update request to have the Operator updated to the new version.
You can install and subscribe to an Operator from OperatorHub by using the OKD web console.
Access to an OKD cluster using an account with Operator installation permissions.
Navigate in the web console to the Operators → OperatorHub page.
Scroll or type a keyword into the Filter by keyword box to find the Operator you want. For example, type advanced
to find the Advanced Cluster Management for Kubernetes Operator.
You can also filter options by Infrastructure Features. For example, select Disconnected if you want to see Operators that work in disconnected environments, also known as restricted network environments.
Select the Operator to display additional information.
Choosing a Community Operator warns that Red Hat does not certify Community Operators; you must acknowledge the warning before continuing. |
Read the information about the Operator and click Install.
On the Install Operator page:
Choose a specific, single namespace in which to install the Operator. The Operator will only watch and be made available for use in this single namespace.
If the cluster is in AWS STS mode, enter the Amazon Resource Name (ARN) of the AWS IAM role of your service account in the role ARN field.
To create the role’s ARN, follow the procedure described in Preparing AWS account.
If more than one update channel is available, select an Update channel.
Select Automatic or Manual approval strategy, as described earlier.
If the web console shows that the cluster is in "STS mode", you must set Update approval to Manual. Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update. |
Click Install to make the Operator available to the selected namespaces on this OKD cluster.
If you selected a Manual approval strategy, the upgrade status of the subscription remains Upgrading until you review and approve the install plan.
After approving on the Install Plan page, the subscription upgrade status moves to Up to date.
If you selected an Automatic approval strategy, the upgrade status should resolve to Up to date without intervention.
After the upgrade status of the subscription is Up to date, select Operators → Installed Operators to verify that the cluster service version (CSV) of the installed Operator eventually shows up. The Status should ultimately resolve to InstallSucceeded in the relevant namespace.
For the All namespaces… installation mode, the status resolves to InstallSucceeded in the |
If it does not:
Check the logs in any pods in the openshift-operators
project (or other relevant namespace if A specific namespace… installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.
Instead of using the OKD web console, you can install an Operator from OperatorHub by using the CLI. Use the oc
command to create or update a Subscription
object.
Access to an OKD cluster using an account with Operator installation permissions.
You have installed the OpenShift CLI (oc
).
View the list of Operators available to the cluster from OperatorHub:
$ oc get packagemanifests -n openshift-marketplace
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
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.
The namespace to which you subscribe the Operator must have an Operator group that matches the install mode of the Operator, either the AllNamespaces
or SingleNamespace
mode. If the Operator you intend to install uses the AllNamespaces
mode, the openshift-operators
namespace already has the appropriate global-operators
Operator group in place.
However, if the Operator uses the SingleNamespace
mode and you do not already have an appropriate Operator group in place, you must create one.
|
Create an OperatorGroup
object YAML file, for example operatorgroup.yaml
:
OperatorGroup
objectapiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
name: <operatorgroup_name>
namespace: <namespace>
spec:
targetNamespaces:
- <namespace>
Operator Lifecycle Manager (OLM) creates the following cluster roles for each Operator group:
When you manually create an Operator group, you must specify a unique name that does not conflict with the existing cluster roles or other Operator groups on the cluster. |
Create the OperatorGroup
object:
$ oc apply -f operatorgroup.yaml
Create a Subscription
object YAML file to subscribe a namespace to an Operator, for example sub.yaml
:
Subscription
objectapiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: <subscription_name>
namespace: openshift-operators (1)
spec:
channel: <channel_name> (2)
name: <operator_name> (3)
source: redhat-operators (4)
sourceNamespace: openshift-marketplace (5)
config:
env: (6)
- name: ARGS
value: "-v=10"
envFrom: (7)
- secretRef:
name: license-secret
volumes: (8)
- name: <volume_name>
configmap:
name: <configmap_name>
volumeMounts: (9)
- mountPath: <directory_name>
name: <volume_name>
tolerations: (10)
- operator: "Exists"
resources: (11)
requests:
memory: "64Mi"
cpu: "250m"
limits:
memory: "128Mi"
cpu: "500m"
nodeSelector: (12)
foo: bar
1 | For default AllNamespaces install mode usage, specify the openshift-operators namespace. Alternatively, you can specify a custom global namespace, if you have created one. Otherwise, specify the relevant single namespace for SingleNamespace install mode usage. |
2 | Name of the channel to subscribe to. |
3 | Name of the Operator to subscribe to. |
4 | Name of the catalog source that provides the Operator. |
5 | Namespace of the catalog source. Use openshift-marketplace for the default OperatorHub catalog sources. |
6 | The env parameter defines a list of Environment Variables that must exist in all containers in the pod created by OLM. |
7 | The envFrom parameter defines a list of sources to populate Environment Variables in the container. |
8 | The volumes parameter defines a list of Volumes that must exist on the pod created by OLM. |
9 | The volumeMounts parameter defines 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. |
10 | The tolerations parameter defines a list of Tolerations for the pod created by OLM. |
11 | The resources parameter defines resource constraints for all the containers in the pod created by OLM. |
12 | The nodeSelector parameter defines a NodeSelector for the pod created by OLM. |
If the cluster is in STS mode, include the following fields in the Subscription
object:
kind: Subscription
# ...
spec:
installPlanApproval: Manual (1)
config:
env:
- name: ROLEARN
value: "<role_arn>" (2)
1 | Subscriptions with automatic update approvals are not recommended because there might be permission changes to make prior to updating. Subscriptions with manual update approvals ensure that administrators have the opportunity to verify the permissions of the later version and take any necessary steps prior to update. |
2 | Include the role ARN details. |
Create the Subscription
object:
$ oc apply -f sub.yaml
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.
You can install a specific version of an Operator by setting the cluster service version (CSV) in a Subscription
object.
Access to an OKD cluster using an account with Operator installation permissions.
You have installed the OpenShift CLI (oc
).
Look up the available versions and channels of the Operator you want to install by running the following command:
$ oc describe packagemanifests <operator_name> -n <catalog_namespace>
For example, the following command prints the available channels and versions of the Red Hat Quay Operator from OperatorHub:
$ oc describe packagemanifests quay-operator -n openshift-marketplace
Name: quay-operator
Namespace: operator-marketplace
Labels: catalog=redhat-operators
catalog-namespace=openshift-marketplace
hypershift.openshift.io/managed=true
operatorframework.io/arch.amd64=supported
operatorframework.io/os.linux=supported
provider=Red Hat
provider-url=
Annotations: <none>
API Version: packages.operators.coreos.com/v1
Kind: PackageManifest
...
Current CSV: quay-operator.v3.7.11
...
Entries:
Name: quay-operator.v3.7.11
Version: 3.7.11
Name: quay-operator.v3.7.10
Version: 3.7.10
Name: quay-operator.v3.7.9
Version: 3.7.9
Name: quay-operator.v3.7.8
Version: 3.7.8
Name: quay-operator.v3.7.7
Version: 3.7.7
Name: quay-operator.v3.7.6
Version: 3.7.6
Name: quay-operator.v3.7.5
Version: 3.7.5
Name: quay-operator.v3.7.4
Version: 3.7.4
Name: quay-operator.v3.7.3
Version: 3.7.3
Name: quay-operator.v3.7.2
Version: 3.7.2
Name: quay-operator.v3.7.1
Version: 3.7.1
Name: quay-operator.v3.7.0
Version: 3.7.0
Name: stable-3.7
...
Current CSV: quay-operator.v3.8.5
...
Entries:
Name: quay-operator.v3.8.5
Version: 3.8.5
Name: quay-operator.v3.8.4
Version: 3.8.4
Name: quay-operator.v3.8.3
Version: 3.8.3
Name: quay-operator.v3.8.2
Version: 3.8.2
Name: quay-operator.v3.8.1
Version: 3.8.1
Name: quay-operator.v3.8.0
Version: 3.8.0
Name: stable-3.8
Default Channel: stable-3.8
Package Name: quay-operator
You can print an Operator’s version and channel information in the YAML format by running the following command:
|
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
|
An Operator group, defined by an OperatorGroup
object, selects target namespaces in which to generate required role-based access control (RBAC) access for all Operators in the same namespace as the Operator group.
The namespace to which you subscribe the Operator must have an Operator group that matches the install mode of the Operator, either the AllNamespaces
or SingleNamespace
mode. If the Operator you intend to install uses the AllNamespaces
mode, then the openshift-operators
namespace already has an appropriate Operator group in place.
However, if the Operator uses the SingleNamespace
mode and you do not already have an appropriate Operator group in place, you must create one:
Create an OperatorGroup
object YAML file, for example operatorgroup.yaml
:
OperatorGroup
objectapiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
name: <operatorgroup_name>
namespace: <namespace>
spec:
targetNamespaces:
- <namespace>
Operator Lifecycle Manager (OLM) creates the following cluster roles for each Operator group:
When you manually create an Operator group, you must specify a unique name that does not conflict with the existing cluster roles or other Operator groups on the cluster. |
Create the OperatorGroup
object:
$ oc apply -f operatorgroup.yaml
Create a Subscription
object YAML file that subscribes a namespace to an Operator with a specific version by setting the startingCSV
field. Set the installPlanApproval
field to Manual
to prevent the Operator from automatically upgrading if a later version exists in the catalog.
For example, the following sub.yaml
file can be used to install the Red Hat Quay Operator specifically to version 3.7.10:
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
name: quay-operator
namespace: quay
spec:
channel: stable-3.7
installPlanApproval: Manual (1)
name: quay-operator
source: redhat-operators
sourceNamespace: openshift-marketplace
startingCSV: quay-operator.v3.7.10 (2)
1 | Set the approval strategy 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. |
2 | Set a specific version of an Operator CSV. |
Create the Subscription
object:
$ oc apply -f sub.yaml
Manually approve the pending install plan to complete the Operator installation.