feat: aws auth sdk default chain (#1394)

**Description**

This PR updates the AWS authentication handler to support the AWS SDK’s
default credential chain, enabling native integration with modern AWS
identity providers like IRSA (IAM Roles for Service Accounts) and EKS
Pod Identity.

Previously, credentials had to be explicitly provided via config
literals. Now, if no credential file is set, the handler automatically
falls back to config.LoadDefaultConfig, which supports:

- IRSA (EKS service accounts)
- EKS Pod Identity
- EC2 Instance Profiles
- Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
- Shared credentials files (~/.aws/credentials)

This simplifies AWS deployments and aligns with best practices by
avoiding static credentials.
This makes it much easier to deploy the AI Gateway on AWS infrastructure
while
following AWS security best practices by avoiding static credentials.

The PR includes:

- Refactored AWS authentication handler to use the default credential
chain when no credentials file is provided
- Added example configs for IRSA and EKS Pod Identity
- Updated documentation with setup guides for both methods
- Extended tests to cover the new credential resolution logic
- Update API documentation

**Related Issues/PRs (if applicable)**

#568

---------

Signed-off-by: José Luis Jiménez Quereda <[email protected]>

Author: seluard

api/v1alpha1/backendsecurity_policy.go

@@ -268,20 +268,34 @@ type AzureOIDCExchangeToken struct {
 	BackendSecurityPolicyOIDC `json:",inline"`
 }
 
-// BackendSecurityPolicyAWSCredentials contains the supported authentication mechanisms to access aws.
+// 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:
+//  1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
+//  2. EKS Pod Identity - automatically rotates credentials for pods in EKS clusters
+//  3. IAM Roles for Service Accounts (IRSA) - injects credentials via mounted service account tokens
+//  4. EC2 instance metadata (IAM instance roles)
+//  5. 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).
 type BackendSecurityPolicyAWSCredentials struct {
 	// Region specifies the AWS region associated with the policy.
 	//
 	// +kubebuilder:validation:MinLength=1
 	Region string `json:"region"`
 
 	// CredentialsFile specifies the credentials file to use for the AWS provider.
+	// When specified, this takes precedence over the default credential chain.
 	//
 	// +optional
 	CredentialsFile *AWSCredentialsFile `json:"credentialsFile,omitempty"`
 
 	// OIDCExchangeToken specifies the oidc configurations used to obtain an oidc token. The oidc token will be
 	// used to obtain temporary credentials to access AWS.
+	// When specified, this takes precedence over the default credential chain.
 	//
 	// +optional
 	OIDCExchangeToken *AWSOIDCExchangeToken `json:"oidcExchangeToken,omitempty"`

examples/basic/README.md

@@ -1,2 +1,16 @@
-This contains the basic example manifest to create an Envoy Gateway that handles
-the traffics for both OpenAI and AWS Bedrock at the same time.
+This contains the basic example manifests to create an Envoy AI Gateway that handles
+traffic for various AI providers.
+
+## Examples
+
+- `basic.yaml` - Basic configuration without any backends
+- `openai.yaml` - OpenAI integration
+- `aws.yaml` - AWS Bedrock with static credentials
+- `aws-irsa.yaml` - AWS Bedrock with IRSA (IAM Roles for Service Accounts)
+- `aws-pod-identity.yaml` - AWS Bedrock with EKS Pod Identity
+- `azure_openai.yaml` - Azure OpenAI integration
+- `gcp_vertex.yaml` - GCP Vertex AI integration
+- `tars.yaml` - TARS integration
+
+For AWS Bedrock, we recommend using either `aws-pod-identity.yaml` (EKS 1.24+) or
+`aws-irsa.yaml` (all EKS versions) for production deployments instead of static credentials. [Docs](https://docs.aws.amazon.com/eks/latest/best-practices/identity-and-access-management.html#_identities_and_credentials_for_eks_pods)

examples/basic/aws-irsa.yaml

@@ -0,0 +1,168 @@
+# Copyright Envoy AI Gateway Authors
+# SPDX-License-Identifier: Apache-2.0
+# The full text of the Apache license is available in the LICENSE file at
+# the root of the repo.
+
+# This example demonstrates how to configure AWS Bedrock with IRSA (IAM Roles for Service Accounts)
+# on EKS, eliminating the need for static AWS credentials.
+#
+# Prerequisites for IRSA:
+# 1. EKS cluster with OIDC provider enabled
+# 2. IAM role with Bedrock permissions and trust policy for your ServiceAccount
+# 3. ServiceAccount annotated with eks.amazonaws.com/role-arn
+#
+# For EKS Pod Identity (newer, simpler method), see aws-pod-identity.yaml instead.
+#
+# For AWS IRSA setup instructions, see:
+# https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html
+#
+# For AI Gateway integration instructions, see:
+# https://docs.envoyproxy.io/ai-gateway/latest/getting-started/connect-providers/aws-bedrock.html
+
+---
+# Step 1: Create a custom ServiceAccount with IRSA annotation for the data plane
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+  annotations:
+    # Replace with your IAM role ARN that has Bedrock permissions
+    eks.amazonaws.com/role-arn: arn:aws:iam::ACCOUNT_ID:role/ai-gateway-bedrock-role
+---
+# Step 2: Create minimal RBAC for the ServiceAccount
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: ai-gateway-dataplane-aws
+subjects:
+  - kind: ServiceAccount
+    name: ai-gateway-dataplane-aws
+    namespace: envoy-gateway-system
+---
+# Step 3: Create custom EnvoyProxy configuration that uses the ServiceAccount
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: ai-gateway-with-aws
+  namespace: envoy-gateway-system
+spec:
+  provider:
+    type: Kubernetes
+    kubernetes:
+      envoyDeployment:
+        pod:
+          # This tells Envoy Gateway to use our AWS-enabled ServiceAccount
+          serviceAccountName: ai-gateway-dataplane-aws
+---
+# Step 4: Create Gateway that references the custom EnvoyProxy
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: envoy-ai-gateway-basic
+  namespace: default
+  annotations:
+    # This links the Gateway to use our custom EnvoyProxy with AWS credentials
+    gateway.envoyproxy.io/envoy-proxy: envoy-gateway-system/ai-gateway-with-aws
+spec:
+  gatewayClassName: envoy-ai-gateway
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+---
+# Step 5: Create AIGatewayRoute for routing to Bedrock
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: AIGatewayRoute
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  parentRefs:
+    - name: envoy-ai-gateway-basic
+      kind: Gateway
+      group: gateway.networking.k8s.io
+  rules:
+    - matches:
+        - headers:
+            - type: Exact
+              name: x-ai-eg-model
+              value: us.meta.llama3-2-1b-instruct-v1:0
+      backendRefs:
+        - name: envoy-ai-gateway-basic-aws
+---
+# Step 6: Create AIServiceBackend for AWS Bedrock
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: AIServiceBackend
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  schema:
+    name: AWSBedrock
+  backendRef:
+    name: envoy-ai-gateway-basic-aws
+    kind: Backend
+    group: gateway.envoyproxy.io
+---
+# Step 7: Create BackendSecurityPolicy using AWS credential chain
+# This automatically uses IRSA credentials from the ServiceAccount annotation!
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: BackendSecurityPolicy
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  targetRefs:
+    - group: aigateway.envoyproxy.io
+      kind: AIServiceBackend
+      name: envoy-ai-gateway-basic-aws
+  type: AWSCredentials
+  awsCredentials:
+    region: us-east-1
+    # No credentialsFile or oidcExchangeToken needed!
+    # The AWS SDK will automatically use the default credential chain which includes:
+    # - IRSA (if ServiceAccount has eks.amazonaws.com/role-arn annotation)
+    # - Other AWS credential sources (environment variables, instance profile, etc.)
+---
+# Step 8: Create Backend pointing to AWS Bedrock
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: Backend
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  endpoints:
+    - fqdn:
+        hostname: bedrock-runtime.us-east-1.amazonaws.com
+        port: 443
+---
+# Step 9: Create BackendTLSPolicy for HTTPS
+apiVersion: gateway.networking.k8s.io/v1alpha3
+kind: BackendTLSPolicy
+metadata:
+  name: envoy-ai-gateway-basic-aws-tls
+  namespace: default
+spec:
+  targetRefs:
+    - group: "gateway.envoyproxy.io"
+      kind: Backend
+      name: envoy-ai-gateway-basic-aws
+  validation:
+    wellKnownCACertificates: "System"
+    hostname: bedrock-runtime.us-east-1.amazonaws.com

examples/basic/aws-pod-identity.yaml

@@ -0,0 +1,166 @@
+# Copyright Envoy AI Gateway Authors
+# SPDX-License-Identifier: Apache-2.0
+# The full text of the Apache license is available in the LICENSE file at
+# the root of the repo.
+
+# This example demonstrates how to configure AWS Bedrock with EKS Pod Identity,
+# eliminating the need for static AWS credentials or OIDC provider configuration.
+#
+# Prerequisites for EKS Pod Identity:
+# 1. EKS cluster v1.24+
+# 2. EKS Pod Identity Agent installed (DaemonSet)
+# 3. IAM role with Bedrock permissions and trust policy for pods.eks.amazonaws.com
+# 4. Pod Identity association created linking your ServiceAccount to the IAM role
+#
+# For AWS Pod Identity setup instructions, see:
+# https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html
+#
+# For AI Gateway integration instructions, see:
+# https://docs.envoyproxy.io/ai-gateway/latest/getting-started/connect-providers/aws-bedrock.html
+
+---
+# Step 1: Create a ServiceAccount for the data plane
+# Note: No annotations needed for Pod Identity (unlike IRSA)
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+---
+# Step 2: Create minimal RBAC for the ServiceAccount
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+rules:
+  - apiGroups: [""]
+    resources: ["secrets"]
+    verbs: ["get", "list", "watch"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: ai-gateway-dataplane-aws
+  namespace: envoy-gateway-system
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: ai-gateway-dataplane-aws
+subjects:
+  - kind: ServiceAccount
+    name: ai-gateway-dataplane-aws
+    namespace: envoy-gateway-system
+---
+# Step 3: Create custom EnvoyProxy configuration that uses the ServiceAccount
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: EnvoyProxy
+metadata:
+  name: ai-gateway-with-aws
+  namespace: envoy-gateway-system
+spec:
+  provider:
+    type: Kubernetes
+    kubernetes:
+      envoyDeployment:
+        pod:
+          # This tells Envoy Gateway to use our AWS-enabled ServiceAccount
+          serviceAccountName: ai-gateway-dataplane-aws
+---
+# Step 4: Create Gateway that references the custom EnvoyProxy
+apiVersion: gateway.networking.k8s.io/v1
+kind: Gateway
+metadata:
+  name: envoy-ai-gateway-basic
+  namespace: default
+  annotations:
+    # This links the Gateway to use our custom EnvoyProxy with AWS credentials
+    gateway.envoyproxy.io/envoy-proxy: envoy-gateway-system/ai-gateway-with-aws
+spec:
+  gatewayClassName: envoy-ai-gateway
+  listeners:
+    - name: http
+      protocol: HTTP
+      port: 80
+---
+# Step 5: Create AIGatewayRoute for routing to Bedrock
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: AIGatewayRoute
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  parentRefs:
+    - name: envoy-ai-gateway-basic
+      kind: Gateway
+      group: gateway.networking.k8s.io
+  rules:
+    - matches:
+        - headers:
+            - type: Exact
+              name: x-ai-eg-model
+              value: us.meta.llama3-2-1b-instruct-v1:0
+      backendRefs:
+        - name: envoy-ai-gateway-basic-aws
+---
+# Step 6: Create AIServiceBackend for AWS Bedrock
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: AIServiceBackend
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  schema:
+    name: AWSBedrock
+  backendRef:
+    name: envoy-ai-gateway-basic-aws
+    kind: Backend
+    group: gateway.envoyproxy.io
+---
+# Step 7: Create BackendSecurityPolicy using AWS credential chain
+# This automatically detects and uses EKS Pod Identity credentials!
+apiVersion: aigateway.envoyproxy.io/v1alpha1
+kind: BackendSecurityPolicy
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  targetRefs:
+    - group: aigateway.envoyproxy.io
+      kind: AIServiceBackend
+      name: envoy-ai-gateway-basic-aws
+  type: AWSCredentials
+  awsCredentials:
+    region: us-east-1
+    # No credentialsFile or oidcExchangeToken needed!
+    # The AWS SDK will automatically use the default credential chain which includes:
+    # - EKS Pod Identity (if Pod Identity association exists)
+    # - IRSA (if ServiceAccount has eks.amazonaws.com/role-arn annotation)
+    # - Other AWS credential sources (environment variables, instance profile, etc.)
+---
+# Step 8: Create Backend pointing to AWS Bedrock
+apiVersion: gateway.envoyproxy.io/v1alpha1
+kind: Backend
+metadata:
+  name: envoy-ai-gateway-basic-aws
+  namespace: default
+spec:
+  endpoints:
+    - fqdn:
+        hostname: bedrock-runtime.us-east-1.amazonaws.com
+        port: 443
+---
+# Step 9: Create BackendTLSPolicy for HTTPS
+apiVersion: gateway.networking.k8s.io/v1alpha3
+kind: BackendTLSPolicy
+metadata:
+  name: envoy-ai-gateway-basic-aws-tls
+  namespace: default
+spec:
+  targetRefs:
+    - group: "gateway.envoyproxy.io"
+      kind: Backend
+      name: envoy-ai-gateway-basic-aws
+  validation:
+    wellKnownCACertificates: "System"
+    hostname: bedrock-runtime.us-east-1.amazonaws.com