[peppescg]

Description

Documents service accounts in Stacklok Enterprise, following the acceptance criteria in stacklok/stacklok-enterprise-platform#4934. A service account gives a Kubernetes workload its own directory identity, groups, model set grants, and budget. The workload authenticates to both the AI Gateway and the Connector Gateway with its pod's projected ServiceAccount token, so there's no static key.

New pages:

• platform/enterprise-directory/service-accounts.mdx (AC4.1, AC4.5, AC4.6): when to use a service account instead of a virtual API key, trusting a cluster's issuer, the creation wizard, pinned and name-only bindings (including reassign), activation, revocation and deletion, and what an account can reach depending on model access, budgets, and connector authentication.
• ai-gateway/kubernetes-workloads.mdx (AC4.2): the projected token volume, audience and expirationSeconds: 1800, Authorization: Bearer only, what 401, 402, 403, and 503 mean, and where an administrator finds the reason behind a refusal.
• connector-gateway/kubernetes-workloads.mdx: the same token on /gw/mcp, a curl check, which connectors and tools an account gets (None, Bearer token, and Header injection connectors granted to its groups, no connections to make), and the gateway's 401, 403, and 503.

Updated pages:

• configure-ai-gateway.mdx: new "Accept service account workloads" section with the cluster administrator's prerequisites (AC4.3).
• configure-connector-gateway.mdx: new "Accept service account workloads" section (on by default over TLS, what the chart sets up, egress rules, turning it off, accounts shared with the AI Gateway), plus the workloadTrustSaSubjectAllowlist row for a renamed gateway.
• users-and-groups, manage-budgets, budgets-and-pricing, virtual-api-keys (AC4.4).
• control-model-access, connector-policies, connectors (service accounts on the Activity tab), both forward-audit-logs pages (service account subjects), the console and directory index pages, and sidebars.ts.

Every claim was checked against stacklok-enterprise-platform main (v0.26.0), including the Connector Gateway work in stacklok/stacklok-enterprise-platform#5799, #5849, #5855, #5930, and #5963.

Keep in draft until

• A release ships with the service_accounts console flag removed. stacklok/stacklok-enterprise-platform#5519 merged on 2026-11-04, but no tag contains it yet; v0.26.0 still defaults the flag to off.
• stacklok/stacklok-enterprise-platform#4933 lands. The pages state the 60-minute token lifetime ceiling it decides; main still has 2 hours.
• The v0.26.0 upstream release sync lands. The generated Helm reference is still at chart 0.25.0, so it lacks global.stacklok.connectorGateway.workloadIdentity.enabled, connector-gateway.enterpriseConfig.workloadIdentity.pollInterval, and the Connector Gateway entry in the workloadTrustSaSubjectAllowlist default.

Resolved: the Connector Gateway accepts workload tokens (v0.26.0), the console labels the in-cluster issuer This cluster (stacklok/stacklok-enterprise-platform#5543), and #1244 merged.

Where the pages follow the code instead of #4934

• AC4.5, "bound or not": both gateways refuse any workload the directory doesn't resolve to an active, bound account (stacklok/stacklok-enterprise-platform#5401), even with model access and budgets off.
• AC4.2, the opaque 401: an invalid token gets 401, while a valid token without an active binding gets 403. The pages cover both, with the audit reason_code values and the Enterprise Manager's workload.resolutions metric and debug log.
• AC4.3, Envoy trust limits: skipped. The Envoy-based gateway doesn't serve service accounts (stacklok/stacklok-enterprise-platform#4961).
• AC4.3, in-cluster key permission: both charts bind system:service-account-issuer-discovery, so it's documented as a check, not a manual step.
• Audience: the console has no default audience, so the pages tell administrators to enter one, with stacklok-enterprise-platform as the example.
• Key rotation: the pages say to wait 15 minutes before signing with a new key, the longest a gateway keeps cached keys, instead of the default 5-minute valid_for.

Type of change

• New documentation
• Documentation update
• Navigation/structure change

Related issues/PRs

• stacklok/stacklok-enterprise-platform#4934 (user documentation for service accounts)
• stacklok/stacklok-enterprise-platform#5024 (console service accounts story)
• stacklok/stacklok-enterprise-platform#5640 (Connector Gateway service accounts epic)
• stacklok/stacklok-enterprise-platform#4933 (token lifetime ceiling)
• stacklok/stacklok-enterprise-platform#5519 (console flag removal)

Screenshots

None. No page in the platform, AI Gateway, or Connector Gateway sections uses screenshots.

Submitter checklist

Content and formatting

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

Navigation

• New pages include a frontmatter section with title and description at a minimum
• Sidebar navigation (sidebars.ts) updated for added, deleted, reordered, or renamed files
• Redirects added to vercel.json for moved, renamed, or deleted pages (no URLs changed, so none needed)

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	Nov 4, 2026 6:15pm UTC

[peppescg]

@claude please review this PR as a subject matter expert and technical writer, following .claude/skills/review-docs-pr/SKILL.md and the docs-review criteria in .claude/skills/docs-review/SKILL.md.

Focus on accuracy, clarity, information architecture (placement, duplication, inbound links to the two new Kubernetes workloads pages), and compliance with STYLE-GUIDE.md.

Already known, so don't re-raise:

• The 60-minute token lifetime, pending stacklok-enterprise-platform#4933.
• The service_accounts feature flag, pending stacklok-enterprise-platform#5519.

Post one body-level review comment with primary and secondary issues. Don't push commits.

[claude]

Claude finished @peppescg's task in 2m 23s —— View job

---

Review: Document service accounts

Verdict: needs a few changes, then it's ready. The three new pages are tightly written, follow Diataxis, and end with Next steps, Related information, and Troubleshooting in the right order. The Kubernetes workloads pages are linked from more than the sidebar. The Copilot fixes in e203b7f hold up: suspend-first revocation, the pod-creation caveat on pinned bindings, /128, and the scoped prerequisites. What's left is mostly about where content lives. One existing page now contradicts the new guidance, and the issuer and key-rotation guidance is split between the directory page and the cluster admin page.

I skipped the 60-minute lifetime and the service_accounts flag, as you asked. I couldn't read stacklok-enterprise-platform from this runner, so I checked claims against this repo's docs and generated references, not the upstream code.

---

Primary issues

1. roll-out-gateway-clients.mdx now contradicts the new guidance (and is a missing inbound link)
docs/platform/enterprise-platform/roll-out-gateway-clients.mdx:48-54 ("Choose an authentication method") still sends "scripts, scheduled jobs, continuous integration, and other clients without a browser flow" to virtual API keys. The PR's change to virtual-api-keys.mdx:14-17 says Kubernetes agents and jobs should use a service account. This page is where an administrator picks a client auth method, so it's the most natural inbound link for the new pages.
Ask: Add a third bullet, for example: "Use a service account for agents and jobs running in Kubernetes. The workload authenticates with its pod's ServiceAccount token and its requests are attributed to the account." Narrow the virtual-key bullet to scripts and CI outside Kubernetes.

2. Trusted issuer guidance is split across two audiences, and the security reason is on the wrong page

• service-accounts.mdx:58-61 tells the directory admin to choose This cluster "only when every gateway runs in this cluster."
• configure-ai-gateway.mdx step 4 ("Plan one issuer per cluster") gives a different condition: "every gateway runs in the same cluster as the workloads it serves." It also gives the reason that matters: clusters often share the default issuer URL, so one This cluster issuer would accept every cluster's tokens.
• The person who picks This cluster in the console reads the directory page, which leaves out both the workloads condition and the cross-cluster risk. Step 4 is also a console decision, not chart configuration, and the Connector Gateway section doesn't have it.

Ask: Keep the full guidance in one place: the This cluster bullet in service-accounts.mdx "Trust the cluster's issuer". Use the stricter condition (gateways and workloads in the cluster that runs Stacklok Enterprise) and state the shared-issuer-URL risk. On configure-ai-gateway.mdx, replace step 4 with a one-sentence pointer.

3. JWKS key rotation is on the cluster admin page but done in the console
configure-ai-gateway.mdx step 5 ("Rotate signing keys in this order") covers uploaded JWKS and JWKS URLs. Those belong to a trusted issuer the directory admin manages on the Trusted issuers tab. The 15-minute cache applies to both gateways, but only the AI Gateway page mentions it, so someone who only runs the Connector Gateway never sees it.
Ask: Move the rotation steps to service-accounts.mdx as a short subsection under "Trust the cluster's issuer", for example "Rotate an issuer's signing keys". Say they apply to both gateways, and link to them from both configure pages.

4. Revocation: the token-lifetime paragraph can read as if suspending doesn't take effect right away
service-accounts.mdx:155-167: right after "suspend its account... The gateways refuse the workload's next request," the next paragraph says "A token already issued keeps working until it expires... because the gateways verify tokens by their signature." A reader under pressure may take this to mean a suspended account's tokens still work for up to an hour. The point is that deleting the Kubernetes ServiceAccount doesn't revoke anything. That paragraph's last sentence also repeats lines 132-134 (a recreated ServiceAccount matches a name-only binding).
Ask: Lead with the point and drop the repeat, for example: "Deleting the Kubernetes ServiceAccount doesn't revoke access. Tokens already issued stay valid until they expire, up to 60 minutes, because the gateways verify tokens by their signature. Suspend the account or remove its binding instead."

---

Secondary issues

Issue	Recommendation
The pages are ahead of the Helm reference. docs/platform/reference/helm/platform.mdx is generated from chart 0.25.0. Its workloadTrustSaSubjectAllowlist default has no Connector Gateway entry. Neither global.stacklok.connectorGateway.workloadIdentity.enabled nor connector-gateway.enterpriseConfig.workloadIdentity.pollInterval appears in any generated reference yet.	Add "the v0.26.0 upstream release sync lands" to the PR's Keep in draft until list, so the keys in configure-connector-gateway.mdx match the reference when this merges.
ai-gateway/kubernetes-workloads.mdx:19 says the administrator "grants it models and a budget" with no condition. service-accounts.mdx:100-104 makes both conditional on the gateway's controls.	Change it to "and, when the gateway enforces model access and budgets, grants it models and a budget."
service-accounts.mdx:135-137, "Pin the UID when the account's grants and budget are worth more than what the cluster already grants that ServiceAccount name," is hard to act on.	Say it concretely, for example: "Pin the UID for any account whose grants or budget you wouldn't give to whoever can create a ServiceAccount with that name in the namespace."
service-accounts.mdx:200-213: Helm keys in the table headers and the acknowledgeUnmetered/modelAccess.endpoint paragraph are cluster admin config on a page for directory admins.	Use plain headers (Model access On/Off, Budgets On/Off) and replace the Helm paragraph with links to the configure page or Control model access and Budgets and pricing, which own those settings.
The rule "None, Bearer token, or Header injection only" is restated in six places: service-accounts.mdx (twice), connector-gateway/kubernetes-workloads.mdx (body and troubleshooting), connector-policies.mdx, and configure-connector-gateway.mdx. Each gives the reason in slightly different words.	Keep the explanation in service-accounts.mdx "What an account can reach" and keep the other mentions to one clause plus a link, so a future auth type needs only one edit.
connector-gateway/index.mdx:35 link text "Call the gateway from Kubernetes workloads" doesn't match the page title.	Use "Call the Connector Gateway from Kubernetes workloads", per the link-text rule.
ai-gateway/index.mdx:33 still reads "Limit which models each user or group can call," even though the line above now adds service accounts.	Add "or service account" for consistency.
manage-budgets.mdx "Service account budgets", where "The account's Budgets tab under Service Accounts" is ambiguous: this section is also about a Service Accounts tab on the Budgets screen.	Name the path: "On an account's page under Administration > Service Accounts, the Budgets tab shows..."
ai-gateway/kubernetes-workloads.mdx:158: "Gateways install a new issuer" on a single-gateway page (the Connector page says "The gateway").	Change to "The gateway installs".

---

What works well

• The "virtual key vs. service account" choice comes early in service-accounts.mdx and links both ways.
• The Handle errors tables map each response to its message and to an action, and the audit reason_code and workload.resolutions guidance gives administrators a real diagnostic path.
• The Connector page reuses the AI page for token rules instead of copying them, so each page stands alone without duplicating.
• No changelog framing, no em dashes in new prose, and placeholders use <ALL_CAPS> consistently.

Out of scope

• manage-budgets.mdx uses an en dash in 80–100%. It's probably the literal UI label, so leave it unless the console changes.

I didn't push any commits.

[peppescg]

@claude thanks for the review. Commit 5f7a7a5 addresses every primary and secondary issue from it. Please review the PR again with the same criteria (.claude/skills/review-docs-pr/SKILL.md and .claude/skills/docs-review/SKILL.md):

1. Confirm each finding from your previous review is resolved, or say what's still missing.
2. Report any new issues the changes introduced, especially in the moved content: the This cluster guidance and the new "Rotate an issuer's signing keys" subsection in service-accounts.mdx, and the pointers that replace them in configure-ai-gateway.mdx and configure-connector-gateway.mdx.

Already tracked in the PR's Keep in draft until list, so don't re-raise:

• The 60-minute token lifetime (stacklok-enterprise-platform#4933).
• The service_accounts feature flag (stacklok-enterprise-platform#5519).
• The Helm reference still at chart 0.25.0 until the v0.26.0 release sync.

Post one body-level review comment. Don't push commits.

[claude]

Claude finished @peppescg's task in 1m 21s —— View job

---

Re-review: Document service accounts

Verdict: ready once two small fixes land. 5f7a7a5 fixes every primary issue from the last review, and all but one secondary issue. The moved This cluster and key-rotation content reads well on the service accounts page, and both configure pages now point to it. One meaning got lost in the move (item 1 below), and the connector auth-type rule is still restated in more places than needed.

I skipped the 60-minute lifetime, the service_accounts flag, and the chart 0.25.0 Helm reference, as you asked. As before, I couldn't read stacklok-enterprise-platform from this runner, so I checked claims against this repo only.

---

Previous findings

#	Finding	Status
P1	roll-out-gateway-clients.mdx contradicts the new guidance	✅ Resolved. The virtual key bullet now covers clients "that act as a person," and a service account bullet links to the new page.
P2	This cluster guidance split across pages	✅ Resolved. The stricter condition and the shared-issuer-URL risk are now in service-accounts.mdx:58-63, and configure-ai-gateway.mdx has a pointer instead. See new issue 1.
P3	JWKS rotation on the cluster admin page	✅ Resolved. Moved to service-accounts.mdx:89-99, says it applies to both gateways, and both configure pages link to it.
P4	Revocation paragraph read as if suspending were delayed	✅ Resolved. It now starts with deleting the Kubernetes ServiceAccount, and the repeated sentence is gone.
S	AI Gateway prerequisite made models and budget unconditional	✅ Resolved
S	Hard-to-act-on wording for when to pin the UID	✅ Resolved
S	Helm keys in the "What an account can reach" table	✅ Resolved. Plain On/Off headers, with links out.
S	"None / Bearer token / Header injection" rule repeated in six places	⚠️ Partly resolved. See new issue 2.
S	Link text in connector-gateway/index.mdx	✅ Resolved
S	ai-gateway/index.mdx didn't mention service accounts	✅ Resolved, but the edit adds a nit (see the secondary issues table).
S	Ambiguous Budgets tab path in manage-budgets.mdx	✅ Resolved
S	"Gateways install" on a single-gateway page	✅ Resolved

---

Primary issues

1. The move dropped "its own" issuer URL for clusters registered as Another issuer
The removed step 4 in configure-ai-gateway.mdx said to register each cluster as Another issuer "with its own public issuer URL." service-accounts.mdx:70-72 now says only "When gateways or workloads span clusters, add each cluster this way. Enter its public Issuer URL…"

The bullet just above gives the reason this matters: clusters often share the default issuer URL. A reader whose clusters all use the default https://kubernetes.default.svc issuer still doesn't know they must give each cluster a distinct issuer before adding it. "Add each cluster this way" also doesn't say whether the cluster that runs Stacklok Enterprise is one of them. It should be, because once workloads span clusters, This cluster no longer applies.

Ask: Restore the requirement and make the scope explicit. For example: "When gateways or workloads span clusters, add every cluster this way, including the one that runs Stacklok Enterprise. Each cluster needs its own issuer URL, so a cluster that uses the default issuer needs a unique one set first." Please confirm the uniqueness requirement upstream, since I couldn't.

2. The connector auth-type list still appears in five places
5f7a7a5 shortened the explanation in connector-gateway/kubernetes-workloads.mdx body and linked it to the canonical section. That's good. The full None, Bearer token, or Header injection list still appears in:

• service-accounts.mdx:199-203, the canonical section (keep)
• connector-gateway/kubernetes-workloads.mdx:91 (body, now linked) and :161 (troubleshooting)
• connector-gateway/connector-policies.mdx (new paragraph, links to the top of the page, not the section)
• configure-connector-gateway.mdx:559

If a new auth type works for service accounts, all five need an edit. The commit message says these rules are kept "in one place each," but they're not yet.

Ask: In connector-policies.mdx, configure-connector-gateway.mdx, and the troubleshooting entry, replace the list with a phrase such as "connectors whose authentication type can serve a service account," linking to service-accounts.mdx#what-an-account-can-reach. This is low risk, so it can wait for a follow-up if you'd rather merge.

---

Secondary issues (new in 5f7a7a5)

Location	Issue	Recommendation
service-accounts.mdx:94	"Publish or upload the new public key alongside the current one." With Upload JWKS you upload a whole document, so "alongside" is unclear.	"Add the new public key to the JWKS URL's document, or upload a JWKS that contains both the new and current keys."
service-accounts.mdx:95-99	Steps 2 and 3 happen on the cluster, where the API server's signing key changes. The directory admin reading this page usually doesn't do that.	Add a lead-in such as "Coordinate with the cluster's administrator, who changes the signing key."
configure-ai-gateway.mdx:372-375, configure-connector-gateway.mdx:580-581	The pointer says "rotate an issuer's signing keys" but links to the parent section.	Link the rotation half to #rotate-an-issuers-signing-keys, for example "see Trust the cluster's issuer and Rotate an issuer's signing keys."
configure-ai-gateway.mdx:372-373	The pointer repeats the This cluster condition, a second copy of what you just consolidated. It's one sentence, so it's acceptable, but it can drift.	Optional: drop the condition and keep only the link sentence.
ai-gateway/index.mdx:33-34	"show each user only the models they can use" replaced "each caller." control-model-access.mdx:12 still says the endpoints list "only the models the caller can use," and that includes service accounts.	Revert to "each caller."
service-accounts.mdx:224-226	"A cluster administrator sets both in the gateway's chart values" links to the whole configure page. The relevant settings are in its Enable it section, around line 58 (budgets.acknowledgeUnmetered).	Link to configure-ai-gateway.mdx#enable-it.

---

What works well

• The This cluster bullet now gives the condition, the reason, and the alternative in one place. This is the right page for it, because this reader makes the choice.
• The rotation subsection is short, ordered, and scoped to both gateways. The 15-minute and 60-minute figures match the rest of the PR.
• The revocation section now flows well: suspend first, then the binding fallback caveat, then why deleting the ServiceAccount doesn't revoke tokens already issued.
• The new bullet in roll-out-gateway-clients.mdx mirrors the virtual key bullet, and the "act as a person" / "act on their own" contrast matches virtual-api-keys.mdx and the service accounts intro.

I didn't push any commits.

[peppescg]

@claude commit c5182ba addresses your re-review. Please check it once more with the same criteria and post one body-level comment. Don't push commits.

What changed, verified against stacklok-enterprise-platform v0.26.0:

• One issuer per URL. workload_trusts has a UNIQUE constraint on the issuer, and the directory returns "a workload trust for issuer … already exists". The Another issuer guidance now says each cluster needs a distinct issuer URL.
• This cluster. Each gateway reads in-cluster keys from the API server of its own cluster (workloadtrust/keysource.go, fetchInCluster), so the condition is that every gateway runs in the cluster that runs Stacklok Enterprise. Workloads in other clusters can still use their own Another issuer. I relaxed the "every gateway and every workload" wording to match, and Another issuer now covers every cluster, including that one, when gateways span clusters.
• Rotation links go straight to #rotate-an-issuers-signing-keys, and the duplicated condition is gone from configure-ai-gateway.mdx.
• The auth-type list now lives only in "What an account can reach" and in the Connector Gateway workloads page body. connector-policies.mdx, configure-connector-gateway.mdx, and the troubleshooting entry link to that section.
• The other secondary issues are fixed: the JWKS step 1 wording, the cluster administrator lead-in, "each caller", and the #enable-it link.

Still tracked in Keep in draft until, so don't re-raise them: #4933, #5519, and the v0.26.0 Helm reference sync.

[claude]

Claude finished @peppescg's task in 1m 16s —— View job

---

Third review: Document service accounts

Verdict: ready to merge once the draft blockers clear. c5182ba resolves both primary issues and all six secondary issues from the re-review. Two small wording problems came in with the reworked Trust the cluster's issuer step. Neither blocks the PR, but both are cheap to fix.

I skipped #4933, #5519, and the v0.26.0 Helm reference sync, as you asked. I still can't read stacklok-enterprise-platform from this runner, so I took the UNIQUE constraint and the fetchInCluster behavior from your description and checked everything else against this repo.

---

Re-review findings

#	Finding	Status
P1	"Its own" issuer URL lost, and the scope of Another issuer unclear	✅ Resolved. service-accounts.mdx:75-78 requires a distinct issuer URL per cluster, and :70-72 includes the cluster that runs Stacklok Enterprise when gateways span clusters. Scoping This cluster to where the gateways run (not the workloads) matches the key-source behavior you described, and the mixed case still works: gateways in cluster A, workloads in A and B, with A as This cluster and B as Another issuer.
P2	Auth-type list in five places	✅ Resolved. The full list now appears only in service-accounts.mdx:208-209 (canonical) and connector-gateway/kubernetes-workloads.mdx:91. connector-policies.mdx, configure-connector-gateway.mdx, and the troubleshooting entry link to #what-an-account-can-reach.
S	JWKS step 1 "alongside"	✅ Resolved
S	Cluster administrator lead-in for rotation	✅ Resolved
S	Rotation pointers linked to the parent section	✅ Resolved. Both configure pages link #rotate-an-issuers-signing-keys, and the anchor slug matches the heading.
S	Repeated This cluster condition in configure-ai-gateway.mdx	✅ Resolved
S	"each user" in ai-gateway/index.mdx	✅ Resolved
S	#enable-it link	✅ Resolved. The heading is at configure-ai-gateway.mdx:35.

The 30-second poll in "Both gateways pick up a new or changed issuer" (service-accounts.mdx:85-86) matches both configure pages (configure-ai-gateway.mdx:321, configure-connector-gateway.mdx:552).

---

New issues (minor)

1. "Another issuer trusts any other cluster" now contradicts the next sentence.
service-accounts.mdx:70-72: the bullet says Another issuer is for "any other cluster," then says to use it for "every cluster..., including the one that runs Stacklok Enterprise." Describe the option by how it works, not by which cluster it's for. For example: "Another issuer trusts a cluster by its public issuer URL and keys. Use it for every cluster other than the one that runs Stacklok Enterprise. When gateways run in more than one cluster, use it for that cluster too."

2. The This cluster reason covers only the shared-URL risk.
service-accounts.mdx:60-62 explains why a gateway in another cluster is unsafe when clusters share the default issuer URL. It doesn't say what happens when the URLs are distinct, which the next paragraph now requires. In that case, a gateway in another cluster can't verify this cluster's tokens, so these workloads are refused there. A reader whose clusters already have distinct URLs could decide the warning doesn't apply and pick This cluster anyway. Suggest stating both outcomes: "Each gateway reads the keys from the Kubernetes API of its own cluster. A gateway in another cluster can't verify this cluster's tokens, and when that cluster shares the issuer URL, it accepts its own cluster's tokens instead."

3. Changing --service-account-issuer affects the whole cluster.
service-accounts.mdx:76-78 tells a self-managed cluster to set a distinct --service-account-issuer without a caveat. That flag governs every projected token in the cluster. If the old value is replaced, the API server rejects tokens that pods already hold until the pods refresh them. Kubernetes accepts the flag more than once: it signs with the first value and accepts all of them. Suggest adding: "Add the new value as the first --service-account-issuer flag and keep the old one after it, so tokens already issued stay valid." Also, "Amazon EKS clusters already have one" is narrower than it needs to be. GKE also issues a per-cluster URL, so "Managed clusters such as Amazon EKS usually already have one" would read better. Please check the AKS behavior before you name it.

4. Nit: configure-connector-gateway.mdx:557-560.
"an account bound for the AI Gateway also reaches the connectors its groups are granted" now reads as unconditional, because the auth-type qualifier moved into the link. "can also reach the connectors its groups are granted" keeps the warning accurate without restating the list.

---

What works well

• The issuer section explains which option to pick, why, and what has to be true first (distinct URLs), all in the one place the directory admin reads.
• With the single-link pointers, the configure pages now just say what to set up in the cluster and link to the console steps.
• Each page that mentions the auth-type rule now only refers to it and links to "What an account can reach", so a new auth type needs one edit (plus the Connector Gateway workloads page body).

I didn't push any commits.

[peppescg]

@claude commit 15af88e adds content from a code audit against stacklok-enterprise-platform v0.26.0. Please review it with the same criteria (.claude/skills/review-docs-pr/SKILL.md and .claude/skills/docs-review/SKILL.md) and post one body-level review comment. Don't push commits.

What changed, with the code evidence:

• AI Gateway directory over TLS (configure-ai-gateway.mdx, new step 1 of "Accept service account workloads", plus a pointer in step 2 of "Bring it up in this order"). GetWorkloadTrustSnapshot is in the directory's tlsRequiredMethods (toolhive-enterprise/internal/directory/app/grpc.go). A cleartext caller gets FailedPrecondition "this RPC requires a TLS transport", so the gateway installs no issuer and workload tokens fall through to the OIDC path and get 401. Virtual keys and group resolution have no TLS requirement, which is why the existing cleartext bring-up stays as is for users. directory.caBundle.secretName / .key (default ca.crt) are in the ai-gateway-v2 chart since v0.24.0.
• Troubleshooting logs on both workloads pages. workload trust snapshot poll failed; keeping installed trusts until their validity runs out with a state attribute (gRPC code), logged by workloadauth/workloadtrust/adapter.go. workload trust dropped only fires after a successful snapshot, when installing an issuer fails. The AI Gateway prefixes both with ai-gateway-v2:, and the Connector Gateway has no prefix.
• Cedar (connector-policies.mdx, the Connector Gateway workloads page, and service-accounts.mdx). toolhive-enterprise/docs/design/connector-policy.md says an unconstrained permit (principal, action, resource); "admits every active account on a service-arm Connector, including an account in no group", because accounts share the Client principal with users and carry no claims.
• MCP session (Connector Gateway workloads page). The gateway is stateful (go-sdk streamable HTTP). Without Mcp-Session-Id, tools/list fails as "invalid during session initialization", and a missing Accept value gets 400.
• Console (service-accounts.mdx), from enterprise/toolhive-cloud-ui:
  • the account tabs Model Sets, Bindings, Budgets (conditional), and Connectors;
  • Edit service account;
  • Already trusted. once a This cluster issuer exists;
  • the Budget fields gated like the Budgets screen;
  • the Suspend confirmation;
  • type-to-confirm on delete.
• 403 rows now name suspended and deleted accounts (account_inactive and no_binding both resolve empty).

Already tracked in Keep in draft until, so don't re-raise them: #4933, #5519, and the v0.26.0 Helm reference sync.

[claude]

Claude finished @peppescg's task in 3m 19s —— View job

---

Fourth review: Document service accounts (15af88e)

Verdict: ready once the draft blockers clear. One placement fix in the new TLS step is worth making first. The audit additions are accurate where I could check them, and they fill real gaps. The TLS requirement explains a failure that would otherwise be silent: users and virtual keys keep working while every workload gets 401. The troubleshooting entries now separate "couldn't fetch issuers" from "couldn't install one". The main problem is that the new AI Gateway step sends an AI-Gateway-only administrator to the Connector Gateway page twice.

I skipped #4933, #5519, and the v0.26.0 Helm reference sync, as you asked. I still can't read stacklok-enterprise-platform or toolhive-cloud-ui from this runner. I took the tlsRequiredMethods, log message, Cedar, MCP session, and console evidence from your description. I checked everything else against this repo:

• Matches: directory.caBundle.secretName, the ca.crt default key, and reading the bundle again at every reconnect all match docs/platform/reference/helm/ai-gateway.mdx:581-601.
• Matches: The TLS dial needs directory.tokenProjection.enabled, which "Bring it up in this order" step 2 already sets.
• No extra rule needed: The <RELEASE_NAME>-enterprise-manager-directory NetworkPolicy already admits AI Gateway pods on both gRPC ports (deployment.mdx:669-676), so the switch to 9443 needs no new ingress rule.
• Anchors resolve: #troubleshooting on both workloads pages and #cedar-mode-connectors.
• Style: No em or en dashes in the touched pages.

---

Primary issues

1. The TLS step sends AI Gateway administrators to the Connector Gateway page for two shared settings
configure-ai-gateway.mdx:327-354, step 1 of "Accept service account workloads":

• The TLS listener link goes to the Connector Gateway page. That section itself points back to Encrypting stored credentials as the source for grpc.tls.
• The CA Secret link lands in the Connector Gateway's secrets section. Prepare the gateway's secrets is mostly about the KEK and authorization server keys. A reader who runs only the AI Gateway has to pick the CA Secret out of three Connector Gateway secrets.
• The endpoint host may not match the certificate. The example uses <ENTERPRISE_MANAGER_SERVICE>.<NAMESPACE>.svc:9443. The Connector Gateway example uses …svc.cluster.local:9443, and grpc.tls.existingSecret says "Its SANs must cover the Service name." If the certificate lists only one form, the poll fails with Unavailable and the step doesn't say why.

Ask:

• Link the TLS listener to deployment.mdx#encrypting-stored-credentials.
• Put the two-line kubectl create secret generic enterprise-manager-grpc-ca --from-file=ca.crt=./ca.crt command in the step, with the cert-manager caveat as one clause, or link to it.
• Add a sentence: "Use a host name that the Enterprise Manager's gRPC certificate covers." Use the same host form as the Connector Gateway example.

Fix this →

2. The Cedar warning gives only one way to fix the problem it describes
connector-policies.mdx:51-56: the paragraph warns that an unconstrained permit admits every active service account, including one in no group. The only fix it offers is conditioning on a token claim, which shuts out every service account and any user whose token lacks the claim. The more common goal is "admit these groups, users and accounts alike." The paragraph sets that up ("with its groups as parents") but doesn't follow through. As written, a reader who wants service accounts in group X, but not ungrouped ones, has no way forward.

Ask: Add one sentence on conditioning the principal on group membership, for example: "To admit only members of certain groups, users and service accounts alike, scope the principal to those groups." Please confirm the entity type name upstream before adding a code example. The two shorter mentions (connector-gateway/kubernetes-workloads.mdx:101-104, service-accounts.mdx:227-230) already link here, so this is a one-place fix.

---

Secondary issues

Location	Issue	Recommendation
connector-gateway/kubernetes-workloads.mdx:102-103	"a policy that reads a token claim admits none." A forbid or unless clause can read a claim without blocking anyone. connector-policies.mdx says "condition the policy on a token claim."	Use "a policy that requires a token claim admits none."
connector-gateway/kubernetes-workloads.mdx:108-110	The tool name is "the connector's name, a short hash, and the backend's own tool name." quickstart.mdx:81 calls the middle part "an ID." Your list of evidence doesn't cover this sentence.	Confirm the format upstream and use the same term on both pages.
ai-gateway/kubernetes-workloads.mdx:100, 401 row	The audit bullet now says the gateway "couldn't fetch or install" the issuer, but the table still says "couldn't install." The new cleartext case is a fetch failure.	Change the row to "couldn't fetch or install it." The Connector Gateway row has the same wording, but that gateway is always on TLS, so leaving it is fine.
Both workloads pages, troubleshooting	The two sibling entries describe the same states differently. The AI page says "missing from the issuer allowlist" and "Unavailable when it can't reach the directory or verify its certificate". The Connector page says "missing from workloadTrustSaSubjectAllowlist" and leaves out the certificate case, although that gateway also dials TLS.	Use the same wording on both: name the setting, and include certificate verification under Unavailable.
service-accounts.mdx:63-64	"You can add one such issuer; once it exists, the option shows Already trusted. For Issuer URL…": the label's period makes it run into the next instruction. The note also splits the explanation from the field instructions.	Move it to the end of the bullet, after the command: "Only one This cluster issuer can exist. Once it does, the option is marked Already trusted."
service-accounts.mdx:127-128 and :154	"when the console's Budgets screen is available, which requires the AI Gateway" and "Budgets when budgets are available" describe the same condition in two ways. "Requires the AI Gateway" doesn't say what about the AI Gateway: installed, enabled, or connected?	Name the condition once, for example "when the AI Gateway is enabled," and reuse it in both places.

---

What works well

• The TLS step explains a silent failure. Users and virtual keys keep working while workloads get 401, which is the hardest kind of failure to diagnose. The pointer from bring-up step 2 means a first-time reader finds it.
• The troubleshooting split helps diagnosis. snapshot poll failed covers the fetch, with a state per cause, and workload trust dropped covers the install. Including the ai-gateway-v2: prefix on one page and not the other lets a reader grep the right string.
• The Mcp-Session-Id paragraph covers hand-rolled HTTP clients. It names the request order and what fails without the header, and it keeps out of the way of readers using an MCP client library.
• The console additions are concrete. The 403 rows now cover suspended and deleted accounts, and the tab order, Edit service account, Suspend confirmation, and type-to-confirm delete match how the rest of the page names UI elements.

I didn't push any commits.

[peppescg]

@claude please review the latest commit (363db0b), which addresses your fourth review. As before, skip #4933, #5519, and the v0.26.0 Helm reference sync.

You can't read stacklok-enterprise-platform, so here is the evidence for the new claims, all at tag v0.26.0:

• TLS step host. enterprise/toolhive-enterprise/helm/templates/certificate-grpc-tls.yaml: the cert-manager Certificate (issued when grpc.tls.issuerRef is set and existingSecret isn't) lists every form of the Service name in dnsNames: <fullname>.<ns>.svc.cluster.local, <fullname>.<ns>.svc, <fullname>.<ns>, and <fullname>. For existingSecret, values.yaml says "Its SANs must cover the Service name". The example now uses svc.cluster.local, like the Connector Gateway example.
• TLS listener link. It now points to deployment.mdx#encrypting-stored-credentials, and the CA Secret command and cert-manager caveat are inline. No more Connector Gateway links in that step.
• Cedar group scoping. internal/directory/infra/policycedar/evaluate.go userGroupUIDs: the principal's parents are UserGroup::"<slug>", where the slug is the group's immutable groups.name. contracts/directory/v1/dto.go says Name is that slug and DisplayName is what the console shows, and that they can differ ("Engineering" can have the slug engineering-2). Hence the "name in the Enterprise Manager API" wording.
• Budgets condition. toolhive-cloud-ui/src/lib/ui-services.ts: budgetsRequirements = needsAll([services.gateway.isAvailable(), userManagementRequirements]), plus the directory admin check. service-overrides/gateway.ts: isAvailable is !!getGatewayProxyUrl(). config-server-client.ts: getGatewayProxyUrl() is undefined unless AI Gateway v2 is installed, then returns gateway.proxy_url from the Enterprise Manager config or GATEWAY_PROXY_URL, which the chart renders from global.stacklok.aiGatewayV2.url. The service account Budgets tab and the wizard use the same uiServices.budgets.isAvailableToCurrentUser(). The pages say "when the AI Gateway is enabled and its public URL is set" in both places, because anyone on the Service Accounts screen already meets the directory and admin conditions.
• "Already trusted." trusted-clusters-admin/components/cluster-location-field.tsx renders Already trusted. in place of the option's description when one exists.
• Tool names. The middle segment is now "an ID", matching quickstart.mdx.

[claude]

Claude finished @peppescg's task in 1m 18s —— View job

---

Fifth review: Document service accounts (363db0b)

Verdict: ready to merge once the draft blockers clear. 363db0b fixes both primary issues and all six secondary issues from the fourth review. I found one small accuracy gap in the new inline CA step, plus two nits. None of them block the PR.

As you asked, I skipped #4933, #5519, and the v0.26.0 Helm reference sync. I took the cert-manager dnsNames, the UserGroup slug, the budgets gating, and the Already trusted. evidence from your comment, and checked everything else against this repo.

---

Fourth-review findings

#	Finding	Status
P1	TLS step sent AI Gateway admins to Connector Gateway pages	✅ Resolved. The listener link now goes to deployment.mdx#encrypting-stored-credentials, and the anchor resolves to the #### heading at deployment.mdx:587. The CA Secret command is inline, and the endpoint uses svc.cluster.local like configure-connector-gateway.mdx:153. The new "Use a host name that the … certificate covers" sentence explains the failure that used to have no explanation. The step no longer links to any Connector Gateway page.
P2	Cedar warning gave only one fix	✅ Resolved. connector-policies.mdx:55-65 now gives the group-scoped permit and explains how the group's name differs from its console name. It keeps the token-claim option for "users only".
S	"reads a token claim"	✅ Resolved, now "requires a token claim"
S	Tool name middle segment	✅ Resolved. It now says "an ID", matching quickstart.mdx.
S	AI 401 row said "couldn't install" only	✅ Resolved, now "couldn't fetch or install"
S	Troubleshooting wording differed between the two workloads pages	✅ Resolved. Both pages now name workloadTrustSaSubjectAllowlist and include certificate verification under Unavailable.
S	Already trusted. ran into the next instruction	✅ Resolved. The sentence now comes after the command, and the period is outside the bold.
S	Budgets condition worded two ways	✅ Resolved. Both places now say "when the AI Gateway is enabled and its public URL is set", which matches the getGatewayProxyUrl() gate you described.

---

New issues (minor)

1. The AI Gateway CA step says a rotated CA needs no restart, but leaves out that the copy goes stale.
configure-ai-gateway.mdx:355-366 tells readers using cert-manager to copy ca.crt into enterprise-manager-grpc-ca, then says "The gateway reads the Secret again at every reconnect, so a rotated CA needs no restart." Both statements are true. But when cert-manager rotates the CA, the copy doesn't change, so the gateway keeps trusting the old CA. The TLS handshakes then fail with Unavailable, and every workload gets 401. The Connector Gateway page covers this right after the same command: "A copied Secret goes stale when cert-manager rotates the CA. For GitOps, keep the copy in sync automatically instead, for example with a trust-manager…" (configure-connector-gateway.mdx:105-107).

Ask: Add one sentence before the reconnect sentence, for example: "A copied Secret goes stale when cert-manager rotates the CA, so update it then, or keep it in sync with a tool such as trust-manager. The gateway reads the Secret again at every reconnect, so an updated CA needs no restart."

Fix this →

2. Nit: the page doesn't say where to find <GROUP_NAME>.
connector-policies.mdx:62-63 says the value is "the group's name in the Enterprise Manager API" and that it can differ from the console's name. The reader still has to work out how to look it up. The Enterprise Manager API link is two lines below, at the end of the next paragraph. Name the route that lists groups, or move the API link into this sentence. If the console shows the slug anywhere, such as in the URL of a group's page, say that instead. A placeholder such as <GROUP_SLUG> would also signal that this isn't the display name, but that's optional.

3. Nit: grpc.tls.issuerRef in the host-name sentence.
configure-ai-gateway.mdx:350-352: the values block above it sets enterprise-manager.grpc.tls.existingSecret, and deployment.mdx:612 says "set issuerRef.name for cert-manager." For consistency, write enterprise-manager.grpc.tls.issuerRef, or issuerRef.name, so the reader knows which key goes where in the values block.

---

What works well

• The TLS step stands on its own. An admin who runs only the AI Gateway can now finish it without leaving the page. It covers the port, the listener, the endpoint host, and the CA Secret, and links out only for the shared grpc.tls setup.
• The Cedar example is the right one. Group scoping is what most admins want: one policy for users and service accounts alike. The note about the immutable slug versus the console's display name heads off a mismatch that would otherwise be hard to find.
• The two troubleshooting sections now match. Both pages name the same setting and the same state values. The only differences are real ones: the AI Gateway's ai-gateway-v2: prefix and its FailedPrecondition case for the cleartext listener.

I didn't push any commits.

[danbarr]

Content approved. The model-discovery correction resolves my remaining finding, and I have no further editorial changes to request.

Please hold the merge until the documented service account behavior ships in the stable channel, including the console availability and 60-minute token ceiling. v0.25.0 is the current stable version; v0.26.0 is on the beta channel. The generated references should continue to follow stable releases and be synced when the corresponding version reaches stable.