| id | api_references |
|---|---|
| title | API Reference |
| toc_min_heading_level | 2 |
| toc_max_heading_level | 4 |
Package v1alpha1 contains API schema definitions for the aigateway.envoyproxy.io API group.
- AIGatewayRoute
- AIGatewayRouteList
- AIServiceBackend
- AIServiceBackendList
- BackendSecurityPolicy
- BackendSecurityPolicyList
- GatewayConfig
- GatewayConfigList
- MCPRoute
- MCPRouteList
- QuotaPolicy
- QuotaPolicyList
Appears in:
AIGatewayRoute combines multiple AIServiceBackends and attaching them to Gateway(s) resources.
This serves as a way to define a "unified" AI API for a Gateway which allows downstream clients to use a single schema API to interact with multiple AI backends.
Envoy AI Gateway will generate the following k8s resources corresponding to the AIGatewayRoute:
- HTTPRoute of the Gateway API as a top-level resource to bind all backends. The name of the HTTPRoute is the same as the AIGatewayRoute.
- HTTPRouteFilter of the Envoy Gateway API per namespace for automatic hostname rewrite.
The name of the HTTPRouteFilter is
ai-eg-host-rewrite-${AIGatewayRoute.Name}.
All of these resources are created in the same namespace as the AIGatewayRoute. Note that this is the implementation detail subject to change. If you want to customize the default behavior of the Envoy AI Gateway, you can use these resources as a reference and create your own resources. Alternatively, you can use EnvoyPatchPolicy API of the Envoy Gateway to patch the generated resources. For example, you can configure the retry fallback behavior by attaching BackendTrafficPolicy API of Envoy Gateway to the generated HTTPRoute.
AIGatewayRouteList contains a list of AIGatewayRoute.
Appears in:
AIServiceBackend is a resource that represents a single backend for AIGatewayRoute. A backend is a service that handles traffic with a concrete API specification.
A AIServiceBackend is "attached" to a Backend which is either a k8s Service or a Backend resource of the Envoy Gateway.
When a backend with an attached AIServiceBackend is used as a routing target in the AIGatewayRoute (more precisely, the HTTPRouteSpec defined in the AIGatewayRoute), the ai-gateway will generate the necessary configuration to do the backend specific logic in the final HTTPRoute.
AIServiceBackendList contains a list of AIServiceBackends.
Appears in:
BackendSecurityPolicy specifies configuration for authentication and authorization rules on the traffic exiting the gateway to the backend.
BackendSecurityPolicyList contains a list of BackendSecurityPolicy
Appears in:
GatewayConfig provides configuration for the AI Gateway external processor container that is deployed alongside the Gateway.
A GatewayConfig is referenced by a Gateway via the annotation "aigateway.envoyproxy.io/gateway-config". The GatewayConfig must be in the same namespace as the Gateway that references it.
This allows gateway-level configuration of the external processor, including environment variables (e.g., for tracing configuration) and resource requirements.
Multiple Gateways can reference the same GatewayConfig to share configuration.
Environment Variable Precedence: When merging environment variables, the following precedence applies (highest to lowest):
- GatewayConfig.Spec.ExtProc.Kubernetes.Env (this resource)
- Global controller flags (extProcExtraEnvVars)
If the same environment variable name exists in both sources, the GatewayConfig value takes precedence.
GatewayConfigList contains a list of GatewayConfig.
Appears in:
MCPRoute defines how to route MCP requests to the backend MCP servers.
This serves as a way to define a "unified" AI API for a Gateway which allows downstream clients to use a single schema API to interact with multiple MCP backends.
MCPRouteList contains a list of MCPRoute.
Appears in:
QuotaPolicy specifies token quota configuration for inference services. Generates rate limit configuration and tracks quota usage. Reject requests with 429 once all related quota to that request has been exceeded.
QuotaPolicyList contains a list of QuotaPolicy
- AIGatewayRouteRule
- AIGatewayRouteRuleBackendRef
- AIGatewayRouteRuleMatch
- AIGatewayRouteSpec
- AIGatewayRouteStatus
- AIServiceBackendSpec
- AIServiceBackendStatus
- APISchema
- AWSCredentialsFile
- AWSOIDCExchangeToken
- AzureOIDCExchangeToken
- BackendSecurityPolicyAPIKey
- BackendSecurityPolicyAWSCredentials
- BackendSecurityPolicyAnthropicAPIKey
- BackendSecurityPolicyAzureAPIKey
- BackendSecurityPolicyAzureCredentials
- BackendSecurityPolicyGCPCredentials
- BackendSecurityPolicyOIDC
- BackendSecurityPolicySpec
- BackendSecurityPolicyStatus
- BackendSecurityPolicyType
- GCPCredentialsFile
- GCPOIDCExchangeToken
- GCPServiceAccountImpersonationConfig
- GCPWorkloadIdentityFederationConfig
- GCPWorkloadIdentityProvider
- GatewayConfigExtProc
- GatewayConfigSpec
- GatewayConfigStatus
- HTTPBodyField
- HTTPBodyMutation
- HTTPHeaderMutation
- JWKS
- JWTSource
- LLMRequestCost
- LLMRequestCostType
- MCPAuthorizationSource
- MCPAuthorizationTarget
- MCPBackendAPIKey
- MCPBackendSecurityPolicy
- MCPHeaderForward
- MCPRouteAuthorization
- MCPRouteAuthorizationRule
- MCPRouteBackendRef
- MCPRouteOAuth
- MCPRouteSecurityPolicy
- MCPRouteSpec
- MCPRouteStatus
- MCPToolFilter
- PerModelQuota
- ProtectedResourceMetadata
- QuotaBucketMode
- QuotaDefinition
- QuotaPolicySpec
- QuotaPolicyStatus
- QuotaRule
- QuotaValue
- ServiceQuotaDefinition
- ToolCall
- VersionedAPISchema
Appears in:
AIGatewayRouteRule is a rule that defines the routing behavior of the AIGatewayRoute.
https://gateway.envoyproxy.io/docs/tasks/traffic/failover/ as well as
https://gateway.envoyproxy.io/docs/tasks/traffic/retry/."
/>https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRouteMatch"
/>
Appears in:
AIGatewayRouteRuleBackendRef is a reference to a backend with a weight. It can reference either an AIServiceBackend or an InferencePool resource.
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.BackendRef
Default is 1."
/>https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/priority
Note: This will override the `faillback` property of the underlying Envoy Gateway Backend
This field is ignored when referencing InferencePool resources.
Default is 0."
/>
Appears in:
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPHeaderMatch" />
Appears in:
AIGatewayRouteSpec details the AIGatewayRoute configuration.
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRouteSpec
for the details of the Hostnames field in the Gateway API."
/>https://gateway-api.sigs.k8s.io/api-types/httproute/).
AI Gateway controller will generate a HTTPRoute based on the configuration given here with the additional
modifications to achieve the necessary jobs, notably inserting the AI Gateway filter responsible for
the transformation of the request and response, etc.
In the matching conditions in the AIGatewayRouteRule, `x-ai-eg-model` header is available
if we want to describe the routing behavior based on the model name. The model name is extracted
from the request content before the routing decision.
How multiple rules are matched is the same as the Gateway API. See for the details:
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRoute
At most 15 rules are allowed per AIGatewayRoute, corresponding to the Gateway API's limit on
HTTPRoute.spec.rules (one slot is reserved for a controller-injected catch-all rule). To
configure more rules on the same Gateway, split them across multiple AIGatewayRoute resources."
/>
Appears in:
AIGatewayRouteStatus contains the conditions by the reconciliation result.
Appears in:
AIServiceBackendSpec details the AIServiceBackend configuration.
https://github.com/envoyproxy/issues/902 for more details.
This is required to be set."
/>
Appears in:
AIServiceBackendStatus contains the conditions by the reconciliation result.
Underlying type: string
Appears in:
APISchema defines the API schema.
https://github.com/openai/openai-openapi
"
/>https://docs.cohere.com/v2
"
/>https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html
"
/>https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#api-specs
"
/>https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.endpoints/generateContent?hl=en
"
/>https://docs.anthropic.com/en/api/claude-on-vertex-ai
"
/>https://docs.claude.com/en/home
"
/>https://aws.amazon.com/bedrock/anthropic/
https://docs.claude.com/en/api/claude-on-amazon-bedrock
"
/>
Appears in:
AWSCredentialsFile specifies the credentials file to use for the AWS provider. Envoy reads the secret file, and the profile to use is specified by the Profile field.
Appears in:
AWSOIDCExchangeToken specifies credentials to obtain oidc token from a sso server. For AWS, the controller will query STS to obtain AWS AccessKeyId, SecretAccessKey, and SessionToken, and store them in a temporary credentials file.
Appears in:
AzureOIDCExchangeToken specifies credentials to obtain oidc token from a sso server. For Azure, the controller will query Azure Entra ID to get an Azure Access Token, and store them in a secret.
Appears in:
BackendSecurityPolicyAPIKey specifies the API key.
Appears in:
BackendSecurityPolicyAWSCredentials contains the supported authentication mechanisms to access AWS.
When neither CredentialsFile nor OIDCExchangeToken is specified, the AWS SDK's default credential chain will be used. This automatically supports various authentication methods in the following order:
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
- EKS Pod Identity - automatically rotates credentials for pods in EKS clusters
- IAM Roles for Service Accounts (IRSA) - injects credentials via mounted service account tokens
- EC2 instance metadata (IAM instance roles)
- ECS task roles
The default credential chain is recommended for Kubernetes deployments as it supports automatic credential rotation without manual configuration. Credentials are refreshed automatically when they approach expiration (typically hourly for IRSA and Pod Identity).
Appears in:
BackendSecurityPolicyAnthropicAPIKey specifies the Anthropic API key.
Appears in:
BackendSecurityPolicyAzureAPIKey specifies the Azure OpenAI API key.
Appears in:
BackendSecurityPolicyAzureCredentials contains the supported authentication mechanisms to access Azure. Only one of ClientSecretRef or OIDCExchangeToken must be specified. Credentials will not be generated if neither are set.
Appears in:
BackendSecurityPolicyGCPCredentials contains the supported authentication mechanisms to access GCP.
Appears in:
BackendSecurityPolicyOIDC specifies OIDC related fields.
Appears in:
BackendSecurityPolicySpec specifies authentication rules on access the provider from the Gateway. Only one mechanism to access a backend(s) can be specified.
Only one type of BackendSecurityPolicy can be defined.
https://docs.claude.com/en/api/overview#authentication" />
Appears in:
BackendSecurityPolicyStatus contains the conditions by the reconciliation result.
Underlying type: string
Appears in:
BackendSecurityPolicyType specifies the type of auth mechanism used to access a backend.
Appears in:
GCPCredentialsFile specifies the service account key json file to authenticate with GCP provider.
Appears in:
Appears in:
Appears in:
https://cloud.google.com/iam/docs/workload-identity-federation?hl=en" />
Appears in:
GatewayConfigExtProc holds runtime-specific configuration for the external processor.
Appears in:
GatewayConfigSpec defines the configuration for the AI Gateway.
Appears in:
GatewayConfigStatus defines the observed state of GatewayConfig.
Appears in:
HTTPBodyField represents a JSON field name and value for body mutation
Appears in:
HTTPBodyMutation defines the mutation of HTTP request body JSON fields that will be applied to the request
Appears in:
HTTPHeaderMutation defines the mutation of HTTP headers that will be applied to the request
https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
Input:
GET /foo HTTP/1.1
my-header1: foo
my-header2: bar
my-header3: baz
Config:
remove: [`my-header1`, `my-header3`]
Output:
GET /foo HTTP/1.1
my-header2: bar"
/>
Appears in:
JWKS defines how to obtain JSON Web Key Sets (JWKS) either from a remote HTTP/HTTPS endpoint or from a local source.
Appears in:
JWTSource defines the MCP authorization source for JWT tokens. At least one of scopes or claims must be provided. Scopes and claims are AND-ed: when both are specified, both sets must match.
Appears in:
LLMRequestCost configures each request cost.
Underlying type: string
Appears in:
LLMRequestCostType specifies the type of the LLMRequestCost.
Appears in:
MCPAuthorizationSource defines the source of an authorization rule.
Appears in:
MCPAuthorizationTarget defines the target of an authorization rule.
Appears in:
MCPBackendAPIKey defines the configuration for the API Key Authentication to a backend.
When both header and queryParam are unspecified, the API key will be injected into the "Authorization" header by default.
Appears in:
MCPBackendSecurityPolicy defines the security policy for a backend MCP server.
Appears in:
MCPHeaderForward specifies a header to extract from the incoming request and forward to a backend.
Appears in:
MCPRouteAuthorization defines the authorization configuration for a MCPRoute.
Appears in:
MCPRouteAuthorizationRule defines an authorization rule for MCPRoute based on the MCP authorization spec. Reference: https://modelcontextprotocol.io/specification/draft/basic/authorization#scope-challenge-handling
Appears in:
MCPRouteBackendRef wraps a EG's BackendObjectReference to reference an MCP server.
Appears in:
MCPRouteOAuth defines a MCP spec compatible OAuth authentication configuration for a MCPRoute. Reference: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-audience-binding-and-validation" />
Appears in:
MCPRouteSecurityPolicy defines the security policy for a MCPRoute.
Appears in:
MCPRouteSpec details the MCPRoute configuration.
https://api.example.com/mcp`,
and the Envoy AI Gateway will route the requests to the appropriate MCP server based on the requests.
All names must be unique within this list to avoid potential tools, resources, etc. name collisions.
Also, cross-namespace references are not supported. In other words, the backend MCP servers must be in the
same namespace as the MCPRoute."
/>
Appears in:
MCPRouteStatus contains the conditions by the reconciliation result.
Appears in:
MCPToolFilter filters tools using include and exclude patterns with exact matches or regular expressions. Exclude rules take precedence over include rules (deny-wins). When both include and exclude are specified, a tool must match an include rule AND not match any exclude rule to be allowed.
Appears in:
Appears in:
ProtectedResourceMetadata represents the Protected Resource Metadata of the MCP server as per RFC 9728.
References:
- https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location
- https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata
https://api.example.com/mcp`, the Resource should be `https://api.example.com/mcp`." />
Underlying type: string
Appears in:
QuotaBucketMode specifies whether the default and per request buckets values are exclusive or inclusive.
Appears in:
QuotaDefinition specified expression for computing request cost and rules for matching requests to quota buckets.
Appears in:
QuotaPolicySpec specifies rules for computing token based costs of requests.
Appears in:
QuotaPolicyStatus contains the conditions by the reconciliation result.
Appears in:
Appears in:
QuotaValue defines the quota limits using sliding window.
Appears in:
Appears in:
ToolCall represents a tool call in the MCP authorization target.
Appears in:
VersionedAPISchema defines the API schema of either AIGatewayRoute (the input) or AIServiceBackend (the output).
This allows the ai-gateway to understand the input and perform the necessary transformation depending on the API schema pair (input, output).
Note that this is vendor specific, and the stability of the API schema is not guaranteed by the ai-gateway, but by the vendor via proper versioning.
https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#rest-api-versioning).
This field is ignored for OpenAI, AWSBedrock, GCPVertexAI, and Anthropic.
For OpenAI and Anthropic, use prefix to configure custom request paths.
See https://aigateway.envoyproxy.io/docs/capabilities/llm-integrations/supported-providers for details."
/>https://ai.google.dev/gemini-api/docs/openai) uses
`/v1beta/openai` prefix. Another example is that Cohere AI (https://docs.cohere.com/v2/docs/compatibility-api)
uses `/compatibility/v1` prefix. On the other hand, DeepSeek (https://api-docs.deepseek.com/) doesn't
use prefix, so you can leave this field unset.
See https://aigateway.envoyproxy.io/docs/capabilities/llm-integrations/supported-providers for details."
/>
Package v1beta1 contains API schema definitions for the aigateway.envoyproxy.io API group. This is the beta version of the API, preferred over v1alpha1 for new resources.
- AIGatewayRoute
- AIGatewayRouteList
- AIServiceBackend
- AIServiceBackendList
- BackendSecurityPolicy
- BackendSecurityPolicyList
- GatewayConfig
- GatewayConfigList
- MCPRoute
- MCPRouteList
Appears in:
AIGatewayRoute combines multiple AIServiceBackends and attaching them to Gateway(s) resources.
This serves as a way to define a "unified" AI API for a Gateway which allows downstream clients to use a single schema API to interact with multiple AI backends.
Envoy AI Gateway will generate the following k8s resources corresponding to the AIGatewayRoute:
- HTTPRoute of the Gateway API as a top-level resource to bind all backends. The name of the HTTPRoute is the same as the AIGatewayRoute.
- HTTPRouteFilter of the Envoy Gateway API per namespace for automatic hostname rewrite.
The name of the HTTPRouteFilter is
ai-eg-host-rewrite-${AIGatewayRoute.Name}.
All of these resources are created in the same namespace as the AIGatewayRoute. Note that this is the implementation detail subject to change. If you want to customize the default behavior of the Envoy AI Gateway, you can use these resources as a reference and create your own resources. Alternatively, you can use EnvoyPatchPolicy API of the Envoy Gateway to patch the generated resources. For example, you can configure the retry fallback behavior by attaching BackendTrafficPolicy API of Envoy Gateway to the generated HTTPRoute.
AIGatewayRouteList contains a list of AIGatewayRoute.
Appears in:
AIServiceBackend is a resource that represents a single backend for AIGatewayRoute. A backend is a service that handles traffic with a concrete API specification.
A AIServiceBackend is "attached" to a Backend which is either a k8s Service or a Backend resource of the Envoy Gateway.
When a backend with an attached AIServiceBackend is used as a routing target in the AIGatewayRoute (more precisely, the HTTPRouteSpec defined in the AIGatewayRoute), the ai-gateway will generate the necessary configuration to do the backend specific logic in the final HTTPRoute.
AIServiceBackendList contains a list of AIServiceBackends.
Appears in:
BackendSecurityPolicy specifies configuration for authentication and authorization rules on the traffic exiting the gateway to the backend.
BackendSecurityPolicyList contains a list of BackendSecurityPolicy
Appears in:
GatewayConfig provides configuration for the AI Gateway external processor container that is deployed alongside the Gateway.
A GatewayConfig is referenced by a Gateway via the annotation "aigateway.envoyproxy.io/gateway-config". The GatewayConfig must be in the same namespace as the Gateway that references it.
This allows gateway-level configuration of the external processor, including environment variables (e.g., for tracing configuration) and resource requirements.
Multiple Gateways can reference the same GatewayConfig to share configuration.
Environment Variable Precedence: When merging environment variables, the following precedence applies (highest to lowest):
- GatewayConfig.Spec.ExtProc.Kubernetes.Env (this resource)
- Global controller flags (extProcExtraEnvVars)
If the same environment variable name exists in both sources, the GatewayConfig value takes precedence.
GatewayConfigList contains a list of GatewayConfig.
Appears in:
MCPRoute defines how to route MCP requests to the backend MCP servers.
This serves as a way to define a "unified" AI API for a Gateway which allows downstream clients to use a single schema API to interact with multiple MCP backends.
MCPRouteList contains a list of MCPRoute.
- AIGatewayRouteRule
- AIGatewayRouteRuleBackendRef
- AIGatewayRouteRuleMatch
- AIGatewayRouteSpec
- AIGatewayRouteStatus
- AIServiceBackendSpec
- AIServiceBackendStatus
- APISchema
- AWSCredentialsFile
- AWSOIDCExchangeToken
- AzureOIDCExchangeToken
- BackendSecurityPolicyAPIKey
- BackendSecurityPolicyAWSCredentials
- BackendSecurityPolicyAnthropicAPIKey
- BackendSecurityPolicyAzureAPIKey
- BackendSecurityPolicyAzureCredentials
- BackendSecurityPolicyGCPCredentials
- BackendSecurityPolicyOIDC
- BackendSecurityPolicySpec
- BackendSecurityPolicyStatus
- BackendSecurityPolicyType
- GCPCredentialsFile
- GCPOIDCExchangeToken
- GCPServiceAccountImpersonationConfig
- GCPWorkloadIdentityFederationConfig
- GCPWorkloadIdentityProvider
- GatewayConfigExtProc
- GatewayConfigSpec
- GatewayConfigStatus
- HTTPBodyField
- HTTPBodyMutation
- HTTPHeaderMutation
- JWKS
- JWTSource
- LLMRequestCost
- LLMRequestCostType
- MCPAuthorizationSource
- MCPAuthorizationTarget
- MCPBackendAPIKey
- MCPBackendSecurityPolicy
- MCPHeaderForward
- MCPRouteAuthorization
- MCPRouteAuthorizationRule
- MCPRouteBackendRef
- MCPRouteOAuth
- MCPRouteSecurityPolicy
- MCPRouteSpec
- MCPRouteStatus
- MCPToolFilter
- ProtectedResourceMetadata
- ToolCall
- VersionedAPISchema
Appears in:
AIGatewayRouteRule is a rule that defines the routing behavior of the AIGatewayRoute.
https://gateway.envoyproxy.io/docs/tasks/traffic/failover/ as well as
https://gateway.envoyproxy.io/docs/tasks/traffic/retry/."
/>https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRouteMatch"
/>
Appears in:
AIGatewayRouteRuleBackendRef is a reference to a backend with a weight. It can reference either an AIServiceBackend or an InferencePool resource.
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.BackendRef
Default is 1."
/>https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/upstream/load_balancing/priority
Note: This will override the `faillback` property of the underlying Envoy Gateway Backend
This field is ignored when referencing InferencePool resources.
Default is 0."
/>
Appears in:
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPHeaderMatch" />
Appears in:
AIGatewayRouteSpec details the AIGatewayRoute configuration.
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRouteSpec
for the details of the Hostnames field in the Gateway API."
/>https://gateway-api.sigs.k8s.io/api-types/httproute/).
AI Gateway controller will generate a HTTPRoute based on the configuration given here with the additional
modifications to achieve the necessary jobs, notably inserting the AI Gateway filter responsible for
the transformation of the request and response, etc.
In the matching conditions in the AIGatewayRouteRule, `x-ai-eg-model` header is available
if we want to describe the routing behavior based on the model name. The model name is extracted
from the request content before the routing decision.
How multiple rules are matched is the same as the Gateway API. See for the details:
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io%2fv1.HTTPRoute
At most 15 rules are allowed per AIGatewayRoute, corresponding to the Gateway API's limit on
HTTPRoute.spec.rules (one slot is reserved for a controller-injected catch-all rule). To
configure more rules on the same Gateway, split them across multiple AIGatewayRoute resources."
/>
Appears in:
AIGatewayRouteStatus contains the conditions by the reconciliation result.
Appears in:
AIServiceBackendSpec details the AIServiceBackend configuration.
https://github.com/envoyproxy/issues/902 for more details.
This is required to be set."
/>
Appears in:
AIServiceBackendStatus contains the conditions by the reconciliation result.
Underlying type: string
Appears in:
APISchema defines the API schema.
https://github.com/openai/openai-openapi
"
/>https://docs.cohere.com/v2
"
/>https://docs.aws.amazon.com/bedrock/latest/APIReference/API_Operations_Amazon_Bedrock_Runtime.html
"
/>https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#api-specs
"
/>https://cloud.google.com/vertex-ai/docs/reference/rest/v1/projects.locations.endpoints/generateContent?hl=en
"
/>https://docs.anthropic.com/en/api/claude-on-vertex-ai
"
/>https://docs.claude.com/en/home
"
/>https://aws.amazon.com/bedrock/anthropic/
https://docs.claude.com/en/api/claude-on-amazon-bedrock
"
/>
Appears in:
AWSCredentialsFile specifies the credentials file to use for the AWS provider. Envoy reads the secret file, and the profile to use is specified by the Profile field.
Appears in:
AWSOIDCExchangeToken specifies credentials to obtain oidc token from a sso server. For AWS, the controller will query STS to obtain AWS AccessKeyId, SecretAccessKey, and SessionToken, and store them in a temporary credentials file.
Appears in:
AzureOIDCExchangeToken specifies credentials to obtain oidc token from a sso server. For Azure, the controller will query Azure Entra ID to get an Azure Access Token, and store them in a secret.
Appears in:
BackendSecurityPolicyAPIKey specifies the API key.
Appears in:
BackendSecurityPolicyAWSCredentials contains the supported authentication mechanisms to access AWS.
When neither CredentialsFile nor OIDCExchangeToken is specified, the AWS SDK's default credential chain will be used. This automatically supports various authentication methods in the following order:
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
- EKS Pod Identity - automatically rotates credentials for pods in EKS clusters
- IAM Roles for Service Accounts (IRSA) - injects credentials via mounted service account tokens
- EC2 instance metadata (IAM instance roles)
- ECS task roles
The default credential chain is recommended for Kubernetes deployments as it supports automatic credential rotation without manual configuration. Credentials are refreshed automatically when they approach expiration (typically hourly for IRSA and Pod Identity).
Appears in:
BackendSecurityPolicyAnthropicAPIKey specifies the Anthropic API key.
Appears in:
BackendSecurityPolicyAzureAPIKey specifies the Azure OpenAI API key.
Appears in:
BackendSecurityPolicyAzureCredentials contains the supported authentication mechanisms to access Azure. Only one of ClientSecretRef or OIDCExchangeToken must be specified. Credentials will not be generated if neither are set.
Appears in:
BackendSecurityPolicyGCPCredentials contains the supported authentication mechanisms to access GCP.
When neither CredentialsFile nor WorkloadIdentityFederationConfig is specified, Application Default Credentials (ADC) will be used. This supports GKE Workload Identity, environment variables, and default service account credentials when running on GCP.
Appears in:
BackendSecurityPolicyOIDC specifies OIDC related fields.
Appears in:
BackendSecurityPolicySpec specifies authentication rules on access the provider from the Gateway. Only one mechanism to access a backend(s) can be specified.
Only one type of BackendSecurityPolicy can be defined.
https://docs.claude.com/en/api/overview#authentication" />
Appears in:
BackendSecurityPolicyStatus contains the conditions by the reconciliation result.
Underlying type: string
Appears in:
BackendSecurityPolicyType specifies the type of auth mechanism used to access a backend.
Appears in:
GCPCredentialsFile specifies the service account key json file to authenticate with GCP provider.
Appears in:
Appears in:
Appears in:
https://cloud.google.com/iam/docs/workload-identity-federation?hl=en" />
Appears in:
GatewayConfigExtProc holds runtime-specific configuration for the external processor.
Appears in:
GatewayConfigSpec defines the configuration for the AI Gateway.
Appears in:
GatewayConfigStatus defines the observed state of GatewayConfig.
Appears in:
HTTPBodyField represents a JSON field name and value for body mutation
Appears in:
HTTPBodyMutation defines the mutation of HTTP request body JSON fields that will be applied to the request
Appears in:
HTTPHeaderMutation defines the mutation of HTTP headers that will be applied to the request
https://datatracker.ietf.org/doc/html/rfc2616#section-4.2).
Input:
GET /foo HTTP/1.1
my-header1: foo
my-header2: bar
my-header3: baz
Config:
remove: [`my-header1`, `my-header3`]
Output:
GET /foo HTTP/1.1
my-header2: bar"
/>
Appears in:
JWKS defines how to obtain JSON Web Key Sets (JWKS) either from a remote HTTP/HTTPS endpoint or from a local source.
Appears in:
JWTSource defines the MCP authorization source for JWT tokens. At least one of scopes or claims must be provided. Scopes and claims are AND-ed: when both are specified, both sets must match.
Appears in:
LLMRequestCost configures each request cost.
Underlying type: string
Appears in:
LLMRequestCostType specifies the type of the LLMRequestCost.
Appears in:
MCPAuthorizationSource defines the source of an authorization rule.
Appears in:
MCPAuthorizationTarget defines the target of an authorization rule.
Appears in:
MCPBackendAPIKey defines the configuration for the API Key Authentication to a backend.
When both header and queryParam are unspecified, the API key will be injected into the "Authorization" header by default.
Appears in:
MCPBackendSecurityPolicy defines the security policy for a backend MCP server.
Appears in:
MCPHeaderForward specifies a header to extract from the incoming request and forward to a backend.
Appears in:
MCPRouteAuthorization defines the authorization configuration for a MCPRoute.
Appears in:
MCPRouteAuthorizationRule defines an authorization rule for MCPRoute based on the MCP authorization spec. Reference: https://modelcontextprotocol.io/specification/draft/basic/authorization#scope-challenge-handling
Appears in:
MCPRouteBackendRef wraps a EG's BackendObjectReference to reference an MCP server.
Appears in:
MCPRouteOAuth defines a MCP spec compatible OAuth authentication configuration for a MCPRoute. Reference: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization
https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#token-audience-binding-and-validation" />
Appears in:
MCPRouteSecurityPolicy defines the security policy for a MCPRoute.
Appears in:
MCPRouteSpec details the MCPRoute configuration.
https://api.example.com/mcp`,
and the Envoy AI Gateway will route the requests to the appropriate MCP server based on the requests.
All names must be unique within this list to avoid potential tools, resources, etc. name collisions.
Also, cross-namespace references are not supported. In other words, the backend MCP servers must be in the
same namespace as the MCPRoute."
/>
Appears in:
MCPRouteStatus contains the conditions by the reconciliation result.
Appears in:
MCPToolFilter filters tools using include and exclude patterns with exact matches or regular expressions. Exclude rules take precedence over include rules (deny-wins). When both include and exclude are specified, a tool must match an include rule AND not match any exclude rule to be allowed.
Appears in:
ProtectedResourceMetadata represents the Protected Resource Metadata of the MCP server as per RFC 9728.
References:
- https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#authorization-server-location
- https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata
https://api.example.com/mcp`, the Resource should be `https://api.example.com/mcp`." />
Appears in:
ToolCall represents a tool call in the MCP authorization target.
Appears in:
VersionedAPISchema defines the API schema of either AIGatewayRoute (the input) or AIServiceBackend (the output).
This allows the ai-gateway to understand the input and perform the necessary transformation depending on the API schema pair (input, output).
Note that this is vendor specific, and the stability of the API schema is not guaranteed by the ai-gateway, but by the vendor via proper versioning.
https://learn.microsoft.com/en-us/azure/ai-services/openai/reference#rest-api-versioning).
This field is ignored for OpenAI, AWSBedrock, GCPVertexAI, and Anthropic.
For OpenAI and Anthropic, use prefix to configure custom request paths.
See https://aigateway.envoyproxy.io/docs/capabilities/llm-integrations/supported-providers for details."
/>https://ai.google.dev/gemini-api/docs/openai) uses
`/v1beta/openai` prefix. Another example is that Cohere AI (https://docs.cohere.com/v2/docs/compatibility-api)
uses `/compatibility/v1` prefix. On the other hand, DeepSeek (https://api-docs.deepseek.com/) doesn't
use prefix, so you can leave this field unset.
See https://aigateway.envoyproxy.io/docs/capabilities/llm-integrations/supported-providers for details."
/>