diff --git a/docs/docs/concepts/exports.md b/docs/docs/concepts/exports.md new file mode 100644 index 000000000..3b3194146 --- /dev/null +++ b/docs/docs/concepts/exports.md @@ -0,0 +1,143 @@ +--- +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. + +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 + any importer project they add. 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 "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) + 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..01f5d39ac 100644 --- a/docs/docs/concepts/fleets.md +++ b/docs/docs/concepts/fleets.md @@ -468,6 +468,20 @@ 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 + +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. + +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 +for running dev environments, tasks, and services. See [Exports](exports.md) for more details. + ## Manage fleets ### List fleets @@ -507,5 +521,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