[carlos-lopez-vecino]

Summary

v0.23.1 is the target of the toolhive upgrade: v0.23.0 plus an auth fix. After the PAIINFRA-198 merge, dp-stable sits at v0.19.0. v0.20–v0.23 bring the v1beta1 API. Storage moves to v1beta1 with conversion: None, and the schemas are identical to v1alpha1. So one merge covers the whole range. The operator CRDs are shared by the prod (v0.19) and stg operators in every cluster, so this merge also adds shims that keep the new CRDs admitting the objects prod still has.

Nothing is deployed by this PR. The rollout is PAIINFRA-201.

• Merges upstream v0.23.1 into dp-stable (117 upstream commits, 38 conflicting files). Merge with a merge commit, not squash.
• MCPServer.spec.groupRef shim. Upstream v0.20 made it object-only, but every prod MCPServer uses a plain string. The field is now schemaless in the CRD, and MCPGroupRef.UnmarshalJSON decodes both "name" and {name: ...}. Any other shape decodes to an empty name, so a single bad object can't break list/watch decoding in the operator; GroupRefValidated then reports it.
• VirtualMCPServer.spec.groupRef shim. It stays optional in the CRD, because prod objects don't set it until PAIINFRA-201. The controller still rejects objects without it.
• Keeps every fork-only CRD field: sessionTTL, sessionStorage.usernameRef, allowedClientIds, optional oidcConfigRef.audience, redis address, and the secrets list keys (name+key).
• Carries every DocPlanner patch. The non-obvious conflict resolutions are listed under "Special notes".

Type of change

• Other (describe): upstream release merge

Test plan

• Unit tests (task test)

• Linting (task lint-fix; unrelated rewrites it made to upstream files were reverted)

• Manual testing (describe below)

• task build, go vet ./..., task operator-generate, task operator-manifests, task crdref-gen and task helm-docs all ran. The generated files are committed.

• task test: two packages fail, and both fail the same way on dp-stable before this merge: pkg/vmcp/session/internal/security (TestRestoreHijackPrevention_AuthenticatedRoundTrip) and pkg/webhook/validating (TestValidatingMiddleware_HTTP422AlwaysDenies). pkg/vmcp/aggregator has a data race in a fork test that is flaky on both branches.

• task lint: 86 findings, against 90 on dp-stable. Nothing new beyond the capped goconst list reporting different test files.

• envtest integration suites (k8s 1.31): EmbeddingServer, MCPExternalAuthConfig, MCPGroup, MCPOIDCConfig, MCPTelemetryConfig and MCPToolConfig pass. MCPRegistry (17/21), MCPRemoteProxy (4) and MCPServer (1) fail with the same specs on dp-stable. The VirtualMCPServer composite-tool watch spec is flaky under -p on both branches, and passes when run alone.

• New envtest cases in mcpserver_cel_validation_integration_test.go check the groupRef shim against a real API server:

  • the string form is admitted and decoded through both v1beta1 and v1alpha1;
  • the object form works;
  • a malformed value doesn't break List.

• Prod objects against the new CRDs. I rendered toolhive-config / toolhive-config-stg from platform-apps@develop for every environment. Each toolhive CR was then dry-run created on an envtest API server and decoded into the new v1beta1 Go types:

  • control, current CRDs from dp-stable: 263/263 pass;
  • new CRDs, prod on base chart 0.17.2 (today's prod pin): 258/263. The 5 failures are the i0 hub VirtualMCPServers, whose outgoingAuth.backends.*.type: external_auth_config_ref was removed upstream in v0.21;
  • new CRDs, prod on base chart 0.18.0 (PAIINFRA-199): 180/180 pass, including all 95 MCPServers with a string groupRef.

Does this introduce a user-facing change?

No. Nothing is deployed until PAIINFRA-201.

Special notes for reviewers

Rollout gate for PAIINFRA-201: prod must run toolhive-config ≥ 0.18.0 before these CRDs roll out, or the 5 i0 hub VirtualMCPServers stop validating.

For review, compare against upstream: git diff v0.23.1 origin/chore/merge-upstream-v0.23.1 is the full fork delta (177 files, mostly fork code carried over from before this merge). git diff origin/dp-stable... is dominated by the upstream changes.

Non-obvious resolutions:

• CEL can't validate the groupRef shim. The ticket planned a CEL rule, but Kubernetes can't build CEL type information for a schemaless field. That's true both from the parent and on the field itself; the API server rejects the CRD. Validation therefore happens in the operator, not at admission.
• vMCP serve. Upstream moved it to pkg/vmcp/cli (Extract vMCP serve/validate logic into pkg/vmcp/cli/ stacklok/toolhive#4891). The fork's backend init/request timeouts, sessionTTL, write timeout and session-owner URL are ported to pkg/vmcp/cli/serve_timeouts.go, along with their tests.
• Session manager. The fork implementation is kept, as in the v0.19 merge.
  • DataStorage.Upsert is restored: upstream Remove Upsert from DataStorage interface — closes #4726 stacklok/toolhive#4797 removed it, but the fork's HA session paths still call it.
  • Upstream's write-back of restored metadata (Persist restored session metadata to Redis in loadSession stacklok/toolhive#4842) is taken, and its tests are ported. It fits the fork, whose checkSession also compares only backend IDs.
  • Upstream's BeforeListTools/BeforeCallTool lazy tool injection is dropped. The fork already repairs cross-replica sessions in OnRequestInitialization, which runs first.
• Backend session hints on restore (Add horizontal scaling tests for vmcp stacklok/toolhive#4724) are accepted but not forwarded. Sending a stored Mcp-Session-Id on Initialize would fail restores against backends that reject unknown sessions (e.g. mcp-for-argocd). The fork already recovers lost sessions by reconnecting.
• Auth-server token handler. It keeps the fork's default audience for every grant type, which client credentials depend on. Upstream Grant default aud when resource is absent stacklok/toolhive#4805 limits that to authorization_code. The one upstream change taken: an empty resource counts as absent.
• MCPOIDCConfigReference.resourceUrl was added by both sides, and git's rename detection produced a duplicate field. It's collapsed into upstream's.
• Operator RBAC. Regenerating the operator ClusterRole overwrote the fork's release-qualified name (Release-qualify operator RBAC object names #5), so that change was reverted.
• Legacy inline OIDC. v0.21 removed it; one fork test that used it now uses anonymous auth, since it only exercises authz mapping.

🤖 Generated with Claude Code

[github-actions]

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.

---

This review will be automatically dismissed once you add the justification section.