[onuryilmaz]

Summary

Closes #2248.

The kubeconfig controller fully overwrites ClusterKubeconfig.spec.kubeconfig on every reconcile (server URL + CA from the cluster secret, OIDC config from the org). Until now there was no way to override individual fields per cluster — needed e.g. for new-tenant OIDC setups.

This PR introduces greenhouse.sap/kubeconfig-overrides: an annotation on the Cluster resource that lets operators patch any kubeconfig field after the controller builds the spec.

Annotation format

annotations:
  greenhouse.sap/kubeconfig-overrides: |
    {
      "clusters[0].cluster.server": "https://new-tenant-api.example.com:6443",
      "users[0].user.auth-provider.config.client-id": "new-tenant-client-id",
      "users[0].user.auth-provider.config.idp-issuer-url": "https://new-tenant-issuer.example.com",
      "users[0].user.auth-provider.config.client-secret": {
        "secretRef": {"name": "my-tenant-secret", "key": "client-secret"}
      }
    }

• Keys are dot-separated JSON field names matching the kubeconfig structure; use [0] for array entries (there is always exactly one cluster, user, and context).
• Values can be either a plain JSON string or a {"secretRef": {"name": "…", "key": "…"}} object — the controller resolves secretRefs at reconcile time, keeping secrets out of the annotation.
• Applied after the main spec patch, so it wins over greenhouse.sap/oidc-override on any overlapping field.
• The existing greenhouse.sap/oidc-override annotation is kept for backwards compatibility.

Error handling

Condition	Reason
Annotation value is not valid JSON	OverrideResolveError
secretRef target secret / key does not exist	OverrideResolveError
Dot-path does not exist in the kubeconfig structure	OverrideError
k8s patch fails	OverridePatchError

Removing the bad annotation causes the controller to self-heal on the next reconcile.

Changes

• api/well_known.go — new AnnotationKeyKubeconfigOverrides constant
• internal/controller/cluster/kubeconfig_controller.go — resolveKubeconfigOverrides (secretRef + plain string resolution), applyKubeconfigOverrides (dot-path walker, now takes pre-resolved map), wired into Reconcile after the main spec patch
• internal/controller/cluster/kubeconfig_controller_test.go — 4 new envtest specs covering OIDC field overrides, secretRef resolution (including missing-secret error), server URL override, and invalid-JSON error handling

Demo

Test plan

• go build ./... passes
• New envtest specs pass:

  KUBEBUILDER_ASSETS=$(bin/setup-envtest use 1.36.0 -p path) \
    go test ./internal/controller/cluster/ \
    --ginkgo.focus="generic kubeconfig|secretRef values|ReconcileFailedCondition on invalid" \
    --ginkgo.v --ginkgo.no-color -timeout 180s -v
  

• Full ClusterKubeconfig suite (17 specs) passes with no regressions

[Copilot]

🟡 Changes recommended

Separate spec patches cause continuous reconciliation, while nonexistent paths can silently succeed.

2 open findings

• Apply overrides atomically to prevent reconcile loops · New
• Document string and secretRef annotation value forms · New

What changed in this PR

Adds per-cluster kubeconfig field overrides, including values resolved from Secrets.

Changes:

• Defines the new annotation.
• Resolves and applies dot-path overrides.
• Adds envtest coverage for common override and error scenarios.

File	Description
api/​well_known.go	Defines the annotation constant.
internal/​controller/​cluster/​kubeconfig_controller.go	Implements override resolution and patching.
internal/​controller/​cluster/​kubeconfig_controller_test.go	Tests overrides and error handling.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Unknown paths are silently ignored, patch errors use the wrong reason, and one error-path test can pass on stale status.

1 open finding

• Classify override patch failures as OverridePatchError · New

2 resolved since last review

• Apply overrides atomically to prevent reconcile loops
• Document string and secretRef annotation value forms

Previously missed (2)

In code that hasn't changed since last review

Reject unknown JSON fields during override decoding

internal/​controller/​cluster/​kubeconfig_controller.go:492

json.Unmarshal silently ignores unknown object fields, so a typo such as clusters[0].cluster.serve is accepted, discarded during this decode, and reported as successfully applied instead of producing the documented OverrideError. Decode with unknown-field rejection; map entries under auth-provider.config will remain extensible because that node is a map.

Assert the invalid-JSON diagnostic after asynchronous reconciliation

internal/​controller/​cluster/​kubeconfig_controller_test.go:624

This assertion can pass on the missing-secret condition left by the preceding ordered spec: deleting that annotation only schedules an asynchronous reconciliation, while both old and expected messages contain kubeconfig-overrides. Match the invalid-JSON diagnostic so this spec waits for and verifies its own reconciliation.

🧠 Review effort: Balanced

[Copilot]

🟡 Changes recommended

Invalid paths can succeed silently, and some overrides persist after annotation removal.

1 open finding

• Rebuild complete kubeconfig baseline before applying overrides · New

1 resolved since last review

• Classify override patch failures as OverridePatchError

🧠 Review effort: Balanced

[abhijith-darshan]

In my opinion Specing annotations with index and dot paths and merging them would be flaky.
This mirrors the drawbacks of ingress-nginx annotations sprawls and we should avoid it.

A declarative approach while verbose is a better fit due to strong typing and kubernetes CRD validation.

Example - A configOverrides in spec can be done the following way

type ClusterKubeconfigSpec struct {
	....
	ConfigOverrides *ClusterKubeconfigOverrides `json:"configOverrides,omitempty"`
}

type ClusterKubeconfigOverrides struct {
	Clusters       []ClusterItemOverride `json:"clusters,omitempty"`
	Users          []AuthInfoOverride    `json:"users,omitempty"`
	Contexts       []ContextItemOverride `json:"contexts,omitempty"`
	CurrentContext string                `json:"currentContext,omitempty"`
}

type ClusterItemOverride struct {
	Name                        string              `json:"name"`
	Server                      string              `json:"server,omitempty"`
	CertificateAuthorityDataRef *SecretKeyReference `json:"certificateAuthorityDataRef,omitempty"`
}

type AuthInfoOverride struct {
	Name string              `json:"name"`
	OIDC *OIDCConfigOverride `json:"oidc,omitempty"`
}

type OIDCConfigOverride struct {
	ClientID        string              `json:"clientID,omitempty"`
	IssuerURL       string              `json:"issuerURL,omitempty"`
	ClientIDRef     *SecretKeyReference `json:"clientIDRef,omitempty"`
	ClientSecretRef *SecretKeyReference `json:"clientSecretRef,omitempty"`
}

type ContextItemOverride struct {
	Name      string `json:"name"`
	Cluster   string `json:"cluster,omitempty"`
	User      string `json:"user,omitempty"`
	Namespace string `json:"namespace,omitempty"`
}

With this there will be a clean possibility to override by matching by name. by design this extends the possibility to upsert a context or users.

Example -

apiVersion: greenhouse.sap/v1alpha1
kind: ClusterKubeconfig
metadata:
  name: my-cluster
spec:
  configOverrides:
    clusters:
      - name: my-cluster
        server: https://new-tenant-api.example.com:6443
    users:
      - name: oidc@my-cluster
        oidc:
          clientID: new-tenant-client-id
          issuerURL: https://new-tenant-issuer.example.com
          clientSecretRef:
            name: my-tenant-secret
            key: client-secret

Appending a second user and context, a future possibility is left open by name-matched shape

spec:
  configOverrides:
    users:
      - name: admin@my-cluster
        oidc:
          clientID: admin-client-id
          clientSecretRef:
            name: admin-secret
            key: client-secret
    contexts:
      - name: my-cluster-admin
        cluster: my-cluster
        user: admin@my-cluster
        namespace: kube-system

The controller can build this during reconcile and do comparison using go-cmp for early exits. or even hash the overrides.

[onuryilmaz]

Replaced the annotation-based dot-path approach with the strongly-typed configOverrides spec field exactly as suggested — all types (ClusterKubeconfigOverrides, ClusterItemOverride, AuthInfoOverride, OIDCConfigOverride, ContextItemOverride) are implemented with name-matched merging. CreateOrPatch already handles early exits when nothing changes, so no additional go-cmp comparison is needed.

[Copilot]

🟡 Changes recommended

Removing legacy Cluster-level OIDC annotation handling silently replaces existing custom credentials with organization defaults during reconciliation, potentially breaking authentication and violating promised backward compatibility.

4 open issues

• Preserve legacy cluster OIDC annotation overrides · New
• Honor the advertised kubeconfig override annotation · New
• Reject kubeconfig overrides with dangling references · New
• Keep inline client ID ahead of secret references · New

1 resolved since last review

• Rebuild complete kubeconfig baseline before applying overrides

1 file not reviewed

• api/v1alpha1/zz_generated.deepcopy.go: Generated file

_{Review effort: Balanced}