diff --git a/assets/agw-docs/pages/agentgateway/llm/virtual-keys.md b/assets/agw-docs/pages/agentgateway/llm/virtual-keys.md index 33960caae..8ac335b4c 100644 --- a/assets/agw-docs/pages/agentgateway/llm/virtual-keys.md +++ b/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:` 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 | diff --git a/assets/agw-docs/pages/reference/agctl/main/agctl-migrate.md b/assets/agw-docs/pages/reference/agctl/main/agctl-migrate.md new file mode 100644 index 000000000..7de03613e --- /dev/null +++ b/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 + diff --git a/assets/agw-docs/pages/reference/agctl/main/agctl.md b/assets/agw-docs/pages/reference/agctl/main/agctl.md index 01e23217d..f59728bad 100644 --- a/assets/agw-docs/pages/reference/agctl/main/agctl.md +++ b/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 diff --git a/assets/agw-docs/pages/reference/api/api-main.md b/assets/agw-docs/pages/reference/api/api-main.md index 92fd94d20..befc645ff 100644 --- a/assets/agw-docs/pages/reference/api/api-main.md +++ b/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.
When omitted, default Google credential discovery is used. | | Optional: \{\}
| | `oauthTokenExchange` _[OAuthTokenExchange](#oauthtokenexchange)_ | OAuth 2.0 token exchange (RFC 8693) / jwt-bearer (RFC 7523) authentication. | | Optional: \{\}
| | `crossAppAccess` _[CrossAppAccessAuth](#crossappaccessauth)_ | Cross App Access (Identity Assertion / ID-JAG) authentication. | | Optional: \{\}
| -| `location` _[AuthorizationLocation](#authorizationlocation)_ | Where backend credentials are inserted. Defaults to the `Authorization`
header with the `Bearer ` prefix. Applies to `key`, `secretRef`, and
`passthrough`. | | ExactlyOneOf: [header queryParameter cookie]
Optional: \{\}
| +| `location` _[AuthorizationLocation](#authorizationlocation)_ | Where backend credentials are inserted.
If omitted, credentials are written to the `Authorization` header with the `Bearer ` prefix.
This applies to `key`, `secretRef`, and `passthrough`. Entries in `credentials` carry their own location. | | ExactlyOneOf: [header queryParameter cookie]
Optional: \{\}
| +| `credentials` _[BackendAuthCredential](#backendauthcredential) array_ | Credentials is a list of additional credentials to inject on the
backend request. Each entry resolves a Secret key and writes its value
to the entry's location. `credentials` is independent of the primary
`key`/`secretRef`/`passthrough` mechanism and may be set on its own or
alongside it. | | MaxItems: 8
MinItems: 1
Optional: \{\}
| + + +#### 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]
Required: \{\}
| +| `secretRef` _[LocalSecretKeyRef](#localsecretkeyref)_ | SecretRef references a Kubernetes Secret holding the credential value, and
optionally overrides the key read from it. Defaults to `Authorization`,
matching the key convention used by the top-level `secretRef`. | | Required: \{\}
| #### BackendAuthPassthrough @@ -1087,7 +1107,7 @@ _Appears in:_ | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend
When set, TLS is originated to the backend using the system trusted CA
certificates, and SNI is inferred from the destination. | | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: \{\}
| | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend | | Optional: \{\}
| | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` | | Optional: \{\}
| -| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| +| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| | `ai` _[BackendAI](#backendai)_ | Settings for AI workloads. This is only applicable when
connecting to a `Backend` of type `ai`. | | Optional: \{\}
| | `mcp` _[BackendMCP](#backendmcp)_ | Settings for MCP workloads. This is only applicable when
connecting to a `Backend` of type `mcp`. | | Optional: \{\}
| | `transformation` _[Transformation](#transformation)_ | Mutates and transforms requests and responses sent to and from the backend. | | Optional: \{\}
| @@ -1155,7 +1175,7 @@ _Appears in:_ | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend
When set, TLS is originated to the backend using the system trusted CA
certificates, and SNI is inferred from the destination. | | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: \{\}
| | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend | | Optional: \{\}
| | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` | | Optional: \{\}
| -| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| +| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| #### BackendTCP @@ -1249,7 +1269,7 @@ _Appears in:_ | `tls` _[BackendTLS](#backendtls)_ | Settings for managing TLS connections to the backend
When set, TLS is originated to the backend using the system trusted CA
certificates, and SNI is inferred from the destination. | | AtMostOneOf: [verifySubjectAltNames insecureSkipVerify]
Optional: \{\}
| | `http` _[BackendHTTP](#backendhttp)_ | Settings for managing HTTP requests to the backend | | Optional: \{\}
| | `tunnel` _[BackendTunnel](#backendtunnel)_ | Settings for managing tunnel connections to the backend, like `HTTPS_PROXY` | | Optional: \{\}
| -| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | ExactlyOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| +| `auth` _[BackendAuth](#backendauth)_ | Settings for managing authentication to the backend | | AtMostOneOf: [key secretRef passthrough aws azure gcp oauthTokenExchange crossAppAccess]
Optional: \{\}
| | `ai` _[BackendAI](#backendai)_ | Settings for AI workloads. This is only applicable when
connecting to a `Backend` of type `ai`. | | Optional: \{\}
| | `transformation` _[Transformation](#transformation)_ | Mutates and transforms requests and responses sent to and from the backend. | | Optional: \{\}
| | `health` _[Health](#health)_ | Settings for passive and active health checking. | | Optional: \{\}
| @@ -2891,6 +2911,7 @@ location-specific default key is used. _Appears in:_ - [BackendAuth](#backendauth) +- [BackendAuthCredential](#backendauthcredential) - [BasicAuthentication](#basicauthentication) - [BedrockGuardrailsAuth](#bedrockguardrailsauth) - [GcpAuth](#gcpauth) diff --git a/assets/agw-docs/pages/reference/api/main/agentgateway.dev_agentgatewaybackends.yaml.html b/assets/agw-docs/pages/reference/api/main/agentgateway.dev_agentgatewaybackends.yaml.html index 0dfaaf630..7c8add4a1 100644 --- a/assets/agw-docs/pages/reference/api/main/agentgateway.dev_agentgatewaybackends.yaml.html +++ b/assets/agw-docs/pages/reference/api/main/agentgateway.dev_agentgatewaybackends.yaml.html @@ -1012,1506 +1012,1566 @@
  • workloadIdentityobject
    • -
  • crossAppAccess
    • -
  • gcp
    • -
  • keystring
    • -
  • location