Expose freeform service configuration on the ControlPlane

[berendt]

Category: feature | Scope: Large

Description

The ControlPlane exposes a curated subset of each service's settings and no freeform configuration. This issue adds a global INI block spec.globalExtraConfig and per-service blocks spec.services.keystone.extraConfig, spec.services.glance.extraConfig, and spec.services.horizon.extraConfig, merges the INI blocks key by key with the per-service block winning, projects the result onto the child resources, and runs the two checks the sibling issues built — the per-release option catalog and the owned-key registry — against the merged result at ControlPlane admission. Every rejection and warning names the block that contributed the offending key, so a platform operator edits the file that actually carries it.

Three decisions were settled with the author during elaboration and are binding for this plan:

1. Merge semantics are key by key. Sections are unioned; within a section the per-service value wins per key, and global keys without a per-service counterpart stay effective. This matches policy.MergePolicies (internal/common/policy/policy.go:90), which merges the Rules map the same way. A per-service section never replaces a whole global section.
2. Horizon is in scope, as a per-service block only. Horizon carries flat Django settings (map[string]apiextensionsv1.JSON, operators/horizon/api/v1alpha1/horizon_types.go:243), not INI, so the global INI block never applies to it and no merge happens: the block is projected verbatim. Horizon has an ownership registry but no option catalog (settled in the Meta Issue), so it gets the ownership check only.
3. The ControlPlane webhook imports the service api packages directly (operators/keystone/api/v1alpha1, operators/glance/api/v1alpha1, operators/horizon/api/v1alpha1) to reach the embedded catalogs and ownership registries. This contradicts the recorded L1 import rule in the DECISION comment at operators/c5c3/api/v1alpha1/controlplane_types.go:182-195 ("the L1 api package imports ONLY commonv1, k8s.io/apimachinery/, k8s.io/api/core/v1, and sigs.k8s.io/controller-runtime/"); that comment must be amended in this change to record the new rule and its rationale — the module dependency has existed since the L2 reconciler landed (operators/c5c3/go.mod requires all three service modules), so only package-level purity is given up, and the catalogs stay single-source instead of being duplicated.

1. API fields

Already exists: ControlPlaneSpec.GlobalPolicyOverrides with per-service precedence on ServiceKeystoneSpec.PolicyOverrides (operators/c5c3/api/v1alpha1/controlplane_types.go:110 and :250) is the naming and precedence template. The child CRs already carry the target fields: ExtraConfig map[string]map[string]string on Keystone (operators/keystone/api/v1alpha1/keystone_types.go:212) and Glance (operators/glance/api/v1alpha1/glance_types.go:188), ExtraConfig map[string]apiextensionsv1.JSON on Horizon (operators/horizon/api/v1alpha1/horizon_types.go:243).

This issue adds, in controlplane_types.go:

• GlobalExtraConfig map[string]map[string]string (JSON globalExtraConfig) on ControlPlaneSpec, placed next to GlobalPolicyOverrides. Godoc states: applies to every INI-configured service the ControlPlane declares (Keystone and Glance today), key-by-key merge, per-service block wins per key, never applies to Horizon.
• ExtraConfig map[string]map[string]string (JSON extraConfig) on ServiceKeystoneSpec and on ServiceGlanceSpec.
• ExtraConfig map[string]apiextensionsv1.JSON (JSON extraConfig) on ServiceHorizonSpec, mirroring the Horizon child's field shape (the c5c3 api package gains a direct import of k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1, already an indirect dependency in operators/c5c3/go.mod).
• One CEL rule appended to the ServiceKeystoneSpec XValidation block (controlplane_types.go:206-217): extraConfig is forbidden when mode is External, message "services.keystone.extraConfig is forbidden when services.keystone.mode is External". Glance and Horizon need no rule: services.glance and services.horizon are already forbidden whole in External mode (operators/c5c3/api/v1alpha1/controlplane_webhook.go:1905-1909). globalExtraConfig stays legal in External mode and applies to nothing — the same posture globalPolicyOverrides already has.
• The amended DECISION comment from binding decision 3.

2. Merge helper

Already exists: config.MergeDefaults(userConfig, defaults) (internal/common/config/config.go:111) merges two INI maps key by key, user values winning, into a fresh map without mutating its inputs — exactly the decided semantics with userConfig = per-service block and defaults = global block.

This issue adds: an exported helper MergedExtraConfig(global, service map[string]map[string]string) map[string]map[string]string in a new file operators/c5c3/api/v1alpha1/controlplane_extraconfig.go. It returns config.MergeDefaults(service, global), normalized to nil when the result has length zero, so an empty merge projects an absent field rather than an empty map. It lives in the api package because both the reconciler and the validating webhook must call the same function — validating one merge and projecting another is the drift this issue exists to prevent.

3. Projection onto the children

Already exists: the Keystone projection computes policy.MergePolicies(cp.Spec.GlobalPolicyOverrides, cp.Spec.Services.Keystone.PolicyOverrides) and assigns it (operators/c5c3/internal/controller/reconcile_keystone.go:238 and :307); the Glance child spec is built in operators/c5c3/internal/controller/reconcile_glance.go:377-449; the Horizon child is mutated in a create-or-update closure (operators/c5c3/internal/controller/reconcile_horizon.go:242-262). None of the three assigns ExtraConfig today.

This issue adds one unconditional assignment per projection, following the existing convention that clearing a ControlPlane field must revert the child rather than pin the old value (the replicas comment at reconcile_horizon.go:244-250 states the rule):

• reconcile_keystone.go: keystone.Spec.ExtraConfig = c5c3v1alpha1.MergedExtraConfig(cp.Spec.GlobalExtraConfig, cp.Spec.Services.Keystone.ExtraConfig), next to the policy assignment at :307.
• reconcile_glance.go: glance.Spec.ExtraConfig = c5c3v1alpha1.MergedExtraConfig(cp.Spec.GlobalExtraConfig, cp.Spec.Services.Glance.ExtraConfig), next to glance.Spec.OpenStackRelease at :403.
• reconcile_horizon.go: inside the mutate closure, assign a deep copy of cp.Spec.Services.Horizon.ExtraConfig (copy the map and DeepCopy() each apiextensionsv1.JSON value so the child never aliases cp.Spec; nil when the source is nil or empty).

Because MergedExtraConfig yields nil when both blocks are empty, the SSA-applied Keystone/Glance intent then carries no extraConfig field and a value set directly on the child stays unowned — the same behavior PolicyOverrides has today. Once a ControlPlane block is set, the projection owns the field and direct child edits are reverted on the next reconcile.

4. Admission checks in the ControlPlane webhook

Already exists: the shared check module internal/common/config — LookupCatalog (catalog.go:89), CatalogExemptions (catalog.go:109), KeyExemptionsFromRegistry (catalog.go:119), FindUnknownOptions (catalog.go:163), FindOwnedOverrides (ownership.go:57), FindOwnedSettingOverrides (ownership.go:80) — plus the per-service data: Keystone OwnedConfigKeys (operators/keystone/api/v1alpha1/config_ownership.go:33) and OptionCatalogForRelease keyed by image tag (operators/keystone/api/v1alpha1/option_catalog.go:30); Glance OwnedConfigKeys (operators/glance/api/v1alpha1/config_ownership.go:34), CatalogExemptSections (operators/glance/api/v1alpha1/option_catalog.go:33), and OptionCatalogForRelease keyed by spec.openStackRelease (option_catalog.go:38); Horizon OwnedConfigKeys (operators/horizon/api/v1alpha1/config_ownership.go:40), WebSSOSettingNames / MultiDomainSettingNames (operators/horizon/api/v1alpha1/horizon_types.go:93 and :101), and the Python-identifier pattern pythonSettingName (operators/horizon/api/v1alpha1/horizon_webhook.go:31). The ControlPlane webhook entry points are ValidateCreate (controlplane_webhook.go:1199), ValidateUpdate (:1223), and the accumulated validate (:1246).

This issue adds two validation families in controlplane_extraconfig.go, wired into the webhook, plus one small export: rename pythonSettingName to PythonSettingName in the horizon api package (update its two uses in horizon_webhook.go) so the ControlPlane webhook shares the pattern instead of copying it.

Family A — shape and ownership, un-gated (validateExtraConfigOwnership(cp *ControlPlane) (admission.Warnings, field.ErrorList)), runs on every create and every update, mirroring the child webhooks, which run their rejected-key checks un-gated:

• Reject an empty section name or empty option key in any of the three INI blocks (mirror of operators/glance/api/v1alpha1/glance_webhook.go:433-455; the CRD schema cannot constrain map keys).
• Reject an empty or non-PythonSettingName setting name in services.horizon.extraConfig (mirror of horizon_webhook.go:241-257) — without this, the Horizon child webhook rejects the projection and the ControlPlane wedges in HorizonProjectionRejected.
• Reject Rejected-flagged owned keys on the merged per-service result, with field.Forbidden at every contributing block's path:
  • Glance [keystone_authtoken] password: always (the child rejects it unconditionally, glance_webhook.go:457-475).
  • Keystone [federation] trusted_dashboard: only when the ControlPlane will project a non-empty trusted-dashboards list — the child gates this rejection on the typed list being non-empty (operators/keystone/api/v1alpha1/keystone_webhook.go:867-869 and :892-907), and the projection fills it from the Horizon block (reconcile_keystone.go:372-378). To share the derivation, move the body of horizonPublicEndpoint (operators/c5c3/internal/controller/identity_backends.go:162-173) into a new method func (s *ServiceHorizonSpec) DerivedPublicEndpoint() string in the api package and make horizonPublicEndpoint delegate to it. The rejection fires exactly when cp.Spec.Services.Horizon.DerivedPublicEndpoint() != ""; with no Horizon block the key stays admissible (an externally-run dashboard doing WebSSO against the managed Keystone is a legitimate use), surfacing only as an owned-key warning.
  • Horizon SECRET_KEY, every WebSSOSettingNames entry, and every MultiDomainSettingNames entry: always. This is deliberately stricter than the child, which gates the websso/multiDomain collisions on the typed blocks being present (horizon_webhook.go:506, :606-620): the ControlPlane projects spec.websso/spec.multiDomain dynamically from attached identity backends (reconcile_horizon.go:261-262), so whether the collision materializes is not decidable at admission, and admitting the key would plant a runtime HorizonProjectionRejected wedge. The message says the settings are owned by the ControlPlane's identity-backend projection.
• Emit one admission warning per Reported (non-Rejected) owned key found on the merged result via FindOwnedOverrides (Keystone/Glance registries) and FindOwnedSettingOverrides (Horizon registry), naming the key, the owning source (OwnedBy), the Impact when set, and the contributing block path(s). Warnings, not errors: the sibling issue settled that owned-key overrides are honored and surfaced, and the child's ExtraConfigHealthy condition still reports them after projection. An OwnedKey that is exempt at the service level (Keystone [cache] enabled, Horizon OPENSTACK_ENDPOINT_TYPE / SECURE_PROXY_SSL_HEADER) is absent from the registries, so it stays silent here too — no new list is introduced.

Family B — option catalog, gated on update (validateExtraConfigCatalogs(cp *ControlPlane) (admission.Warnings, field.ErrorList)), runs always on create, and on update only when controlPlaneExtraConfigCatalogInputsChanged(oldObj, newObj) reports a change — mirroring the child rule that a stale-invalid resource must not be rejected by an unrelated update (keystone_webhook.go:1032-1058). Inputs: globalExtraConfig, services.keystone.extraConfig, services.glance.extraConfig, openStackRelease, services.keystone.image, and the presence of the services.keystone / services.glance blocks (compared with reflect.DeepEqual where maps are involved).

Per declared INI service — Keystone when services.keystone is set and mode is not External, Glance when services.glance is set — the check computes MergedExtraConfig(global, service) and validates it:

• Catalog resolution: Keystone via keystonev1alpha1.OptionCatalogForRelease(tag) where tag is services.keystone.image.Tag when the image override is set, else spec.openStackRelease (the same resolution the projection applies, reconcile_keystone.go:185-193); Glance via glancev1alpha1.OptionCatalogForRelease(cp.Spec.OpenStackRelease) (the projection copies exactly that value onto the child, reconcile_glance.go:403).
• Fail open: when no catalog resolves (digest-pinned or unparseable Keystone image tag, or a build embedding no catalog for the release), return exactly one warning per affected service and no error, with the two message variants of keystone_webhook.go:960-977 adapted to name the ControlPlane field.
• Exemptions: Keystone gets CatalogExemptions{Keys: KeyExemptionsFromRegistry(keystonev1alpha1.OwnedConfigKeys)} and no plugin sections — the projection never sets spec.plugins on the child, so there are none to exempt; Glance gets Sections from glancev1alpha1.CatalogExemptSections plus Keys from its registry.
• Each UnknownOption becomes field.Invalid naming the service and release catalog (for example no such option in the glance 2026.1 option catalog); the unknown-section variant must not repeat the child's "declare via spec.plugins" hint (keystone_webhook.go:1000-1001) — the ControlPlane has no plugins field, so the message says plugin-registered sections are not configurable through the ControlPlane. Each DeprecatedOption becomes a warning naming the replacement, as in keystone_webhook.go:1008-1021.
• Provenance: findings are computed once on the merged map, then attributed by membership — a finding at (section, key) produces one error (or one warning mention) per block that contains that pair, anchored at the real field path: spec.globalExtraConfig[<section>][<key>] and/or spec.services.<svc>.extraConfig[<section>][<key>]. A key present in both blocks therefore yields two errors, one per path. Because the global block reaches every declared INI service, a global key must be valid in every declared service's catalog: a Keystone-only option in globalExtraConfig is rejected while services.glance is declared, the error path pointing at spec.globalExtraConfig and the message naming the Glance catalog — moving the key to services.keystone.extraConfig is the fix the message implies.

Wiring: both families are called from ValidateCreate and ValidateUpdate directly — not from validate (controlplane_webhook.go:1246), whose signature returns no warnings. This mirrors the keystone webhook, whose ValidateCreate computes the catalog warnings and errors itself and folds the errors in alongside validate's (keystone_webhook.go:231-232). Both entry points append the families' warnings to the existing insecurePublicEndpointWarnings result and fold the families' error lists together with w.validate(cp)'s into the single newInvalidIfErrs response; ValidateUpdate additionally passes oldObj into the Family B gate. validateKeystoneMode's External-mode forbidden-field list (controlplane_webhook.go:1856-1898) gains the extraConfig mirror of the new CEL rule.

5. Generated artifacts, docs, and tests

Already exists: CRD generation via make manifests into operators/c5c3/config/crd/bases/c5c3.io_controlplanes.yaml, the Helm copy via make sync-crds guarded by make verify-crd-sync (Makefile), deepcopy via make generate; the invalid-CR e2e suite generated from tests/e2e/c5c3/invalid-cr/_generate.py with chainsaw-test.yaml assertions and the make verify-invalid-cr-fixtures gate; webhook unit tests in operators/c5c3/api/v1alpha1/controlplane_webhook_test.go; controller tests in operators/c5c3/internal/controller/reconcile_{keystone,glance,horizon}_test.go; the freeform-configuration guide docs/guides/advanced-configuration.md (its ExtraConfig section currently lives under "Standalone Keystone, without a ControlPlane") and the CRD reference docs/reference/c5c3/controlplane-crd.md.

This issue adds: regenerated deepcopy/CRD/Helm artifacts; new invalid-CR fixtures (global unknown option, per-service unknown option, External-mode extraConfig, Horizon SECRET_KEY) added to _generate.py's FIXTURES with matching chainsaw-test.yaml steps and test_generate.py expectations; webhook unit tests and controller projection tests per the acceptance criteria; a ControlPlane section in docs/guides/advanced-configuration.md documenting both block levels, the key-by-key merge, the Horizon special case, and the provenance in rejection messages; and the four new fields in docs/reference/c5c3/controlplane-crd.md. Docs must carry no issue references (repo rule, enforced style).

One known limitation belongs in the guide text: the catalogs consulted at ControlPlane admission are the ones embedded in the c5c3-operator build. A deployed service operator of a different build may embed a different catalog; the child webhook remains defense-in-depth for that skew, and a skewed rejection surfaces as KeystoneProjectionRejected / GlanceProjectionRejected on the ControlPlane's conditions.

Motivation

A platform operator running the ControlPlane through GitOps cannot set a single service configuration option today. The freeform field exists only on the child resources, and a direct child edit does not stick once the ControlPlane owns the field — the remaining route is a forge change and a release cycle for what upstream treats as day-to-day tuning.

The two checks the sibling issues delivered — admission-time option validation and the owned-key registry — currently protect only whoever edits service CRs by hand. The ControlPlane is the surface a GitOps deployment actually manages, so until the blocks exist there and the checks run there, that work is invisible to its primary audience. Running the checks against the merged result at ControlPlane admission also closes the failure mode the Meta Issue names: without it, a bad ControlPlane is accepted on submission and fails later during projection, as a child-webhook rejection wedged into a status condition that names a resource the operator never wrote.

Provenance is what keeps two block levels usable. A rejection that names only [DEFAULT] verbose_typo leaves the operator searching the global block and up to three per-service blocks across their GitOps repository; a rejection anchored at spec.globalExtraConfig[DEFAULT][verbose_typo] is fixed in one edit.

User Stories

• As a platform operator, I want to set an oslo option once for every service and override it for one service, so that routine tuning lands through GitOps without a forge release.
  • Setting [database] connection_recycle_time in globalExtraConfig on a ControlPlane declaring Keystone and Glance renders that option into both children's spec.extraConfig.
  • Adding the same key with a different value under services.glance.extraConfig changes only the Glance child's rendered value; the Keystone child keeps the global value.
• As a platform operator, I want a rejected ControlPlane to name the block and key that failed, so that I edit the right file on the first attempt.
  • A typo in the global block is rejected with an error path starting spec.globalExtraConfig; the same typo in a per-service block is rejected with an error path starting spec.services.<svc>.extraConfig.
• As a platform operator, I want to set a Django setting for the dashboard, so that Horizon behavior (for example SESSION_TIMEOUT) is configurable without editing the Horizon CR.
  • A services.horizon.extraConfig entry appears verbatim in the Horizon child's spec.extraConfig and in the rendered local_settings.py.

Affected Areas

• operators/c5c3/api/v1alpha1/controlplane_types.go (four new spec fields, one new CEL rule on ServiceKeystoneSpec, amended L1-import DECISION comment)
• operators/c5c3/api/v1alpha1/controlplane_extraconfig.go (new: MergedExtraConfig, validateExtraConfigOwnership, validateExtraConfigCatalogs, controlPlaneExtraConfigCatalogInputsChanged, DerivedPublicEndpoint)
• operators/c5c3/api/v1alpha1/controlplane_webhook.go (wire both families into validate/ValidateCreate/ValidateUpdate, extend validateKeystoneMode's External-mode list)
• operators/c5c3/api/v1alpha1/controlplane_webhook_test.go (unit tests for all admission criteria below)
• operators/c5c3/api/v1alpha1/zz_generated.deepcopy.go (regenerated)
• operators/c5c3/config/crd/bases/c5c3.io_controlplanes.yaml, operators/c5c3/helm/c5c3-operator/crds/c5c3.io_controlplanes.yaml (regenerated via make manifests sync-crds)
• operators/c5c3/go.mod (k8s.io/apiextensions-apiserver moves from indirect to direct via go mod tidy)
• operators/c5c3/internal/controller/reconcile_keystone.go, reconcile_glance.go, reconcile_horizon.go (one ExtraConfig projection each)
• operators/c5c3/internal/controller/identity_backends.go (horizonPublicEndpoint delegates to the new DerivedPublicEndpoint method)
• operators/c5c3/internal/controller/reconcile_keystone_test.go, reconcile_glance_test.go, reconcile_horizon_test.go (projection assertions)
• operators/horizon/api/v1alpha1/horizon_webhook.go (export pythonSettingName as PythonSettingName, update its uses)
• tests/e2e/c5c3/invalid-cr/_generate.py, chainsaw-test.yaml, test_generate.py, plus the generated fixture files (four new rejection fixtures)
• docs/guides/advanced-configuration.md (ControlPlane freeform-configuration section)
• docs/reference/c5c3/controlplane-crd.md (the four new fields)

Acceptance Criteria

API and generated artifacts:

• Add globalExtraConfig, services.keystone.extraConfig, services.glance.extraConfig (each map[string]map[string]string), and services.horizon.extraConfig (map[string]apiextensionsv1.JSON) to the ControlPlane spec; kubectl explain the regenerated CRD shows all four.
• Add the CEL rule forbidding services.keystone.extraConfig in External mode; applying such a CR against the CRD alone (webhook absent) is rejected with the rule's message.
• Amend the DECISION comment at controlplane_types.go:182-195 to record that the api package imports the three service api packages for catalogs and registries.
• Run make generate manifests sync-crds; make verify-crd-sync passes.

Merge helper (MergedExtraConfig):

• Return the per-service value for a key present in both blocks, and keep global keys with no per-service counterpart.
• Return nil when both inputs are nil.
• Return nil when both inputs are empty non-nil maps.
• Return an independent copy when exactly one input is set — mutating the result never mutates cp.Spec.

Projection:

• Project the merged result onto the Keystone child's spec.extraConfig and the Glance child's spec.extraConfig; controller tests assert the merged content for a ControlPlane with both blocks set.
• Project services.horizon.extraConfig verbatim (deep-copied) onto the Horizon child's spec.extraConfig.
• Assign unconditionally: clearing every ControlPlane block projects nil and the child's field reverts; controller tests cover the set-then-cleared transition for all three children.

Webhook rejections (unit-tested in controlplane_webhook_test.go, each asserting the error's field path):

• Reject an unknown option in globalExtraConfig with only Keystone declared, at path spec.globalExtraConfig[<section>][<key>], message naming the keystone catalog and release.
• Reject a Keystone-only option in globalExtraConfig when services.glance is also declared, at the spec.globalExtraConfig path, message naming the glance catalog.
• Reject an unknown option in services.glance.extraConfig at path spec.services.glance.extraConfig[<section>][<key>].
• Reject a key that is unknown and present in both blocks with two errors, one per contributing path.
• Reject an unknown section without the child's "declare via spec.plugins" hint; the message states plugin-registered sections are not configurable through the ControlPlane.
• Accept a valid option present in both blocks, and accept a whole valid ControlPlane with all four blocks populated (the acceptance base case).
• Reject [keystone_authtoken] password in either INI block whenever services.glance is declared, regardless of any other field.
• Reject [federation] trusted_dashboard in the merged Keystone result when services.horizon carries a publicEndpoint or a gateway hostname; accept it (with an owned-key warning) when services.horizon is absent.
• Reject Horizon SECRET_KEY, any WebSSOSettingNames entry, and any MultiDomainSettingNames entry in services.horizon.extraConfig unconditionally.
• Reject an empty section name or empty option key in any INI block, and an empty or non-Python-identifier setting name in the Horizon block.
• Reject services.keystone.extraConfig in External mode also via the webhook mirror in validateKeystoneMode.

Webhook warnings (unit-tested, each asserting the warning text):

• Warn on a Reported owned key (for example Keystone [DEFAULT] debug in globalExtraConfig), naming the key, OwnedBy, and the contributing block path; the CR is admitted.
• Warn on a deprecated option, naming its replacement; the CR is admitted.
• Emit exactly one fail-open warning and no error when services.keystone.image is digest-pinned and services.keystone.extraConfig is set (catalog unresolvable from the image).
• Emit exactly one fail-open warning per affected service and no error when spec.openStackRelease names a release with no embedded catalog.
• Emit no extraConfig warning and no extraConfig error when all four blocks are absent (nil) — the empty path adds nothing to an otherwise-valid CR.

Update gating:

• Admit an update that touches no catalog input (for example a replicas bump) on a stored ControlPlane whose extraConfig is no longer catalog-valid.
• Re-validate on an update that changes any block, openStackRelease, services.keystone.image, or declares a previously-absent services.glance (which newly exposes the global block to the glance catalog).
• Reject an update that adds services.horizon with a publicEndpoint while the stored ControlPlane carries [federation] trusted_dashboard in globalExtraConfig or services.keystone.extraConfig (Family A is un-gated).

End-to-end:

• Add four rejection fixtures via _generate.py (global unknown option, per-service unknown option, External-mode extraConfig, Horizon SECRET_KEY) with chainsaw-test.yaml steps asserting the admission messages; make verify-invalid-cr-fixtures passes.

Docs:

• Document both block levels, the key-by-key merge with per-service precedence, the Horizon flat-block special case, the provenance-carrying messages, and the operator-build catalog limitation in docs/guides/advanced-configuration.md; document the four fields in docs/reference/c5c3/controlplane-crd.md; neither file gains an issue reference.

Non-Goals

• Applying globalExtraConfig to Horizon — Horizon renders flat Django settings, not INI sections; its per-service block is the whole surface.
• An option catalog for Horizon — Django settings have no machine-readable registry; settled in the Meta Issue, Horizon gets the ownership check only.
• A ControlPlane-level plugin declaration or plugin-section exemption — the projection sets no spec.plugins on any child, so plugin-owned sections are rejected as unknown at ControlPlane admission; a deployment needing plugin sections configures the service CR directly.
• Mirroring the children's ExtraConfigHealthy condition into ControlPlane status — the child condition remains the post-projection reporting surface; ControlPlane admission warnings cover submission time.
• Changing the report-don't-reject posture for operator-owned keys — this issue renders that settled posture as admission warnings, nothing more.
• A ConfigMap indirection for extraConfig (the ConfigMapRef pattern PolicySpec has) — the child fields are inline maps and the ControlPlane mirrors them.
• Preventing catalog skew between the c5c3-operator build and a deployed service-operator build — the child webhook stays as defense-in-depth and the projection-rejected conditions surface the mismatch.

References

• Meta Issue Meta: validated freeform service configuration — key ownership, per-release option catalog, ControlPlane passthrough #701 (framing, shared decisions); sibling Guard operator-owned configuration keys and unify the merge precedence #702 (owned-key registry and merge precedence, landed as PR Guard operator-owned configuration keys and unify the merge precedence #706); sibling Validate freeform configuration against a per-release option catalog #703 (per-release option catalog and admission validation, landed as PR feat: validate extraConfig against a per-release option catalog #711).
• Shared check module: internal/common/config/catalog.go, internal/common/config/ownership.go, internal/common/config/config.go (MergeDefaults).
• Policy-merge precedent: internal/common/policy/policy.go (MergePolicies), consumed at operators/c5c3/internal/controller/reconcile_keystone.go:238.
• Child webhook behaviors mirrored: operators/keystone/api/v1alpha1/keystone_webhook.go (validateExtraConfigOptions, extraConfigCatalogInputsChanged), operators/glance/api/v1alpha1/glance_webhook.go, operators/horizon/api/v1alpha1/horizon_webhook.go.
• Guide and reference to extend: docs/guides/advanced-configuration.md, docs/reference/c5c3/controlplane-crd.md.

---

Elaborated by planwerk-agent with Claude:claude-fable-5

[berendt]

Implementation Plan (issue #704)

Summary

• Add the four freeform-config fields (spec.globalExtraConfig, spec.services.{keystone,glance}.extraConfig as INI maps, spec.services.horizon.extraConfig as a flat Django JSON map) to the ControlPlane API, merge global+per-service key-by-key via a single exported helper MergedExtraConfig built on the existing config.MergeDefaults, project the result unconditionally onto the three children, and run the already-landed ownership registry (Guard operator-owned configuration keys and unify the merge precedence #702 / PR Guard operator-owned configuration keys and unify the merge precedence #706) and option-catalog (Validate freeform configuration against a per-release option catalog #703 / PR feat: validate extraConfig against a per-release option catalog #711) checks against the merged result at ControlPlane admission with per-block provenance in every error and warning.
• All new c5c3 logic concentrates in one new file, operators/c5c3/api/v1alpha1/controlplane_extraconfig.go, so the reconciler and the webhook call the same merge function — the drift the issue exists to prevent. The only cross-cutting touches are a one-symbol export in the horizon api package (pythonSettingName → PythonSettingName) and moving the body of horizonPublicEndpoint into a new ServiceHorizonSpec.DerivedPublicEndpoint() method so the webhook and the projection derive the trusted-dashboard gate identically.
• This is the smallest change set because every consumed building block already exists on main (verified below); no new shared-module code, no new catalogs, no status-condition mirroring, and no plugin surface are added, per the Non-Goals.

Ground-Truth Notes

• operators/c5c3/api/v1alpha1/controlplane_types.go — confirmed: GlobalPolicyOverrides at :110, ServiceKeystoneSpec.PolicyOverrides at :250, DECISION L1-import comment at :182-193, XValidation block at :206-217 (12 rules, one per managed-only field), ServiceHorizonSpec at :668-747, ServiceGlanceSpec at :765-859. None carries ExtraConfig today.
• operators/c5c3/api/v1alpha1/controlplane_webhook.go — confirmed: ValidateCreate :1199, ValidateUpdate :1223, validate :1246 (returns field.ErrorList, no warnings), newInvalidIfErrs :1955, validateKeystoneMode :1790 with the External forbidden-field list at :1856-1898 and the glance/horizon whole-block forbids at :1905-1912 (issue said :1905-1909; same code, three lines later). Already imports internal/common/release and internal/common/policy; does not yet import reflect or any service api package.
• internal/common/config — confirmed: MergeDefaults(userConfig, defaults) at config.go:111 (returns a fresh, never-nil map; user wins per key), LookupCatalog at catalog.go:89, CatalogExemptions :109, KeyExemptionsFromRegistry :119, FindUnknownOptions :163, FindOwnedOverrides at ownership.go:57, FindOwnedSettingOverrides :80. Note: the landed OwnedKey uses a Rejected bool field (not the Class enum from Guard operator-owned configuration keys and unify the merge precedence #702's elaboration) — issue Expose freeform service configuration on the ControlPlane #704's text already matches the landed shape.
• Service api packages — confirmed: keystone OwnedConfigKeys (config_ownership.go, [federation] trusted_dashboard is the sole Rejected: true entry at :93) and OptionCatalogForRelease(tag) (option_catalog.go:30); glance OwnedConfigKeys ([keystone_authtoken] password Rejected), CatalogExemptSections (option_catalog.go:33), OptionCatalogForRelease(openStackRelease) (:38); horizon OwnedConfigKeys (built from WebSSOSettingNames horizon_types.go:~238 block, MultiDomainSettingNames, SECRET_KEY Rejected), ExtraConfig map[string]apiextensionsv1.JSON at horizon_types.go:243 (import alias apiextensionsv1).
• Mirrored child-webhook behaviors — confirmed: keystone validateExtraConfigOptions fail-open variants at keystone_webhook.go:960-977, plugins-hint message :1000-1001, deprecated warnings :1008-1021, extraConfigCatalogInputsChanged :1032-1058, ValidateCreate/ValidateUpdate wiring :230-249, trusted-dashboard gate :867-869 + registry-driven rejection :892-907; glance empty-section/key checks glance_webhook.go:433-455, Rejected-key loop :457-478; horizon pythonSettingName at horizon_webhook.go:31, SECRET_KEY/identifier checks :229-257, validateWebSSO nil-gate ~:506, validateExtraConfigCollision ~:610. Minor discrepancy: pythonSettingName has one code use (MatchString at :250) plus its declaration — the issue's "two uses" overcounts; the rename touches only horizon_webhook.go (no test references it).
• Projections — confirmed: reconcile_keystone.go image resolution :185-193, policy.MergePolicies :238, keystone.Spec.PolicyOverrides = merged :307, trustedDashboards :372-378; reconcile_glance.go child built :393-401, glance.Spec.OpenStackRelease :403; reconcile_horizon.go CreateOrUpdate mutate closure :191-265 with the replicas revert-on-clear comment :244-250 and websso/multiDomain :261-262; horizonPublicEndpoint at identity_backends.go:162-173.
• operators/c5c3/go.mod — confirmed: requires all three service modules directly (with replace directives); k8s.io/apiextensions-apiserver v0.36.2 // indirect at :80.
• e2e — confirmed: tests/e2e/c5c3/invalid-cr/ has fixtures 00–57, _generate.py (SCAFFOLD with {infrastructure}/{keystone}/{horizon}/{glance}/{service_accounts} placeholders — no global-extraConfig placeholder yet, must be added; scaffold pins openStackRelease: "2025.2"), chainsaw-test.yaml (hand-maintained, contains($error, …) assertions), test_generate.py with _EXPECTED_FIXTURE_COUNT = 58. Keystone's catalog step shape at tests/e2e/keystone/invalid-cr/chainsaw-test.yaml:350-354 is the model.
• Docs — confirmed: docs/guides/advanced-configuration.md "### ExtraConfig — free-form INI sections" at :307 (says "not exposed on the ControlPlane CRD today" at :309) and the feature-pointer-table row at :137 ("not exposed — standalone-only"); docs/reference/c5c3/controlplane-crd.md ControlPlaneSpec table :197, ServiceKeystoneSpec :324 (managed-only enumeration at :350), ServiceHorizonSpec :374, ServiceGlanceSpec :407, Validation Rules :1234 (CEL matrix row listing the managed-only fields).
• Build/test plumbing — confirmed: Makefile targets generate :223, manifests :242, sync-crds :263, verify-crd-sync :283, verify-invalid-cr-fixtures :376 (runs c5c3's _generate.py --check), test / test-operator OPERATOR=<op>, lint. CRD copies at operators/c5c3/config/crd/bases/c5c3.io_controlplanes.yaml and operators/c5c3/helm/c5c3-operator/crds/c5c3.io_controlplanes.yaml. Test conventions: Gomega, validControlPlane() (controlplane_webhook_test.go:25), keystoneControlPlane()/glanceControlPlane()/horizonControlPlane() + getProjectedKeystone/Glance/Horizon helpers; option_catalog.go/option_catalog_test.go file pairing exists in both service api packages, so a paired controlplane_extraconfig_test.go matches convention. No integration_test.go exists in the c5c3 api package (unlike keystone/glance) — webhook unit tests + chainsaw e2e are the c5c3 coverage surface.

Work Breakdown Coverage

• Section 1 — API fields — covered by Change Set entries for controlplane_types.go (four fields, CEL rule, DECISION amendment), zz_generated.deepcopy.go, both CRD YAMLs, go.mod; Commit 2; Test Plan "CEL/e2e fixture 60" and generated-artifact verification commands; Documentation Plan (CRD reference rows).
• Section 2 — Merge helper — covered by controlplane_extraconfig.go (MergedExtraConfig) and controlplane_extraconfig_test.go; Commit 2; Test Plan merge-helper tests.
• Section 3 — Projection onto the children — covered by reconcile_keystone.go, reconcile_glance.go, reconcile_horizon.go, identity_backends.go entries; Commit 3; Test Plan projection tests in the three controller test files.
• Section 4 — Admission checks — covered by controlplane_extraconfig.go (Family A/B + gate + DerivedPublicEndpoint), controlplane_webhook.go wiring, horizon_webhook.go export; Commits 1 and 4; Test Plan webhook rejection/warning/gating tests.
• Section 5 — Generated artifacts, docs, and tests — covered by the regeneration entries, the four e2e fixtures + generator/chainsaw/test_generate changes (Commit 5), and the Documentation Plan (Commit 6).

User Stories

• As a platform operator, I want to set an oslo option once for every service and override it for one service, so that routine tuning lands through GitOps without a forge release — extracted from the issue.
• As a platform operator, I want a rejected ControlPlane to name the block and key that failed, so that I edit the right file on the first attempt — extracted from the issue.
• As a platform operator, I want to set a Django setting for the dashboard, so that Horizon behavior (for example SESSION_TIMEOUT) is configurable without editing the Horizon CR — extracted from the issue.

Change Set

• operators/horizon/api/v1alpha1/horizon_webhook.go — modify: rename pythonSettingName (:31) to PythonSettingName, update the doc comment (:26-30) and the single MatchString call site (:250). No other file references the symbol.

• operators/c5c3/api/v1alpha1/controlplane_types.go — modify:

  • Add GlobalExtraConfig map[string]map[string]string (JSON globalExtraConfig, +optional) on ControlPlaneSpec, directly after GlobalPolicyOverrides (:110) and before KORC. Godoc: applies to every INI-configured service the ControlPlane declares (Keystone and Glance today); merged key-by-key with the per-service extraConfig, per-service value winning per key; never applies to Horizon (flat Django settings, not INI); legal but inert in External mode (same posture as globalPolicyOverrides).
  • Add ExtraConfig map[string]map[string]string (JSON extraConfig, +optional) on ServiceKeystoneSpec and on ServiceGlanceSpec; godoc notes the merge with globalExtraConfig and projection onto the child's spec.extraConfig.
  • Add ExtraConfig map[string]apiextensionsv1.JSON (JSON extraConfig, +optional) on ServiceHorizonSpec, mirroring horizon_types.go:243; godoc notes verbatim projection, no global merge. Add the import apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1" (matching the horizon alias).
  • Append one CEL rule to the ServiceKeystoneSpec XValidation block (:206-217): // +kubebuilder:validation:XValidation:rule="!(has(self.mode) && self.mode == 'External') || !has(self.extraConfig)",message="services.keystone.extraConfig is forbidden when services.keystone.mode is External".
  • Amend the DECISION comment at :182-193: record that the api package now additionally imports the three service api packages (operators/keystone/api/v1alpha1, operators/glance/api/v1alpha1, operators/horizon/api/v1alpha1) to reach the embedded option catalogs and ownership registries for admission-time extraConfig validation; rationale: the module dependency has existed since the L2 reconciler landed (all three are direct requires in operators/c5c3/go.mod), so only package-level purity is given up, and the catalogs stay single-source instead of duplicated.

• operators/c5c3/api/v1alpha1/controlplane_extraconfig.go — create (SPDX header pair like every .go file). Contents:

  • func MergedExtraConfig(global, service map[string]map[string]string) map[string]map[string]string — returns config.MergeDefaults(service, global) (per-service wins per key, sections unioned), normalized to nil when the result has length zero. Godoc states it is the single merge both the reconciler and the webhook consume.
  • func (s *ServiceHorizonSpec) DerivedPublicEndpoint() string — nil-receiver-safe move of the body of horizonPublicEndpoint (identity_backends.go:162-173): explicit PublicEndpoint wins with trailing / trimmed (strings.TrimRight), else "https://" + Gateway.Hostname when set, else "".
  • func validateExtraConfigOwnership(cp *ControlPlane) (admission.Warnings, field.ErrorList) — Family A, un-gated:
    • Shape: for each of the three INI blocks (spec.globalExtraConfig, spec.services.keystone.extraConfig, spec.services.glance.extraConfig) that is present, reject an empty section name (field.Invalid at the block path) or empty option key (field.Invalid at <block>.Key(section)), mirroring glance_webhook.go:433-455 messages. For spec.services.horizon.extraConfig, reject an empty setting name and any name failing horizonv1alpha1.PythonSettingName, mirroring horizon_webhook.go:241-257 messages, at spec.services.horizon.extraConfig / …​.Key(name).
    • Keystone merged result (only when services.keystone is set and mode is not External): compute merged := MergedExtraConfig(cp.Spec.GlobalExtraConfig, ks.ExtraConfig) and walk config.FindOwnedOverrides(merged, keystonev1alpha1.OwnedConfigKeys). For the Rejected entry [federation] trusted_dashboard: when cp.Spec.Services.Horizon.DerivedPublicEndpoint() != "" emit field.Forbidden at every contributing block's path (spec.globalExtraConfig[federation][trusted_dashboard] and/or spec.services.keystone.extraConfig[federation][trusted_dashboard]; membership test: the pair exists in that block), message stating the key is managed via the ControlPlane's Horizon-derived trusted-dashboards projection; when the derived endpoint is empty, fall through to the owned-key warning path instead (externally-run dashboard use case). Non-Rejected entries → one warning per entry naming key, OwnedBy, Impact when set, and the contributing block path(s).
    • Glance merged result (only when services.glance is set): same walk with glancev1alpha1.OwnedConfigKeys; the Rejected [keystone_authtoken] password is always field.Forbidden at every contributing block path (message mirrors glance_webhook.go:469-471 incl. Impact); Reported entries → warnings as above.
    • Horizon block (only when services.horizon is set): config.FindOwnedSettingOverrides(<keys of the map>, horizonv1alpha1.OwnedConfigKeys). Rejected entries (SECRET_KEY, every WebSSOSettingNames/MultiDomainSettingNames entry) are always field.Forbidden at spec.services.horizon.extraConfig[<KEY>] — deliberately stricter than the child (whose websso/multiDomain collision check is gated on the typed blocks, horizon_webhook.go:506, :602-620), because the ControlPlane projects those blocks dynamically from identity backends (reconcile_horizon.go:261-262). Messages: SECRET_KEY is managed via services.horizon.secretKeyRef; WEBSSO_*/multi-domain settings are owned by the ControlPlane's identity-backend projection. Reported entries → warnings.
  • func validateExtraConfigCatalogs(cp *ControlPlane) (admission.Warnings, field.ErrorList) — Family B:
    • Keystone (when services.keystone set and mode not External): resolve tag := ks.Image.Tag if ks.Image != nil, else cp.Spec.OpenStackRelease (mirror of reconcile_keystone.go:185-193); keystonev1alpha1.OptionCatalogForRelease(tag). Glance (when services.glance set): glancev1alpha1.OptionCatalogForRelease(cp.Spec.OpenStackRelease) (mirror of reconcile_glance.go:403).
    • Fail open per service: when no catalog resolves and the service's merged map is non-empty, exactly one warning, no errors — the two variants of keystone_webhook.go:960-977 (distinguish via release.ParseRelease) adapted to name the ControlPlane fields, e.g. ControlPlane extraConfig for keystone was not validated against an option catalog: services.keystone.image does not name an OpenStack release / …: no catalog for release "X" is embedded in this operator build.
    • Exemptions: keystone config.CatalogExemptions{Keys: config.KeyExemptionsFromRegistry(keystonev1alpha1.OwnedConfigKeys)} (no plugin sections — the projection never sets spec.plugins); glance adds Sections built from glancev1alpha1.CatalogExemptSections plus Keys from its registry.
    • Compute catalog.FindUnknownOptions(merged, ex) once per service on the merged map, then attribute each finding by membership: one field.Invalid per contributing block at spec.globalExtraConfig[<s>][<k>] and/or spec.services.<svc>.extraConfig[<s>][<k>] (a pair in both blocks yields two errors). Known-section detail: no such option in the <svc> <release> option catalog. Unknown-section detail: no such section in the <svc> <release> option catalog (plugin-registered sections are not configurable through the ControlPlane) — must not carry the child's "declare via spec.plugins" hint. Each DeprecatedOption → one warning per contributing block naming section, key, release, and replacement (or "no replacement"), following keystone_webhook.go:1008-1021.
  • func controlPlaneExtraConfigCatalogInputsChanged(oldObj, newObj *ControlPlane) bool — mirrors keystone_webhook.go:1032-1058: reflect.DeepEqual on GlobalExtraConfig, on the two per-service INI maps (nil-safe via block presence), plain compares on OpenStackRelease, reflect.DeepEqual on Services.Keystone.Image, and the presence booleans of Services.Keystone / Services.Glance.

• operators/c5c3/api/v1alpha1/controlplane_extraconfig_test.go — create: unit tests for MergedExtraConfig (all four merge-helper ACs) and DerivedPublicEndpoint (nil receiver, explicit endpoint incl. trailing-slash trim, gateway-derived, neither set), Gomega style.

• operators/c5c3/api/v1alpha1/controlplane_webhook.go — modify:

  • ValidateCreate (:1199): compute both families on obj; warnings := append(insecurePublicEndpointWarnings(obj), ownWarnings...) then append(warnings, catWarnings...); fold ownErrs and catErrs into w.validate(obj)'s list before the existing newInvalidIfErrs call (mirror of keystone_webhook.go:230-233). validateUniqueInNamespace/validateNamespaceClaims stay as-is.
  • ValidateUpdate (:1223): always run Family A on newObj; run Family B only when controlPlaneExtraConfigCatalogInputsChanged(oldObj, newObj); append both families' errors to the existing allErrs aggregation and both warning sets to insecurePublicEndpointWarnings(newObj).
  • validateKeystoneMode External list (:1856-1898): add if ks.ExtraConfig != nil { field.Forbidden(ksPath.Child("extraConfig"), "forbidden when services.keystone.mode is External (no Keystone workload is deployed)") } — the webhook mirror of the new CEL rule. Add the reflect import.

• operators/c5c3/api/v1alpha1/controlplane_webhook_test.go — modify: admission tests per the Test Plan below.

• operators/c5c3/internal/controller/reconcile_keystone.go — modify: add keystone.Spec.ExtraConfig = c5c3v1alpha1.MergedExtraConfig(cp.Spec.GlobalExtraConfig, cp.Spec.Services.Keystone.ExtraConfig) next to the PolicyOverrides assignment (:307), with a short comment noting the unconditional assign-to-revert convention and that nil keeps the SSA intent free of the field.

• operators/c5c3/internal/controller/reconcile_glance.go — modify: add glance.Spec.ExtraConfig = c5c3v1alpha1.MergedExtraConfig(cp.Spec.GlobalExtraConfig, cp.Spec.Services.Glance.ExtraConfig) next to glance.Spec.OpenStackRelease (:403).

• operators/c5c3/internal/controller/reconcile_horizon.go — modify: inside the mutate closure (near :242-254), assign a deep copy of cp.Spec.Services.Horizon.ExtraConfig: nil when the source is nil or empty; otherwise a fresh map[string]apiextensionsv1.JSON with each value *v.DeepCopy() so the child never aliases cp.Spec. Unconditional assignment (revert-on-clear, per the replicas comment at :244-250).

• operators/c5c3/internal/controller/identity_backends.go — modify: horizonPublicEndpoint (:162-173) becomes a one-line delegation return hz.DerivedPublicEndpoint() (nil handled by the method); keep the function so existing call sites (trustedDashboards, websso projection) are untouched.

• operators/c5c3/internal/controller/reconcile_keystone_test.go, reconcile_glance_test.go, reconcile_horizon_test.go — modify: projection tests per the Test Plan.

• operators/c5c3/api/v1alpha1/zz_generated.deepcopy.go — regenerated via make generate.

• operators/c5c3/config/crd/bases/c5c3.io_controlplanes.yaml, operators/c5c3/helm/c5c3-operator/crds/c5c3.io_controlplanes.yaml — regenerated via make manifests sync-crds.

• operators/c5c3/go.mod (and go.sum if it changes) — go mod tidy inside operators/c5c3 moves k8s.io/apiextensions-apiserver from indirect to direct.

• tests/e2e/c5c3/invalid-cr/_generate.py — modify: insert a {global_extra_config} placeholder into SCAFFOLD between the openStackRelease line and {infrastructure} and a matching global_extra_config: str = "" field on the Fixture dataclass (renders "" for all existing fixtures, so their output stays byte-identical); append four fixtures:

  • 58-global-extraconfig-unknown-option.yaml — Managed keystone + MANAGED_INFRA, globalExtraConfig with [token] providr (mirrors keystone fixture 24); rejected by Family B with path spec.globalExtraConfig and the keystone-catalog message.
  • 59-glance-extraconfig-unknown-option.yaml — Managed keystone + MANAGED_INFRA + VALID_GLANCE extended with extraConfig: {glance_store: {default_backend_typo: …}}; rejected with the glance-catalog message at spec.services.glance.extraConfig….
  • 60-keystone-extraconfig-in-external.yaml — VALID_EXTERNAL_KEYSTONE + extraConfig: {DEFAULT: {debug: "true"}}; rejected by the new CEL rule (schema layer runs before the webhook, like fixtures 05–10).
  • 61-horizon-extraconfig-secret-key.yaml — Managed keystone + MANAGED_INFRA + horizon block with extraConfig: {SECRET_KEY: hunter2}; rejected by Family A.

• tests/e2e/c5c3/invalid-cr/chainsaw-test.yaml — modify: four new steps in the c5c3-invalid-cr Test asserting, respectively: no such option in the keystone 2025.2 option catalog + globalExtraConfig; no such option in the glance 2025.2 option catalog; services.keystone.extraConfig is forbidden when services.keystone.mode is External; a stable substring of the SECRET_KEY Forbidden message (e.g. SECRET_KEY is managed via).

• tests/e2e/c5c3/invalid-cr/test_generate.py — modify: _EXPECTED_FIXTURE_COUNT 58 → 62.

• The four generated fixture YAML files — created by running python3 tests/e2e/c5c3/invalid-cr/_generate.py.

• docs/guides/advanced-configuration.md, docs/reference/c5c3/controlplane-crd.md — modify per the Documentation Plan.

Commit Sequence

Repo conventions for the implementer: branch off main first (never commit on main); commit bodies hard-wrapped at 72 columns (write the message to a file, use git commit -F); trailer block in exactly this order, no blank lines between trailers: On-behalf-of: @SAP, Assisted-by: Claude:<model>, Signed-off-by: …; no Co-Authored-By; no issue numbers as commit scopes; do not push.

1. refactor(horizon): export the Python setting-name pattern — operators/horizon/api/v1alpha1/horizon_webhook.go; the ControlPlane webhook must share the identifier pattern instead of copying it.
2. feat(c5c3): add extraConfig API fields and merge helper — controlplane_types.go, new controlplane_extraconfig.go (only MergedExtraConfig + DerivedPublicEndpoint at this point) + controlplane_extraconfig_test.go, regenerated zz_generated.deepcopy.go and both CRD YAMLs, operators/c5c3/go.mod/go.sum; the four spec fields, the CEL rule, and the amended DECISION comment land together with their generated artifacts so the tree stays green.
3. feat(c5c3): project merged extraConfig onto service children — reconcile_keystone.go, reconcile_glance.go, reconcile_horizon.go, identity_backends.go, three controller test files; one unconditional assignment per projection following the revert-on-clear convention.
4. feat(c5c3): validate ControlPlane extraConfig at admission — controlplane_extraconfig.go (Family A, Family B, update gate), controlplane_webhook.go, controlplane_webhook_test.go; runs the sibling issues' checks against the merged result with per-block provenance.
5. test(e2e): add ControlPlane extraConfig invalid-cr fixtures — _generate.py, four generated fixtures, chainsaw-test.yaml, test_generate.py; pins the four admission rejections against a real API server.
6. docs: document ControlPlane freeform service configuration — docs/guides/advanced-configuration.md, docs/reference/c5c3/controlplane-crd.md; documents both block levels, merge semantics, provenance, and the catalog-build limitation.

Test Plan

Merge helper + endpoint derivation (operators/c5c3/api/v1alpha1/controlplane_extraconfig_test.go, new):

• TestMergedExtraConfig_PerServiceWinsPerKey — key in both blocks → per-service value; global-only keys and global-only sections survive (Story 1).
• TestMergedExtraConfig_NilWhenBothNil, TestMergedExtraConfig_NilWhenBothEmpty — nil result for nil/empty-non-nil inputs.
• TestMergedExtraConfig_ReturnsIndependentCopy — exactly one input set; mutate the result, assert the input map unchanged.
• TestDerivedPublicEndpoint — nil receiver → ""; explicit endpoint trimmed of trailing /; gateway-hostname derivation; neither → "".

Webhook (operators/c5c3/api/v1alpha1/controlplane_webhook_test.go, extend; each rejection asserts the error's field path, each warning asserts content):

• Global unknown option, keystone only declared → path spec.globalExtraConfig[<s>][<k>], message names keystone catalog + release (Story 2).
• Keystone-only option in globalExtraConfig with services.glance also declared → error at the spec.globalExtraConfig path naming the glance catalog (use e.g. [token] expiration — valid keystone 2025.2 option, no [token] section in glance).
• Unknown option in services.glance.extraConfig → path spec.services.glance.extraConfig[<s>][<k>].
• Same unknown key in both blocks → exactly two errors, one per contributing path.
• Unknown section → message contains "plugin-registered sections are not configurable through the ControlPlane" and does not contain "spec.plugins".
• Acceptance: a valid option in both blocks admitted; a full ControlPlane with all four blocks populated admitted (the base case).
• [keystone_authtoken] password in the global block and in the glance block (two cases) with services.glance declared → Forbidden regardless of other fields.
• [federation] trusted_dashboard in the merged keystone result: rejected when services.horizon carries publicEndpoint (and, second case, a gateway hostname); admitted with an owned-key warning when services.horizon is absent.
• Horizon SECRET_KEY, one WebSSOSettingNames entry, one MultiDomainSettingNames entry → Forbidden unconditionally at spec.services.horizon.extraConfig[<KEY>].
• Empty section name / empty option key in each INI block; empty and non-Python-identifier setting name in the Horizon block → rejected.
• services.keystone.extraConfig with mode External → Forbidden via the validateKeystoneMode mirror.
• Warnings: Reported owned key (keystone [DEFAULT] debug via globalExtraConfig) → warning naming key, OwnedBy, block path; CR admitted. Deprecated option ([DEFAULT] logfile) → warning naming [DEFAULT] log_file; admitted. Digest-pinned services.keystone.image + keystone extraConfig → exactly one fail-open warning, zero errors. spec.openStackRelease with no embedded catalog (e.g. 2027.1) with keystone and glance declared and blocks set → exactly one warning per service, zero errors. All four blocks nil → no extraConfig warning and no extraConfig error.
• Update gating: stored CP with stale-invalid extraConfig — replicas bump admitted; block edit, openStackRelease change, services.keystone.image change, and newly-declared services.glance each re-validate and reject. Update adding services.horizon with publicEndpoint while the stored CP carries [federation] trusted_dashboard in either INI block → rejected (Family A un-gated).

Controller projections:

• reconcile_keystone_test.go — TestReconcileKeystone_ExtraConfigMerge (both blocks set, merged content asserted on the child; model: TestReconcileKeystone_PolicyMerge :300) and TestReconcileKeystone_ExtraConfigClearedProjectsNil (set → reconcile → clear → reconcile → child field nil; model: TestReconcileKeystone_ClearsFederationProxyImageOverride :851) (Story 1).
• reconcile_glance_test.go — same pair for Glance via getProjectedGlance (Story 1).
• reconcile_horizon_test.go — TestReconcileHorizon_ExtraConfigProjectedVerbatim (entry appears verbatim on the child; assert no aliasing: mutate the projected child's map/value, cp.Spec unchanged) and TestReconcileHorizon_ExtraConfigClearedProjectsNil (Story 3).

E2E: the four new chainsaw steps above; make verify-invalid-cr-fixtures and python3 tests/e2e/c5c3/invalid-cr/test_generate.py stay green. (The rendered-local_settings.py half of Story 3's second checkbox is already covered by the horizon operator's own render tests; the ControlPlane side ends at the child's spec.extraConfig.)

Documentation Plan

• docs/guides/advanced-configuration.md — add a ControlPlane freeform-configuration section (new ## section, referenced from the feature-pointer table): spec.globalExtraConfig + per-service blocks, key-by-key merge with per-service precedence, the Horizon flat-block special case (global INI never applies), provenance-carrying rejection paths (spec.globalExtraConfig[…] vs spec.services.<svc>.extraConfig[…]), External-mode posture (globalExtraConfig legal and inert), the ownership-warning and catalog behavior at ControlPlane admission (fail-open, update gating), and the known limitation: catalogs consulted at ControlPlane admission are the ones embedded in the c5c3-operator build; a skewed service-operator build's child webhook stays as defense-in-depth and surfaces as KeystoneProjectionRejected/GlanceProjectionRejected. Update the feature-pointer-table row at :137 (currently "not exposed — standalone-only") and the stale claim at :309 ("not exposed on the ControlPlane CRD today") to cross-link the new section. No issue references anywhere (repo rule).
• docs/reference/c5c3/controlplane-crd.md — add the globalExtraConfig row to the ControlPlaneSpec table (:197ff) and an extraConfig row to each of the ServiceKeystoneSpec (:324ff, also extend the managed-only field enumeration at :350), ServiceHorizonSpec (:374ff, flat Django map[string]JSON), and ServiceGlanceSpec (:407ff) tables; in Validation Rules (:1234ff) extend the per-field External-mode CEL row with extraConfig and describe the webhook-only Family A/B rules (shape checks, owned-key rejections/warnings, catalog validation with fail-open and the update gate — no CEL backstop for the catalog).

Verification Commands

• make generate manifests sync-crds (after the API change; commit the outputs) and cd operators/c5c3 && go mod tidy
• make verify-crd-sync
• python3 tests/e2e/c5c3/invalid-cr/_generate.py then make verify-invalid-cr-fixtures
• python3 tests/e2e/c5c3/invalid-cr/test_generate.py
• make test-operator OPERATOR=c5c3 and make test-operator OPERATOR=horizon (fast loop), then make test (all modules)
• make lint

Risks & Open Questions

• The issue says to update pythonSettingName's "two uses"; the code has the declaration plus exactly one MatchString use (horizon_webhook.go:250). The rename is smaller than stated — no risk, noted for fidelity.
• A global Reported key owned by more than one service registry (e.g. [DEFAULT] debug, in both keystone's and glance's) yields one warning per declared service. The issue specifies "one admission warning per Reported owned key found on the merged result" per service walk, so per-service warnings are the planned behavior; the warning tests pin it.
• The Affected Areas line says "wire both families into validate/ValidateCreate/ValidateUpdate", while Description §4's Wiring paragraph explicitly says the families are called from ValidateCreate/ValidateUpdate directly, not from validate (whose signature returns no warnings). The plan follows §4 — it is normative and matches the keystone precedent.
• Clearing extraConfig on the SSA-applied Keystone/Glance children is asserted with the fake client; the existing clear-transition test TestReconcileKeystone_ClearsFederationProxyImageOverride proves the pattern works in this harness, so no envtest is needed.
• _generate.py's SCAFFOLD gains a {global_extra_config} placeholder; it must render to the empty string for every existing fixture so --check stays byte-stable — the drift gate itself verifies this.
• Local macOS quirk (known, pre-existing): a handful of test-shell files and make helm-deps fail even on main; none of the verification commands above depend on them — do not chase those failures as regressions.

Status

STATUS: PLAN_READY

---

Implementation plan generated by planwerk-agent c4682b7 implement with Claude