From e3ac65aa5fc0c26a2fb9fc1583ced053b9f68309 Mon Sep 17 00:00:00 2001 From: Danny Kopping Date: Wed, 1 Jul 2026 10:54:19 +0200 Subject: [PATCH] docs: add AI Gateway rebranding migration guide (#26854) ## Summary Adds an operator-facing migration guide for the AI Bridge to AI Gateway rebrand, as a new docs page under **AI Coder > AI Gateway** (last child in the section). The guide documents: - **Config aliases** (env vars, CLI flags, YAML group keys): old `aibridge` names still work as hidden, deprecated aliases; new `ai_gateway` names are canonical. Includes full env-var mapping tables and the mechanical substitution rules. - **HTTP API**: canonical path is now `/api/v2/ai-gateway`; legacy `/api/v2/aibridge` routes retained. - **Metrics**: prefixes renamed `coder_aibridged_*` -> `coder_ai_gateway_*` and `coder_aibridgeproxyd_*` -> `coder_ai_gateway_proxy_*`. Both old and new names are emitted today, so dashboards keep working; guidance to migrate before the old names are removed, plus an optional `metric_relabel_configs` drop snippet. - **No database changes** and no required config changes to upgrade. Implements the docs/release-notes portion of [AIGOV-240](https://linear.app/codercom/issue/AIGOV-240) (parent: [AIGOV-207](https://linear.app/codercom/issue/AIGOV-207)). ## Notes - Content reflects what actually shipped in the codebase (metrics are *aliased*, not hard-renamed), which differs from the original RFC that assumed a hard rename. - Registered in `docs/manifest.json` with `state: ["ai governance add-on"]` to match sibling pages. --- *This PR was produced by opencode (agent) using the `anthropic/claude-opus-4-8` model, under human direction and review.* --------- Signed-off-by: Danny Kopping --- docs/ai-coder/ai-gateway/index.md | 4 +- .../ai-gateway/rebranding-migration.md | 210 ++++++++++++++++++ docs/manifest.json | 6 + 3 files changed, 217 insertions(+), 3 deletions(-) create mode 100644 docs/ai-coder/ai-gateway/rebranding-migration.md diff --git a/docs/ai-coder/ai-gateway/index.md b/docs/ai-coder/ai-gateway/index.md index b7cc056350..3fcbaf15f2 100644 --- a/docs/ai-coder/ai-gateway/index.md +++ b/docs/ai-coder/ai-gateway/index.md @@ -22,9 +22,7 @@ AI Gateway solves 3 key problems: > As of Coder v2.32, deployments without the add-on will not be able to > access AI Gateway. > -> AI Gateway was previously known as "AI Bridge". Some configuration -> options, environment variables, and API paths still use the old name -> and will be updated in a future release. +> AI Gateway was previously known as "AI Bridge". Visit [Rebranding Migration](./rebranding-migration.md) for details. ## When to use AI Gateway diff --git a/docs/ai-coder/ai-gateway/rebranding-migration.md b/docs/ai-coder/ai-gateway/rebranding-migration.md new file mode 100644 index 0000000000..1404f7bcc3 --- /dev/null +++ b/docs/ai-coder/ai-gateway/rebranding-migration.md @@ -0,0 +1,210 @@ +# Rebranding Migration + +AI Bridge has been renamed to **AI Gateway**. This is a cosmetic rebrand to make +the feature easier to understand. It changes user-visible names, configuration +options, the canonical HTTP API path, and the Prometheus metric names. + +> [!NOTE] +> This release does not break existing deployments. Previous names keep working as +> deprecated aliases, there are no database changes, and no configuration +> changes are required to upgrade. + +The previous `aibridge` names are retained for backward compatibility. There is no +planned removal date, but you should adopt the new `ai_gateway` names as soon as possible, so +your configuration matches the current documentation. + +> [!IMPORTANT] +> New settings added in every area except the database (configuration options, +> environment variables, CLI flags, and API paths) will use only the new +> `ai_gateway` name, with no `aibridge` alias. + +## At a glance + +| Area | Old name | New (canonical) name | Old name still works? | +|-----------------------|------------------------------------------------|---------------------------------------------------|------------------------------------| +| Environment variables | `CODER_AIBRIDGE_*` | `CODER_AI_GATEWAY_*` | Yes (deprecated alias) | +| CLI flags | `--aibridge-*` | `--ai-gateway-*` | Yes (deprecated alias) | +| YAML config group | `aibridge:` / `aibridgeproxy:` | `ai_gateway:` / `ai_gateway_proxy:` | Yes (deprecated alias) | +| HTTP API | `/api/v2/aibridge` | `/api/v2/ai-gateway` | Yes (legacy route retained) | +| Prometheus metrics | `coder_aibridged_*` / `coder_aibridgeproxyd_*` | `coder_ai_gateway_*` / `coder_ai_gateway_proxy_*` | Yes (both emitted, old deprecated) | +| Database | (no change) | (no change) | n/a | + +## What did not change + +- **No database changes.** Table and column names (for example, + `aibridge_interceptions`) are unchanged. No migration runs and no data is + rewritten on upgrade. +- **No behavioral changes.** This is a naming change only. Values, defaults, and + semantics of every option are identical. +- **Internal/library references.** Some internal package names, log fields, and + library identifiers still use the `aibridge` name. These are not part of the + supported configuration surface and do not affect operators. + +## Configuration (env vars, flags, YAML) + +The new names are the canonical options; the previous `aibridge` names still set the +same values as hidden, deprecated aliases. + +If both a previous name and a new name are set for the same setting, set only one (prefer +the new name). + +### Naming rules + +The rename is a mechanical substitution: + +- Environment variables: `CODER_AIBRIDGE_` becomes `CODER_AI_GATEWAY_`. +- CLI flags: `--aibridge-` becomes `--ai-gateway-`. +- YAML: only the top-level group key changes + (`aibridge:` becomes `ai_gateway:`, `aibridgeproxy:` becomes + `ai_gateway_proxy:`). The keys nested under the group are unchanged. + +### YAML example + +Before: + +```yaml +aibridge: + enabled: true + openai_base_url: https://api.openai.com/v1/ + retention: 60d +aibridgeproxy: + enabled: true + listen_addr: ":8888" +``` + +After: + +```yaml +ai_gateway: + enabled: true + openai_base_url: https://api.openai.com/v1/ + retention: 60d +ai_gateway_proxy: + enabled: true + listen_addr: ":8888" +``` + +### Environment variable reference + +Core AI Gateway settings: + +| Deprecated | New | Note | +|----------------------------------------------------|------------------------------------------------------|----------------------------------------------------------------| +| `CODER_AIBRIDGE_ENABLED` | `CODER_AI_GATEWAY_ENABLED` | | +| `CODER_AIBRIDGE_OPENAI_BASE_URL` | `CODER_AI_GATEWAY_OPENAI_BASE_URL` | | +| `CODER_AIBRIDGE_OPENAI_KEY` | `CODER_AI_GATEWAY_OPENAI_KEY` | | +| `CODER_AIBRIDGE_ANTHROPIC_BASE_URL` | `CODER_AI_GATEWAY_ANTHROPIC_BASE_URL` | | +| `CODER_AIBRIDGE_ANTHROPIC_KEY` | `CODER_AI_GATEWAY_ANTHROPIC_KEY` | | +| `CODER_AIBRIDGE_BEDROCK_BASE_URL` | `CODER_AI_GATEWAY_BEDROCK_BASE_URL` | | +| `CODER_AIBRIDGE_BEDROCK_REGION` | `CODER_AI_GATEWAY_BEDROCK_REGION` | | +| `CODER_AIBRIDGE_BEDROCK_ACCESS_KEY` | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY` | | +| `CODER_AIBRIDGE_BEDROCK_ACCESS_KEY_SECRET` | `CODER_AI_GATEWAY_BEDROCK_ACCESS_KEY_SECRET` | | +| `CODER_AIBRIDGE_BEDROCK_MODEL` | `CODER_AI_GATEWAY_BEDROCK_MODEL` | | +| `CODER_AIBRIDGE_BEDROCK_SMALL_FAST_MODEL` | `CODER_AI_GATEWAY_BEDROCK_SMALL_FAST_MODEL` | | +| `CODER_AIBRIDGE_INJECT_CODER_MCP_TOOLS` | `CODER_AI_GATEWAY_INJECT_CODER_MCP_TOOLS` | | +| `CODER_AIBRIDGE_RETENTION` | `CODER_AI_GATEWAY_RETENTION` | | +| `CODER_AIBRIDGE_MAX_CONCURRENCY` | `CODER_AI_GATEWAY_MAX_CONCURRENCY` | | +| `CODER_AIBRIDGE_RATE_LIMIT` | `CODER_AI_GATEWAY_RATE_LIMIT` | | +| `CODER_AIBRIDGE_STRUCTURED_LOGGING` | `CODER_AI_GATEWAY_STRUCTURED_LOGGING` | | +| `CODER_AIBRIDGE_SEND_ACTOR_HEADERS` | `CODER_AI_GATEWAY_SEND_ACTOR_HEADERS` | | +| `CODER_AIBRIDGE_ALLOW_BYOK` | `CODER_AI_GATEWAY_ALLOW_BYOK` | | +| `CODER_AIBRIDGE_CIRCUIT_BREAKER_ENABLED` | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_ENABLED` | | +| `CODER_AIBRIDGE_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_FAILURE_THRESHOLD` | | +| `CODER_AIBRIDGE_CIRCUIT_BREAKER_INTERVAL` | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_INTERVAL` | | +| `CODER_AIBRIDGE_CIRCUIT_BREAKER_TIMEOUT` | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_TIMEOUT` | | +| `CODER_AIBRIDGE_CIRCUIT_BREAKER_MAX_REQUESTS` | `CODER_AI_GATEWAY_CIRCUIT_BREAKER_MAX_REQUESTS` | | +| `CODER_AIBRIDGE_PROVIDER__` | `CODER_AI_GATEWAY_PROVIDER__` | Cannot be mixed; see [below](#provider-configuration-env-vars) | + +AI Gateway Proxy settings: + +| Deprecated | New | Note | +|----------------------------------------------|------------------------------------------------|-----------------------------------| +| `CODER_AIBRIDGE_PROXY_ENABLED` | `CODER_AI_GATEWAY_PROXY_ENABLED` | | +| `CODER_AIBRIDGE_PROXY_LISTEN_ADDR` | `CODER_AI_GATEWAY_PROXY_LISTEN_ADDR` | | +| `CODER_AIBRIDGE_PROXY_TLS_CERT_FILE` | `CODER_AI_GATEWAY_PROXY_TLS_CERT_FILE` | | +| `CODER_AIBRIDGE_PROXY_TLS_KEY_FILE` | `CODER_AI_GATEWAY_PROXY_TLS_KEY_FILE` | | +| `CODER_AIBRIDGE_PROXY_CERT_FILE` | `CODER_AI_GATEWAY_PROXY_CERT_FILE` | | +| `CODER_AIBRIDGE_PROXY_KEY_FILE` | `CODER_AI_GATEWAY_PROXY_KEY_FILE` | | +| `CODER_AIBRIDGE_PROXY_UPSTREAM` | `CODER_AI_GATEWAY_PROXY_UPSTREAM` | | +| `CODER_AIBRIDGE_PROXY_UPSTREAM_CA` | `CODER_AI_GATEWAY_PROXY_UPSTREAM_CA` | | +| `CODER_AIBRIDGE_PROXY_ALLOWED_PRIVATE_CIDRS` | `CODER_AI_GATEWAY_PROXY_ALLOWED_PRIVATE_CIDRS` | | +| `CODER_AIBRIDGE_PROXY_DUMP_DIR` | `CODER_AI_GATEWAY_PROXY_DUMP_DIR` | | +| `CODER_AIBRIDGE_PROXY_DOMAIN_ALLOWLIST` | `CODER_AI_GATEWAY_PROXY_DOMAIN_ALLOWLIST` | Already deprecated; has no effect | + +CLI flags follow the same mapping with the `--aibridge-*` to `--ai-gateway-*` +prefix change. + +### Provider configuration env vars + +Providers are configured with indexed environment variables of the form +`CODER_AI_GATEWAY_PROVIDER__` (for example, +`CODER_AI_GATEWAY_PROVIDER_0_TYPE`, `CODER_AI_GATEWAY_PROVIDER_0_NAME`, +`CODER_AI_GATEWAY_PROVIDER_0_KEY`, `CODER_AI_GATEWAY_PROVIDER_0_BASE_URL`). The +old `CODER_AIBRIDGE_PROVIDER__` prefix is accepted as a deprecated alias. + +Unlike the scalar settings above, you **cannot mix the two prefixes**. Setting +both `CODER_AIBRIDGE_PROVIDER_*` and `CODER_AI_GATEWAY_PROVIDER_*` variables in +the same deployment causes startup to fail with: + +```text +cannot mix CODER_AIBRIDGE_PROVIDER_* and CODER_AI_GATEWAY_PROVIDER_* environment variables, please consolidate onto CODER_AI_GATEWAY_PROVIDER_* +``` + +Move every provider variable onto the new `CODER_AI_GATEWAY_PROVIDER_*` prefix +together (for example, `CODER_AIBRIDGE_PROVIDER_0_TYPE` becomes +`CODER_AI_GATEWAY_PROVIDER_0_TYPE`). + +## HTTP API + +The canonical API path is now `/api/v2/ai-gateway` (and +`/api/v2/ai-gateway/proxy`). The legacy `/api/v2/aibridge` and +`/api/v2/aibridge/proxy` routes are retained for backward compatibility and +continue to serve the same handlers. + +If you have external integrations or agents calling the API directly, update them to the +new path at your convenience. No immediate action is required. + +AI clients (such as Claude Code, Codex, and other tools) that are configured +with a base URL pointing at the legacy `/api/v2/aibridge` path continue to work, +but should be updated to the new `/api/v2/ai-gateway` base URL. + +## Metrics + +The metric prefixes have been renamed: + +| Deprecated prefix | New prefix | +|--------------------------|----------------------------| +| `coder_aibridged_*` | `coder_ai_gateway_*` | +| `coder_aibridgeproxyd_*` | `coder_ai_gateway_proxy_*` | + +**Both the old and new metric names are emitted simultaneously today.** Every +series is exported under both prefixes from the same underlying collector, so +existing dashboards, alerts, and recording rules keep working immediately after +upgrade with no changes. + +The old prefixes are retained for backward compatibility with no planned removal +date. To keep your observability aligned with the new names: + +1. Update Grafana dashboards, Prometheus alerting rules, and recording rules to + reference the new `coder_ai_gateway_*` and `coder_ai_gateway_proxy_*` names. +2. Verify the new series are present in your monitoring stack (they are emitted + as of this release). + +### Optional: dropping the old names + +If you have already migrated to the new names and do not want both prefixes +ingested (for example, to avoid doubling cardinality in your time-series +database), you can drop the deprecated series at scrape time with Prometheus +`metric_relabel_configs`: + +```yaml +metric_relabel_configs: + - source_labels: [__name__] + regex: 'coder_aibridged_.*|coder_aibridgeproxyd_.*' + action: drop +``` + +This keeps the canonical `coder_ai_gateway_*` and `coder_ai_gateway_proxy_*` +series and discards the deprecated `coder_aibridged_*` and +`coder_aibridgeproxyd_*` ones before they are stored. Only do this once your +dashboards, alerts, and recording rules reference the new names. diff --git a/docs/manifest.json b/docs/manifest.json index 71b1d33b33..363601b080 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -1323,6 +1323,12 @@ "description": "Technical reference for AI Gateway", "path": "./ai-coder/ai-gateway/reference.md", "state": ["ai governance add-on"] + }, + { + "title": "Rebranding Migration", + "description": "Migrate from AI Bridge names to AI Gateway", + "path": "./ai-coder/ai-gateway/rebranding-migration.md", + "state": ["ai governance add-on"] } ] },