diff --git a/mkdocs/docs/guides/upgrade.md b/mkdocs/docs/guides/upgrade.md
index 220c6b747..4cced2d51 100644
--- a/mkdocs/docs/guides/upgrade.md
+++ b/mkdocs/docs/guides/upgrade.md
@@ -7,6 +7,59 @@ description: Upgrading to newer versions of dstack
 
 <!-- TODO: Add general sections on how to migrate to newer releases and how major and minor versions compatibility  and deprecation policy is handled -->
 
+## 0.21.* { #0_21 }
+
+### CLI compatibility
+
+- CLI versions `0.20.*` and later remain backward compatible with the `0.21.*` `dstack` server.
+- CLI versions `0.21.*` are not compatible with server versions prior to `0.21.*`.
+
+> Upgrade the server before upgrading the CLI, or upgrade both at the same time. CLI versions prior to `0.20.0` must be upgraded along with the server.
+
+### Pydantic v2
+
+`dstack` has migrated from Pydantic v1 to Pydantic v2. The `dstack` Python API and `dstack` plugins now work with Pydantic v2 models.
+
+> If you use the Python API or have plugins installed, ensure the code works with Pydantic v2 models before upgrading.
+
+If you call the `dstack` HTTP API directly, note that UTC datetimes are now serialized with a `Z` suffix instead of `+00:00`.
+
+### Gateway routers
+
+The top-level `router` property of gateway and run configurations, deprecated in `0.20.17` in favor of [replica-based routers](../concepts/services.md#pd-disaggregation), has been removed. Configurations that use it are no longer accepted, and the behavior of gateways and services created with it before the upgrade is undefined.
+
+> Terminate services and gateways that use the top-level `router` property before upgrading, then recreate them using replica-based routers.
+
+### Presets
+
+[Preset](../concepts/presets.md) configuration properties have changed: `max_trials` is now `trials`, and `context_length` is now `min_context_length`. The `max_ttft`, `min_context_length`, and `concurrency` properties no longer have defaults and must be specified. Presets are an experimental feature, so no aliases were kept - existing configurations fail with `extra fields not permitted`.
+
+> Update preset configurations to the new property names before upgrading.
+
+### Deprecated feature removal
+
+The following deprecated API endpoints have been removed in **0.21**:
+
+- `/api/project/{project_name}/runs/submit`
+- `/api/project/{project_name}/fleets/create`
+
+Use the corresponding replacements:
+
+- `/api/project/{project_name}/runs/apply`
+- `/api/project/{project_name}/fleets/apply`
+
+### Deprecations
+
+The following API response fields are no longer populated by the server and will be removed in **0.22**:
+
+- `Resources.description`
+- `Gateway.backend`
+- `Gateway.region`
+
+> For gateways, use `Gateway.configuration.backend` and `Gateway.configuration.region` instead.
+
+> For more details on the changes, see the [release notes](https://github.com/dstackai/dstack/releases).
+
 ## 0.20.* { #0_20 }
 
 ### CLI compatibility