Skip to content

[Docs]: Gateway Exports #3862

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jvstme wants to merge 1 commit into
base: master
Choose a base branch
from
+37 −24
Open

[Docs]: Gateway Exports #3862

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 32 additions & 24 deletions mkdocs/docs/concepts/exports.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ 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.
Currently, [SSH fleets](fleets.md#ssh-fleets) and [gateways](gateways.md) 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.
Expand All @@ -28,27 +28,27 @@ for running tasks, dev environments, and services. Imported resources appear wit
### 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`:
with `--fleet`, the gateways to export with `--gateway`, and the importer projects with `--importer`:

<div class="termy">

```shell
$ dstack export create my-export --fleet my-fleet --importer team-b
NAME FLEETS IMPORTERS
my-export my-fleet team-b
$ dstack export create my-export --fleet my-fleet --gateway my-gateway --importer team-b
NAME FLEETS GATEWAYS IMPORTERS
my-export my-fleet my-gateway team-b

```

</div>

Both `--fleet` and `--importer` can be specified multiple times:
`--fleet`, `--gateway`, and `--importer` can be specified multiple times:

<div class="termy">

```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
NAME FLEETS GATEWAYS IMPORTERS
shared-gpus gpu-fleet-1, gpu-fleet-2 - team-b, team-c

```

Expand All @@ -62,37 +62,37 @@ Use `dstack export list` (or simply `dstack export`) to list all exports in the

```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
NAME FLEETS GATEWAYS IMPORTERS
my-export my-fleet my-gateway team-b
shared-gpus gpu-fleet-1, gpu-fleet-2 - team-b, team-c

```

</div>

### Update exports

Use the `dstack export update` command to add or remove fleets and importers from an existing export:
Use the `dstack export update` command to add or remove fleets, gateways, and importers from an existing export:

<div class="termy">

```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
NAME FLEETS GATEWAYS IMPORTERS
my-export my-fleet, another-fleet my-gateway team-b, team-c

```

</div>

To remove a fleet or importer:
To remove a fleet, gateway, or importer:

<div class="termy">

```shell
$ dstack export update my-export --remove-importer team-b
NAME FLEETS IMPORTERS
my-export my-fleet, another-fleet team-c
NAME FLEETS GATEWAYS IMPORTERS
my-export my-fleet, another-fleet my-gateway team-c

```

Expand All @@ -114,22 +114,22 @@ Export my-export deleted

Use `-y` to skip the confirmation prompt.

## Access imported fleets
## Access imported resources

From the importer project's perspective, use `dstack import list` (or simply `dstack import`) to list all imports in the project — i.e., all exports from other projects that this project has been granted access to:

<div class="termy">

```shell
$ dstack import list
NAME FLEETS
team-a/my-export my-fleet, another-fleet
NAME FLEETS GATEWAYS
team-a/my-export my-fleet, another-fleet my-gateway

```

</div>

Imported fleets also appear in `dstack fleet list` in the `<project>/<fleet>` format:
Imported fleets and gateways also appear in `dstack fleet list` and `dstack gateway list` in the `<project>/<name>` format:

<div class="termy">

Expand All @@ -140,17 +140,24 @@ $ dstack fleet list
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

$ dstack gateway list
NAME BACKEND HOSTNAME DOMAIN DEFAULT STATUS
team-a/my-gateway aws (eu-west-1) 10.0.0.4 gtw.mycompany.example running

```

</div>

Imported fleets can be used for runs just like the project's own fleets.
Imported resources can be used for runs just like the project's own resources.

<div editor-title=".dstack.yml">

```yaml
type: dev-environment
ide: vscode
type: service
image: nginx
port: 80

gateway: team-a/my-gateway

fleets:
- my-local-fleet
Expand All @@ -166,4 +173,5 @@ fleets:
1. Check the [`dstack export` CLI reference](../reference/cli/dstack/export.md)
1. Check the [`dstack import` CLI reference](../reference/cli/dstack/import.md)
1. Learn how to manage [fleets](fleets.md)
1. Learn how to manage [gateways](gateways.md)
1. Read about [projects](projects.md) and project roles
5 changes: 5 additions & 0 deletions mkdocs/docs/concepts/gateways.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,6 +174,11 @@ domain: example.com
!!! info "Reference"
For all gateway configuration options, refer to the [reference](../reference/dstack.yml/gateway.md).

## Export gateways

Gateways can be exported to other projects, allowing those projects to use the exported gateways
for running services. See [Exports](exports.md) for more details.

## Manage gateways

### List gateways
Expand Down
Loading