Feat(aigw): v2 azure claude cli

[jbaross]

Description

Fixes #issue

Preview Links

https://deploy-preview-5948--kongdeveloper.netlify.app/ai-gateway/use-claude-code-with-ai-gateway-azure/

Checklist

• Tested how-to docs. If not, note why here.
• All pages contain metadata.
• Any new docs link to existing docs.
• All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
• Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
• Every page has a description entry in frontmatter.
• Add new pages to the product documentation index (if applicable).

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	c78eaf3
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a568ee12ac3010008521a49
😎 Deploy Preview	https://deploy-preview-5948--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

Adds a new v2 AI Gateway how-to that walks users through routing Claude Code (Claude CLI) traffic through Kong AI Gateway to an Azure-hosted Anthropic model using kongctl.

Changes:

• Introduces a new how-to page for configuring an AI Model Provider (Azure) and AI Model, then running Claude Code via ANTHROPIC_BASE_URL.
• Provides example kongctl apply manifests for the provider and model entities.
• Includes a basic “verify traffic” section using a Claude Code session prompt and sample query.

[felderi]

Replicated this how-to end-to-end against Azure AI Foundry Claude — the config as written doesn't work; here are the fixes, all validated live (Claude Code → Kong → Azure Foundry Claude returning 200).

The core issue: Foundry Claude is a native Anthropic MaaS endpoint, not Azure-OpenAI — so the type: azure / /openai/deployments/<dep>/v1/messages shape can't reach it. Each fix below was confirmed on the latest AI Gateway 2.0 dev image.

🔴 Blockers

1. Env-var names don't match between the export steps and the config.
Steps 6–7 export DECK_AZURE_INSTANCE_NAME / DECK_AZURE_OPENAI_API_KEY / DECK_AZURE_DEPLOYMENT_ID, but the config blocks !env-reference AZURE_AI_FOUNDRY_RESOURCE_NAME / AZURE_AI_FOUNDRY_TOKEN / AZURE_AI_FOUNDRY_UPSTREAM_URL — and AZURE_AI_FOUNDRY_UPSTREAM_URL is exported nowhere. Following the doc literally, the first kongctl apply fails at config-load:

Error: failed to resolve tag !env: environment variable not set: AZURE_AI_FOUNDRY_RESOURCE_NAME

2. Wrong provider driver + endpoint. type: azure reconstructs the Azure-OpenAI deployments path and 404s against Foundry Claude. Use type: anthropic with upstream_url = the base https://<resource>.services.ai.azure.com/anthropic — no /v1/messages (the anthropic driver appends the incoming request URI; a full path produces /anthropic/v1/messages/v1/messages → 404). Drop instance: and deployment_id: — both are Azure-OpenAI-isms.

3. Wrong auth header + missing version header. Foundry Claude authenticates with x-api-key, not api-key (the latter 401s), and requires anthropic-version: 2023-06-01 (400 without it). Inject the version via a request-transformer-advanced add.headers policy — config.auth.headers accepts only one entry, so it can't also carry the version.

4. No beta-field strip → real Claude Code sessions 400. Claude Code sends beta body fields (output_config, context_management, mcp_servers, container, service_tier) that the Anthropic schema rejects with 400 Extra inputs are not permitted. Add a request-transformer-advanced remove.body for those five. Do not strip model — it drives model selection.

🟡 Minor

• Launch note: claude --model <X> must pass the AI Model name (claude-code-azure-sonnet), not the target model name (claude-sonnet-4-6) — passing the target name trips the model selector → 503.
• Terminology: the prereqs say "Azure OpenAI Service" / DECK_AZURE_OPENAI_API_KEY, but the target is a Claude model via formats:[anthropic] on Azure AI Foundry. Align the language.

✅ Validated drop-in for steps 6–9

Env vars (one consistent set, used in both the exports and the !env refs):

export AZURE_AI_FOUNDRY_TOKEN='<your Azure AI Foundry API key>'
# BASE MaaS endpoint — ends at /anthropic, NO /v1/messages:
export AZURE_AI_FOUNDRY_UPSTREAM_URL='https://<your-resource>.services.ai.azure.com/anthropic'

Provider (Anthropic driver → Foundry MaaS):

ai_gateway_model_providers:
  - ref: azure-claude
    name: azure-claude
    ai_gateway: ai-quickstart
    type: anthropic            # Foundry Claude is native Anthropic MaaS, not Azure-OpenAI
    config:
      auth:
        type: basic
        headers:
          - name: x-api-key    # Foundry MaaS Claude authenticates with x-api-key
            value: !env AZURE_AI_FOUNDRY_TOKEN

Request-compat policy (mandatory anthropic-version + strip Claude Code beta fields):

ai_gateway_policies:
  - ref: claude-code-compat
    name: claude-code-compat
    ai_gateway: ai-quickstart
    type: request-transformer-advanced
    enabled: true
    global: false
    config:
      add:
        headers: ["anthropic-version:2023-06-01"]   # REQUIRED — Foundry 400s without it
      remove:
        headers: [anthropic-beta]
        querystring: [beta]
        body: [output_config, context_management, mcp_servers, container, service_tier]

Model:

ai_gateway_models:
  - ref: claude-code-azure-sonnet
    name: claude-code-azure-sonnet    # the value passed to `claude --model`
    ai_gateway: ai-quickstart
    type: model
    enabled: true
    formats: [{ type: anthropic }]
    config:
      route: { paths: [/] }
      model: { name_header: true }
    capabilities: [generate]
    policies: [ !ref claude-code-compat#name ]
    targets:
      - name: claude-sonnet-4-6       # the real Foundry Claude model
        provider: azure-claude
        config:
          type: anthropic
          upstream_url: !env AZURE_AI_FOUNDRY_UPSTREAM_URL   # base .../anthropic

Verify (unchanged):

ANTHROPIC_BASE_URL=http://localhost:8000/ claude --model 'claude-code-azure-sonnet'

Happy to pair on the rewrite. (Validated against the shared se-ai-gw-resource Foundry resource; the claude-sonnet-4-6 model resolves via the MaaS model-in-body path, not an OpenAI deployment.)

[felderi]

Validation feedback — I ran this config end-to-end on an AI Gateway 2.0 dev build (Claude Code → local DP → Kong → Azure AI Foundry Claude, returning 200 with real Claude responses). The provider-shape fixes from the Slack thread have landed (type: anthropic, x-api-key, the anthropic-version header, display_name) 👍. A few things still block a clean, from-scratch run:

1. (Breaking) The three separate kongctl apply blocks break the model's policy !ref. The AI Model apply references policies: [ !ref claude-code-compat#name ], but claude-code-compat is created in a different apply and isn't re-declared in the model apply — so this fails with resource not found: claude-code-compat (the exact error hit during testing). !ref only resolves within a single apply. Two fixes:

• Combine provider + policy + model into one kongctl apply (simplest), or
• Re-declare the policy (and provider) in the model apply via _external selectors, the way the Bedrock how-to (#5942) does.

2. Prereq env vars don't match the config. prereqs/azure-ai-claude.md exports DECK_AZURE_INSTANCE_NAME / DECK_AZURE_OPENAI_API_KEY / DECK_AZURE_DEPLOYMENT_ID, but the config reads !env AZURE_AI_FOUNDRY_TOKEN and !env AZURE_AI_FOUNDRY_UPSTREAM_URL. A reader following the prereqs ends up with empty values, and AZURE_AI_FOUNDRY_UPSTREAM_URL is never set or documented anywhere.

3. Document the upstream URL format — this is the non-obvious bit. It must be the base endpoint ending at /anthropic, with no /v1/messages (the driver appends that):

export AZURE_AI_FOUNDRY_UPSTREAM_URL='https://<resource>.services.ai.azure.com/anthropic'

Verified: a raw curl to .../anthropic/v1/messages with x-api-key + anthropic-version: 2023-06-01 returns 200.

4. The provider prose is stale. Under "Configure an AI Model Provider," the bullets still describe the old Azure-OpenAI driver — type: azure, name: azure-anthropic, config.instance — none of which match the actual config (type: anthropic, name: azure-claude, no instance).

5. Terminology. Title/description/prereqs say "Azure OpenAI," but this targets Claude on Azure AI Foundry — a native Anthropic MaaS endpoint, not Azure-OpenAI. That framing is exactly what led to the wrong type: azure shape originally; worth correcting so readers don't re-derive the mistake.

6. Add a "validate directly" step (like the Bedrock doc's) that curls the Foundry endpoint bypassing Kong first — it isolates credential/deployment problems from gateway problems in a single command, which would have short-circuited most of the debugging in the thread.

Minor: drop the DECK_ prefixes throughout (this how-to uses kongctl, not decK).

[cloudjumpercat]

manually approving links, the broken one is not even in this PR, it's in an include

[felderi]

One addition to my earlier review — gateway ownership. The provider/policy/model applies here fully declare the gateway:

ai_gateways:
  - ref: ai-quickstart
    name: ai-quickstart
    display_name: "ai-quickstart"

Since ai-quickstart's control plane and data plane are created and owned by the AI quickstart/bootstrap script, kongctl should reference it link-only and manage just the children — not try to own the gateway. Switch each block to _external:

ai_gateways:
  - ref: ai-quickstart
    _external:
      selector:
        matchFields:
          name: ai-quickstart

This matches the pattern in the Bedrock how-to (#5942) and the note on the Vertex how-to (#5952) — keeping all three "Claude Code with X" docs consistent. (Fully declaring it would make kongctl contend with the script for the gateway's lifecycle.)

Everything in my original review still stands (cross-apply !ref, the DECK_AZURE_* vs AZURE_AI_FOUNDRY_* env mismatch + undocumented upstream URL, the stale type: azure/config.instance prose, and the "Azure OpenAI" vs Foundry-Claude terminology).