Fix Connector Gateway configuration gaps

[tgrunnagle]

Description

Addresses the gaps and inaccuracies reported in #1225 on Configure the Connector Gateway, plus follow-up fixes from two rounds of review. Claims were checked against the latest chart release, v0.22.0. The issue was written against v0.18.0, so a few findings have changed since then (noted below).

configure-connector-gateway.mdx

The page now follows this order: required setup, verification, an Advanced configuration section, and Troubleshooting.

• Prerequisites:

  • Requires platform chart v0.22.0 or later, the first release where the gateway reads global.redis.
  • The gateway inherits global.redis settings, including username and TLS. A link points to the Redis ACL instructions.
  • A GitOps-safe way to distribute the Enterprise Manager CA.

• Values example: adds three settings, with short explanations under the values table:

  • vmcpConfig.groupRef. It's required, and no MCPGroup with that name has to exist.
  • authServer.baseline_client_scopes: [openid, offline_access], so dynamically registered MCP clients can get refresh tokens.
  • controlPlane.incomingAuth.oidc, with placeholders for the issuer and audience.

• New section, "Accept console tokens on the REST API": the issuer must match the primary IdP. The audience is the one the IdP assigns to the console's OAuth client (cloud-ui in the Okta example), with a link showing how to confirm it. It also covers restricted audiences and the JWT requirement.

• Rewritten section, "Identify users by a claim other than sub": set primaryIdp.subjectClaim and the Enterprise Manager's binding_claim together. The claim must be on ID tokens (with the Okta step for adding uid) and on the console's access tokens.

• Connect to the Enterprise Manager:

  • The Enterprise Manager fetches clusterOidcIssuer directly from that URL, so its pods need egress to it.
  • The chart computes a fourth allowlist, meteringSaSubjectAllowlist.

• New section, "Keep the AI Gateway's access":

  • Create the AIGateway in the release namespace.
  • Add the api-key-service subject to the allowlist and keep directory.insecure: false.
  • Unset grpc.insecure.
  • Set acknowledgeNoApiKeyServiceCaller when you don't use virtual keys.
  • Add the main-processor subject for group labels.

  configure-ai-gateway.mdx now links to this section.

• New section, Advanced configuration:

  • Restrict the Redis user: the reference ACL, for installs where the gateway is the only global.redis consumer.
  • Use a cleartext connection for development: notes it's incompatible with the Enterprise Manager's key-encryption key.
  • Override the gateway's name: a table of the settings to update and their replacement values. This includes allowedClientSelector for nameOverride, which changes the pod label.

• Troubleshooting: new entries for:

  • The Enterprise Manager failing to start or rejecting callers.
  • 401 on the console's Connectors pages.
  • MCP clients stuck at "needs authentication".
  • AI Gateway 503s and missing group labels.
  • Render failures after a name override.

deployment.mdx

• Enterprise Manager key-encryption key:
  • The existingSecret format, a JSON version map of base64-encoded 32-byte keys.
  • The credential-loss warning comes before the commands.
  • Separate commands for a new install (generate a key) and an existing install (copy the chart-generated key).
  • Rotation, including the restart it requires.
• Directory NetworkPolicy: what the policy admits, that NetworkPolicies are additive, and when to use externallyManagedNetworkPolicy.
• allowedClientSelector example: now passes the label map directly. The chart adds matchLabels itself, so the old nested form rendered an invalid selector. This bug predates the PR and is fixed in its own commit.
• global.redis.username: documented, along with the render error when it's set without existingSecret.

Where v0.22.0 differs from the issue

• Item 1: the gateway inherits global.redis at v0.22.0, so this PR documents username and the minimum chart version instead of a per-component Redis block.
• Item 4: the AIGateway field path is spec.auth.virtualAPIKeys.directory.insecure.

Type of change

• Documentation update

Related issues/PRs

Closes #1225

Submitter checklist

Content and formatting

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

Reviewer checklist

Content

• I have reviewed the content for technical accuracy
• I have reviewed the content for spelling, grammar, and style

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs-website	Ready	Preview	Oct 13, 2026 2:47pm UTC

[tgrunnagle]

Multi-Agent Consensus Review

Agents consulted: cgw-accuracy (connector-gateway / umbrella chart), em-accuracy (Enterprise Manager / Redis / AI Gateway), docs-style (style, structure, issue coverage). Claims were checked against the SEP v0.22.0 chart and Go source, and the page's example values were rendered with helm template.

Consensus Summary

#	Finding	Consensus	Severity	Action
1	A failed discovery fetch stops the Enterprise Manager from starting, rather than causing it to reject gRPC callers	9/10	MEDIUM	Fix
2	The API-key render guard fires without virtual keys; the acknowledgeNoApiKeyServiceCaller escape hatch is undocumented	9/10	MEDIUM	Fix
3	grpc.insecure isn't addressed (issue item 4); it's also refused at startup alongside a KEK	9/10	MEDIUM	Fix
4	subjectClaim is also read from the console's access token	7/10	MEDIUM	Fix
5	grpc.networkPolicy can only widen access; the example contradicts the text	7/10	MEDIUM	Fix
6	Switching to existingSecret with a new KEK loses stored credentials	7/10	MEDIUM	Fix
7	Name overrides: httpSaSubjectAllowlist is missing; the port claim is overstated	7/10	MEDIUM	Fix
8	The dev-cluster cleartext paragraph now sits under "Name overrides"	8/10	MEDIUM	Fix
9	No minimum chart version is stated	8/10	LOW	Fix
10	The API key service must run in the release namespace	9/10	LOW	Fix
11	The AI Gateway main processor also needs an allowlist entry	8/10	LOW	Fix
12	ACL advice: the username is shared, and the required commands and default user are not covered	8/10	LOW	Fix
13	The console-token link has no anchor and doesn't show how to get the audience	7/10	LOW	Fix
14	Use a placeholder for the control-plane issuer	7/10	LOW	Fix

Overall

This is a docs-only PR that closes #1225. It adds the values the Connector Gateway page was missing (groupRef, baseline_client_scopes, controlPlane.incomingAuth.oidc, primaryIdp.subjectClaim), plus sections on console tokens, non-sub subjects, AI Gateway access and name overrides, and Enterprise Manager KEK and NetworkPolicy details in deployment.mdx. The approach is sound. Re-baselining on v0.22.0 instead of the issue's v0.18.0 is the right call, and the PR body explains where the issue no longer applies. Most new claims hold up against source: Redis inheritance, the groupRef validator and its status-only use, baseline_client_scopes semantics, control-plane issuer matching, the drift guards' messages, the KEK version-map format and the openssl command, and the api-key-service subject, field path and 503 symptom. The example values render cleanly at v0.22.0.

None of the findings challenge the approach. They fall into three groups. Several failure modes are described wrongly or only partly: a discovery failure is a startup crash, the API-key guard and grpc.insecure both affect installs without virtual keys, and subjectClaim also applies to access tokens. Two deployment.mdx additions could lead readers to a bad outcome: the NetworkPolicy text contradicts the example above it, and the KEK existingSecret path has no warning for existing installs. The rest are completeness and structure items. Items 1–3 and 6 are the ones worth fixing before merge.

Documentation

All findings are documentation findings, in configure-connector-gateway.mdx and deployment.mdx; see the inline comments. Codex cross-review was not run because the CLI isn't installed.

---

Generated with Claude Code

[danbarr]

The additions close useful configuration gaps, and the earlier review fixes are reflected in this revision. I'm requesting changes primarily to keep the setup procedure focused: required configuration, optional configurations, and failure diagnosis currently compete for attention before readers reach verification.

Editorial scope

The inline comments mark representative places to tighten that boundary. Apply the same approach to these sections in configure-connector-gateway.mdx:

• Accept console tokens on the REST API: retain the issuer, audience, JWT requirement, restricted-audience guidance, and token-verification link. Move the default-validator explanation and resulting 401 symptoms into Troubleshooting.
• Identify users by a claim other than sub: retain the matching settings, ID-token/access-token requirements, Okta instructions, and stable-identity guidance. Consolidate the two 401 explanations into a troubleshooting entry.
• Keep the AI Gateway's access: keep the conditional setup instructions here, including the acknowledgement required when virtual API keys are disabled. Move the 503 symptom and silent loss of telemetry labels into Troubleshooting. Link this section from the AI Gateway setup guide so readers can find it from that journey too.

Group the Redis ACL recipe, cleartext development transport, and name overrides under Advanced configuration after the normal setup and verification sequence. Keep a short pointer where each becomes relevant. Also move the groupRef explanation next to the example or values table; it currently sits under "Choose the gateway ID and issuer," where readers would not look for it.

Retain explanations that help readers choose values or avoid credential loss. The goal is to shorten the main procedure while preserving actionable troubleshooting and optional configuration.

Remaining correctness items

• Name overrides: nameOverride also changes the gateway's app.kubernetes.io/name label. The Enterprise Manager's directory NetworkPolicy and the documented additional policy select connector-gateway, so changing the names and allowlists alone leaves the renamed pods without gRPC access under those policies. Document updating enterprise-manager.grpc.networkPolicy.allowedClientSelector to the actual pod label. fullnameOverride alone preserves that label.
• Enterprise Manager KEK rotation: deployment.mdx says to add a higher-numbered key and retain earlier keys, but omits restarting the Enterprise Manager pods. The KEK provider loads the Secret once at startup, so the new active version is only picked up on restart. Add that activation step, or move rotation into a complete operational procedure and link to it.

Separate follow-up

The existing deployment example nests matchLabels inside grpc.networkPolicy.allowedClientSelector. At v0.22.0 the chart adds matchLabels itself and expects the value to be the label map directly. This predates the PR, so please track or fix it separately.

Reviewed head 50edbf4 and spot-checked these behavior claims against v0.22.0 chart and Go source. Current CI checks pass; this was a source-based review without live deployment testing.

[danbarr]

Please move the full ACL recipe and key-pattern explanation into an optional Advanced configuration subsection. Prerequisites should establish that Redis is available and configured, with a short link to the ACL instructions. This detailed hardening procedure interrupts the setup checklist before readers have prepared the gateway's secrets.

[tgrunnagle]

Addressed in a26a719. The ACL recipe and key-pattern explanation now live under Advanced configuration > Restrict the Redis user. The Redis prerequisite keeps only a one-line link to that section.

[tgrunnagle]

Responses to the review body (#1227 (review)):

• Editorial scope: addressed in a26a719. Changes to configure-connector-gateway.mdx:
  • The default-validator explanation and all 401 symptoms for console tokens and subjectClaim are consolidated into one Troubleshooting entry, "The console's Connectors pages return 401".
  • The AI Gateway 503 symptom and the missing telemetry group labels are now a Troubleshooting entry. The acknowledgement for installs without virtual keys stays in the setup section.
  • The Redis ACL, the cleartext development transport, and name overrides are grouped under a new Advanced configuration section after verification. Each has a short pointer where it becomes relevant.
  • The groupRef explanation now sits under the values table.
  • configure-ai-gateway.mdx now links to Keep the AI Gateway's access from its prerequisites.
• Name overrides and pod labels: addressed in a26a719. The table includes allowedClientSelector with the nameOverride label. A paragraph after it explains that the directory NetworkPolicy admits only pods labeled connector-gateway, so readers who don't enable grpc.networkPolicy should use fullnameOverride.
• KEK rotation: addressed in f152cac. The rotation step now ends with a kubectl rollout restart, because the KEK is read once at startup (directory/app/module.go).
• matchLabels nesting: fixed in a separate commit, e8800f9. I confirmed networkpolicy-grpc.yaml wraps the value in matchLabels itself, so the example now passes the label map directly. No other pages had the nested form.

[danbarr]

The previous review findings are addressed. One nonblocking naming clarification below.

[danbarr]

Nonblocking clarification: the control-plane Service keeps its -control-plane suffix, and serviceAccount.name can independently override the ServiceAccount name. Since the rendered resources are authoritative, I'd remove the simplified naming formulas:

Suggested change

	To read the names, render the chart with `helm template` and find the gateway's
	ServiceAccount and its `-control-plane` Service. With `fullnameOverride`, the
	ServiceAccount and Services take the override as their name; with
	`nameOverride`, they become `<RELEASE_NAME>-<NAME_OVERRIDE>`.
	Render the chart with `helm template`. Use the gateway's ServiceAccount name and
	the control-plane Service's name and port from the rendered output to set these
	values.