Installing an Operator from a catalog in OLM 1.0 (Technology Preview)
Cluster administrators can add catalogs, or curated collections of Operators and Kubernetes extensions, to their clusters. Operator authors publish their products to these catalogs. When you add a catalog to your cluster, you have access to the versions, patches, and over-the-air updates of the Operators and extensions that are published to the catalog.
In the current Technology Preview release of Operator Lifecycle Manager (OLM) 1.0, you manage catalogs and Operators declaratively from the CLI using custom resources (CRs).
OLM 1.0 is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope. |
Prerequisites
Access to an OKD cluster using an account with
cluster-admin
permissionsFor OKD 4.14, documented procedures for OLM 1.0 are CLI-based only. Alternatively, administrators can create and view related objects in the web console by using normal methods, such as the Import YAML and Search pages. However, the existing OperatorHub and Installed Operators pages do not yet display OLM 1.0 components.
The
TechPreviewNoUpgrades
feature set enabled on the clusterEnabling the
TechPreviewNoUpgrade
feature set cannot be undone and prevents minor version updates. These feature sets are not recommended on production clusters.The OpenShift CLI (
oc
) installed on your workstation
Additional resources
About catalogs in OLM 1.0
You can discover installable content by querying a catalog for Kubernetes extensions, such as Operators and controllers, by using the catalogd component. Catalogd is a Kubernetes extension that unpacks catalog content for on-cluster clients and is part of the Operator Lifecycle Manager (OLM) 1.0 suite of microservices. Currently, catalogd unpacks catalog content that is packaged and distributed as container images.
Additional resources
Red Hat-provided Operator catalogs in OLM 1.0
Operator Lifecycle Manager (OLM) 1.0 does not include Red Hat-provided Operator catalogs by default. If you want to add a Red Hat-provided catalog to your cluster, create a custom resource (CR) for the catalog and apply it to the cluster. The following custom resource (CR) examples show how to create a catalog resources for OLM 1.0.
Example Red Hat Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
name: redhat-operators
spec:
source:
type: image
image:
ref: registry.redhat.io/redhat/redhat-operator-index:v4.14
Example Certified Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
name: certified-operators
spec:
source:
type: image
image:
ref: registry.redhat.io/redhat/certified-operator-index:v4.14
Example Community Operators catalog
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
name: community-operators
spec:
source:
type: image
image:
ref: registry.redhat.io/redhat/community-operator-index:v4.14
The following command adds a catalog to your cluster:
Command syntax
$ oc apply -f <catalog_name>.yaml (1)
1 | Specifies the catalog CR, such as redhat-operators.yaml . |
Additional resources
The following procedures use the Red Hat Operators catalog and the Quay Operator as examples. |
About target versions in OLM 1.0
In Operator Lifecycle Manager (OLM) 1.0, cluster administrators set the target version of an Operator declaratively in the Operator’s custom resource (CR).
If you specify a channel in the Operator’s CR, OLM 1.0 installs the latest release from the specified channel. When updates are published to the specified channel, OLM 1.0 automatically updates to the latest release from the channel.
Example CR with a specified channel
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
name: quay-example
spec:
packageName: quay-operator
channel: stable-3.8 (1)
1 | Installs the latest release published to the specified channel. Updates to the channel are automatically installed. |
If you specify the Operator’s target version in the CR, OLM 1.0 installs the specified version. When the target version is specified in the Operator’s CR, OLM 1.0 does not change the target version when updates are published to the catalog.
If you want to update the version of the Operator that is installed on the cluster, you must manually update the Operator’s CR. Specifying a Operator’s target version pins the Operator’s version to the specified release.
Example CR with the target version specified
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
name: quay-example
spec:
packageName: quay-operator
version: 3.8.12 (1)
1 | Specifies the target version. If you want to update the version of the Operator that is installed on the cluster, you must manually update this field the Operator’s CR to the desired target version. |
If you want to change the installed version of an Operator, edit the Operator’s CR to the desired target version.
In previous versions of OLM, Operator authors could define upgrade edges to prevent you from updating to unsupported versions. In its current state of development, OLM 1.0 does not enforce upgrade edge definitions. You can specify any version of an Operator, and OLM 1.0 attempts to apply the update. |
You can inspect an Operator’s catalog contents, including available versions and channels, by running the following command:
Command syntax
$ oc get package <catalog_name>-<package_name> -o yaml
After you create or update a CR, create or configure the Operator by running the following command:
Command syntax
$ oc apply -f <extension_name>.yaml
Troubleshooting
If you specify a target version or channel that does not exist, you can run the following command to check the status of your Operator:
$ oc get operator.operators.operatorframework.io <operator_name> -o yaml
Example output
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"999.99.9"}}
creationTimestamp: "2023-10-19T18:39:37Z"
generation: 3
name: quay-example
resourceVersion: "51505"
uid: 2558623b-8689-421c-8ed5-7b14234af166
spec:
packageName: quay-operator
version: 999.99.9
status:
conditions:
- lastTransitionTime: "2023-10-19T18:50:34Z"
message: package 'quay-operator' at version '999.99.9' not found
observedGeneration: 3
reason: ResolutionFailed
status: "False"
type: Resolved
- lastTransitionTime: "2023-10-19T18:50:34Z"
message: installation has not been attempted as resolution failed
observedGeneration: 3
reason: InstallationStatusUnknown
status: Unknown
type: Installed
Adding a catalog to a cluster
To add a catalog to a cluster, create a catalog custom resource (CR) and apply it to the cluster.
Procedure
Create a catalog custom resource (CR), similar to the following example:
Example
redhat-operators.yaml
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
name: redhat-operators
spec:
source:
type: image
image:
ref: registry.redhat.io/redhat/redhat-operator-index:v4.14 (1)
1 Specify the catalog’s image in the spec.source.image
field.Add the catalog to your cluster by running the following command:
$ oc apply -f redhat-operators.yaml
Example output
catalog.catalogd.operatorframework.io/redhat-operators created
Verification
Run the following commands to verify the status of your catalog:
Check if you catalog is available by running the following command:
$ oc get catalog
Example output
NAME AGE
redhat-operators 20s
Check the status of your catalog by running the following command:
$ oc get catalogs.catalogd.operatorframework.io -o yaml
Example output
apiVersion: v1
items:
- apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Catalog
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"catalogd.operatorframework.io/v1alpha1","kind":"Catalog","metadata":{"annotations":{},"name":"redhat-operators"},"spec":{"source":{"image":{"ref":"registry.redhat.io/redhat/redhat-operator-index:v4.14"},"type":"image"}}}
creationTimestamp: "2023-10-16T13:30:59Z"
generation: 1
name: redhat-operators
resourceVersion: "37304"
uid: cf00c68c-4312-4e06-aa8a-299f0bbf496b
spec:
source:
image:
ref: registry.redhat.io/redhat/redhat-operator-index:v4.14
type: image
status: (1)
conditions:
- lastTransitionTime: "2023-10-16T13:32:25Z"
message: successfully unpacked the catalog image "registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f" (2)
reason: UnpackSuccessful (3)
status: "True"
type: Unpacked
phase: Unpacked (4)
resolvedSource:
image:
ref: registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f (5)
type: image
kind: List
metadata:
resourceVersion: ""
1 Stanza describing the status of the catalog. 2 Output message of the status of the catalog. 3 Displays the reason the catalog is in the current state. 4 Displays the phase of the installion process. 5 Displays the image reference of the catalog.
Finding Operators to install from a catalog
After you add a catalog to your cluster, you can query the catalog to find Operators and extensions to install.
Prerequisite
- You have added a catalog to your cluster.
Procedure
Get a list of the Operators and extensions in the catalog by running the following command:
$ oc get packages
Example output
NAME AGE
redhat-operators-3scale-operator 5m27s
redhat-operators-advanced-cluster-management 5m27s
redhat-operators-amq-broker-rhel8 5m27s
redhat-operators-amq-online 5m27s
redhat-operators-amq-streams 5m27s
redhat-operators-amq7-interconnect-operator 5m27s
redhat-operators-ansible-automation-platform-operator 5m27s
redhat-operators-ansible-cloud-addons-operator 5m27s
redhat-operators-apicast-operator 5m27s
redhat-operators-aws-efs-csi-driver-operator 5m27s
redhat-operators-aws-load-balancer-operator 5m27s
...
Inspect the contents of an Operator or extension’s custom resource (CR) by running the following command:
$ oc get package <catalog_name>-<package_name> -o yaml
Example command
$ oc get package redhat-operators-quay-operator -o yaml
Example output
apiVersion: catalogd.operatorframework.io/v1alpha1
kind: Package
metadata:
creationTimestamp: "2023-10-06T01:14:04Z"
generation: 1
labels:
catalog: redhat-operators
name: redhat-operators-quay-operator
ownerReferences:
- apiVersion: catalogd.operatorframework.io/v1alpha1
blockOwnerDeletion: true
controller: true
kind: Catalog
name: redhat-operators
uid: 403004b6-54a3-4471-8c90-63419f6a2c3e
resourceVersion: "45196"
uid: 252cfe74-936d-44fc-be5d-09a7be7e36f5
spec:
catalog:
name: redhat-operators
channels:
- entries:
- name: quay-operator.v3.4.7
skips:
- red-hat-quay.v3.3.4
- quay-operator.v3.4.6
- quay-operator.v3.4.5
- quay-operator.v3.4.4
- quay-operator.v3.4.3
- quay-operator.v3.4.2
- quay-operator.v3.4.1
- quay-operator.v3.4.0
name: quay-v3.4
- entries:
- name: quay-operator.v3.5.7
replaces: quay-operator.v3.5.6
skipRange: '>=3.4.x <3.5.7'
name: quay-v3.5
- entries:
- name: quay-operator.v3.6.0
skipRange: '>=3.3.x <3.6.0'
- name: quay-operator.v3.6.1
replaces: quay-operator.v3.6.0
skipRange: '>=3.3.x <3.6.1'
- name: quay-operator.v3.6.10
replaces: quay-operator.v3.6.9
skipRange: '>=3.3.x <3.6.10'
- name: quay-operator.v3.6.2
replaces: quay-operator.v3.6.1
skipRange: '>=3.3.x <3.6.2'
- name: quay-operator.v3.6.4
replaces: quay-operator.v3.6.2
skipRange: '>=3.3.x <3.6.4'
- name: quay-operator.v3.6.5
replaces: quay-operator.v3.6.4
skipRange: '>=3.3.x <3.6.5'
- name: quay-operator.v3.6.6
replaces: quay-operator.v3.6.5
skipRange: '>=3.3.x <3.6.6'
- name: quay-operator.v3.6.7
replaces: quay-operator.v3.6.6
skipRange: '>=3.3.x <3.6.7'
- name: quay-operator.v3.6.8
replaces: quay-operator.v3.6.7
skipRange: '>=3.3.x <3.6.8'
- name: quay-operator.v3.6.9
replaces: quay-operator.v3.6.8
skipRange: '>=3.3.x <3.6.9'
name: stable-3.6
- entries:
- name: quay-operator.v3.7.10
replaces: quay-operator.v3.7.9
skipRange: '>=3.4.x <3.7.10'
- name: quay-operator.v3.7.11
replaces: quay-operator.v3.7.10
skipRange: '>=3.4.x <3.7.11'
- name: quay-operator.v3.7.12
replaces: quay-operator.v3.7.11
skipRange: '>=3.4.x <3.7.12'
- name: quay-operator.v3.7.13
replaces: quay-operator.v3.7.12
skipRange: '>=3.4.x <3.7.13'
- name: quay-operator.v3.7.14
replaces: quay-operator.v3.7.13
skipRange: '>=3.4.x <3.7.14'
name: stable-3.7
- entries:
- name: quay-operator.v3.8.0
skipRange: '>=3.5.x <3.8.0'
- name: quay-operator.v3.8.1
replaces: quay-operator.v3.8.0
skipRange: '>=3.5.x <3.8.1'
- name: quay-operator.v3.8.10
replaces: quay-operator.v3.8.9
skipRange: '>=3.5.x <3.8.10'
- name: quay-operator.v3.8.11
replaces: quay-operator.v3.8.10
skipRange: '>=3.5.x <3.8.11'
- name: quay-operator.v3.8.12
replaces: quay-operator.v3.8.11
skipRange: '>=3.5.x <3.8.12'
- name: quay-operator.v3.8.2
replaces: quay-operator.v3.8.1
skipRange: '>=3.5.x <3.8.2'
- name: quay-operator.v3.8.3
replaces: quay-operator.v3.8.2
skipRange: '>=3.5.x <3.8.3'
- name: quay-operator.v3.8.4
replaces: quay-operator.v3.8.3
skipRange: '>=3.5.x <3.8.4'
- name: quay-operator.v3.8.5
replaces: quay-operator.v3.8.4
skipRange: '>=3.5.x <3.8.5'
- name: quay-operator.v3.8.6
replaces: quay-operator.v3.8.5
skipRange: '>=3.5.x <3.8.6'
- name: quay-operator.v3.8.7
replaces: quay-operator.v3.8.6
skipRange: '>=3.5.x <3.8.7'
- name: quay-operator.v3.8.8
replaces: quay-operator.v3.8.7
skipRange: '>=3.5.x <3.8.8'
- name: quay-operator.v3.8.9
replaces: quay-operator.v3.8.8
skipRange: '>=3.5.x <3.8.9'
name: stable-3.8
- entries:
- name: quay-operator.v3.9.0
skipRange: '>=3.6.x <3.9.0'
- name: quay-operator.v3.9.1
replaces: quay-operator.v3.9.0
skipRange: '>=3.6.x <3.9.1'
- name: quay-operator.v3.9.2
replaces: quay-operator.v3.9.1
skipRange: '>=3.6.x <3.9.2'
name: stable-3.9
defaultChannel: stable-3.9
description: ""
icon:
data: PD94bWwgdmVyc2lvbj ...
mediatype: image/svg+xml
packageName: quay-operator
status: {}
Installing an Operator
You can install an Operator from a catalog by creating an Operator custom resource (CR) and applying it to the cluster.
Prerequisite
You have added a catalog to your cluster.
You have inspected the details of an Operator to find what version you want to install.
Procedure
Create an Operator CR, similar to the following example:
Example
test-operator.yaml
CRapiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
name: quay-example
spec:
packageName: quay-operator
version: 3.8.12
Apply the Operator CR to the cluster by running the following command:
$ oc apply -f test-operator.yaml
Example output
operator.operators.operatorframework.io/quay-example created
Verification
View the Operator’s CR in the YAML format by running the following command:
$ oc get operator.operators.operatorframework.io/quay-example -o yaml
Example output
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.8.12"}}
creationTimestamp: "2023-10-19T18:39:37Z"
generation: 1
name: quay-example
resourceVersion: "45663"
uid: 2558623b-8689-421c-8ed5-7b14234af166
spec:
packageName: quay-operator
version: 3.8.12
status:
conditions:
- lastTransitionTime: "2023-10-19T18:39:37Z"
message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
observedGeneration: 1
reason: Success
status: "True"
type: Resolved
- lastTransitionTime: "2023-10-19T18:39:46Z"
message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
observedGeneration: 1
reason: Success
status: "True"
type: Installed
installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
Get information about your Operator’s controller manager pod by running the following command:
$ oc get pod -n quay-operator-system
Example output
NAME READY STATUS RESTARTS AGE
quay-operator.v3.8.12-6677b5c98f-2kdtb 1/1 Running 0 2m28s
Updating an Operator
You can update your Operator by manually editing your Operator’s custom resource (CR) and applying the changes.
Prerequisites
You have a catalog installed.
You have an Operator installed.
Procedure
Inspect your Operator’s package contents to find which channels and versions are available for updating by running the following command:
$ oc get package <catalog_name>-<package_name> -o yaml
Example command
$ oc get package redhat-operators-quay-operator -o yaml
Edit your Operator’s CR to update the version to
3.9.1
, as shown in the following example:Example
test-operator.yaml
CRapiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
name: quay-example
spec:
packageName: quay-operator
version: 3.9.1 (1)
1 Update the version to 3.9.1
Apply the update to the cluster by running the following command:
$ oc apply -f test-operator.yaml
Example output
operator.operators.operatorframework.io/quay-example configured
You can patch and apply the changes to your Operator’s version from the CLI by running the following command:
$ oc patch operator.operators.operatorframework.io/quay-example -p \
‘{“spec”:{“version”:”3.9.1”}}’ \
—type=merge
Example outputoperator.operators.operatorframework.io/quay-example patched
Verification
Verify that the channel and version updates have been applied by running the following command:
$ oc get operator.operators.operatorframework.io/quay-example -o yaml
Example output
apiVersion: operators.operatorframework.io/v1alpha1
kind: Operator
metadata:
annotations:
kubectl.kubernetes.io/last-applied-configuration: |
{"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.9.1"}}
creationTimestamp: "2023-10-19T18:39:37Z"
generation: 2
name: quay-example
resourceVersion: "47423"
uid: 2558623b-8689-421c-8ed5-7b14234af166
spec:
packageName: quay-operator
version: 3.9.1 (1)
status:
conditions:
- lastTransitionTime: "2023-10-19T18:39:37Z"
message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09"
observedGeneration: 2
reason: Success
status: "True"
type: Resolved
- lastTransitionTime: "2023-10-19T18:39:46Z"
message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09"
observedGeneration: 2
reason: Success
status: "True"
type: Installed
installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09
resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09
1 Verify that the version is updated to 3.9.1
.
Deleting an Operator
You can delete an Operator and its custom resource definitions (CRDs) by deleting the Operator’s custom resource (CR).
Prerequisites
You have a catalog installed.
You have an Operator installed.
Procedure
Delete an Operator and its CRDs by running the following command:
$ oc delete operator.operators.operatorframework.io quay-example
Example output
operator.operators.operatorframework.io "quay-example" deleted
Verification
Run the following commands to verify that your Operator and its resources were deleted:
Verify the Operator is deleted by running the following command:
$ oc get operator.operators.operatorframework.io
Example output
No resources found
Verify that the Operator’s system namespace is deleted by running the following command:
$ oc get ns quay-operator-system
Example output
Error from server (NotFound): namespaces "quay-operator-system" not found