From 1ba14ff056d6f7374a6e2d2c4310b9c453666925 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Thu, 12 Mar 2026 14:39:25 +0100 Subject: [PATCH 1/5] Add Exports concept page and CLI reference - Create docs/docs/concepts/exports.md concept page - Create docs/docs/reference/cli/dstack/export.md CLI reference - Add cross-links from Fleets and Projects concept pages - Add Exports to nav in mkdocs.yml Co-Authored-By: Claude Opus 4.6 --- docs/docs/concepts/exports.md | 142 +++++++++++++++++++++++ docs/docs/concepts/fleets.md | 10 +- docs/docs/concepts/projects.md | 5 + docs/docs/reference/cli/dstack/export.md | 63 ++++++++++ mkdocs.yml | 2 + 5 files changed, 220 insertions(+), 2 deletions(-) create mode 100644 docs/docs/concepts/exports.md create mode 100644 docs/docs/reference/cli/dstack/export.md diff --git a/docs/docs/concepts/exports.md b/docs/docs/concepts/exports.md new file mode 100644 index 000000000..b338be2e7 --- /dev/null +++ b/docs/docs/concepts/exports.md @@ -0,0 +1,142 @@ +--- +title: Exports +description: Exporting resources across projects +--- + +# Exports + +Exports allow making resources from one project available to other projects. When a project exports a resource, +the specified importer projects can see and use it as if it were their own. + +!!! warning "Experimental" + Exports are an experimental feature. + Currently, only [SSH fleets](fleets.md#ssh-fleets) can be exported. + Exports do not yet support configuration files and `dstack apply`. + Use the CLI commands below to manage exports. + +An export is created in the exporter project and specifies the resources to export and the +importer projects that will gain access to them. + +Once an export is created, the importer projects can see the exported resources in their resource lists and use them +for running tasks, dev environments, and services. Imported resources appear with a project prefix +(e.g., `team-a/my-fleet`) to distinguish them from the project's own resources. + +!!! info "Required project role" + The user creating or updating an export must have the project admin role on both the exporter project and + each importer project. Alternatively, a global admin can add any project as an importer. + +## Manage exports + +### Create exports + +Use the `dstack export create` command to create a new export. Specify the fleets to export +with `--fleet` and the importer projects with `--importer`: + +
+ +```shell +$ dstack export create my-export --fleet my-fleet --importer team-b + NAME FLEETS IMPORTERS + my-export my-fleet team-b + +``` + +
+ +Both `--fleet` and `--importer` can be specified multiple times: + +
+ +```shell +$ dstack export create shared-gpus --fleet gpu-fleet-1 --fleet gpu-fleet-2 --importer team-b --importer team-c + NAME FLEETS IMPORTERS + shared-gpus gpu-fleet-1, gpu-fleet-2 team-b, team-c + +``` + +
+ +### List exports + +Use `dstack export list` (or simply `dstack export`) to list all exports in the project: + +
+ +```shell +$ dstack export list + NAME FLEETS IMPORTERS + my-export my-fleet team-b + shared-gpus gpu-fleet-1, gpu-fleet-2 team-b, team-c + +``` + +
+ +### Update exports + +Use the `dstack export update` command to add or remove fleets and importers from an existing export: + +
+ +```shell +$ dstack export update my-export --add-fleet another-fleet --add-importer team-c + NAME FLEETS IMPORTERS + my-export my-fleet, another-fleet team-b, team-c + +``` + +
+ +To remove a fleet or importer: + +
+ +```shell +$ dstack export update my-export --remove-importer team-b + NAME FLEETS IMPORTERS + my-export my-fleet, another-fleet team-c + +``` + +
+ +### Delete exports + +Use the `dstack export delete` command to delete an export. This revokes access for all importer projects: + +
+ +```shell +$ dstack export delete my-export +Delete the export my-export? [y/n]: y +Export my-export deleted +``` + +
+ +Use `-y` to skip the confirmation prompt. + +## Access imported fleets + +From the importer project's perspective, exported fleets appear automatically in `dstack fleet list` +with a `/` prefix: + +
+ +```shell +$ dstack fleet list + NAME NODES GPU SPOT BACKEND PRICE STATUS CREATED + my-local-fleet 1 - - ssh - active 3 days ago + team-a/my-fleet 2 A100:80GB:8 - ssh - active 1 week ago + team-a/another-fleet 1 H100:80GB:4 - ssh - active 2 days ago + +``` + +
+ +Imported fleets can be used for runs just like the project's own fleets. + +!!! info "What's next?" + 1. Check the [`dstack export` CLI reference](../reference/cli/dstack/export.md) + 2. Learn how to manage [fleets](fleets.md) + 3. Read about [projects](projects.md) and project roles diff --git a/docs/docs/concepts/fleets.md b/docs/docs/concepts/fleets.md index 027ea14ed..b3e5e0b15 100644 --- a/docs/docs/concepts/fleets.md +++ b/docs/docs/concepts/fleets.md @@ -468,6 +468,11 @@ ssh_config: !!! info "Reference" The fleet configuration file supports additional options, including [`instance_types`](../reference/dstack.yml/fleet.md#instance_types), [`max_price`](../reference/dstack.yml/fleet.md#max_price), [`regions`](../reference/dstack.yml/fleet.md#max_price), among others. For the complete list, see the [reference](../reference/dstack.yml/fleet.md). +## Export fleets + +Fleets can be exported to other projects, allowing those projects to use the exported fleets +for running dev environments, tasks, and services. See [Exports](exports.md) for more details. + ## Manage fleets ### List fleets @@ -507,5 +512,6 @@ To terminate and delete specific instances from a fleet, pass `-i INSTANCE_NUM`. 1. Check [dev environments](dev-environments.md), [tasks](tasks.md), and [services](services.md) 2. Read about [Backends](backends.md) guide - 3. Explore the [`.dstack.yml` reference](../reference/dstack.yml/fleet.md) - 4. See the [Clusters](../../examples.md#clusters) example + 3. Learn how to [export fleets](exports.md) to other projects + 4. Explore the [`.dstack.yml` reference](../reference/dstack.yml/fleet.md) + 5. See the [Clusters](../../examples.md#clusters) example diff --git a/docs/docs/concepts/projects.md b/docs/docs/concepts/projects.md index a7e745407..54692ed1f 100644 --- a/docs/docs/concepts/projects.md +++ b/docs/docs/concepts/projects.md @@ -41,6 +41,11 @@ A user can be added to a project and assigned or unassigned as a project role on Unlike admins, managers cannot configure backends and gateways. * **User** – A user can manage project resources including runs, fleets, and volumes. +## Project exports + +Projects can export resources such as fleets to other projects, allowing them to be used across team +boundaries. See [Exports](exports.md) for more details. + ## Authorization ### User token diff --git a/docs/docs/reference/cli/dstack/export.md b/docs/docs/reference/cli/dstack/export.md new file mode 100644 index 000000000..6b5a3dcf3 --- /dev/null +++ b/docs/docs/reference/cli/dstack/export.md @@ -0,0 +1,63 @@ +# dstack export + +The `dstack export` commands manage [exports](../../../concepts/exports.md) of resources to other projects. + +## dstack export list + +The `dstack export list` command lists all exports in the project. + +##### Usage + +
+ +```shell +$ dstack export list --help +#GENERATE# +``` + +
+ +## dstack export create + +The `dstack export create` command creates a new export. + +##### Usage + +
+ +```shell +$ dstack export create --help +#GENERATE# +``` + +
+ +## dstack export update + +The `dstack export update` command updates an existing export. + +##### Usage + +
+ +```shell +$ dstack export update --help +#GENERATE# +``` + +
+ +## dstack export delete + +The `dstack export delete` command deletes the specified export. + +##### Usage + +
+ +```shell +$ dstack export delete --help +#GENERATE# +``` + +
diff --git a/mkdocs.yml b/mkdocs.yml index de82cba60..3c9f1ee1d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -237,6 +237,7 @@ nav: - Projects: docs/concepts/projects.md - Metrics: docs/concepts/metrics.md - Events: docs/concepts/events.md + - Exports: docs/concepts/exports.md - Guides: - Server deployment: docs/guides/server-deployment.md - Troubleshooting: docs/guides/troubleshooting.md @@ -271,6 +272,7 @@ nav: - dstack volume: docs/reference/cli/dstack/volume.md - dstack gateway: docs/reference/cli/dstack/gateway.md - dstack secret: docs/reference/cli/dstack/secret.md + - dstack export: docs/reference/cli/dstack/export.md - API: - Python API: docs/reference/api/python/index.md - REST API: docs/reference/api/rest/index.md From 2bce3ebda2c5e0ba454cb7500ad7e0fc3e2a780f Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Thu, 12 Mar 2026 18:16:09 +0100 Subject: [PATCH 2/5] Update docs/docs/concepts/exports.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/exports.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/concepts/exports.md b/docs/docs/concepts/exports.md index b338be2e7..d13ae89af 100644 --- a/docs/docs/concepts/exports.md +++ b/docs/docs/concepts/exports.md @@ -23,7 +23,7 @@ for running tasks, dev environments, and services. Imported resources appear wit !!! info "Required project role" The user creating or updating an export must have the project admin role on both the exporter project and - each importer project. Alternatively, a global admin can add any project as an importer. + any importer project they add. Alternatively, a global admin can add any project as an importer. ## Manage exports From 4dc9341aa8c29f0761fd24d3a2039f7cfdc7e648 Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov <54148038+peterschmidt85@users.noreply.github.com> Date: Thu, 12 Mar 2026 18:26:52 +0100 Subject: [PATCH 3/5] Update docs/docs/concepts/exports.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> --- docs/docs/concepts/exports.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs/concepts/exports.md b/docs/docs/concepts/exports.md index d13ae89af..900004821 100644 --- a/docs/docs/concepts/exports.md +++ b/docs/docs/concepts/exports.md @@ -11,8 +11,6 @@ the specified importer projects can see and use it as if it were their own. !!! warning "Experimental" Exports are an experimental feature. Currently, only [SSH fleets](fleets.md#ssh-fleets) can be exported. - Exports do not yet support configuration files and `dstack apply`. - Use the CLI commands below to manage exports. An export is created in the exporter project and specifies the resources to export and the importer projects that will gain access to them. From 868fef46779f4fa1b361cb35241fca08257c945b Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Thu, 12 Mar 2026 22:58:50 +0100 Subject: [PATCH 4/5] Add tenant isolation section to Fleets and Exports docs Describe the current host access model for fleet workloads and link to the SSH reverse proxy roadmap issue. Add a brief cross-reference in the Exports page. Co-Authored-By: Claude Opus 4.6 --- docs/docs/concepts/exports.md | 3 +++ docs/docs/concepts/fleets.md | 9 +++++++++ 2 files changed, 12 insertions(+) diff --git a/docs/docs/concepts/exports.md b/docs/docs/concepts/exports.md index 900004821..3b3194146 100644 --- a/docs/docs/concepts/exports.md +++ b/docs/docs/concepts/exports.md @@ -134,6 +134,9 @@ $ dstack fleet list Imported fleets can be used for runs just like the project's own fleets. +!!! info "Tenant isolation" + Exported fleets share the same access model as regular fleets. See [Tenant isolation](fleets.md#tenant-isolation) for details. + !!! info "What's next?" 1. Check the [`dstack export` CLI reference](../reference/cli/dstack/export.md) 2. Learn how to manage [fleets](fleets.md) diff --git a/docs/docs/concepts/fleets.md b/docs/docs/concepts/fleets.md index b3e5e0b15..02259b5ef 100644 --- a/docs/docs/concepts/fleets.md +++ b/docs/docs/concepts/fleets.md @@ -468,6 +468,15 @@ ssh_config: !!! info "Reference" The fleet configuration file supports additional options, including [`instance_types`](../reference/dstack.yml/fleet.md#instance_types), [`max_price`](../reference/dstack.yml/fleet.md#max_price), [`regions`](../reference/dstack.yml/fleet.md#max_price), among others. For the complete list, see the [reference](../reference/dstack.yml/fleet.md). +## Tenant isolation + +Workloads running on a fleet have access to the host, including mounted folders. For distributed workloads, +containers use host network mode. + +Tighter isolation is on the roadmap, including [SSH reverse proxy](https://github.com/dstackai/dstack/issues/3644){:target="_blank"} and rootless access to the host. + +When [exporting fleets](exports.md) to other projects, the same access model applies to members of the importer projects. + ## Export fleets Fleets can be exported to other projects, allowing those projects to use the exported fleets From 3a87188dd77ff8dfbfda836796e04a66f2d0216a Mon Sep 17 00:00:00 2001 From: Andrey Cheptsov Date: Fri, 13 Mar 2026 11:49:54 +0100 Subject: [PATCH 5/5] Update tenant isolation wording per review feedback Clarify that host network mode applies to all workloads (not just distributed), and refine language around host access and instance volumes. Co-Authored-By: Claude Opus 4.6 --- docs/docs/concepts/fleets.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/concepts/fleets.md b/docs/docs/concepts/fleets.md index 02259b5ef..01f5d39ac 100644 --- a/docs/docs/concepts/fleets.md +++ b/docs/docs/concepts/fleets.md @@ -470,8 +470,8 @@ ssh_config: ## Tenant isolation -Workloads running on a fleet have access to the host, including mounted folders. For distributed workloads, -containers use host network mode. +Users running workloads on a fleet have access to the host, including the folders that may be used as instance volumes, +and containers use host network mode unless the host has multiple [blocks](#blocks) configured and the job uses only a subset of them. Tighter isolation is on the roadmap, including [SSH reverse proxy](https://github.com/dstackai/dstack/issues/3644){:target="_blank"} and rootless access to the host.