[Automated] Draft docs (agentgateway): feat(controller): select the CA bundle key in AgentgatewayPolicy CA refs (+2 related)

[github-actions]

Feature clusters

These pull requests document one feature between them:

Cluster	Pull requests	Product	Why grouped
c2	agentgateway/agentgateway#3419, agentgateway/agentgateway#3449, agentgateway/agentgateway#3618	agentgateway	both are drafted into content/docs/kubernetes/main/documentation/operations/debug.md, the only page a code-path rule names for one of them, so separate pull requests would conflict

Worked in another repository as well. This does not hold the cluster: a different repository documents itself in a different product's tree, on a schedule this run does not control. Listed so the other work is not a surprise later:

Cluster	Also worked by	What it is
c2	#1039	Docs for per-key rate limits and certificate key and metrics (merged)

Draft a documentation change

agentgateway/agentgateway#3419 — feat(controller): select the CA bundle key in AgentgatewayPolicy CA refs

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: kubernetes/main
• Code issue: Allow selecting the CA bundle key in AgentgatewayPolicy.backend.tls.caCertificateRefs instead of hardcoding ca.crt agentgateway#3418
• Summary (read from the body): This PR adds the support of ca bundle key configuration in certificate references. Up to now, it always (and only) resolved ca.crt key in the configured Secret / ConfigMap. This is now a configurable key, with default value of ca.crt if omitted for backward compatibility.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 2 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • controller/pkg/agentgateway/cacert/ca.go
  • controller/pkg/agentgateway/remotehttp/ca_bundle.go

agentgateway/agentgateway#3618 — guardrails: add fail open/fail closed polciy to all types

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): guardrails: add fail open/fail closed polciy to all types
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 1 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • api/resource.pb.go

New configuration: no page mentions it yet

agentgateway/agentgateway#3449 — feat(aws): add support for externalId in assumeRole

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: standalone/main, kubernetes/main
• Summary (read from the body): Add an optional externalId to backendAuth.aws.assumeRole
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 3 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • api/resource.pb.go
  • crates/agentgateway/src/http/auth/aws.rs
  • crates/agentgateway/src/http/auth/tests.rs

Warnings

• feat(aws): add support for externalId in assumeRole agentgateway#3449: re-drafting because it was named on this run, though its earlier draft is open ([Automated] Draft docs (agentgateway): feat(aws): add support for externalId in assumeRole #1100). Nothing removes the earlier entry; the new draft replaces it in the ledger when it opens.

agentgateway/agentgateway#3419, #3449, #3618 — CA key selection, AWS External ID, and guardrail failure modes

• Product: agentgateway (upstream) → agentgateway/website
• Docs version: kubernetes/main for #3419; standalone/main and kubernetes/main for #3449 and #3618. These are development trees for unreleased changes.

agentgateway/agentgateway#3419 adds a key selector to backend TLS CA certificate references, #3449 adds assumeRole.externalId to AWS backend authentication, and #3618 adds failureMode to cloud provider guardrails. The CA key behavior was already documented in the target checkout by the merged website sibling, so this draft leaves that page unchanged. This draft adds assumeRole.externalId to the AWS authentication examples and field tables, with the STS length and character limits. It also documents provider failure handling for prompt guards, including the new fail-closed default for provider errors and the failOpen/FailOpen override values.

How agentgateway-3419 was drafted, and what was not verified

agentgateway/agentgateway#3419, #3449, #3618 — CA key selection, AWS External ID, and guardrail failure modes

• Code PR: feat(controller): select the CA bundle key in AgentgatewayPolicy CA refs agentgateway#3419, feat(aws): add support for externalId in assumeRole agentgateway#3449, guardrails: add fail open/fail closed polciy to all types agentgateway#3618
• Code issue: Allow selecting the CA bundle key in AgentgatewayPolicy.backend.tls.caCertificateRefs instead of hardcoding ca.crt agentgateway#3418 for #3419; none linked for #3449 or #3618
• Product: agentgateway (upstream) → agentgateway/website
• Docs version: kubernetes/main for #3419; standalone/main and kubernetes/main for #3449 and #3618. These are development trees for unreleased changes.
• Category: cluster of scoped-edit and new-feature items / pr
• Possibly incomplete: Docs for per-key rate limits and certificate key and metrics #1039 also worked issue #3418 and was already merged; I used only the local target checkout and dossier facts.

Plan, and what changed it

• Planned: Document the CA key selector, AWS assumeRole.externalId, and guardrail provider failureMode in the pages that own those tasks.
• Learned: assets/agw-docs/pages/security/backendtls.md already documents the CA key behavior from Docs for per-key rate limits and certificate key and metrics #1039, while the AWS authentication pages and guardrail overview pages did not cover the new fields.
• Did: Added the AWS External ID and provider failure-mode docs, wrote no CA-key page edit, and wrote a collected release-note entry for the cluster.

Why a documentation change is necessary

#3449 adds externalId to AWS AssumeRole configuration in both the Kubernetes CRDs and the standalone schema, and the existing AWS backend authentication guides listed the other AssumeRole fields without this one. The body and diff also state the validation limits and that the value is part of the credential cache key, which readers need when they configure trust policies that require sts:ExternalId.

#3618 adds failureMode to OpenAI moderation, Bedrock Guardrails, Google Model Armor, and standalone Azure Content Safety guards. The guardrail overviews explained action: audit but did not say what happens when a provider call fails, and the diff changes the fallback from fail open to fail closed for provider errors.

What changed on disk

• assets/agw-docs/pages/security/backend-authn-aws.md: Added the Kubernetes assumeRole.externalId example and field-table row behind a main-only version gate.
• assets/agw-docs/pages/security/backend-authn-aws-standalone.md: Added the standalone assumeRole.externalId example and field-table row behind a main-only version gate.
• content/docs/kubernetes/main/documentation/llm/guardrails/overview.md: Added the Provider failures section with the Kubernetes FailClosed/FailOpen values.
• content/docs/standalone/main/documentation/llm/prompt-guards/overview.md: Added the Provider failures section with the standalone failClosed/failOpen values.

How to verify this change

1. In a Kubernetes main environment that includes these code changes, apply an AgentgatewayPolicy with spec.backend.auth.aws.assumeRole.externalId: tenant-a:prod/12345; kubectl apply --dry-run=server -f <file> accepts the field.
2. In the same Kubernetes environment, apply an AgentgatewayPolicy with spec.backend.ai.promptGuard.request[].openAIModeration.failureMode: FailOpen; kubectl apply --dry-run=server -f <file> accepts the enum value.
3. In a standalone main environment that includes these code changes, run agentgateway --validate-only -f <file> for a config with backendAuth.aws.assumeRole.externalId: tenant-a:prod/12345 and llm.policies.guardrails.request[].openAIModeration.failureMode: failOpen; validation succeeds.
4. For #3419, apply an AgentgatewayPolicy or AgentgatewayBackend with tls.caCertificateRefs[].key set to a key other than ca.crt; kubectl get <resource> -o yaml shows the configured key, and traffic to a backend that uses that CA succeeds.

Proposed release note

A note is needed because #3419 and #3449 add feature surface and #3618 changes observable provider-error behavior by defaulting these guardrail provider failures to fail closed.

What was not verified

The configuration was not applied to a cluster, so every command in this draft is unrun. The #3449 and #3618 diffs are truncated; each cut falls inside the last shown file with no additional files below it by name, so content past the cut was not verified.

Release notes

This pull request also adds its release-note entries:

• content/docs/kubernetes/main/release-notes/release-notes.md: Backend authentication and guardrail controls (feature)

Draft branch: pr-tracker-draft-agentgateway-3419-plus2

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. Doc tests, link checking and the static checks are held as action_required until somebody presses Approve and run on the Checks tab. Cloudflare Pages and DCO are GitHub Apps rather than Actions, so those two do run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[cloudflare-workers-and-pages]

Deploying agentproxy with    Cloudflare Pages

Latest commit:	e851f78
Status:	⚡️  Build in progress...

View logs