Skip to content

Commit 058e705

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 058e705

File tree

1 file changed

+166
-0
lines changed

1 file changed

+166
-0
lines changed

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

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
## Description
2+
3+
!!! note
4+
This feature is still in *alpha* 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`) 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+
config:
132+
configType: Inline
133+
inline:
134+
watchNamespace: dev-team-a # <--- MUST differ from Install Namespace
135+
```
136+
137+
#### Scenario C: The Modern "AllNamespaces" Operator
138+
* **Capability:** Supports `AllNamespaces`.
139+
* **Requirement:** Works cluster-wide by default, but you want to restrict it to a single namespace for security or resource reasons.
140+
* **Config:** `watchNamespace` is optional. Adding it restricts the operator.
141+
142+
```yaml
143+
apiVersion: olm.operatorframework.io/v1
144+
kind: ClusterExtension
145+
metadata:
146+
name: global-operator
147+
spec:
148+
namespace: operators
149+
# No config provided = Operator watches the entire cluster (AllNamespaces)
150+
# OR provide config below to restrict it:
151+
config:
152+
configType: Inline
153+
inline:
154+
watchNamespace: specific-target-ns
155+
```
156+
157+
## Troubleshooting Configuration Errors
158+
159+
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.
160+
161+
| Error Message Example | Cause | Solution |
162+
|:------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------|
163+
| `invalid bundle configuration: missing required key 'watchNamespace'` | The bundle does not support `AllNamespaces` default mode. | Add the `inline` block and specify a `watchNamespace`. |
164+
| `invalid bundle configuration: value must be the install namespace` | You tried to set a different watch namespace for an `OwnNamespace`-only bundle. | Change `watchNamespace` to match `spec.namespace`. |
165+
| `invalid bundle configuration: value must not be the install namespace` | You tried to set the watch namespace to the install namespace for a `SingleNamespace`-only bundle. | Change `watchNamespace` to a different target namespace. |
166+
| `invalid bundle configuration: unknown key '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)