diff --git a/docs/blog/posts/0_20.md b/docs/blog/posts/0_20.md new file mode 100644 index 000000000..33f7e66e8 --- /dev/null +++ b/docs/blog/posts/0_20.md @@ -0,0 +1,127 @@ +--- +title: "dstack 0.20 GA: Fleet-first UX and other important changes" +date: 2025-12-18 +description: "TBA" +slug: "0_20" +image: https://dstack.ai/static-assets/static-assets/images/dstack-0_20.png +categories: + - Changelog +links: + - Release notes: https://github.com/dstackai/dstack/releases/tag/0.20.0 + - Migration guide: https://dstack.ai/docs/guides/migration/#0_20 +--- + +# dstack 0.20 GA: Fleet-first UX and other important changes + +We’re releasing `dstack` 0.20.0, a major update that improves how teams orchestrate GPU workloads for development, training, and inference. Most `dstack` updates are incremental and backward compatible, but this version introduces a few major changes to how you work with `dstack`. + +In `dstack` 0.20.0, fleets are now a first-class concept, giving you more explicit control over how GPU capacity is provisioned and managed. We’ve also added *Events*, which record important system activity—such as scheduling decisions, run status changes, and resource lifecycle updates—so it’s easier to understand what’s happening without digging through server logs. + + + +This post goes through the changes in detail and explains how to upgrade and migrate your existing setup. + + + +## Fleets + +In earlier versions, submitting a run that didn’t match any existing fleet would cause `dstack` to automatically create one. While this reduced setup overhead, it also made capacity provisioning implicit and less predictable. + +With `dstack` 0.20.0, fleets must be created explicitly and treated as first-class resources. This shift makes capacity provisioning declarative, improving control over resource limits, instance lifecycles, and overall fleet behavior. + +For users who previously relied on auto-created fleets, similar behavior can be achieved by defining an elastic fleet, for example: + +
+ + ```yaml + type: fleet + # The name is optional, if not specified, generated randomly + name: default + + # Can be a range or a fixed number + # Allow to provision of up to 2 instances + nodes: 0..2 + + # Uncomment to ensure instances are inter-connected + #placement: cluster + + # Deprovision instances above the minimum if they remain idle + idle_duration: 1h + + resources: + # Allow to provision up to 8 GPUs + gpu: 0..8 + ``` + +
+ +If the `nodes` range starts above `0`, `dstack` provisions the initial capacity upfront and scales additional instances on demand, enabling more predictable capacity planning. + +When a run does not explicitly reference a fleet (via the [`fleets`](../../docs/reference/dstack.yml/dev-environment.md#fleets) property), `dstack` automatically selects one that satisfies the run’s requirements. + +## Events + +Previously, when `dstack` changed the state of a run or other resource, that information was written only to the server logs. This worked for admins, but it made it hard for users to understand what happened or why. + +Starting with version `0.20.0`, `dstack` exposes these events directly to users. + +Each resource now includes an `Events` tab in the UI, showing related events in real time: + + + +There is also a dedicated `Events` page that aggregates events across resources. You can filter by project, user, run, or job to quickly narrow down what you’re looking for: + + + +The same information is available through the CLI: + + + +This makes it easier to track state changes, debug issues, and review past actions without needing access to server logs. + +## Runs + +This release updates several defaults related to run configuration. The goal is to reduce implicit assumptions and make it more convenient. + +### Working directory + +Previously, the `working_dir` property defaulted to `/workflow`. Now, the default working directory is always taken from the Docker image. + +The working directory in the default Docker images (if you don't specify image) is now set to `/dstack/run`. + +### Repo directory + +Previously, if you didn't specify a repo path, the repo was cloned to `/workflow`. Now, in that case the repo will be cloned to the working directory. + +
+ +```yaml +type: dev-environment +name: vscode + +repos: + # Clones the repo from the parent directory (`examples/..`) to `` + - .. + +ide: vscode +``` + +
+ +Also, now if the repo directory is not empty, the run will fail with an error. + +## Backward compatibility + +While the update introduces breaking changes, 0.19.* CLIs remain compatible with 0.20.* servers. + +> Note, the 0.20.* CLI only works with a 0.20.* server. + +!!! warning "Breaking changes" + This release introduces breaking changes that may affect existing setups. Before upgrading either the CLI or the server, review the [migration guide](https://dstack.ai/docs/guides/migration/#0_20). + +## What's next + +1. Follow the [Installation](../../docs/installation/index.md) guide +2. Try the [Quickstart](../../docs/quickstart.md) +3. Report issues on [GitHub](https://github.com/dstackai/dstack/issues) +4. Ask questions on [Discord](https://discord.gg/u8SmfwPpMd)