diff --git a/docs/install/releases/esr-2.29-2.34-upgrade.md b/docs/install/releases/esr-2.29-2.34-upgrade.md index 9baee0b73d..b5a7eac7c6 100644 --- a/docs/install/releases/esr-2.29-2.34-upgrade.md +++ b/docs/install/releases/esr-2.29-2.34-upgrade.md @@ -172,33 +172,34 @@ The CLI and dashboard gained smaller but meaningful workflow improvements: The following changes introduced after 2.29 might break workflows, require manual updates, or change administrator expectations: -| Initial State (2.29 and before) | New State (2.30-2.34) | Change Required | -|-----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Terraform modules are downloaded during each workspace start. | Terraform modules are cached and pinned per template version. | Publish a new template version when upstream module changes should apply. Test templates that relied on fresh module downloads. See [speed up templates](../../tutorials/best-practices/speed-up-templates.md). | -| Integrations may use experimental AI Bridge endpoints under `/api/experimental/aibridge/*`. | Experimental AI Bridge endpoints were removed after AI Gateway graduated to stable routes. | Update clients to use `/api/v2/aibridge/*` routes. Review API consumers again because `/api/v2/aibridge/interceptions` is now deprecated in favor of `/api/v2/aibridge/sessions`. See the [AI Gateway API reference](../../reference/api/aigateway.md). | -| Unknown external OAuth providers did not default to PKCE. | Unknown external OAuth providers now default to PKCE. | If a provider does not support PKCE, set `CODER_EXTERNAL_AUTH__PKCE_METHODS=none`. See [external authentication](../../admin/external-auth/index.md). | -| `--secure-auth-cookie` defaulted independently from the access URL. | Secure auth cookies are enabled automatically when `CODER_ACCESS_URL` uses HTTPS. | Confirm reverse proxies send the correct scheme headers. To preserve old behavior, explicitly set `CODER_SECURE_AUTH_COOKIE=false`. | -| SFTP and SCP connections always landed in `$HOME`. | SFTP and SCP now respect the workspace agent `dir` setting. | Update scripts that relied on implicit `$HOME` paths. Prefer explicit absolute paths for file transfers. | -| `coder_agent` `dir` attribute accepted any path without warning. | `dir` is deprecated and emits a warning. Non-`$HOME`/`~` values also break [Coder Desktop file sync](../../user-guides/desktop/desktop-connect-sync.md). | Set `dir` to `$HOME` or omit it on `coder_agent` resources. The attribute still works in 2.34 but will be removed in a future release. | -| Pre-2.28 Tasks templates might still exist in older deployments. | The pre-2.28 Tasks template format is no longer supported as of 2.30. | Update Tasks templates to use `app_id` instead of the deprecated `sidebar_app` flow. See the [Tasks migration guide](../../ai-coder/tasks-migration.md). | -| Tasks is the primary AI coding workflow. | Coder Agents is the long-term replacement, and Tasks is supported through the 2.34 ESR window (into 2026). | Plan migration from the Tasks API to the Chats API and Coder Agents. See [Migrating from the Tasks API to the Chats API](../../ai-coder/agents/tasks-to-chats-migration.md). | -| AI Gateway injected MCP tools can be used for tool exposure. | Injected MCP tools are deprecated. | Move new integrations toward Coder Agents MCP server configuration or the MCP server flow. See [AI Gateway MCP](../../ai-coder/ai-gateway/mcp.md) and [MCP servers](../../ai-coder/agents/platform-controls/mcp-servers.md). | -| AI Bridge is opt-in via `CODER_AIBRIDGE_ENABLED` (default `false`). | The toggle is renamed to `CODER_AI_GATEWAY_ENABLED` and now defaults to `true`. | The in-memory AI Gateway now starts on every deployment. Set `CODER_AI_GATEWAY_ENABLED=false`, or the deprecated `CODER_AIBRIDGE_ENABLED` alias which still works, to keep the old behavior. | -| AI Gateway providers are configured with `CODER_AIBRIDGE_PROVIDER_*` or `CODER_AI_GATEWAY_PROVIDER_*` env vars. | Provider configuration is stored in the database. Env vars seed the database once on first startup, then are deprecated. | After upgrade, visit `/ai/settings/providers` to verify seeded providers, then remove the env vars. Coderd fails to start if env vars drift from the seeded database row. See [AI Gateway providers](../../ai-coder/ai-gateway/providers.md). | -| Regular users can read their own AI Gateway interceptions. | Only owners and auditors can read AI Gateway interception data. | Update dashboards, scripts, or user workflows that expected self-service interception reads. This intentionally narrows the RBAC surface. | -| `coder groups list -o json` returns the old command output shape. | `coder groups list -o json` returns a flat structure matching other list commands. | Update scripts that parse this command output. | -| `coder tokens rm` deletes token records by default. | `coder tokens rm` expires tokens by default and keeps records for auditability. | Use `coder tokens rm --delete` only when the token record must be deleted. Update scripts that expect removed tokens to disappear from token history. | -| Deprecated Prometheus metrics are still emitted. | Deprecated Prometheus metrics were removed. | Update dashboards and alerts that use `coderd_api_workspace_latest_build_total` or `coderd_oauth2_external_requests_rate_limit_total`. Use the replacement metrics without the `_total` suffix. | -| Authenticated rate limits are effectively shared by client IP in some deployments. | Authenticated request rate limits are keyed by user. | Review monitoring and expectations for NATed users or shared proxies. Per-user limits now apply more consistently after API key precheck. | -| `coder login` can run while `CODER_SESSION_TOKEN` is set. | `coder login` errors when `CODER_SESSION_TOKEN` is set. | Unset `CODER_SESSION_TOKEN` in interactive login flows. Keep using the environment variable for non-interactive automation. | -| Workspace starts with new parameters can proceed without an explicit stop in some flows. | Workspace starts with new parameters stop the workspace before starting. | Expect downtime when applying new parameters. Update automation that assumes the workspace remains running. | -| `mode=auto` workspace links can silently create workspaces with prefilled parameters. | Users must confirm workspace auto-creation before provisioning starts. | Update Open in Coder buttons, runbooks, or internal flows that expect one-click workspace creation without a consent dialog. | -| Users with `--login-type none` are common for automation. | `--login-type none` is deprecated. | For Premium deployments, migrate automation to service accounts. For OSS deployments, use regular users with password, GitHub, or OIDC authentication. See [headless auth](../../admin/users/headless-auth.md). | -| Terminal commands can be executed from URL parameters without extra confirmation. | The dashboard requires confirmation before executing terminal commands from URLs. | Update runbooks or deep links that expected immediate terminal execution. This protects users from accidental command execution. | -| Agent SSH port forwarding is always available when the agent allows SSH. | Reverse and local port forwarding can be disabled per agent. | Review templates and IDE workflows before enabling `--block-reverse-port-forwarding` or `--block-local-port-forwarding`. See [port forwarding](../../admin/networking/port-forwarding.md). | -| `PATCH /api/v2/templates/{template}` accepts value fields for metadata updates. | Template metadata update fields are optional pointer fields in the SDK, and 304 responses were removed. | Update SDK consumers and direct API clients that patch template metadata. Send only fields that should change, including false or zero values explicitly. | -| External provisioner daemons use the 2.29 provisionerd protocol. | The provisionerd protocol changed for provisioner operations and file upload/download. | Update external provisioner daemons to the matching 2.34 protocol. The protocol reserves removed fields such as `stop_modules`, `exp_reuse_terraform_workspace`, and `user_secrets`, and adds `DownloadFile`. | -| Helm chart health probes and observability bind addresses use older chart defaults. | Readiness and liveness probes have `enabled` toggles and more fields, and Prometheus/pprof addresses are overridable. | Review custom Helm values for probe behavior and observability bindings. Prefer restricting pprof to a local address when exposing diagnostics. | +| Initial State (2.29 and before) | New State (2.30-2.34) | Change Required | +|-----------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Terraform modules are downloaded during each workspace start. | Terraform modules are cached and pinned per template version. | Publish a new template version when upstream module changes should apply. Test templates that relied on fresh module downloads. See [speed up templates](../../tutorials/best-practices/speed-up-templates.md). | +| Integrations may use experimental AI Bridge endpoints under `/api/experimental/aibridge/*`. | Experimental AI Bridge endpoints were removed after AI Gateway graduated to stable routes. | Update clients to use `/api/v2/aibridge/*` routes. Review API consumers again because `/api/v2/aibridge/interceptions` is now deprecated in favor of `/api/v2/aibridge/sessions`. See the [AI Gateway API reference](../../reference/api/aigateway.md). | +| Unknown external OAuth providers did not default to PKCE. | Unknown external OAuth providers now default to PKCE. | If a provider does not support PKCE, set `CODER_EXTERNAL_AUTH__PKCE_METHODS=none`. See [external authentication](../../admin/external-auth/index.md). | +| GitLab external auth required only the `write_repository` scope. | GitLab external auth now requires `write_repository` and `read_api` scopes by default. | Add the `read_api` scope to your GitLab OAuth application. Existing users must re-authenticate to obtain the new scope. If you set scopes explicitly via `CODER_EXTERNAL_AUTH__SCOPES`, add `read_api` there as well. See [external authentication](../../admin/external-auth/index.md). | +| `--secure-auth-cookie` defaulted independently from the access URL. | Secure auth cookies are enabled automatically when `CODER_ACCESS_URL` uses HTTPS. | Confirm reverse proxies send the correct scheme headers. To preserve old behavior, explicitly set `CODER_SECURE_AUTH_COOKIE=false`. | +| SFTP and SCP connections always landed in `$HOME`. | SFTP and SCP now respect the workspace agent `dir` setting. | Update scripts that relied on implicit `$HOME` paths. Prefer explicit absolute paths for file transfers. | +| `coder_agent` `dir` attribute accepted any path without warning. | `dir` is deprecated and emits a warning. Non-`$HOME`/`~` values also break [Coder Desktop file sync](../../user-guides/desktop/desktop-connect-sync.md). | Set `dir` to `$HOME` or omit it on `coder_agent` resources. The attribute still works in 2.34 but will be removed in a future release. | +| Pre-2.28 Tasks templates might still exist in older deployments. | The pre-2.28 Tasks template format is no longer supported as of 2.30. | Update Tasks templates to use `app_id` instead of the deprecated `sidebar_app` flow. See the [Tasks migration guide](../../ai-coder/tasks-migration.md). | +| Tasks is the primary AI coding workflow. | Coder Agents is the long-term replacement, and Tasks is supported through the 2.34 ESR window (into 2026). | Plan migration from the Tasks API to the Chats API and Coder Agents. See [Migrating from the Tasks API to the Chats API](../../ai-coder/agents/tasks-to-chats-migration.md). | +| AI Gateway injected MCP tools can be used for tool exposure. | Injected MCP tools are deprecated. | Move new integrations toward Coder Agents MCP server configuration or the MCP server flow. See [AI Gateway MCP](../../ai-coder/ai-gateway/mcp.md) and [MCP servers](../../ai-coder/agents/platform-controls/mcp-servers.md). | +| AI Bridge is opt-in via `CODER_AIBRIDGE_ENABLED` (default `false`). | The toggle is renamed to `CODER_AI_GATEWAY_ENABLED` and now defaults to `true`. | The in-memory AI Gateway now starts on every deployment. Set `CODER_AI_GATEWAY_ENABLED=false`, or the deprecated `CODER_AIBRIDGE_ENABLED` alias which still works, to keep the old behavior. | +| AI Gateway providers are configured with `CODER_AIBRIDGE_PROVIDER_*` or `CODER_AI_GATEWAY_PROVIDER_*` env vars. | Provider configuration is stored in the database. Env vars seed the database once on first startup, then are deprecated. | After upgrade, visit `/ai/settings/providers` to verify seeded providers, then remove the env vars. Coderd fails to start if env vars drift from the seeded database row. See [AI Gateway providers](../../ai-coder/ai-gateway/providers.md). | +| Regular users can read their own AI Gateway interceptions. | Only owners and auditors can read AI Gateway interception data. | Update dashboards, scripts, or user workflows that expected self-service interception reads. This intentionally narrows the RBAC surface. | +| `coder groups list -o json` returns the old command output shape. | `coder groups list -o json` returns a flat structure matching other list commands. | Update scripts that parse this command output. | +| `coder tokens rm` deletes token records by default. | `coder tokens rm` expires tokens by default and keeps records for auditability. | Use `coder tokens rm --delete` only when the token record must be deleted. Update scripts that expect removed tokens to disappear from token history. | +| Deprecated Prometheus metrics are still emitted. | Deprecated Prometheus metrics were removed. | Update dashboards and alerts that use `coderd_api_workspace_latest_build_total` or `coderd_oauth2_external_requests_rate_limit_total`. Use the replacement metrics without the `_total` suffix. | +| Authenticated rate limits are effectively shared by client IP in some deployments. | Authenticated request rate limits are keyed by user. | Review monitoring and expectations for NATed users or shared proxies. Per-user limits now apply more consistently after API key precheck. | +| `coder login` can run while `CODER_SESSION_TOKEN` is set. | `coder login` errors when `CODER_SESSION_TOKEN` is set. | Unset `CODER_SESSION_TOKEN` in interactive login flows. Keep using the environment variable for non-interactive automation. | +| Workspace starts with new parameters can proceed without an explicit stop in some flows. | Workspace starts with new parameters stop the workspace before starting. | Expect downtime when applying new parameters. Update automation that assumes the workspace remains running. | +| `mode=auto` workspace links can silently create workspaces with prefilled parameters. | Users must confirm workspace auto-creation before provisioning starts. | Update Open in Coder buttons, runbooks, or internal flows that expect one-click workspace creation without a consent dialog. | +| Users with `--login-type none` are common for automation. | `--login-type none` is deprecated. | For Premium deployments, migrate automation to service accounts. For OSS deployments, use regular users with password, GitHub, or OIDC authentication. See [headless auth](../../admin/users/headless-auth.md). | +| Terminal commands can be executed from URL parameters without extra confirmation. | The dashboard requires confirmation before executing terminal commands from URLs. | Update runbooks or deep links that expected immediate terminal execution. This protects users from accidental command execution. | +| Agent SSH port forwarding is always available when the agent allows SSH. | Reverse and local port forwarding can be disabled per agent. | Review templates and IDE workflows before enabling `--block-reverse-port-forwarding` or `--block-local-port-forwarding`. See [port forwarding](../../admin/networking/port-forwarding.md). | +| `PATCH /api/v2/templates/{template}` accepts value fields for metadata updates. | Template metadata update fields are optional pointer fields in the SDK, and 304 responses were removed. | Update SDK consumers and direct API clients that patch template metadata. Send only fields that should change, including false or zero values explicitly. | +| External provisioner daemons use the 2.29 provisionerd protocol. | The provisionerd protocol changed for provisioner operations and file upload/download. | Update external provisioner daemons to the matching 2.34 protocol. The protocol reserves removed fields such as `stop_modules`, `exp_reuse_terraform_workspace`, and `user_secrets`, and adds `DownloadFile`. | +| Helm chart health probes and observability bind addresses use older chart defaults. | Readiness and liveness probes have `enabled` toggles and more fields, and Prometheus/pprof addresses are overridable. | Review custom Helm values for probe behavior and observability bindings. Prefer restricting pprof to a local address when exposing diagnostics. | ## Upgrading @@ -263,7 +264,9 @@ The Coder team recommends taking the following steps when performing the upgrade support window, but new automation should use Coder Agents and the Chats API. Update internal docs, templates, and API clients accordingly. - **Validate external authentication:** Test GitHub, GitLab, OIDC, and custom - external auth providers. Disable PKCE for providers that do not support it. + external auth providers. Add the `read_api` scope to GitLab OAuth applications + and have users re-authenticate. Disable PKCE for providers that do not support + it. - **Migrate headless automation to service accounts:** Replace users created with `--login-type none` where possible, and verify CI/CD tokens, template publish jobs, and workspace automation.