Workspaces are a mechanism to isolate multiple builds, deploys, etc. of the same applications. A common use case of workspaces are to provide environments for branch-based development, staging, etc.

Operations such as deploy will deploy the latest built artifact from the same workspace. Deployed applications will get a unique URL per workspace (if the URL service is enabled). Following this logic, it is hopefully apparent how workspaces can be used to model environments.

»Using Workspaces

By default, all operations are performed in the "default" workspace. By specifying the -workspace flag to any operation, Waypoint will operate in a different workspace but on the same underlying infrastructure (by default). Workspaces are created on-demand. By using the -workspace flag with a new value, the workspace will be automatically created.

All builds, deploys, and releases are scoped to their given workspace. A release will only release deployments that are within the same workspace, a deploy will only deploy builds from the same workspace, etc.

If the URL service is enabled, the application URL is generated per workspace.

»Deleting Workspaces

waypoint destroy will destroy all resources within the current workspace. Note that "destroy" behavior is dependent on plugins. In most cases, releases and deployments are deleted but builds and artifacts are retained and must be deleted outside of Waypoint if desired.

You may delete the "default" workspace, but it will be recreated on the next operation that doesn't specify a workspace. There is no way to change the default workspace.

»Listing Workspaces

There is currently no easy way to list the workspaces that currently exist except by manually using the ListWorkspaces API. We plan on adding CLI and web UI interfaces to workspace management soon.