[Feature]: use webhooks to verify mutually exclusive fields

[whg517]

Duplicates

I have searched the existing issues

Summary 💡

In some field attributes, it is necessary to verify the mutually exclusive condition of the attribute fields. The oneof field configuration cannot be generated using kubebuilder's mark, so it is necessary to implement the logical verification on the server side through webhook.

expect:

spec:
  properties:
    provider:
      oneOf:
      - required:
          - static
      - required:
          - ldap
      - required:
          - oidc
      - required:
          - tls
      properties:
        ldap:
          type: object
        oidc:
          type: object
        static:
          type: object
        tls:
          type: object
      type: object
  type: object

Actual kubebuilder can only be generated:

spec:
  properties:
    provider:
      properties:
        ldap:
          type: object
        oidc:
          type: object
        static:
          type: object
        tls:
          type: object
      type: object
  type: object

Some useful links:

• Support more complex validations (oneOf/anyOf/allOf/etc)
• Add discriminators to all unions/oneof in the API

[whg517]

Picked this up in triage. The premise still holds; the conclusion does not — and the investigation found the gap is a fail-open, not the API-ergonomics wish it was filed as.

What is still true, and what changed

kubebuilder still cannot emit oneOf (controller-tools#461 and kubernetes#35345 are both still open). But that no longer implies a webhook: CEL expresses exactly-one declaratively, and this repo already uses it for the same class of problem (the role/role-group name rules in cluster_types.go).

Proven end-to-end on the real AuthenticationClass CRD, generated with commons-operator's own controller-gen invocation and installed in a k8s 1.35 envtest API server: zero, two and five providers rejected; each of the five singletons accepted.

A webhook is also the more expensive option by a wide margin: the org has no webhook infrastructure anywhere — no operator registers a validator, no chart deploys a webhook or cert-manager, every kustomize WEBHOOK/CERTMANAGER block is commented scaffolding. pkg/webhook's ProductValidator[CR] is the wrong shape besides: it is wired through ctrl.NewWebhookManagedBy on a product cluster CR, while AuthenticationClass is a cluster-scoped platform CRD with no controller at all.

The gap is live, and worse than ambiguity

AuthenticationClass has no controller in any repo, so this object is only ever read at build time by whichever product operator references it. Five of them read it five different ways:

• trino — first-match if/else (OIDC > Static > LDAP); TLS and Kerberos fall through to return "", nil
• superset — not first-match: it appends both the OIDC block and the LDAP block into the same superset_config.py, and both assign AUTH_TYPE, so Python's last-assignment-wins silently selects LDAP while the OAUTH_PROVIDERS block stays in the file
• doris / hbase / hdfs — each reads exactly one field and ignores the rest

And the shipped CRD accepts provider: {} today. That fails open: trino returns a nil authenticator, hbase and hdfs skip the oauth2-proxy container entirely, so the UI is served unauthenticated — with a V(5) log line as the only trace.

What #626 ships, and what it deliberately does not

Both halves, because neither is sufficient:

1. +kubebuilder:validation:ExactlyOneOf=oidc;tls;static;ldap;kerberos — stops new bad objects at admission. Inert until commons-operator regenerates the CRD (it is the only repo that generates it, from operator-go's package, pinning controller-gen v0.19.0).
2. authentication.ResolveProvider(*AuthenticationProvider) (ProviderKind, error) — the half that reaches objects that already exist. The marker rejects writes; a class stored before the rule, or on a cluster whose CRD was never upgraded, is read exactly as before. One shared implementation is what actually ends the five-way divergence, on every cluster, regardless of CRD version.

Before the CRD is regenerated: settle the Kubernetes floor

This is a prerequisite, not a footnote.

On clusters below k8s 1.30 there is no CRDValidationRatcheting, and CEL has been enforced since 1.25. Proven on envtest 1.26.1 against the real shipped CRD: with a two-provider object stored, upgrading the CRD then makes kubectl label rejected, a full PUT with the provider byte-identical rejected, and a server-side apply of the identical manifest rejected. Only GET/LIST/DELETE and a conflict-resolving edit work. A GitOps pipeline managing such an object goes permanently failed-sync.

On 1.35 the same operations are accepted with a Warning: header — but ratcheting is nearly vacuous here anyway, because AuthenticationClassSpec has exactly one field. Any real maintenance edit (rotating an IdP hostname, changing an LDAP bind secretClass) touches spec.provider and is refused.

The org contradicts itself about which clusters must not break: operator-go/docs/architecture.md:1365 says "K8s Version: 1.31+", while commons-operator — the repo that ships this CRD — defaults its e2e kind cluster to 1.26.15, as do ten other operator repos. Either raise those defaults to ≥1.30 and state the floor in the chart's kubeVersion, or accept that the rule is a hard break on supported clusters and say so in the release notes.

Known migration cost found so far: two commons-operator fixtures set all four providers at once.

Leaving this open until the CRD side lands, since #626 only carries the SDK half.

[whg517]

Deferred — not being worked on. Marked wontfix as a do-not-pick-up signal rather than a rejection; the analysis in the comment above stands and PR #626 has been closed.

Recovering it needs two things, in this order:

1. Settle the Kubernetes floor. operator-go/docs/architecture.md says 1.31+, commons-operator and ten other repos default their e2e kind cluster to 1.26.15. Below k8s 1.30 there is no CRDValidationRatcheting, so applying the regenerated CRD write-locks every stored violating AuthenticationClass — even kubectl label is rejected. This is a prerequisite, not a footnote.
2. Then re-land branch docs/backlog-triage (still pushed): the ExactlyOneOf marker plus authentication.ResolveProvider.

Worth remembering if this sits: the runtime half (ResolveProvider) has no such prerequisite. It works on every cluster regardless of CRD version, and it is the half that ends the five-way downstream divergence and the provider: {} fail-open. If only one thing is ever revived, it is that one.