1. Documentation
×

Configuring cluster extensions

In Operator Lifecycle Manager (OLM) v1, extensions watch all namespaces by default. Some Operators support only namespace-scoped watching based on OLM (Classic) install modes. To install these Operators, configure the watch namespace for the extension. For more information, see "Discovering bundle install modes".

Configuring a watch namespace for a cluster extension 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.

Extension configuration

Configure the namespace an extension watches by using the .spec.config field in the ClusterExtension resource.

OLM v1 configuration API 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.

Extensions watch all namespaces by default. Some Operators support only namespace-scoped watching based on OLM (Classic) install modes. Configure the .spec.config.inline.watchNamespace field to install these Operators.

Whether you must configure this field depends on the install modes supported by the bundle.

Configuration API structure

The configuration API uses an opaque structure. The bundle validates the configuration values, not OLM v1. Operator authors can define their own configuration requirements.

Currently, the Inline configuration type is the only supported type:

Example inline configuration
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: <extension_name>
...
spec:
  namespace: <installation_namespace>
  config:
    configType: Inline
    inline:
      watchNamespace: <watch_namespace>

where:

<installation_namespace>

Specifies the namespace where the extension components run.

config.configType

Specifies the configuration type. Currently, Inline is the only supported type.

<watch_namespace>

Specifies the namespace where the extension watches for custom resources. The watch namespace can match or differ from the installation namespace, depending on the install modes supported by the bundle.

Additional resources

Watch namespace configuration requirements

Avoid installation failures by using the correct watchNamespace value for the install modes supported by your bundle. Requirements vary based on whether the bundle supports AllNamespaces, OwnNamespace, and SingleNamespace install modes.

OLM (Classic) registry+v1 bundles declare the install modes they support. These install modes control whether watchNamespace configuration is required or optional, and what values are valid.

OLM v1 does not support multi-tenancy. You cannot install the same extension more than once on a cluster. As a result, the MultiNamespace install mode is not supported.
AllNamespaces

Watches resources across all namespaces in the cluster.

OwnNamespace

Watches resources only in the installation namespace.

SingleNamespace

Watches resources in a single namespace that differs from the installation namespace.

Whether the .spec.config.inline.watchNamespace field is required depends on the install modes that the bundle supports.

Table 1. Watch namespace requirements by bundle capability
Bundle install mode support watchNamespace field Valid values

AllNamespaces mode only

Not applicable

The watchNamespace field is not supported. Extensions watch all namespaces.

OwnNamespace mode only

Required

Must match .spec.namespace field

SingleNamespace mode only

Required

Must differ from .spec.namespace field

Both OwnNamespace and SingleNamespace install modes

Required

Can match or differ from .spec.namespace field

AllNamespaces install mode with one or both of the OwnNamespace and SingleNamespace install modes

Optional

Omit to watch all namespaces, or specify a namespace to watch only that namespace

OLM v1 validates the watchNamespace value based on the install mode support that is declared by the bundle. The installation fails with a validation error if you specify an invalid value or omit a required field.

Discovering bundle install modes

You can render the bundle metadata to find which install modes a bundle supports.

Prerequisites

  • You have installed the jq CLI tool.

  • You have installed the opm CLI tool.

Procedure

  1. Render the bundle metadata by running the following command:

    $ opm render <bundle_image> -o json | \
  jq 'select(.schema == "olm.bundle") | .properties[] | select(.type == "olm.bundle.object")'
    Example output
    {
  "type": "olm.bundle.object",
  "value": {
    "data": "...",
    "ref": "olm.csv"
  }
}

  2. Decode the base64-encoded CSV data to view install mode declarations:

    $ echo "<base64_data>" | base64 -d | jq '.spec.installModes'
    Example output
    [
  {
    "type": "OwnNamespace",
    "supported": true
  },
  {
    "type": "SingleNamespace",
    "supported": true
  },
  {
    "type": "MultiNamespace",
    "supported": false
  },
  {
    "type": "AllNamespaces",
    "supported": false
  }
]

    In this example, the bundle supports both OwnNamespace and SingleNamespace modes. The .spec.config.inline.watchNamespace field is required and can match or differ from the .spec.namespace field.

Configuring a watch namespace for a cluster extension (Technology Preview)

You can configure the watch namespace for extensions that support namespace-scoped resource watching.

Configuring watch namespace for a cluster extension 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

  • You have access to an OKD cluster using an account with cluster-admin permissions.

  • You have enabled the TechPreviewNoUpgrade feature set on the cluster.

  • You have created a service account and assigned enough role-based access controls (RBAC) to install, update, and manage the extension. For more information, see "Cluster extension permissions".

  • You have verified the supported install modes for the extension and determined the required watchNamespace configuration.

Procedure

  1. Create a custom resource (CR) based on where you want the extension to watch for resources:

    • To configure the extension to watch its own installation namespace:

      apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: <extension_name>
spec:
  namespace: <installation_namespace>
  config:
    configType: Inline
    inline:
      watchNamespace: <installation_namespace>
  serviceAccount:
    name: <service_account>
  source:
    sourceType: Catalog
    catalog:
      packageName: <package_name>
      version: <version>
      upgradeConstraintPolicy: CatalogProvided

      where:

      config.inline.watchNamespace

      Specifies the namespace to watch for resources. For requirements and valid values, see "Extension configuration".

    • To configure the extension to watch a different namespace:

      apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: <extension_name>
spec:
  namespace: <installation_namespace>
  config:
    configType: Inline
    inline:
      watchNamespace: <watched_namespace>
  serviceAccount:
    name: <service_account>
  source:
    sourceType: Catalog
    catalog:
      packageName: <package_name>
      version: <version>
      upgradeConstraintPolicy: CatalogProvided

  2. Apply the CR to the cluster by running the following command:

    $ oc apply -f <cluster_extension_cr>.yaml
Verification

  • Verify that the extension installed successfully by running the following command:

    $ oc get clusterextension <extension_name> -o yaml
    Example output
    apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: <extension_name>
spec:
  namespace: <installation_namespace>
  config:
    configType: Inline
    inline:
      watchNamespace: <installation_namespace>
status:
  conditions:
  - type: Installed
    status: "True"
    reason: Succeeded

Watch namespace configuration examples

To configure the watchNamespace field correctly for your bundle’s install mode, see the following examples. These show valid configurations for Operators that support the AllNamespaces, OwnNamespace, and SingleNamespace install modes.

Example AllNamespaces install mode
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: example-extension
spec:
  namespace: openshift-operators
  serviceAccount:
    name: example-sa
  source:
    sourceType: Catalog
    catalog:
      packageName: example-operator

  • The config field is omitted. The extension watches all namespaces by default.

Example OwnNamespace install mode
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: example-extension
spec:
  namespace: example-operators
  config:
    configType: Inline
    inline:
      watchNamespace: example-operators
  serviceAccount:
    name: example-sa
  source:
    sourceType: Catalog
    catalog:
      packageName: example-operator

  • You must set the watchNamespace field to use the OwnNamespace install mode.

  • The watchNamespace value must match the spec.namespace field value.

Example SingleNamespace install mode
apiVersion: olm.operatorframework.io/v1
kind: ClusterExtension
metadata:
  name: example-extension
spec:
  namespace: example-operators
  config:
    configType: Inline
    inline:
      watchNamespace: production
  serviceAccount:
    name: example-sa
  source:
    sourceType: Catalog
    catalog:
      packageName: example-operator

  • You must set the watchNamespace field to use the SingleNamespace install mode.

  • The watchNamespace value must differ from the spec.namespace field value.

  • In this example, the extension runs in the example-operators namespace but watches resources in the production namespace.

Watch namespace validation errors

Validation errors occur when the watchNamespace field is omitted or contains an invalid value for the install modes supported by the bundle.

Table 2. Common watchNamespace field validation errors
Error Cause Resolution

Required field missing

The bundle requires the watchNamespace field but it is omitted.

Add the watchNamespace field with a value that matches the install modes supported by the bundle.

OwnNamespace validation error

The bundle only supports OwnNamespace mode but the watchNamespace value does not match the .spec.namespace field.

Set the watchNamespace field to the same value as the .spec.namespace field.

SingleNamespace validation error

The bundle only supports SingleNamespace mode but the watchNamespace value matches the .spec.namespace field.

Set the watchNamespace field to a different namespace than the .spec.namespace field.

Invalid configuration

The .spec.config structure is malformed or has unsupported fields.

Verify the configuration follows the correct API structure with configType: Inline and valid inline fields.

Additional resources