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 permissions

    For 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 cluster

    Enabling 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

  1. apiVersion: catalogd.operatorframework.io/v1alpha1
  2. kind: Catalog
  3. metadata:
  4. name: redhat-operators
  5. spec:
  6. source:
  7. type: image
  8. image:
  9. ref: registry.redhat.io/redhat/redhat-operator-index:v4.14

Example Certified Operators catalog

  1. apiVersion: catalogd.operatorframework.io/v1alpha1
  2. kind: Catalog
  3. metadata:
  4. name: certified-operators
  5. spec:
  6. source:
  7. type: image
  8. image:
  9. ref: registry.redhat.io/redhat/certified-operator-index:v4.14

Example Community Operators catalog

  1. apiVersion: catalogd.operatorframework.io/v1alpha1
  2. kind: Catalog
  3. metadata:
  4. name: community-operators
  5. spec:
  6. source:
  7. type: image
  8. image:
  9. ref: registry.redhat.io/redhat/community-operator-index:v4.14

The following command adds a catalog to your cluster:

Command syntax

  1. $ oc apply -f <catalog_name>.yaml (1)
1Specifies 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

  1. apiVersion: operators.operatorframework.io/v1alpha1
  2. kind: Operator
  3. metadata:
  4. name: quay-example
  5. spec:
  6. packageName: quay-operator
  7. channel: stable-3.8 (1)
1Installs 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

  1. apiVersion: operators.operatorframework.io/v1alpha1
  2. kind: Operator
  3. metadata:
  4. name: quay-example
  5. spec:
  6. packageName: quay-operator
  7. version: 3.8.12 (1)
1Specifies 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

  1. $ 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

  1. $ 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:

    1. $ oc get operator.operators.operatorframework.io <operator_name> -o yaml

    Example output

    1. apiVersion: operators.operatorframework.io/v1alpha1
    2. kind: Operator
    3. metadata:
    4. annotations:
    5. kubectl.kubernetes.io/last-applied-configuration: |
    6. {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"999.99.9"}}
    7. creationTimestamp: "2023-10-19T18:39:37Z"
    8. generation: 3
    9. name: quay-example
    10. resourceVersion: "51505"
    11. uid: 2558623b-8689-421c-8ed5-7b14234af166
    12. spec:
    13. packageName: quay-operator
    14. version: 999.99.9
    15. status:
    16. conditions:
    17. - lastTransitionTime: "2023-10-19T18:50:34Z"
    18. message: package 'quay-operator' at version '999.99.9' not found
    19. observedGeneration: 3
    20. reason: ResolutionFailed
    21. status: "False"
    22. type: Resolved
    23. - lastTransitionTime: "2023-10-19T18:50:34Z"
    24. message: installation has not been attempted as resolution failed
    25. observedGeneration: 3
    26. reason: InstallationStatusUnknown
    27. status: Unknown
    28. 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

  1. Create a catalog custom resource (CR), similar to the following example:

    Example redhat-operators.yaml

    1. apiVersion: catalogd.operatorframework.io/v1alpha1
    2. kind: Catalog
    3. metadata:
    4. name: redhat-operators
    5. spec:
    6. source:
    7. type: image
    8. image:
    9. ref: registry.redhat.io/redhat/redhat-operator-index:v4.14 (1)
    1Specify the catalog’s image in the spec.source.image field.
  2. Add the catalog to your cluster by running the following command:

    1. $ oc apply -f redhat-operators.yaml

    Example output

    1. catalog.catalogd.operatorframework.io/redhat-operators created

Verification

  • Run the following commands to verify the status of your catalog:

    1. Check if you catalog is available by running the following command:

      1. $ oc get catalog

      Example output

      1. NAME AGE
      2. redhat-operators 20s
    2. Check the status of your catalog by running the following command:

      1. $ oc get catalogs.catalogd.operatorframework.io -o yaml

      Example output

      1. apiVersion: v1
      2. items:
      3. - apiVersion: catalogd.operatorframework.io/v1alpha1
      4. kind: Catalog
      5. metadata:
      6. annotations:
      7. kubectl.kubernetes.io/last-applied-configuration: |
      8. {"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"}}}
      9. creationTimestamp: "2023-10-16T13:30:59Z"
      10. generation: 1
      11. name: redhat-operators
      12. resourceVersion: "37304"
      13. uid: cf00c68c-4312-4e06-aa8a-299f0bbf496b
      14. spec:
      15. source:
      16. image:
      17. ref: registry.redhat.io/redhat/redhat-operator-index:v4.14
      18. type: image
      19. status: (1)
      20. conditions:
      21. - lastTransitionTime: "2023-10-16T13:32:25Z"
      22. message: successfully unpacked the catalog image "registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f" (2)
      23. reason: UnpackSuccessful (3)
      24. status: "True"
      25. type: Unpacked
      26. phase: Unpacked (4)
      27. resolvedSource:
      28. image:
      29. ref: registry.redhat.io/redhat/redhat-operator-index@sha256:bd2f1060253117a627d2f85caa1532ebae1ba63da2a46bdd99e2b2a08035033f (5)
      30. type: image
      31. kind: List
      32. metadata:
      33. resourceVersion: ""
      1Stanza describing the status of the catalog.
      2Output message of the status of the catalog.
      3Displays the reason the catalog is in the current state.
      4Displays the phase of the installion process.
      5Displays 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

  1. Get a list of the Operators and extensions in the catalog by running the following command:

    1. $ oc get packages

    Example output

    1. NAME AGE
    2. redhat-operators-3scale-operator 5m27s
    3. redhat-operators-advanced-cluster-management 5m27s
    4. redhat-operators-amq-broker-rhel8 5m27s
    5. redhat-operators-amq-online 5m27s
    6. redhat-operators-amq-streams 5m27s
    7. redhat-operators-amq7-interconnect-operator 5m27s
    8. redhat-operators-ansible-automation-platform-operator 5m27s
    9. redhat-operators-ansible-cloud-addons-operator 5m27s
    10. redhat-operators-apicast-operator 5m27s
    11. redhat-operators-aws-efs-csi-driver-operator 5m27s
    12. redhat-operators-aws-load-balancer-operator 5m27s
    13. ...
  2. Inspect the contents of an Operator or extension’s custom resource (CR) by running the following command:

    1. $ oc get package <catalog_name>-<package_name> -o yaml

    Example command

    1. $ oc get package redhat-operators-quay-operator -o yaml

    Example output

    1. apiVersion: catalogd.operatorframework.io/v1alpha1
    2. kind: Package
    3. metadata:
    4. creationTimestamp: "2023-10-06T01:14:04Z"
    5. generation: 1
    6. labels:
    7. catalog: redhat-operators
    8. name: redhat-operators-quay-operator
    9. ownerReferences:
    10. - apiVersion: catalogd.operatorframework.io/v1alpha1
    11. blockOwnerDeletion: true
    12. controller: true
    13. kind: Catalog
    14. name: redhat-operators
    15. uid: 403004b6-54a3-4471-8c90-63419f6a2c3e
    16. resourceVersion: "45196"
    17. uid: 252cfe74-936d-44fc-be5d-09a7be7e36f5
    18. spec:
    19. catalog:
    20. name: redhat-operators
    21. channels:
    22. - entries:
    23. - name: quay-operator.v3.4.7
    24. skips:
    25. - red-hat-quay.v3.3.4
    26. - quay-operator.v3.4.6
    27. - quay-operator.v3.4.5
    28. - quay-operator.v3.4.4
    29. - quay-operator.v3.4.3
    30. - quay-operator.v3.4.2
    31. - quay-operator.v3.4.1
    32. - quay-operator.v3.4.0
    33. name: quay-v3.4
    34. - entries:
    35. - name: quay-operator.v3.5.7
    36. replaces: quay-operator.v3.5.6
    37. skipRange: '>=3.4.x <3.5.7'
    38. name: quay-v3.5
    39. - entries:
    40. - name: quay-operator.v3.6.0
    41. skipRange: '>=3.3.x <3.6.0'
    42. - name: quay-operator.v3.6.1
    43. replaces: quay-operator.v3.6.0
    44. skipRange: '>=3.3.x <3.6.1'
    45. - name: quay-operator.v3.6.10
    46. replaces: quay-operator.v3.6.9
    47. skipRange: '>=3.3.x <3.6.10'
    48. - name: quay-operator.v3.6.2
    49. replaces: quay-operator.v3.6.1
    50. skipRange: '>=3.3.x <3.6.2'
    51. - name: quay-operator.v3.6.4
    52. replaces: quay-operator.v3.6.2
    53. skipRange: '>=3.3.x <3.6.4'
    54. - name: quay-operator.v3.6.5
    55. replaces: quay-operator.v3.6.4
    56. skipRange: '>=3.3.x <3.6.5'
    57. - name: quay-operator.v3.6.6
    58. replaces: quay-operator.v3.6.5
    59. skipRange: '>=3.3.x <3.6.6'
    60. - name: quay-operator.v3.6.7
    61. replaces: quay-operator.v3.6.6
    62. skipRange: '>=3.3.x <3.6.7'
    63. - name: quay-operator.v3.6.8
    64. replaces: quay-operator.v3.6.7
    65. skipRange: '>=3.3.x <3.6.8'
    66. - name: quay-operator.v3.6.9
    67. replaces: quay-operator.v3.6.8
    68. skipRange: '>=3.3.x <3.6.9'
    69. name: stable-3.6
    70. - entries:
    71. - name: quay-operator.v3.7.10
    72. replaces: quay-operator.v3.7.9
    73. skipRange: '>=3.4.x <3.7.10'
    74. - name: quay-operator.v3.7.11
    75. replaces: quay-operator.v3.7.10
    76. skipRange: '>=3.4.x <3.7.11'
    77. - name: quay-operator.v3.7.12
    78. replaces: quay-operator.v3.7.11
    79. skipRange: '>=3.4.x <3.7.12'
    80. - name: quay-operator.v3.7.13
    81. replaces: quay-operator.v3.7.12
    82. skipRange: '>=3.4.x <3.7.13'
    83. - name: quay-operator.v3.7.14
    84. replaces: quay-operator.v3.7.13
    85. skipRange: '>=3.4.x <3.7.14'
    86. name: stable-3.7
    87. - entries:
    88. - name: quay-operator.v3.8.0
    89. skipRange: '>=3.5.x <3.8.0'
    90. - name: quay-operator.v3.8.1
    91. replaces: quay-operator.v3.8.0
    92. skipRange: '>=3.5.x <3.8.1'
    93. - name: quay-operator.v3.8.10
    94. replaces: quay-operator.v3.8.9
    95. skipRange: '>=3.5.x <3.8.10'
    96. - name: quay-operator.v3.8.11
    97. replaces: quay-operator.v3.8.10
    98. skipRange: '>=3.5.x <3.8.11'
    99. - name: quay-operator.v3.8.12
    100. replaces: quay-operator.v3.8.11
    101. skipRange: '>=3.5.x <3.8.12'
    102. - name: quay-operator.v3.8.2
    103. replaces: quay-operator.v3.8.1
    104. skipRange: '>=3.5.x <3.8.2'
    105. - name: quay-operator.v3.8.3
    106. replaces: quay-operator.v3.8.2
    107. skipRange: '>=3.5.x <3.8.3'
    108. - name: quay-operator.v3.8.4
    109. replaces: quay-operator.v3.8.3
    110. skipRange: '>=3.5.x <3.8.4'
    111. - name: quay-operator.v3.8.5
    112. replaces: quay-operator.v3.8.4
    113. skipRange: '>=3.5.x <3.8.5'
    114. - name: quay-operator.v3.8.6
    115. replaces: quay-operator.v3.8.5
    116. skipRange: '>=3.5.x <3.8.6'
    117. - name: quay-operator.v3.8.7
    118. replaces: quay-operator.v3.8.6
    119. skipRange: '>=3.5.x <3.8.7'
    120. - name: quay-operator.v3.8.8
    121. replaces: quay-operator.v3.8.7
    122. skipRange: '>=3.5.x <3.8.8'
    123. - name: quay-operator.v3.8.9
    124. replaces: quay-operator.v3.8.8
    125. skipRange: '>=3.5.x <3.8.9'
    126. name: stable-3.8
    127. - entries:
    128. - name: quay-operator.v3.9.0
    129. skipRange: '>=3.6.x <3.9.0'
    130. - name: quay-operator.v3.9.1
    131. replaces: quay-operator.v3.9.0
    132. skipRange: '>=3.6.x <3.9.1'
    133. - name: quay-operator.v3.9.2
    134. replaces: quay-operator.v3.9.1
    135. skipRange: '>=3.6.x <3.9.2'
    136. name: stable-3.9
    137. defaultChannel: stable-3.9
    138. description: ""
    139. icon:
    140. data: PD94bWwgdmVyc2lvbj ...
    141. mediatype: image/svg+xml
    142. packageName: quay-operator
    143. 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

  1. Create an Operator CR, similar to the following example:

    Example test-operator.yaml CR

    1. apiVersion: operators.operatorframework.io/v1alpha1
    2. kind: Operator
    3. metadata:
    4. name: quay-example
    5. spec:
    6. packageName: quay-operator
    7. version: 3.8.12
  2. Apply the Operator CR to the cluster by running the following command:

    1. $ oc apply -f test-operator.yaml

    Example output

    1. operator.operators.operatorframework.io/quay-example created

Verification

  1. View the Operator’s CR in the YAML format by running the following command:

    1. $ oc get operator.operators.operatorframework.io/quay-example -o yaml

    Example output

    1. apiVersion: operators.operatorframework.io/v1alpha1
    2. kind: Operator
    3. metadata:
    4. annotations:
    5. kubectl.kubernetes.io/last-applied-configuration: |
    6. {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.8.12"}}
    7. creationTimestamp: "2023-10-19T18:39:37Z"
    8. generation: 1
    9. name: quay-example
    10. resourceVersion: "45663"
    11. uid: 2558623b-8689-421c-8ed5-7b14234af166
    12. spec:
    13. packageName: quay-operator
    14. version: 3.8.12
    15. status:
    16. conditions:
    17. - lastTransitionTime: "2023-10-19T18:39:37Z"
    18. message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
    19. observedGeneration: 1
    20. reason: Success
    21. status: "True"
    22. type: Resolved
    23. - lastTransitionTime: "2023-10-19T18:39:46Z"
    24. message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7"
    25. observedGeneration: 1
    26. reason: Success
    27. status: "True"
    28. type: Installed
    29. installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
    30. resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:bf26c7679ea1f7b47d2b362642a9234cddb9e366a89708a4ffcbaf4475788dc7
  2. Get information about your Operator’s controller manager pod by running the following command:

    1. $ oc get pod -n quay-operator-system

    Example output

    1. NAME READY STATUS RESTARTS AGE
    2. 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

  1. Inspect your Operator’s package contents to find which channels and versions are available for updating by running the following command:

    1. $ oc get package <catalog_name>-<package_name> -o yaml

    Example command

    1. $ oc get package redhat-operators-quay-operator -o yaml
  2. Edit your Operator’s CR to update the version to 3.9.1, as shown in the following example:

    Example test-operator.yaml CR

    1. apiVersion: operators.operatorframework.io/v1alpha1
    2. kind: Operator
    3. metadata:
    4. name: quay-example
    5. spec:
    6. packageName: quay-operator
    7. version: 3.9.1 (1)
    1Update the version to 3.9.1
  3. Apply the update to the cluster by running the following command:

    1. $ oc apply -f test-operator.yaml

    Example output

    1. 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:

    1. $ oc patch operator.operators.operatorframework.io/quay-example -p \
    2. ‘{“spec”:{“version”:”3.9.1”}}’ \
    3. type=merge
    Example output
    1. operator.operators.operatorframework.io/quay-example patched

Verification

  • Verify that the channel and version updates have been applied by running the following command:

    1. $ oc get operator.operators.operatorframework.io/quay-example -o yaml

    Example output

    1. apiVersion: operators.operatorframework.io/v1alpha1
    2. kind: Operator
    3. metadata:
    4. annotations:
    5. kubectl.kubernetes.io/last-applied-configuration: |
    6. {"apiVersion":"operators.operatorframework.io/v1alpha1","kind":"Operator","metadata":{"annotations":{},"name":"quay-example"},"spec":{"packageName":"quay-operator","version":"3.9.1"}}
    7. creationTimestamp: "2023-10-19T18:39:37Z"
    8. generation: 2
    9. name: quay-example
    10. resourceVersion: "47423"
    11. uid: 2558623b-8689-421c-8ed5-7b14234af166
    12. spec:
    13. packageName: quay-operator
    14. version: 3.9.1 (1)
    15. status:
    16. conditions:
    17. - lastTransitionTime: "2023-10-19T18:39:37Z"
    18. message: resolved to "registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09"
    19. observedGeneration: 2
    20. reason: Success
    21. status: "True"
    22. type: Resolved
    23. - lastTransitionTime: "2023-10-19T18:39:46Z"
    24. message: installed from "registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09"
    25. observedGeneration: 2
    26. reason: Success
    27. status: "True"
    28. type: Installed
    29. installedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09
    30. resolvedBundleResource: registry.redhat.io/quay/quay-operator-bundle@sha256:4864bc0d5c18a84a5f19e5e664b58d3133a2ac2a309c6b5659ab553f33214b09
    1Verify 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:

    1. $ oc delete operator.operators.operatorframework.io quay-example

    Example output

    1. 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:

      1. $ oc get operator.operators.operatorframework.io

      Example output

      1. No resources found
    • Verify that the Operator’s system namespace is deleted by running the following command:

      1. $ oc get ns quay-operator-system

      Example output

      1. Error from server (NotFound): namespaces "quay-operator-system" not found