AI-123 + AI-125: Bedrock Mantle and VPC endpoint docs for AI Gateway 2.3

app/_data/ai-gateway/v2/providers.yaml

@@ -7,7 +7,7 @@ providers:
       generate:
         supported: true
         streaming: true
-        upstream_path: 'Uses the `Converse` and `ConverseStream` API'
+        upstream_path: "Uses the `Converse` and `ConverseStream` APIs. When a client sends an Anthropic-format request to an Anthropic Claude model, {{site.ai_gateway}} sends it to `InvokeModel` or `InvokeModelWithResponseStream` instead, because the request is already in Claude's native format."
         model_example: '[Use the model name for the specific LLM provider](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html)'
         min_version: '2.0'
       completions:
@@ -41,7 +41,7 @@ providers:
         model_example: 'n/a'
         min_version: '2.0'
         note:
-          content: 'Amazon Bedrock does not have a dedicated files API. File storage uses Google Cloud Storage, similar to AWS S3.'
+          content: 'Amazon Bedrock does not have a dedicated files API. Batch input and output files are stored in Amazon S3 and referenced by S3 URI.'
       image:
         supported: true
         streaming: false
@@ -106,6 +106,23 @@ providers:
       statistics_logging:
         - 'Statistics logging is not available for image generation or editing APIs for Amazon Bedrock'
 
+  - name: Amazon Bedrock Mantle
+    url_patterns:
+      - 'https://bedrock-mantle.{region}.api.aws'
+    min_version: '2.3'
+    variant_trigger: 'set `endpoint_type: mantle` in the target `config` of your AI Model'
+    capabilities:
+      generate:
+        supported: true
+        streaming: true
+        upstream_path: 'Forwards OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages requests without translation'
+        model_example: '[Use a model ID that Amazon Bedrock serves through the Mantle endpoint](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html)'
+        min_version: '2.3'
+    limitations:
+      provider_specific:
+        - 'Mantle has no Converse or InvokeModel API, so Konnect rejects a target with `endpoint_type: mantle` if its AI Model declares a format with `type: bedrock`. Use the `openai` or `anthropic` format instead.'
+      statistics_logging: []
+
   - name: Anthropic
     url_patterns:
       - 'https://api.anthropic.com:443/{capability_path}'
@@ -688,7 +705,7 @@ providers:
     url_patterns:
       - 'https://aiplatform.googleapis.com/'
     min_version: '2.0'
-    variant_trigger: 'Setting `config.gcp_environment` (with `api_endpoint`, `location_id`, and `project_id`) on the AI Model''s target.'
+    variant_trigger: 'set `config.gcp_environment` (with `api_endpoint`, `location_id`, and `project_id`) on the AI Model''s target'
     capabilities:
       generate:
         supported: true
@@ -715,7 +732,7 @@ providers:
         model_example: 'n/a'
         min_version: '2.0'
         note:
-          content: 'Gemini Enterprise does not have a dedicated Files API. File storage uses Google Cloud Storage, similar to AWS S3.'
+          content: 'Gemini Enterprise does not have a dedicated Files API. File storage uses Google Cloud Storage, similar to Amazon S3.'
       batches:
         supported: true
         streaming: false

app/_how-tos/ai-gateway/connect-to-bedrock-through-vpc-endpoint.md

@@ -0,0 +1,147 @@
+---
+title: Connect to Amazon Bedrock through a VPC endpoint with {{site.ai_gateway}}
+content_type: how_to
+permalink: /ai-gateway/connect-to-bedrock-through-vpc-endpoint/
+
+related_resources:
+  - text: Amazon Bedrock provider
+    url: /ai-gateway/ai-providers/bedrock/
+  - text: AI Model Provider entity
+    url: /ai-gateway/entities/ai-model-provider/
+  - text: AI Model entity
+    url: /ai-gateway/entities/ai-model/
+  - text: Route OpenAI traffic to Amazon Bedrock Mantle
+    url: /ai-gateway/route-openai-traffic-to-bedrock-mantle/
+
+description: Send Amazon Bedrock traffic from {{site.ai_gateway}} through an AWS PrivateLink interface VPC endpoint while keeping Bedrock paths, streaming, and SigV4 signing intact.
+
+products:
+  - ai-gateway
+
+works_on:
+  - konnect
+
+tools:
+  - kongctl
+
+min_version:
+  ai-gateway: '2.3'
+
+tags:
+  - ai
+  - bedrock
+
+tldr:
+  q: How do I route {{site.ai_gateway}} traffic to Amazon Bedrock over AWS PrivateLink?
+  a: Set `vpc_endpoint` in the Bedrock target `config` of your AI Model to the DNS name of your Bedrock Runtime interface VPC endpoint. {{site.ai_gateway}} connects to that host, keeps building the Bedrock path for each operation, and signs requests with SigV4 for the real Bedrock service and region.
+
+prereqs:
+  inline:
+    - title: Amazon Bedrock VPC endpoint
+      content: |
+        1. Create an interface VPC endpoint for the Bedrock Runtime service (`com.amazonaws.<region>.bedrock-runtime`) in the VPC where your data plane nodes run. See [Use interface VPC endpoints (AWS PrivateLink)](https://docs.aws.amazon.com/bedrock/latest/userguide/vpc-interface-endpoints.html) in the AWS documentation.
+        1. Make sure your data plane nodes can resolve the endpoint's DNS name and reach it on port 443.
+        1. Make sure your IAM user or role has `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` permissions, and that the VPC endpoint policy allows them.
+        1. Export your AWS credentials, region, and the endpoint DNS name:
+           ```bash
+           export AWS_ACCESS_KEY_ID='YOUR_AWS_ACCESS_KEY_ID'
+           export AWS_SECRET_ACCESS_KEY='YOUR_AWS_SECRET_ACCESS_KEY'
+           export AWS_REGION='YOUR_AWS_REGION'
+           export BEDROCK_VPC_ENDPOINT='YOUR_VPC_ENDPOINT_DNS_NAME'
+           ```
+cleanup:
+  inline:
+    - title: Clean up {{site.ai_gateway}} resources
+      include_content: cleanup/products/ai-gateway
+
+---
+
+{% comment %}
+TODO(reviewer, AI-125):
+- Confirm the value format for `vpc_endpoint` (bare hostname vs. URL with scheme) and update the prereq export and example.
+- Confirm which data plane deployments can use this (self-managed hybrid only, or also Dedicated Cloud Gateways with private networking).
+- Q1: Confirm the `vpc_endpoint` + `upstream_url` behavior (precedence or validation error).
+{% endcomment %}
+
+## Create an AI Model Provider
+
+Create an [AI Model Provider](/ai-gateway/entities/ai-model-provider/) of type `bedrock` that stores your AWS credentials:
+
+{% entity_examples %}
+ai_gateway_model_providers:
+  - ref: my-aws-account
+    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
+    name: my-aws-account
+    display_name: "AWS Production"
+    type: bedrock
+    config:
+      auth:
+        type: aws
+        access_key_id: !env AWS_ACCESS_KEY_ID
+        secret_access_key: !secret {source: !env AWS_SECRET_ACCESS_KEY}
+{% endentity_examples %}
+
+## Create an AI Model that uses the VPC endpoint
+
+Create an [AI Model](/ai-gateway/entities/ai-model/) with a Bedrock target that sets `vpc_endpoint`:
+
+{% entity_examples %}
+ai_gateway_models:
+  - ref: my-private-bedrock-model
+    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
+    name: my-private-bedrock-model
+    display_name: "my-private-bedrock-model"
+    type: model
+    formats:
+      - type: openai
+    config:
+      route:
+        paths:
+          - /v1
+        model:
+          body_param: model
+          values:
+            - my-private-bedrock-model
+    targets:
+      - name: us.anthropic.claude-haiku-4-5-20251001-v1:0
+        provider: my-aws-account
+        config:
+          type: bedrock
+          region: !env AWS_REGION
+          vpc_endpoint: !env BEDROCK_VPC_ENDPOINT
+    capabilities:
+      - generate
+{% endentity_examples %}
+
+The target uses the following settings:
+
+* `vpc_endpoint`: Replaces only the host that {{site.ai_gateway}} connects to. {{site.ai_gateway}} still builds the Bedrock path for each operation, including streaming, and SigV4 still signs for the Bedrock service in `region`.
+* `region`: Sets the region used for SigV4 signing. It must match the region of the VPC endpoint.
+
+Leave `upstream_url` unset on this target. If both are set, `upstream_url` takes precedence and replaces the full URL, including the path.
+
+If your AI Model also uses Bedrock embeddings, set `vpc_endpoint` in [`config.balancer.embeddings`](/ai-gateway/entities/ai-model/#schema-aigateway-model-config-balancer-embeddings) as well.
+
+## Validate
+
+Send a streaming chat request to the AI Model:
+
+<!-- vale off -->
+{% validation request-check %}
+url: /v1/chat/completions
+status_code: 200
+method: POST
+retry: true
+headers:
+    - 'Accept: application/json'
+    - 'Content-Type: application/json'
+body:
+  messages:
+  - role: "user"
+    content: "Say this is a test!"
+  model: my-private-bedrock-model
+  stream: true
+{% endvalidation %}
+<!-- vale on -->
+
+A `200` response with streamed chunks confirms that {{site.ai_gateway}} reached Bedrock through the VPC endpoint and built the streaming path. If the request fails with a connection error, check that your data plane nodes can resolve and reach the VPC endpoint. {{site.ai_gateway}} doesn't fall back to the public Bedrock endpoint.

app/_how-tos/ai-gateway/route-openai-traffic-to-bedrock-mantle.md

@@ -0,0 +1,143 @@
+---
+title: Route OpenAI traffic to Amazon Bedrock Mantle with {{site.ai_gateway}}
+content_type: how_to
+permalink: /ai-gateway/route-openai-traffic-to-bedrock-mantle/
+
+related_resources:
+  - text: Amazon Bedrock provider
+    url: /ai-gateway/ai-providers/bedrock/
+  - text: AI Model Provider entity
+    url: /ai-gateway/entities/ai-model-provider/
+  - text: AI Model entity
+    url: /ai-gateway/entities/ai-model/
+  - text: Connect to Amazon Bedrock through a VPC endpoint
+    url: /ai-gateway/connect-to-bedrock-through-vpc-endpoint/
+
+description: Configure an AI Model that sends OpenAI Chat Completions requests to the Amazon Bedrock Mantle endpoint without translating them.
+
+products:
+  - ai-gateway
+
+works_on:
+  - konnect
+
+tools:
+  - kongctl
+
+min_version:
+  ai-gateway: '2.3'
+
+tags:
+  - ai
+  - bedrock
+
+tldr:
+  q: How do I send OpenAI-format requests to Amazon Bedrock Mantle through {{site.ai_gateway}}?
+  a: Create an AI Model Provider of type `bedrock` with your AWS credentials, then create an AI Model with the `openai` format and a Bedrock target that sets `endpoint_type` to `mantle`. {{site.ai_gateway}} forwards OpenAI requests to `bedrock-mantle.{region}.api.aws` as-is and signs them with SigV4.
+
+prereqs:
+  inline:
+    - title: Amazon Bedrock Mantle
+      content: |
+        1. In the AWS Management Console, confirm that Amazon Bedrock Mantle is available in your region and that your account has access to the model you want to use.
+        1. Create an IAM user or role with permission to call Bedrock Mantle, then create access keys for it.
+        1. Export your AWS credentials, region, and the Mantle model ID:
+           ```bash
+           export AWS_ACCESS_KEY_ID='YOUR_AWS_ACCESS_KEY_ID'
+           export AWS_SECRET_ACCESS_KEY='YOUR_AWS_SECRET_ACCESS_KEY'
+           export AWS_REGION='YOUR_AWS_REGION'
+           export MANTLE_MODEL_ID='YOUR_MANTLE_MODEL_ID'
+           ```
+cleanup:
+  inline:
+    - title: Clean up {{site.ai_gateway}} resources
+      include_content: cleanup/products/ai-gateway
+
+---
+
+{% comment %}
+TODO(reviewer, AI-123):
+- Name the exact IAM actions Mantle requires (prereqs step 2) and link the AWS Mantle docs.
+- Pick a concrete Mantle model ID and region for this guide so the validation step can run in CI.
+{% endcomment %}
+
+## Create an AI Model Provider
+
+Create an [AI Model Provider](/ai-gateway/entities/ai-model-provider/) of type `bedrock` that stores your AWS credentials. The same provider works for Bedrock Runtime and Bedrock Mantle targets:
+
+{% entity_examples %}
+ai_gateway_model_providers:
+  - ref: my-aws-account
+    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
+    name: my-aws-account
+    display_name: "AWS Production"
+    type: bedrock
+    config:
+      auth:
+        type: aws
+        access_key_id: !env AWS_ACCESS_KEY_ID
+        secret_access_key: !secret {source: !env AWS_SECRET_ACCESS_KEY}
+{% endentity_examples %}
+
+To authenticate with an Amazon Bedrock API key instead of SigV4, set `config.auth.type` to `basic` with an `Authorization` header whose value is `Bearer <BEDROCK_API_KEY>`.
+
+## Create an AI Model with a Mantle target
+
+Create an [AI Model](/ai-gateway/entities/ai-model/) that accepts OpenAI requests and routes them to Bedrock Mantle:
+
+{% entity_examples %}
+ai_gateway_models:
+  - ref: my-mantle-model
+    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
+    name: my-mantle-model
+    display_name: "my-mantle-model"
+    type: model
+    formats:
+      - type: openai
+    config:
+      route:
+        paths:
+          - /v1
+        model:
+          body_param: model
+          values:
+            - my-mantle-model
+    targets:
+      - name: !env MANTLE_MODEL_ID
+        provider: my-aws-account
+        config:
+          type: bedrock
+          region: !env AWS_REGION
+          endpoint_type: mantle
+    capabilities:
+      - generate
+{% endentity_examples %}
+
+The AI Model uses the following settings:
+
+* `formats: [type: openai]`: Accepts OpenAI Chat Completions requests. A Mantle target can't be paired with the `bedrock` format, because Mantle has no Converse or InvokeModel API, and {{site.konnect_short_name}} rejects that configuration.
+* `targets[].config.endpoint_type: mantle`: Sends requests to `https://bedrock-mantle.{region}.api.aws` instead of the default Bedrock Runtime endpoint. {{site.ai_gateway}} forwards the request body as-is and rewrites only the host, path, and authentication headers.
+* `config.route.model`: Lets clients send the alias `my-mantle-model` in the `model` field instead of the upstream model ID.
+
+## Validate
+
+Send a chat request to the AI Model:
+
+<!-- vale off -->
+{% validation request-check %}
+url: /v1/chat/completions
+status_code: 200
+method: POST
+retry: true
+headers:
+    - 'Accept: application/json'
+    - 'Content-Type: application/json'
+body:
+  messages:
+  - role: "user"
+    content: "Say this is a test!"
+  model: my-mantle-model
+{% endvalidation %}
+<!-- vale on -->
+
+A `200` response with an OpenAI Chat Completions body confirms that Bedrock Mantle served the request.

app/_includes/md/ai-gateway/v2/providers.md

@@ -680,9 +680,9 @@ rows:
 {% endtable %}
 {% if provider.capabilities.batches.note.content %}<sup>{{ batches_note_num }}</sup> {% if compare_provider %}**{{ include.variant_label }}:** {% endif %}{{ provider.capabilities.batches.note.content }}{% endif %}
 {% if compare_provider.capabilities.batches.note.content %}<sup>{{ compare_batches_note_num }}</sup> **{{ include.compare_variant_label }}:** {{ compare_provider.capabilities.batches.note.content }}{% endif %}
+
 {:.warning}
-> Batches are configured on a separate AI Model with `type: "api"`, distinct from regular models that handle synchronous capabilities like generate and embeddings.
-> Create a dedicated AI Model exclusively for batches and files, as each model must be either a regular model or an API model, not both.
+> Batch jobs run on an AI Model with [`type: "api"`](/ai-gateway/entities/ai-model/#schema-aigateway-model-type). Regular models handle synchronous capabilities like generate and embeddings, so a model that serves batches can't serve those capabilities.
 {%- endif -%}
 
 {% if has_files %}
@@ -738,8 +738,7 @@ rows:
 {% if compare_provider.capabilities.files.note.content %}<sup>{{ compare_files_note_num }}</sup> **{{ include.compare_variant_label }}:** {{ compare_provider.capabilities.files.note.content }}{% endif %}
 
 {:.warning}
-> Batches are configured on a separate AI Model with [`type: "api"`](/ai-gateway/entities/ai-model/#schema-aigateway-model-type), distinct from regular models that handle synchronous capabilities like generate and embeddings.
-> Create a dedicated AI Model exclusively for batches and files, as each model must be either a regular model or an API model, not both.
+> Files are managed through an AI Model with [`type: "api"`](/ai-gateway/entities/ai-model/#schema-aigateway-model-type), the same type that serves batches. Create one dedicated AI Model for batches and files, and keep generate and embeddings on a separate regular model, because each model is either a regular model or an API model, not both.
 {%- endif -%}
 
 {% if has_skills %}
@@ -902,7 +901,7 @@ rows:
 {% endtable %}
 {% if provider.capabilities.decisions.note.content %}<sup>{{ decisions_note_num }}</sup> {% if compare_provider %}**{{ include.variant_label }}:** {% endif %}{{ provider.capabilities.decisions.note.content }}{% endif %}
 {% if compare_provider.capabilities.decisions.note.content %}<sup>{{ compare_decisions_note_num }}</sup> **{{ include.compare_variant_label }}:** {{ compare_provider.capabilities.decisions.note.content }}{% endif %}
-{%- endif -%}
+{%- endif %}
 
 ## {{ provider.name }} base URL
 
@@ -916,9 +915,9 @@ rows:
 {% if compare_provider %}
 By default, {{site.ai_gateway}} routes {{ provider.name }} requests to {{ include.variant_label }} at `{{ provider.url_patterns.first }}`.{% if has_capability_path %} The `{capability_path}` is determined by the AI capability.{% endif %}
 
-{{ compare_provider.variant_trigger }} This switches routing to {{ include.compare_variant_label }} at `{{ compare_provider.url_patterns.first }}`.
+To route requests to {{ include.compare_variant_label }}, {{ compare_provider.variant_trigger }}. {{site.ai_gateway}} then sends them to `{{ compare_provider.url_patterns.first }}`.
 
-{{site.ai_gateway}} uses the correct URL automatically based on this configuration. You only need to set `upstream_url` in your [AI Model](/ai-gateway/entities/ai-model/) configuration if you're using a self-hosted or {{ provider.name }}-compatible endpoint instead.
+You don't need to set the URL yourself. You only need to set `upstream_url` in your [AI Model](/ai-gateway/entities/ai-model/) configuration if you're using a self-hosted or {{ provider.name }}-compatible endpoint instead.
 {% else %}
 {% if provider.url_is_variable %}
 The base URL is <code>{{ provider.url_patterns.first }}</code>.{% if has_capability_path %} The `{capability_path}` is determined by the AI capability.{% endif %}