You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds a documentation section for AI Gateway v2, the single-service implementation of the AI Gateway that is configured through Helm values instead of the AIGateway custom resource.
The new section lives at docs/ai-gateway-v2/ and mirrors the existing AI Gateway page set:
Overview, model providers, model routing and access, budgets and pricing, budgets in the console
An endpoints reference (AI Gateway v2 has no management API, so this replaces the management API reference)
A migration guide from the AI Gateway: running both side by side, a configuration mapping table, unsupported features, behavior differences, and cutover steps
It also adds platform/enterprise-platform/configure-ai-gateway-v2.mdx (install, identity provider trust, bring-up order, publishing the endpoint, per-client endpoints, network policy, disconnect behavior) and wires the section into the navbar, sidebars, platform overview, deployment flag table, client rollout page, and visual tests.
Content that applies to both gateways (budgets API, pricing catalog, spend monitoring, console budget flow, audit log shippers) moves into partials under docs/ai-gateway/_partials/ that both sections import. While moving it, two statements were corrected for both sections: the budgets endpoints are served by the Enterprise Manager API, and the baseline pricing catalog ships with Enterprise Manager rather than the gateway.
The pages document the upcoming release, so a few Helm values they reference (for example failureLogs and telemetry.spanAttributes) will appear in the generated Helm values reference at the next release sync.
Type of change
New documentation
Navigation/structure change
Related issues/PRs
None.
Screenshots
The navbar gains an "AI Gateway v2" entry, so the visual baselines need a refresh (/update-snapshots).
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
Require redaction or blocking before capturing sensitive prompts
docs/ai-gateway-v2/budgets-and-pricing.mdx:71
Enabling scanning alone doesn't ensure captured prompts are redacted. The scanning guide supports requestAction: log-only and scanning.ner.failureAction: fail-open; both can admit unredacted text with scanning enabled. Specify redaction or blocking for the sensitive entities and fail-closed behavior before enabling capture, rather than implying that the enable flag prevents sensitive content from being persisted.
Clarify AI Gateway trust setup despite unsupported CRD field
The blanket "Not supported" entry conflicts with the generated platform references. docs/platform/reference/helm/enterprise-manager.mdx:557-569 names AI Gateway v2 as a caller that fetches directory workload trusts to verify workload credentials, and docs/platform/reference/helm/platform.mdx:298-301 describes its default allowlist entry. Distinguish the unsupported CRD field from the directory-managed authentication replacement, and document the trust setup and gateway permissions needed before migrating workload callers.
Document unsupported Aadhaar and TFN recognizers
docs/ai-gateway-v2/pci-pii-controls.mdx:107
Listing IN_AADHAAR or AU_TFN does not enable detection: the bundled registry disables these recognizers, and selecting them fails the adapter rollout (docs/platform/reference/helm/ai-gateway.mdx:1158-1162). Document this restriction rather than recommending these entities; Presidio's supported-entity list is broader than the gateway's enabled set.
Thanks for the re-review. All three "previously missed" findings held up against platform main. Addressed in 5c2a0d7:
Require redaction or blocking before capturing sensitive prompts (budgets-and-pricing.mdx): the page now says to set the entities you need to keep out of storage to redact or block, and to keep scanning.ner.failureAction at fail-closed, before turning on budgets.capture. It also says capture stores log-only matches and fail-open requests as the caller sent them.
Document unsupported Aadhaar and TFN recognizers (pci-pii-controls.mdx): removed the IN_AADHAAR and AU_TFN example. The page now says most country-specific entities in the Presidio list ship with their recognizers turned off in the bundled registry, so listing one fails the adapter rollout, and points to custom recognizers instead.
Clarify AI Gateway trust setup despite unsupported CRD field (migrate-from-ai-gateway.mdx): agreed that "Not supported" was misleading. We're holding off on documenting workload callers for now, so I removed the spec.auth.workloadIssuers row rather than describing the replacement. For consistency, I also removed the other content that depends on workload callers: service account budgets in the shared budgets partial and the service account case in the budgets 403 cause.
The reason will be displayed to describe this comment to others. Learn more.
Blocking on the information architecture before this gets further through review.
Customers bought an AI Gateway from us. If the replacement implementation is production-ready and recommended for new deployments, we should document it as the current AI Gateway and place the existing Envoy-based implementation under a legacy path. There should be one AI Gateway navbar entry and one sidebar, with the current implementation's guides directly available there.
The firm requirement is one AI Gateway top-level navigation entry. Version labels such as "v1" and "v2" are reasonable within that section: customers understand versioning, and "v2" matches the chart name operators use during deployment. Separate v1/v2 sidebar groups within AI Gateway remain an option. The concern is presenting the versions as separate products in the top-level navigation, rather than the version terminology itself. The replacement's internal codename doesn't need to become customer-facing terminology.
The product decision we need to confirm is whether the replacement is production-ready and the recommended gateway for new deployments. If it is, my preferred starting point is current guides at the canonical paths, with the existing implementation in a subordinate section. The file and sidebar layouts below illustrate that approach; "legacy" is a working label, and we can use v1/v2 labels and version-specific paths within the single AI Gateway section if that better matches the supported deployment experience:
The unqualified /ai-gateway/... task URLs would document the current implementation. Existing implementation-specific content would move under /ai-gateway/legacy/.... Shared budget administration, pricing, spend reporting, and console workflows should each have one canonical reader-facing home. The shared partials are useful, but identical operations don't need duplicate pages. Gateway-specific budget connection, verification, and failure behavior belong in the corresponding budget-enforcement.mdx guides.
The sidebar would look like:
AI Gateway
├── Overview
├── Configure and deploy
├── Model providers
├── Model routing and access
├── Manage budgets
├── Budgets and pricing
├── Budget enforcement
├── Prompt injection screening
├── PCI/PII controls
├── Audit log forwarding
├── Telemetry
├── Reference
│ └── Endpoints reference
├── Migrate from the legacy gateway
└── Legacy gateway
├── Overview and deployment identification
├── Configure and deploy
├── Model providers
├── Model routing
├── Budget enforcement
├── Prompt injection screening
├── PCI/PII controls
├── Audit log forwarding
├── Telemetry
└── Management API reference
The deployment guides can remain under docs/platform/enterprise-platform/: configure-ai-gateway.mdx would document the current implementation, with the existing implementation's instructions under legacy/configure-ai-gateway.mdx. Link each from its corresponding sidebar location and update the platform deployment guidance consistently.
Existing customers need a visible pointer from the current overview and affected task pages to the legacy instructions, including how to identify their deployment. Update inbound links according to which implementation they describe. Add redirects for retired URLs where there is no replacement page at that address; a canonical task URL reused for the current implementation must remain available rather than redirecting to legacy content.
I'd reserve synchronized tabs for small differences within an otherwise shared procedure. Provider setup, routing capabilities, credential rotation, and operational behavior differ enough that whole-page tabs would obscure which instructions apply.
I'm taking the readiness/recommended-deployment decision, version naming, and support status to Slack for product direction. Both a current/legacy structure and explicit v1/v2 groups within the existing AI Gateway section remain open. If the replacement is still a preview, we should retain the supported implementation as the default until that changes. Either way, a second top-level "AI Gateway v2" entry should not ship.
@danbarr thanks for the review, agreed on all of it. 5ca949e restructures the docs along the lines you suggested:
One AI Gateway navbar entry and one sidebar. The new implementation is now the AI Gateway at the unqualified /ai-gateway/... URLs, and reader-facing prose no longer says "v2". Literal chart and value names (ai-gateway-v2, global.stacklok.aiGatewayV2.enabled) keep it, since readers type those.
The operator-based implementation lives under /ai-gateway/legacy/..., plus platform/enterprise-platform/legacy/configure-ai-gateway. The sidebar matches your layout, with "Legacy gateway" as a collapsed category at the bottom.
Budgets have one canonical home: manage-budgets (console) and budgets-and-pricing (API, pricing, spend). Each gateway gets a budget-enforcement page for its own connection, verification, and failure behavior.
Every legacy page opens with a pointer to its current counterpart and to a new "Identify your deployment" section on the legacy overview. Current task pages point back to their legacy counterparts, and the current overview has a short "Legacy gateway" section.
Inbound links across the platform, directory, and connector gateway pages point at the implementation they describe. /ai-gateway/api-reference is the only retired URL, so it redirects to /ai-gateway/legacy/api-reference. Every other reused task URL now serves the current implementation.
No whole-page tabs.
"Legacy AI Gateway" on first mention and "the legacy gateway" after that are used consistently, so renaming it once the Slack thread settles is a single sweep. Same for the readiness call: if it lands on preview, the swap is mostly reversible since the page shapes now match.
One thing still outside this PR: the generated Helm reference pages mention "AI Gateway v2" and the internal codename. Those come from the upstream chart comments, so the fix has to land there.
Move the budgets API, pricing catalog, spend monitoring, console budget
flow, and audit shipper sections into partials so a second gateway
section can reuse them. The budgets endpoints are served by Enterprise
Manager, so the examples use an Enterprise Manager placeholder.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alejandro Ponce <aponcedeleonch@stacklok.com>
Add a self-contained section for AI Gateway v2 that mirrors the AI
Gateway page set: providers, routing and model access, budgets,
screening, audit logs, telemetry, an endpoints reference, and a
migration guide. Add a platform setup page and wire the section into
the navbar, sidebars, platform overview, and visual tests.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alejandro Ponce <aponcedeleonch@stacklok.com>
Make status codes, egress rules, value path conventions, and the
migration mapping agree across the AI Gateway v2 pages and the setup
page, and document where scan decisions land in audit records.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Alejandro Ponce <aponcedeleonch@stacklok.com>
The shared partials carried over errors from the v1 pages. Pricing
writes go through per-entry PUT with If-Match, budget subjects are
directory UUIDs, and the Fluent Bit and Promtail filters dropped
every audit record. Also cover service account budgets and bulk
import precedence, which exist on platform main.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Add the cluster OIDC issuer and groupsResolutionIssuer to setup,
document disconnect through the API since the console hides it for
v2-only installs, and correct migration mappings, error tables, and
failure classes against source. Also apply repo style conventions.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Snapshot capture also persists bodies, ready pods don't prove a
working budgets or provider setup, and removing a provider's Secret
must wait for the rollout so old pods keep their credentials.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Capture stores log-only matches and fail-open requests unredacted, so
turning on scanning alone doesn't protect captured bodies. Name the
settings that do.
Most country-specific Presidio recognizers ship disabled in the bundled
registry, so listing IN_AADHAAR or AU_TFN fails the adapter rollout
rather than enabling detection.
Drop service account caller content (budgets, 403 cause, and the
workloadIssuers migration row) until workload callers are documented.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trim operational detail the v1 pages don't carry: reason-code, span,
metric, and error tables, troubleshooting entries without a v1
counterpart, and repeated rollout explanations, which now live once in
"How configuration changes apply". Keep sections for v2-only features.
Fill v1 gaps where v2 behaves the same, verified against platform main:
NIST audit fields, the Kubernetes API audit log pointer, Vertex region
and credential notes, the Connector Gateway link, the directory
namespace note, content screening posture, and the private CA note.
Restore the v1 organization default sentence dropped in 5c2a0d7, and
fix the budgets probe check, since a first-try success logs nothing.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Document the new implementation as the AI Gateway at the unqualified
/ai-gateway URLs and move the operator-based implementation under
/ai-gateway/legacy, with one navbar entry and one sidebar. Reader-facing
prose no longer says "v2"; literal chart and value names keep it.
Budgets get one shared home (budgets-and-pricing, manage-budgets), and
each gateway gets a budget-enforcement page for its own connection and
verification steps. The legacy setup page moves to
platform/enterprise-platform/legacy/configure-ai-gateway.
Every legacy page carries a pointer to its current counterpart and to a
new "Identify your deployment" section, and current task pages point
back to their legacy counterparts. The retired management API URL
redirects to its legacy location.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A samplingRate of 0 keeps every root span, and a sampled inbound
traceparent is always kept, so the rate is not a fixed fraction of
traffic. The migration guide also lacked a mapping for the legacy
directoryGrpcEndpoint group label lookup.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The gateway dials TLS by default and trusts only the system store, but
the directory listener it calls is cleartext on 9091, so the examples
without insecure: true failed every directory call and refused all
traffic. Match the dev and staging setup: port 9091, insecure: true,
and a projected token, which the gateway still sends.
Also scope the virtual API key management API note to the legacy
gateway, which is the only one that deploys it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Title the operator chart references as legacy and the gateway chart as
the AI Gateway, in the hand-written Helm index, the sidebar, and the
upstream-projects config that sets the generated titles at the next
release sync.
The legacy setup page now names clusterOidcIssuer alongside the
allowlist step, since the Enterprise Manager verifies the legacy
gateway's ServiceAccount tokens against it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a documentation section for AI Gateway v2, the single-service implementation of the AI Gateway that is configured through Helm values instead of the
AIGatewaycustom resource.The new section lives at
docs/ai-gateway-v2/and mirrors the existing AI Gateway page set:It also adds
platform/enterprise-platform/configure-ai-gateway-v2.mdx(install, identity provider trust, bring-up order, publishing the endpoint, per-client endpoints, network policy, disconnect behavior) and wires the section into the navbar, sidebars, platform overview, deployment flag table, client rollout page, and visual tests.Content that applies to both gateways (budgets API, pricing catalog, spend monitoring, console budget flow, audit log shippers) moves into partials under
docs/ai-gateway/_partials/that both sections import. While moving it, two statements were corrected for both sections: the budgets endpoints are served by the Enterprise Manager API, and the baseline pricing catalog ships with Enterprise Manager rather than the gateway.The pages document the upcoming release, so a few Helm values they reference (for example
failureLogsandtelemetry.spanAttributes) will appear in the generated Helm values reference at the next release sync.Type of change
Related issues/PRs
None.
Screenshots
The navbar gains an "AI Gateway v2" entry, so the visual baselines need a refresh (
/update-snapshots).Submitter checklist
Content and formatting
Navigation
sidebars.ts) updated for added, deleted, reordered, or renamed filesvercel.jsonfor moved, renamed, or deleted pages (no URLs changed, so none needed)Reviewer checklist
Content
🤖 Generated with Claude Code
Visual regression screenshots
Auto-generated by CI from
scripts/pr-screenshot-summary.mjs— edits inside this block are overwritten on the next push.🟡 Changed
/diff
diff
/theme-previewdiff