docs: add single-tenant simplification design

joelanford · claude · joelanford · commit 734cbe282b2b · 2026-03-13T07:53:06.000-04:00
Add a design document proposing changes to re-affirm OLM v1's
single-tenant, cluster-admin-only operational model. The design
covers deprecating the service account field, removing
SingleNamespace/OwnNamespace install mode support, automating
namespace management, and simplifying the content manager.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/docs/draft/project/single-tenant-simplification.md b/docs/draft/project/single-tenant-simplification.md
diff --git a/docs/draft/project/single-tenant-simplification/01-cluster-admin.md b/docs/draft/project/single-tenant-simplification/01-cluster-admin.md
@@ -0,0 +1,55 @@
+# Work Item: Grant operator-controller cluster-admin
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** Nothing (first work item)
+
+## Summary
+
+Grant operator-controller's ServiceAccount `cluster-admin` privileges via its Helm-managed ClusterRoleBinding. This is a prerequisite for all other simplification work items: once operator-controller has cluster-admin, per-extension service account scoping becomes unnecessary.
+
+## Current RBAC architecture
+
+The Helm chart defines RBAC in `helm/olmv1/templates/rbac/clusterrole-operator-controller-manager-role.yml`. The ClusterRole is structured in two tiers, conditional on the `BoxcutterRuntime` feature gate:
+
+### When BoxcutterRuntime is NOT enabled (line 1)
+
+The entire ClusterRole is gated behind `{{- if and .Values.options.operatorController.enabled (not (has "BoxcutterRuntime" .Values.operatorConrollerFeatures)) }}`. It grants:
+
+- `serviceaccounts/token` create and `serviceaccounts` get — for per-CE SA impersonation
+- `customresourcedefinitions` get
+- `clustercatalogs` get/list/watch
+- `clusterextensions` get/list/patch/update/watch, plus finalizers and status updates
+- `clusterrolebindings`, `clusterroles`, `rolebindings`, `roles` list/watch — for `PreflightPermissions` RBAC validation
+- OpenShift SCC `use` (conditional on `.Values.options.openshift.enabled`)
+
+### When BoxcutterRuntime IS enabled (lines 81-113)
+
+Additional rules are appended within the same ClusterRole:
+
+- `*/*` list/watch — broad permissions needed for the Boxcutter tracking cache
+- `clusterextensionrevisions` full CRUD, status, and finalizers
+
+### When BoxcutterRuntime is enabled but the outer guard is false
+
+If BoxcutterRuntime is in `.Values.operatorConrollerFeatures`, the outer guard on line 1 is false, so the entire ClusterRole (including the Boxcutter-specific rules) is not rendered. This suggests the Boxcutter path uses a different RBAC mechanism or that there is a separate ClusterRole for that case.
+
+## Proposed changes
+
+### Helm RBAC
+
+- Replace the conditionally-scoped ClusterRole with a `cluster-admin` ClusterRoleBinding (binding operator-controller's ServiceAccount to the built-in `cluster-admin` ClusterRole).
+- Remove the conditional RBAC templating based on `BoxcutterRuntime`. With cluster-admin, the feature-gate-conditional rules are all subsumed.
+- Remove the `serviceaccounts/token` create and `serviceaccounts` get rules (no longer needed since operator-controller uses its own identity).
+- Remove the RBAC list/watch rules that existed for `PreflightPermissions` validation.
+- The OpenShift SCC `use` permission is also subsumed by cluster-admin.
+
+### Key files
+
+- `helm/olmv1/templates/rbac/clusterrole-operator-controller-manager-role.yml` — Replace with cluster-admin ClusterRoleBinding
+- Any other Helm RBAC templates that may need updating
+
+## Notes
+
+- There is a typo in the Helm template: `.Values.operatorConrollerFeatures` (missing "t" in "Controller"). This can be fixed as part of this work or separately.
+- The cluster-admin grant is intentionally broad. The security boundary shifts from "what can operator-controller do" to "who can create ClusterExtension/ClusterCatalog resources." See the [security analysis](../single-tenant-simplification.md#security-analysis) in the design doc.
diff --git a/docs/draft/project/single-tenant-simplification/02-deprecate-service-account.md b/docs/draft/project/single-tenant-simplification/02-deprecate-service-account.md
@@ -0,0 +1,57 @@
+# Work Item: Deprecate and ignore spec.serviceAccount
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** [01-cluster-admin](01-cluster-admin.md)
+
+## Summary
+
+Mark `ClusterExtension.spec.serviceAccount` as deprecated in the OpenAPI schema and make the controller ignore it. operator-controller uses its own ServiceAccount for all Kubernetes API interactions when managing ClusterExtension resources.
+
+## Scope
+
+- Mark `spec.serviceAccount` as deprecated in the CRD/OpenAPI schema.
+- Modify the controller to stop reading `spec.serviceAccount` and instead use operator-controller's own identity for all API calls.
+- The `RestConfigMapper` / `clientRestConfigMapper` plumbing in `cmd/operator-controller/main.go` that creates per-CE service account-scoped clients becomes unnecessary. The Helm `ActionConfigGetter` should use operator-controller's own config.
+- The field remains in the API for backward compatibility but is ignored.
+
+## Helm applier
+
+- The `RestConfigMapper` / `clientRestConfigMapper` plumbing in `cmd/operator-controller/main.go` that creates per-CE service account-scoped clients becomes unnecessary. The Helm `ActionConfigGetter` should use operator-controller's own config.
+
+## Boxcutter applier
+
+The Boxcutter applier reads `spec.serviceAccount` and propagates it through the revision lifecycle:
+
+- `applier/boxcutter.go:208-209` — `buildClusterExtensionRevision` writes `ServiceAccountNameKey` and `ServiceAccountNamespaceKey` annotations on `ClusterExtensionRevision` objects, sourced from `ext.Spec.ServiceAccount.Name` and `ext.Spec.Namespace`.
+- `controllers/revision_engine_factory.go:82-98` — `getServiceAccount` reads those annotations back from the CER.
+- `controllers/revision_engine_factory.go:101-122` — `createScopedClient` creates an anonymous REST config wrapped with `TokenInjectingRoundTripper` to impersonate the SA.
+- `controllers/revision_engine_factory.go:57-80` — `CreateRevisionEngine` passes the scoped client into the boxcutter `machinery.NewObjectEngine` and `machinery.NewRevisionEngine`.
+
+With single-tenant simplification:
+
+- Stop writing SA annotations on CERs.
+- `RevisionEngineFactory` uses operator-controller's own client directly instead of creating per-CER scoped clients. The factory struct fields `BaseConfig` and `TokenGetter` become unnecessary.
+- Remove `getServiceAccount` and `createScopedClient` from the factory.
+- Remove the `internal/operator-controller/authentication/` package (`TokenGetter` and `TokenInjectingRoundTripper`), which is only used for SA impersonation.
+- Remove `ServiceAccountNameKey` / `ServiceAccountNamespaceKey` label constants.
+
+Note: The Boxcutter `TrackingCache` (informers) is already shared across all CERs — no informer consolidation is needed. The per-CER isolation was only at the client level for SA scoping.
+
+## Key files
+
+- `api/v1/clusterextension_types.go` — Mark field deprecated
+- `cmd/operator-controller/main.go:697-708` — `clientRestConfigMapper` and Helm `ActionConfigGetter` setup
+- `internal/operator-controller/authentication/` — `TokenGetter` / `TokenInjectingRoundTripper` (remove entirely)
+- `internal/operator-controller/applier/boxcutter.go:208-209` — SA annotations written on CERs
+- `internal/operator-controller/controllers/revision_engine_factory.go` — Per-CER scoped client creation
+- `internal/operator-controller/labels/labels.go:29-41` — `ServiceAccountNameKey` / `ServiceAccountNamespaceKey` constants
+
+## Migration
+
+- Existing ClusterExtensions that specify `spec.serviceAccount` continue to function; the field is simply ignored.
+- Cluster-admins can clean up the ServiceAccount, ClusterRole, ClusterRoleBinding, Role, and RoleBinding resources they previously created at their convenience.
+
+## Notes
+
+- Full removal of `spec.serviceAccount` from the API happens in a future API version (Phase 2 in the design doc).
diff --git a/docs/draft/project/single-tenant-simplification/03-remove-preflight-permissions.md b/docs/draft/project/single-tenant-simplification/03-remove-preflight-permissions.md
@@ -0,0 +1,59 @@
+# Work Item: Remove PreflightPermissions feature gate and code
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** Nothing (independent)
+
+## Summary
+
+Remove the `PreflightPermissions` feature gate (currently Alpha, default off) and all associated RBAC pre-authorization code. This also enables removing the `k8s.io/kubernetes` dependency from `go.mod`, along with 30 `replace` directives that exist solely to align `k8s.io/kubernetes` sub-module versions.
+
+## Scope
+
+### Remove feature gate and code
+
+- Remove the `PreflightPermissions` feature gate definition from `internal/operator-controller/features/features.go:26-30`.
+- Remove the `internal/operator-controller/authorization/` package entirely. This package contains the `PreAuthorizer` interface and the RBAC-based implementation that validates user permissions before applying manifests.
+- Remove the `PreAuthorizer` field from the Boxcutter applier (`internal/operator-controller/applier/boxcutter.go:421`).
+- Remove the conditional `PreAuthorizer` setup in `cmd/operator-controller/main.go:722-725`.
+- Remove related tests (`internal/operator-controller/authorization/rbac_test.go`).
+
+### Remove `k8s.io/kubernetes` dependency
+
+The `authorization/rbac.go` imports four packages from `k8s.io/kubernetes` (lines 28-32):
+
+- `k8s.io/kubernetes/pkg/apis/rbac`
+- `k8s.io/kubernetes/pkg/apis/rbac/v1`
+- `k8s.io/kubernetes/pkg/registry/rbac`
+- `k8s.io/kubernetes/pkg/registry/rbac/validation`
+- `k8s.io/kubernetes/plugin/pkg/auth/authorizer/rbac`
+
+These are the **only** imports of `k8s.io/kubernetes` in the entire codebase. Removing the authorization package enables:
+
+- Removing `k8s.io/kubernetes v1.35.0` from `go.mod` (line 46).
+- Removing all 30 `replace` directives (lines 260-319) that exist to align `k8s.io/kubernetes` sub-module versions (`k8s.io/api`, `k8s.io/apiextensions-apiserver`, `k8s.io/apimachinery`, `k8s.io/apiserver`, `k8s.io/cli-runtime`, `k8s.io/client-go`, `k8s.io/cloud-provider`, `k8s.io/cluster-bootstrap`, etc.).
+- Running `go mod tidy` to clean up any transitive dependencies that were only pulled in by `k8s.io/kubernetes`.
+
+### Remove k8s-pin tooling
+
+The `hack/tools/k8smaintainer/` program (invoked via `make k8s-pin`) exists to generate and maintain the `k8s.io/*` `replace` directives in `go.mod`. It reads the `k8s.io/kubernetes` version, enumerates all `k8s.io/*` staging modules in the dependency graph, and pins them to matching versions. The `make verify` target runs `k8s-pin` as a prerequisite.
+
+With `k8s.io/kubernetes` removed from `go.mod`, this tool has nothing to do — the remaining `k8s.io/*` dependencies (`k8s.io/api`, `k8s.io/client-go`, etc.) are used directly and managed normally by `go mod tidy` without `replace` directives.
+
+- Remove `hack/tools/k8smaintainer/` (including `main.go` and `README.md`).
+- Remove the `k8s-pin` Makefile target and its invocation in the `verify` target (replace with just `tidy`).
+
+### Remove RBAC list/watch permissions
+
+With `PreflightPermissions` removed, operator-controller no longer needs the `clusterrolebindings`, `clusterroles`, `rolebindings`, `roles` list/watch permissions in the Helm ClusterRole. These can be removed as part of [01-cluster-admin](01-cluster-admin.md) or this work item.
+
+## Key files
+
+- `internal/operator-controller/authorization/rbac.go` — Only consumer of `k8s.io/kubernetes`
+- `internal/operator-controller/authorization/rbac_test.go` — Tests
+- `internal/operator-controller/features/features.go` — Feature gate definition
+- `internal/operator-controller/applier/boxcutter.go` — `PreAuthorizer` field
+- `cmd/operator-controller/main.go` — Conditional setup
+- `go.mod` — `k8s.io/kubernetes` dependency and replace directives
+- `hack/tools/k8smaintainer/` — `k8s-pin` tool that generates replace directives
+- `Makefile` — `k8s-pin` target (line 157) and its use in `verify` (line 205)
diff --git a/docs/draft/project/single-tenant-simplification/04-remove-synthetic-permissions.md b/docs/draft/project/single-tenant-simplification/04-remove-synthetic-permissions.md
@@ -0,0 +1,21 @@
+# Work Item: Remove SyntheticPermissions feature gate and code
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** Nothing (independent)
+
+## Summary
+
+Remove the `SyntheticPermissions` feature gate (currently Alpha, default off) and all associated synthetic user permission model code.
+
+## Scope
+
+- Remove the `SyntheticPermissions` feature gate definition.
+- Remove the synthetic user REST config mapper and related code.
+- Remove related tests.
+
+## Key files
+
+- `internal/operator-controller/features/` - Feature gate definitions
+- `cmd/operator-controller/main.go:698-699` - Conditional wrapping with `SyntheticUserRestConfigMapper`
+- Any code implementing the synthetic permissions model
diff --git a/docs/draft/project/single-tenant-simplification/05-remove-single-own-namespace.md b/docs/draft/project/single-tenant-simplification/05-remove-single-own-namespace.md
@@ -0,0 +1,40 @@
+# Work Item: Remove SingleNamespace/OwnNamespace install mode support
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** Nothing (independent)
+
+## Summary
+
+Remove the `SingleOwnNamespaceInstallSupport` feature gate (currently GA, default on) and all associated code. Operators are always installed in AllNamespaces mode. The `watchNamespace` configuration option is removed from the bundle config schema.
+
+## Scope
+
+### Remove feature gate
+
+- Remove the `SingleOwnNamespaceInstallSupport` feature gate definition from `internal/operator-controller/features/features.go:35-39`.
+- Remove all references to `IsSingleOwnNamespaceEnabled` / `SingleOwnNamespaceInstallSupport` throughout the codebase.
+
+### Remove watchNamespace from the config schema
+
+- Remove the `watchNamespace` property from the bundle config JSON schema (`internal/operator-controller/rukpak/bundle/registryv1bundleconfig.json`).
+- Remove `GetWatchNamespace()` from `internal/operator-controller/config/config.go:88-106`.
+- Remove the conditional block in `internal/operator-controller/applier/provider.go:73-79` that extracts `watchNamespace` and passes it to the renderer via `render.WithTargetNamespaces()`.
+- Remove related tests in `internal/operator-controller/config/config_test.go` and `internal/operator-controller/applier/provider_test.go`.
+
+With `watchNamespace` removed from the schema, any ClusterExtension that specifies `spec.config.inline.watchNamespace` will fail schema validation automatically — no explicit validation error needs to be added.
+
+### Update install mode handling
+
+- If a CSV only declares support for `SingleNamespace` and/or `OwnNamespace` (and not `AllNamespaces`), OLM v1 installs it in AllNamespaces mode anyway. OLM v1 takes the position that watching all namespaces is always correct for a cluster-scoped controller installation.
+- Remove the `render.WithTargetNamespaces()` option and related rendering logic that generates namespace-scoped configurations.
+
+## Key files
+
+- `internal/operator-controller/features/features.go` — Feature gate definition
+- `internal/operator-controller/config/config.go` — `GetWatchNamespace()` method
+- `internal/operator-controller/applier/provider.go` — Conditional `IsSingleOwnNamespaceEnabled` block
+- `internal/operator-controller/rukpak/bundle/registryv1bundleconfig.json` — Bundle config schema
+- `internal/operator-controller/rukpak/bundle/registryv1.go` — Bundle config schema handling
+- `hack/tools/schema-generator/main.go` — Schema generator
+- `docs/draft/howto/single-ownnamespace-install.md` — To be archived/removed (see [09-documentation](09-documentation.md))
diff --git a/docs/draft/project/single-tenant-simplification/06-optional-namespace.md b/docs/draft/project/single-tenant-simplification/06-optional-namespace.md
@@ -0,0 +1,68 @@
+# Work Item: Make spec.namespace optional with automatic namespace management
+
+**Parent:** [Single-Tenant Simplification](../single-tenant-simplification.md)
+**Status:** Not started
+**Depends on:** [02-deprecate-service-account](02-deprecate-service-account.md)
+
+## Summary
+
+Change `ClusterExtension.spec.namespace` from required to optional. When not specified, operator-controller determines the installation namespace automatically using CSV annotations or a fallback convention. The installation namespace becomes a managed object of the ClusterExtension.
+
+## Namespace determination precedence
+
+operator-controller determines the installation namespace using the following precedence (highest to lowest):
+
+1. **`ClusterExtension.spec.namespace`** — If specified by the user, this is the namespace name used.
+2. **`operatorframework.io/suggested-namespace` CSV annotation** — If the CSV provides a suggested namespace name, it is used.
+3. **`operatorframework.io/suggested-namespace-template` CSV annotation** — If the CSV provides a namespace template (a full JSON Namespace object), its `metadata.name` is used.
+4. **`<packageName>-system` fallback** — If none of the above are present, operator-controller generates a namespace name from the package name. If `<packageName>-system` exceeds the maximum namespace name length, `<packageName>` is used instead.
+
+## Namespace body/template
+
+- If the CSV contains the `operatorframework.io/suggested-namespace-template` annotation, its value (a full JSON Namespace object) is used as the template for creating the namespace. This allows bundle authors to specify labels, annotations, and other namespace metadata.
+- If `spec.namespace` or `suggested-namespace` specifies a different name than what appears in the template, the template body is still used but with the name overridden.
+- If no template annotation is present, operator-controller creates a plain namespace with the determined name.
+
+### Behavior when both annotations are present
+
+When a CSV defines both `operatorframework.io/suggested-namespace` and `operatorframework.io/suggested-namespace-template`:
+
+- The **name** comes from `suggested-namespace` (unless overridden by `spec.namespace`).
+- The **body** (labels, annotations, other metadata) comes from `suggested-namespace-template`.
+- If the template's `metadata.name` differs from the name determined by `suggested-namespace`, the template's name is overridden.
+
+In other words, `suggested-namespace` controls naming and `suggested-namespace-template` controls the namespace shape. When both are present, the name from `suggested-namespace` takes precedence over any name embedded in the template.
+
+## Namespace lifecycle
+
+- The installation namespace is a **managed object** of the ClusterExtension. It follows the same ownership rules as all other managed objects:
+  - It is created by operator-controller if it does not exist.
+  - A pre-existing namespace results in a conflict error, consistent with the [single-owner objects](../../concepts/single-owner-objects.md) design.
+  - It is deleted when the ClusterExtension is deleted (along with all other managed objects).
+- The immutability constraint on `spec.namespace` is retained — once set (explicitly or by auto-determination), the namespace cannot be changed.
+
+## Migration
+
+- Existing ClusterExtensions that specify `spec.namespace` continue to function identically.
+- For existing installations where the namespace was manually created before the ClusterExtension, operator-controller should adopt the namespace during the migration period (one-time reconciliation to add ownership metadata). The pre-existence error applies only to new installations going forward.
+
+## Scope
+
+### API changes
+
+- Mark `spec.namespace` as optional in `api/v1/clusterextension_types.go` (remove the `required` validation or make the field a pointer).
+- Update CRD/OpenAPI schema generation.
+
+### Controller changes
+
+- Add namespace determination logic implementing the precedence rules above.
+- Add namespace creation/management as a reconciliation step (likely a new `ReconcileStepFunc` in `internal/operator-controller/controllers/clusterextension_reconcile_steps.go`).
+- Read `operatorframework.io/suggested-namespace` and `operatorframework.io/suggested-namespace-template` from the resolved CSV.
+- Handle the migration path: adopt pre-existing namespaces for existing installations.
+
+### Key files
+
+- `api/v1/clusterextension_types.go` — Make `Namespace` optional
+- `internal/operator-controller/controllers/clusterextension_reconcile_steps.go` — New namespace management step
+- `internal/operator-controller/controllers/clusterextension_controller.go` — Integration
+- CSV annotation reading (location TBD based on where bundle metadata is accessed)
diff --git a/docs/draft/project/single-tenant-simplification/07-simplify-contentmanager.md b/docs/draft/project/single-tenant-simplification/07-simplify-contentmanager.md
diff --git a/docs/draft/project/single-tenant-simplification/09-documentation.md b/docs/draft/project/single-tenant-simplification/09-documentation.md
