Skip to content

Commit c5fbd0a

Browse files
peterschmidt85Andrey Cheptsovclaudejvstme
authored
Add Exports concept page and CLI reference (#3659)
* 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 <noreply@anthropic.com> * Update docs/docs/concepts/exports.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> * Update docs/docs/concepts/exports.md Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com> * 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 <noreply@anthropic.com> * 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 <noreply@anthropic.com> --------- Co-authored-by: Andrey Cheptsov <andrey.cheptsov@github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: jvstme <36324149+jvstme@users.noreply.github.com>
1 parent f077822 commit c5fbd0a

5 files changed

Lines changed: 230 additions & 2 deletions

File tree

‎docs/docs/concepts/exports.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Exports
3+
description: Exporting resources across projects
4+
---
5+
6+
# Exports
7+
8+
Exports allow making resources from one project available to other projects. When a project exports a resource,
9+
the specified importer projects can see and use it as if it were their own.
10+
11+
!!! warning "Experimental"
12+
Exports are an experimental feature.
13+
Currently, only [SSH fleets](fleets.md#ssh-fleets) can be exported.
14+
15+
An export is created in the exporter project and specifies the resources to export and the
16+
importer projects that will gain access to them.
17+
18+
Once an export is created, the importer projects can see the exported resources in their resource lists and use them
19+
for running tasks, dev environments, and services. Imported resources appear with a project prefix
20+
(e.g., `team-a/my-fleet`) to distinguish them from the project's own resources.
21+
22+
!!! info "Required project role"
23+
The user creating or updating an export must have the project admin role on both the exporter project and
24+
any importer project they add. Alternatively, a global admin can add any project as an importer.
25+
26+
## Manage exports
27+
28+
### Create exports
29+
30+
Use the `dstack export create` command to create a new export. Specify the fleets to export
31+
with `--fleet` and the importer projects with `--importer`:
32+
33+
<div class="termy">
34+
35+
```shell
36+
$ dstack export create my-export --fleet my-fleet --importer team-b
37+
NAME FLEETS IMPORTERS
38+
my-export my-fleet team-b
39+
40+
```
41+
42+
</div>
43+
44+
Both `--fleet` and `--importer` can be specified multiple times:
45+
46+
<div class="termy">
47+
48+
```shell
49+
$ dstack export create shared-gpus --fleet gpu-fleet-1 --fleet gpu-fleet-2 --importer team-b --importer team-c
50+
NAME FLEETS IMPORTERS
51+
shared-gpus gpu-fleet-1, gpu-fleet-2 team-b, team-c
52+
53+
```
54+
55+
</div>
56+
57+
### List exports
58+
59+
Use `dstack export list` (or simply `dstack export`) to list all exports in the project:
60+
61+
<div class="termy">
62+
63+
```shell
64+
$ dstack export list
65+
NAME FLEETS IMPORTERS
66+
my-export my-fleet team-b
67+
shared-gpus gpu-fleet-1, gpu-fleet-2 team-b, team-c
68+
69+
```
70+
71+
</div>
72+
73+
### Update exports
74+
75+
Use the `dstack export update` command to add or remove fleets and importers from an existing export:
76+
77+
<div class="termy">
78+
79+
```shell
80+
$ dstack export update my-export --add-fleet another-fleet --add-importer team-c
81+
NAME FLEETS IMPORTERS
82+
my-export my-fleet, another-fleet team-b, team-c
83+
84+
```
85+
86+
</div>
87+
88+
To remove a fleet or importer:
89+
90+
<div class="termy">
91+
92+
```shell
93+
$ dstack export update my-export --remove-importer team-b
94+
NAME FLEETS IMPORTERS
95+
my-export my-fleet, another-fleet team-c
96+
97+
```
98+
99+
</div>
100+
101+
### Delete exports
102+
103+
Use the `dstack export delete` command to delete an export. This revokes access for all importer projects:
104+
105+
<div class="termy">
106+
107+
```shell
108+
$ dstack export delete my-export
109+
Delete the export my-export? [y/n]: y
110+
Export my-export deleted
111+
```
112+
113+
</div>
114+
115+
Use `-y` to skip the confirmation prompt.
116+
117+
## Access imported fleets
118+
119+
From the importer project's perspective, exported fleets appear automatically in `dstack fleet list`
120+
with a `<project>/<fleet>` prefix:
121+
122+
<div class="termy">
123+
124+
```shell
125+
$ dstack fleet list
126+
NAME NODES GPU SPOT BACKEND PRICE STATUS CREATED
127+
my-local-fleet 1 - - ssh - active 3 days ago
128+
team-a/my-fleet 2 A100:80GB:8 - ssh - active 1 week ago
129+
team-a/another-fleet 1 H100:80GB:4 - ssh - active 2 days ago
130+
131+
```
132+
133+
</div>
134+
135+
Imported fleets can be used for runs just like the project's own fleets.
136+
137+
!!! info "Tenant isolation"
138+
Exported fleets share the same access model as regular fleets. See [Tenant isolation](fleets.md#tenant-isolation) for details.
139+
140+
!!! info "What's next?"
141+
1. Check the [`dstack export` CLI reference](../reference/cli/dstack/export.md)
142+
2. Learn how to manage [fleets](fleets.md)
143+
3. Read about [projects](projects.md) and project roles

‎docs/docs/concepts/fleets.md‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -468,6 +468,20 @@ ssh_config:
468468
!!! info "Reference"
469469
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).
470470

471+
## Tenant isolation
472+
473+
Users running workloads on a fleet have access to the host, including the folders that may be used as instance volumes,
474+
and containers use host network mode unless the host has multiple [blocks](#blocks) configured and the job uses only a subset of them.
475+
476+
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.
477+
478+
When [exporting fleets](exports.md) to other projects, the same access model applies to members of the importer projects.
479+
480+
## Export fleets
481+
482+
Fleets can be exported to other projects, allowing those projects to use the exported fleets
483+
for running dev environments, tasks, and services. See [Exports](exports.md) for more details.
484+
471485
## Manage fleets
472486

473487
### List fleets
@@ -507,5 +521,6 @@ To terminate and delete specific instances from a fleet, pass `-i INSTANCE_NUM`.
507521
1. Check [dev environments](dev-environments.md), [tasks](tasks.md), and
508522
[services](services.md)
509523
2. Read about [Backends](backends.md) guide
510-
3. Explore the [`.dstack.yml` reference](../reference/dstack.yml/fleet.md)
511-
4. See the [Clusters](../../examples.md#clusters) example
524+
3. Learn how to [export fleets](exports.md) to other projects
525+
4. Explore the [`.dstack.yml` reference](../reference/dstack.yml/fleet.md)
526+
5. See the [Clusters](../../examples.md#clusters) example

‎docs/docs/concepts/projects.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,11 @@ A user can be added to a project and assigned or unassigned as a project role on
4141
Unlike admins, managers cannot configure backends and gateways.
4242
* **User** – A user can manage project resources including runs, fleets, and volumes.
4343

44+
## Project exports
45+
46+
Projects can export resources such as fleets to other projects, allowing them to be used across team
47+
boundaries. See [Exports](exports.md) for more details.
48+
4449
## Authorization
4550

4651
### User token

‎docs/docs/reference/cli/dstack/export.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# dstack export
2+
3+
The `dstack export` commands manage [exports](../../../concepts/exports.md) of resources to other projects.
4+
5+
## dstack export list
6+
7+
The `dstack export list` command lists all exports in the project.
8+
9+
##### Usage
10+
11+
<div class="termy">
12+
13+
```shell
14+
$ dstack export list --help
15+
#GENERATE#
16+
```
17+
18+
</div>
19+
20+
## dstack export create
21+
22+
The `dstack export create` command creates a new export.
23+
24+
##### Usage
25+
26+
<div class="termy">
27+
28+
```shell
29+
$ dstack export create --help
30+
#GENERATE#
31+
```
32+
33+
</div>
34+
35+
## dstack export update
36+
37+
The `dstack export update` command updates an existing export.
38+
39+
##### Usage
40+
41+
<div class="termy">
42+
43+
```shell
44+
$ dstack export update --help
45+
#GENERATE#
46+
```
47+
48+
</div>
49+
50+
## dstack export delete
51+
52+
The `dstack export delete` command deletes the specified export.
53+
54+
##### Usage
55+
56+
<div class="termy">
57+
58+
```shell
59+
$ dstack export delete --help
60+
#GENERATE#
61+
```
62+
63+
</div>

‎mkdocs.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -237,6 +237,7 @@ nav:
237237
- Projects: docs/concepts/projects.md
238238
- Metrics: docs/concepts/metrics.md
239239
- Events: docs/concepts/events.md
240+
- Exports: docs/concepts/exports.md
240241
- Guides:
241242
- Server deployment: docs/guides/server-deployment.md
242243
- Troubleshooting: docs/guides/troubleshooting.md
@@ -271,6 +272,7 @@ nav:
271272
- dstack volume: docs/reference/cli/dstack/volume.md
272273
- dstack gateway: docs/reference/cli/dstack/gateway.md
273274
- dstack secret: docs/reference/cli/dstack/secret.md
275+
- dstack export: docs/reference/cli/dstack/export.md
274276
- API:
275277
- Python API: docs/reference/api/python/index.md
276278
- REST API: docs/reference/api/rest/index.md

0 commit comments

Comments
 (0)