Workspaces: Isolating Teams

Workspaces in SkyPilot allow you to isolate resources and configurations for different teams or projects.

Example use cases:

• Team Isolation: Have different teams use different infra providers.

• Project Separation: Set different SkyPilot configurations for different projects.

• Resource Tracking: Track resource usage by team or project.

Defining workspaces

Defining workspaces in configuration file

Workspaces are defined in the SkyPilot config file of API server, i.e., ~/.sky/config.yaml on the API server host.

For example, assume:

• Your organization has two teams, team-a and team-b.

• SkyPilot API server is configured to use AWS and GCP.

• You want team-a to use both infra, and team-b to use GCP only with a different project ID.

The above is achieved by configuring the following section in the config file:

workspaces:
  team-a:
    # Use both AWS and GCP.
    gcp:
      project_id: project-id-for-team-a

  team-b:
    # Use GCP only with a different project ID.
    gcp:
      project_id: project-id-for-team-b
    aws:
      disabled: true

Schema of the workspaces field:

workspaces:
  # Workspace 'default' is created by SkyPilot and is used if no
  # workspaces are defined. Admins can optionally override settings for
  # this workspace.
  default: {}

  <workspace name>:
     <infra name>:  # aws, gcp, ...; ssh; kubernetes
       disabled: false  # Disable an infra for this workspace (default: false).

     # Certain infra providers support additional fields:
     ssh:
       disabled: false
       allowed_node_pools:
         - node-pool-1

     kubernetes:
       disabled: false
       allowed_contexts:
         - node-pool-1
         - node-pool-2

     gcp:
       disabled: false
       project_id: GCP project ID

     nebius:
       disabled: false
       tenant_id: Nebius tenant ID (tenant-xxxxxxxx)
       credentials_file_path: ~/.nebius/credentials-file-name.json

To apply the configuration, follow the following steps:

Helm Deployment

If you used Helm Deployment to deploy a remote API server, write workspace configuration in a local SkyPilot config file, and run:

# RELEASE_NAME and NAMESPACE are the same as the ones used in the Helm
# deployment.
helm upgrade --install $RELEASE_NAME skypilot/skypilot-nightly --devel \
   --namespace $NAMESPACE \
   --reuse-values \
   --set-file apiService.config=/your/path/to/config.yaml

To change workspace configuration, update the config file and run the same command again. The API server will reload the new configuration automatically with no downtime. For more details, refer to Setting the SkyPilot config in Helm Deployment.

VM Deployment or Local API Server

If you used a VM Deployment for your API server or testing workspaces locally, edit the workspace configuration in the SkyPilot config file, ~/.sky/config.yaml. The API server will automatically reload the configuration to apply the changes.

Defining workspaces in UI

Equivalently, you can also define workspaces in the UI.

The SkyPilot UI (sky dashboard) has a Workspaces page that shows all configured workspaces.

This page shows all workspaces, and for each workspace its current clusters/jobs usage information and enabled infra choices.

To create a new workspace, click on the Create New Workspace button. Users can edit the workspace’s definition in the UI.

To view or edit a workspace’s definition, click on a workspace’s Edit button.

Setting the active workspace

Whenever a SkyPilot CLI or API is called, the workspace to use is picked up from the client side’s active_workspace configuration.

For example, if your organization has a monorepo with multiple teams/projects:

/monorepo
└── team-a
    └── .sky.yaml
    └── training.sky.yaml
└── team-b
    └── .sky.yaml
    └── batch-infer.sky.yaml
└── team-c
    └── # No .sky.yaml file; use the 'default' workspace.
    └── serve.sky.yaml
└── ...

Then, /monorepo/team-a/.sky.yaml may set:

active_workspace: team-a

All SkyPilot CLI or API calls with /monorepo/team-a as the PWD will use the workspace team-a.

Similarly, /monorepo/team-b/.sky.yaml may set:

active_workspace: team-b

All SkyPilot CLI or API calls with /monorepo/team-b as the PWD will use the workspace team-b.

For team-c, since it has no workspace set, all CLI or API calls there will use the default workspace.

Tip

You can also set the workspace in the CLI using --config active_workspace=<workspace>:

sky launch --config active_workspace=team-a ...

See also Configuration Sources and Overrides for various ways to set configuration.

Workspaces in UI

Workspaces are shown in the Workspaces page in sky dashboard.

In the Clusters and Jobs pages, all compute resources are tagged with the workspace they belong to. Users can filter the view by workspace. Example:

User management

Currently, all users in an organization are allowed to use any configured workspace. Users can flexibly switch to a different workspace as shown above.

SkyPilot supports using Okta, Google Workspace, or other SSO providers to authenticate users. See here.