Merge pull request #780 from agentgateway/ref-docs-main

[Automated] Update reference docs (main) from agentgateway main

Author: artberger

assets/agw-docs/pages/agentgateway/llm/virtual-keys.md

@@ -58,6 +58,8 @@ Store your virtual keys in a Kubernetes ConfigMap, with one entry per user. Beca
 
 > [!IMPORTANT]
 > ConfigMaps with hashed keys (as opposed to Secrets) are the recommended way to store virtual keys. If you need to use Kubernetes Secrets, refer to the [API key authentication guide]({{< link-hextra path="/security/apikey/" >}}) for an example.
+>
+> Already storing virtual keys in a Secret? Instead of recreating them by hand, use the [`agctl migrate`]({{< link-hextra path="/reference/agctl/agctl-migrate/" >}}) command to convert your existing Secrets into the recommended ConfigMap format.
 
 1. Generate a `sha256:<hex>` hash for each user's API key. The hash is computed over the exact key bytes, so do not include a trailing newline.
 
@@ -95,6 +97,9 @@ Store your virtual keys in a Kubernetes ConfigMap, with one entry per user. Beca
    EOF
    ```
 
+   > [!TIP]
+   > If you already store virtual keys in a Kubernetes Secret, you do not have to build this ConfigMap by hand. Use the [`agctl migrate`]({{< link-hextra path="/reference/agctl/agctl-migrate/" >}}) command to generate an equivalent ConfigMap (with hashed keys) from your existing Secrets, for example `agctl migrate --apply virtualkeys-to-configmap -n {{< reuse "agw-docs/snippets/namespace.md" >}} | kubectl apply -f -`.
+
    {{% reuse "agw-docs/snippets/review-table.md" %}}
 
    | Setting     | Description |

assets/agw-docs/pages/reference/agctl/main/agctl-migrate.md

@@ -0,0 +1,43 @@
+Migrate agentgateway resources to newer configurations
+
+### Synopsis
+
+Migrate agentgateway resources to newer configurations.
+
+Prints the changes as YAML by default; pass --write to apply them to the cluster.
+
+Available migrations:
+  virtualkeys-to-configmap
+
+```
+agctl migrate [flags]
+```
+
+### Examples
+
+```
+agctl migrate --apply virtualkeys-to-configmap -n my-namespace | kubectl apply -f -
+agctl migrate --apply virtualkeys-to-configmap -n my-namespace > migration.yaml
+agctl migrate --apply virtualkeys-to-configmap -n my-namespace --write
+```
+
+### Options
+
+```
+      --apply strings      migrations to run, comma-separated (virtualkeys-to-configmap)
+  -h, --help               help for migrate
+  -n, --namespace string   Namespace to migrate resources in
+      --policy string      virtualkeys-to-configmap: only migrate the named resource (default: all matching resources in the namespace)
+      --write              apply the changes to the cluster (default: print YAML)
+```
+
+### Options inherited from parent commands
+
+```
+  -k, --kubeconfig string   kubeconfig
+```
+
+### SEE ALSO
+
+* [agctl](../agctl/)	 - agctl controls and inspects Agentgateway resources
+

assets/agw-docs/pages/reference/agctl/main/agctl.md

@@ -11,6 +11,7 @@ agctl controls and inspects Agentgateway resources
 
 * [agctl controller](../agctl-controller/)	 - Inspect and manage the agentgateway controller
 * [agctl costs](../agctl-costs/)	 - Manage model cost catalogs
+* [agctl migrate](../agctl-migrate/)	 - Migrate agentgateway resources to newer configurations
 * [agctl proxy](../agctl-proxy/)	 - Inspect and manage the agentgateway proxy
 * [agctl version](../agctl-version/)	 - Print agctl version information
 

assets/agw-docs/pages/reference/api/api-main.md

@@ -679,6 +679,7 @@ _Validation:_
 
 _Appears in:_
 - [BackendAuth](#backendauth)
+- [BackendAuthCredential](#backendauthcredential)
 - [BedrockGuardrailsAuth](#bedrockguardrailsauth)
 - [OAuthTokenExchange](#oauthtokenexchange)
 - [OpenAIModerationAuth](#openaimoderationauth)
@@ -996,7 +997,7 @@ _Appears in:_
 
 
 _Validation:_
-- ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
+- AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
 
 _Appears in:_
 - [BackendFull](#backendfull)
@@ -1013,7 +1014,26 @@ _Appears in:_
 | `gcp` _[GcpAuth](#gcpauth)_ | Google authentication method for the backend.<br />When omitted, default Google credential discovery is used. |  | Optional: \{\} <br /> |
 | `oauthTokenExchange` _[OAuthTokenExchange](#oauthtokenexchange)_ | OAuth 2.0 token exchange (RFC 8693) / jwt-bearer (RFC 7523) authentication. |  | Optional: \{\} <br /> |
 | `crossAppAccess` _[CrossAppAccessAuth](#crossappaccessauth)_ | Cross App Access (Identity Assertion / ID-JAG) authentication. |  | Optional: \{\} <br /> |
-| `location` _[AuthorizationLocation](#authorizationlocation)_ | Where backend credentials are inserted. Defaults to the `Authorization`<br />header with the `Bearer ` prefix. Applies to `key`, `secretRef`, and<br />`passthrough`. |  | ExactlyOneOf: [header queryParameter cookie] <br />Optional: \{\} <br /> |
+| `location` _[AuthorizationLocation](#authorizationlocation)_ | Where backend credentials are inserted.<br />If omitted, credentials are written to the `Authorization` header with the `Bearer ` prefix.<br />This applies to `key`, `secretRef`, and `passthrough`. Entries in `credentials` carry their own location. |  | ExactlyOneOf: [header queryParameter cookie] <br />Optional: \{\} <br /> |
+| `credentials` _[BackendAuthCredential](#backendauthcredential) array_ | Credentials is a list of additional credentials to inject on the<br />backend request. Each entry resolves a Secret key and writes its value<br />to the entry's location. `credentials` is independent of the primary<br />`key`/`secretRef`/`passthrough` mechanism and may be set on its own or<br />alongside it. |  | MaxItems: 8 <br />MinItems: 1 <br />Optional: \{\} <br /> |
+
+
+#### BackendAuthCredential
+
+
+
+BackendAuthCredential specifies one additional credential to inject on the
+backend request.
+
+
+
+_Appears in:_
+- [BackendAuth](#backendauth)
+
+| Field | Description | Default | Validation |
+| --- | --- | --- | --- |
+| `location` _[AuthorizationLocation](#authorizationlocation)_ | Where the credential is inserted on the backend request. |  | ExactlyOneOf: [header queryParameter cookie] <br />Required: \{\} <br /> |
+| `secretRef` _[LocalSecretKeyRef](#localsecretkeyref)_ | SecretRef references a Kubernetes Secret holding the credential value, and<br />optionally overrides the key read from it. Defaults to `Authorization`,<br />matching the key convention used by the top-level `secretRef`. |  | Required: \{\} <br /> |
 
 
 #### BackendAuthPassthrough
@@ -1087,7 +1107,7 @@ _Appears in:_
 | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend<br />When set, TLS is originated to the backend using the system trusted CA<br />certificates, and SNI is inferred from the destination. |  | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify] <br />Optional: \{\} <br /> |
 | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend |  | Optional: \{\} <br /> |
 | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` |  | Optional: \{\} <br /> |
-| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
+| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
 | `ai` _[BackendAI](#backendai)_ | Settings for AI workloads. This is only applicable when<br />connecting to a `Backend` of type `ai`. |  | Optional: \{\} <br /> |
 | `mcp` _[BackendMCP](#backendmcp)_ | Settings for MCP workloads. This is only applicable when<br />connecting to a `Backend` of type `mcp`. |  | Optional: \{\} <br /> |
 | `transformation` _[Transformation](#transformation)_ | Mutates and transforms requests and responses sent to and from the backend. |  | Optional: \{\} <br /> |
@@ -1155,7 +1175,7 @@ _Appears in:_
 | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend<br />When set, TLS is originated to the backend using the system trusted CA<br />certificates, and SNI is inferred from the destination. |  | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify] <br />Optional: \{\} <br /> |
 | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend |  | Optional: \{\} <br /> |
 | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` |  | Optional: \{\} <br /> |
-| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
+| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
 
 
 #### BackendTCP
@@ -1249,7 +1269,7 @@ _Appears in:_
 | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend<br />When set, TLS is originated to the backend using the system trusted CA<br />certificates, and SNI is inferred from the destination. |  | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify] <br />Optional: \{\} <br /> |
 | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend |  | Optional: \{\} <br /> |
 | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` |  | Optional: \{\} <br /> |
-| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
+| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend |  | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess] <br />Optional: \{\} <br /> |
 | `ai` _[BackendAI](#backendai)_ | Settings for AI workloads. This is only applicable when<br />connecting to a `Backend` of type `ai`. |  | Optional: \{\} <br /> |
 | `transformation` _[Transformation](#transformation)_ | Mutates and transforms requests and responses sent to and from the backend. |  | Optional: \{\} <br /> |
 | `health` _[Health](#health)_ | Settings for passive and active health checking. |  | Optional: \{\} <br /> |
@@ -2891,6 +2911,7 @@ location-specific default key is used.
 
 _Appears in:_
 - [BackendAuth](#backendauth)
+- [BackendAuthCredential](#backendauthcredential)
 - [BasicAuthentication](#basicauthentication)
 - [BedrockGuardrailsAuth](#bedrockguardrailsauth)
 - [GcpAuth](#gcpauth)