Skip to content

Commit 1498d0a

Browse files
author
Per Goncalves da Silva
committed
Adds bundle configuration documentation
Signed-off-by: Per Goncalves da Silva <pegoncal@redhat.com>
1 parent ff7d3c2 commit 1498d0a

File tree

1 file changed

+172
-0
lines changed

1 file changed

+172
-0
lines changed

‎docs/draft/howto/configure-bundles.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
## Description
2+
3+
!!! note
4+
This feature is still in `alpha` and the `SingleOwnNamespaceInstallSupport` feature-gate must be enabled to make use of it.
5+
See the instructions below on how to enable it.
6+
7+
---
8+
9+
# Configuring OLM v1 Extensions: Migration and Reference
10+
11+
In OLM v1, the way extensions are configured has changed significantly to improve flexibility and consistency. This guide explains the architectural shift from OLM v0, how to inspect bundles for supported configurations, and how to correctly configure `registry+v1` (legacy) bundles using the new `ClusterExtension` API.
12+
13+
## OLM v0 vs. OLM v1: The Configuration Shift
14+
15+
In **OLM v0**, configuration was split across multiple resources and concepts. "Install Modes" (defining which namespaces an Operator watches) were handled by the `OperatorGroup` resource, while operand configuration (environment variables, resource limits) was handled via the `Subscription` resource.
16+
17+
In **OLM v1**, these concepts are unified under the **ClusterExtension** resource.
18+
19+
| Feature | OLM v0 Approach | OLM v1 Approach |
20+
|:--------------------|:----------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------|
21+
| **Namespace Scope** | Defined by **OperatorGroup**. You had to pre-create an OperatorGroup to tell the Operator where to watch. | Defined by **Configuration**. You provide a `watchNamespace` value directly in the `ClusterExtension` YAML. |
22+
| **User Settings** | `Subscription.spec.config` (e.g., env, resources). | `ClusterExtension.spec.config.inline` (arbitrary JSON/YAML defined by the bundle author). |
23+
| **Multi-Tenancy** | "Install Modes" allowed multiple instances of an operator to exist. | "Install Modes" are treated as **bundle configuration**. You install the extension once, and configure it to watch specific areas. |
24+
25+
### The `watchNamespace` Configuration
26+
27+
For existing `registry+v1` bundles (standard OLM bundles), OLM v1 automatically generates a configuration schema based on the bundle's capabilities. The primary configuration field available is `watchNamespace`.
28+
29+
* **OLM v0:** You selected `SingleNamespace` mode by creating an `OperatorGroup` that targeted a specific namespace.
30+
* **OLM v1:** You set `watchNamespace: "my-target-namespace"` inside the `ClusterExtension` config.
31+
32+
## Step 1: Identifying Bundle Capabilities
33+
34+
Before configuring a bundle, you must understand which Install Modes it supports. OLM v1 does not allow you to force a configuration that the bundle author has not explicitly supported.
35+
36+
You can inspect a bundle image using the `opm` CLI tool and `jq` to parse the output.
37+
38+
**Prerequisites:**
39+
* `opm` CLI installed.
40+
* `jq` installed.
41+
42+
**Command:**
43+
44+
Run the following command, replacing `<bundle-image>` with your target image (e.g., `quay.io/example/my-operator-bundle:v1.0.0`).
45+
46+
```bash
47+
opm render <bundle-image> -o json | \
48+
jq 'select(.schema == "olm.bundle") | .properties[] | select(.type == "olm.csv") | .value.spec.installModes'
49+
```
50+
51+
**Example Output:**
52+
53+
```json
54+
[
55+
{
56+
"type": "OwnNamespace",
57+
"supported": true
58+
},
59+
{
60+
"type": "SingleNamespace",
61+
"supported": true
62+
},
63+
{
64+
"type": "MultiNamespace",
65+
"supported": false
66+
},
67+
{
68+
"type": "AllNamespaces",
69+
"supported": false
70+
}
71+
]
72+
```
73+
74+
By analyzing which modes are marked `true`, you can determine how to configure the `ClusterExtension` in the next step.
75+
76+
## Step 2: Capability Matrix & Configuration Guide
77+
78+
Use the output from Step 1 to locate your bundle's capabilities in the matrix below. This determines if you *must* provide configuration, if it is optional, and what values are valid.
79+
80+
### Legend
81+
* **Install Namespace:** The namespace where the Operator logic (Pod) runs (defined in `ClusterExtension.spec.namespace`).
82+
* **Watch Namespace:** The namespace the Operator monitors for Custom Resources (defined in `spec.config.inline.watchNamespace`).
83+
84+
### Configuration Matrix
85+
86+
| Capabilities Detected (from `opm`) | `watchNamespace` Field Status | Valid Values / Constraints |
87+
|:-----------------------------------------|:------------------------------|:----------------------------------------------------------------------------------------------------------|
88+
| **OwnNamespace ONLY** | **Required** | Must be exactly the same as the **Install Namespace**. |
89+
| **SingleNamespace ONLY** | **Required** | Must be **different** from the Install Namespace. |
90+
| **OwnNamespace** AND **SingleNamespace** | **Required** | Can be **any** namespace (either the install namespace or a different one). |
91+
| **AllNamespaces** (regardless of others) | **Optional** | If omitted: defaults to Cluster-wide watch.<br>If provided: can be any specific namespace (limits scope). |
92+
93+
### Common Configuration Scenarios
94+
95+
#### Scenario A: The Legacy "OwnNamespace" Operator
96+
* **Capability:** Only supports `OwnNamespace`.
97+
* **Requirement:** The operator is hardcoded to watch its own namespace.
98+
* **Config:** You must explicitly set `watchNamespace` to match the installation namespace.
99+
100+
```yaml
101+
apiVersion: olm.operatorframework.io/v1
102+
kind: ClusterExtension
103+
metadata:
104+
name: my-operator
105+
spec:
106+
namespace: my-operator-ns # <--- Install Namespace
107+
serviceAccount:
108+
name: my-sa
109+
config:
110+
configType: Inline
111+
inline:
112+
watchNamespace: my-operator-ns # <--- MUST match Install Namespace
113+
source:
114+
sourceType: Catalog
115+
catalog:
116+
packageName: my-package
117+
```
118+
119+
#### Scenario B: The "SingleNamespace" Operator
120+
* **Capability:** Supports `SingleNamespace` (but not `OwnNamespace`).
121+
* **Requirement:** The operator runs in one namespace (e.g., `ops-system`) but watches workloads in another (e.g., `dev-team-a`).
122+
* **Config:** You must set `watchNamespace` to the target workload namespace.
123+
124+
```yaml
125+
apiVersion: olm.operatorframework.io/v1
126+
kind: ClusterExtension
127+
metadata:
128+
name: monitor-operator
129+
spec:
130+
namespace: ops-system # <--- Install Namespace
131+
serviceAccount:
132+
name: monitor-operator-installer
133+
source:
134+
sourceType: Catalog
135+
catalog:
136+
packageName: monitor-operator
137+
config:
138+
configType: Inline
139+
inline:
140+
watchNamespace: dev-team-a # <--- MUST differ from Install Namespace
141+
```
142+
143+
#### Scenario C: The Modern "AllNamespaces" Operator
144+
* **Capability:** Only supports `AllNamespaces`.
145+
146+
```yaml
147+
apiVersion: olm.operatorframework.io/v1
148+
kind: ClusterExtension
149+
metadata:
150+
name: global-operator
151+
spec:
152+
namespace: operators
153+
# No config provided = Operator watches the entire cluster (AllNamespaces)
154+
serviceAccount:
155+
name: global-operator-installer
156+
source:
157+
sourceType: Catalog
158+
catalog:
159+
packageName: global-operator
160+
```
161+
162+
163+
## Troubleshooting Configuration Errors
164+
165+
OLM v1 validates your configuration against the bundle's schema before installation proceeds. If your configuration is invalid, the `ClusterExtension` will report a `Progressing` condition with an error message.
166+
167+
| Error Message Example | Cause | Solution |
168+
|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
169+
| `required field "watchNamespace" is missing` | The bundle does not support `AllNamespaces` default mode. | Add the `inline` block and specify a `watchNamespace`. |
170+
| `invalid value "X": watchNamespace must be "Y" (the namespace where the operator is installed) because this operator only supports OwnNamespace install mode` | You tried to set a different watch namespace for an `OwnNamespace`-only bundle. | Change `watchNamespace` to match `spec.namespace`. |
171+
| `invalid value "X": watchNamespace must be different from "Y" (the install namespace) because this operator uses SingleNamespace install mode to watch a different namespace` | You tried to set the watch namespace to the install namespace for a `SingleNamespace`-only bundle. | Change `watchNamespace` to a different target namespace. |
172+
| `unknown field "foo"` | You added extra fields to the inline config. | Remove fields other than `watchNamespace` (unless the bundle author explicitly documents extra schema support). |

0 commit comments

Comments
 (0)