Skip to content

Organisations, workspaces and clusters#

Three objects decide who can do what, and where. An organisation is who administers and pays. A workspace is where a team works. A cluster is where the work runs. A workspace's access to a cluster carries its limits there: quota, fair-share weight, pools of machines, highest priority and what it may take from the machines.

Use them when:

  • Several teams share machines and each must see only its own runs, drives and credentials: one workspace per team.
  • A team must not take the whole fleet: give its workspace a quota on the cluster, and a fair-share weight against the others.
  • Some machines belong to some teams: put machines in pools (pool=h100) and grant each workspace the pools it may use.
  • Production work must go first: allow the production workspace a higher maximum priority, so its runs can preempt others.
  • You want to start at once: use Astraeus Cloud, the shared cluster. You want a cluster for your organisation only: ask Astralyx for a dedicated cluster.

Organisation#

The organisation owns clusters, workspaces, members, single sign-on, alerts, prices and usage. Everyone who signs up starts with a personal one, named <your name> (personal), with one workspace, Default — except people who first sign in through their organisation's single sign-on, who join that organisation instead. You can belong to several organisations and switch between them in the console's top bar.

Organisation role Can
owner Everything an admin can, and manage owners.
admin Add and remove machines, create workspaces and give them access to clusters, invite and remove members, set up single sign-on, alerts and prices. An admin is an admin of every workspace.
member Work in the workspaces they are added to.

Workspace#

A workspace is a team's space: its runs, workers, drives, data sources, credentials, endpoints, replica groups and schedules. Names inside it are its own — two workspaces may each have a run called train.

On each cluster it has access to, a workspace is one namespace, named ws-<12 hex digits> (shown in the workspace's Settings). You never type the namespace: the console, astra and the API take local names, and Astraeus qualifies them with the namespace.

Workspace role Can
admin Everything in the workspace, and manage its members.
editor Create, change and delete runs, drives, credentials and the rest.
viewer Read.
auditor Read the governance record of the workspace's agents and make evidence packs; change nothing.

See Roles and permissions for every permission.

Cluster#

A cluster is where your work runs: the part of the Astralyx control plane that schedules it, and the machines enrolled in it. Astralyx operates every cluster; you bring the machines.

  • Astraeus Cloud is shared by organisations. Your organisation is a tenant of it: your machines run only your workspaces' work, your workers reach only your machines over the mesh, your names resolve only on your machines. An organisation with no dedicated cluster joins it when it adds its first machine. It may have 10 machines there by default; Astralyx can raise it.
  • A dedicated cluster is operated by Astralyx for your organisation only. Ask for one at [email protected]; it then appears in your organisation's clusters.

A workspace's access to a cluster#

Giving a workspace access to a cluster creates its namespace there, with these terms. Organisation admins set them; Astraeus enforces them.

Term Default Effect
Quota Unlimited The most the workspace may hold at once on the cluster: GPUs, CPU cores, memory and workers. A run that would exceed it waits; a run that could never fit is told so.
Weight 1 The workspace's share of free capacity when several workspaces wait. A weight of 2 is entitled to twice the share of a weight of 1.
Pools Any machine Machine labels (pool=a100); the workspace's work runs only on machines carrying all of them, and it sees only those machines.
Max priority 0 The highest run priority the workspace may ask for. A run asking more is refused (403 PRIORITY_NOT_ALLOWED).
Host access Nothing Host paths: directories on the machines its runs, drives and data sources may use. Privileged work: privileged containers, the host's PID or IPC namespace, added capabilities. Grant privileged work only to people you would give root on those machines.

Removing a workspace's access to a cluster deletes everything the workspace runs on that cluster.

Host access is root on the machine

A workspace that may bind / or run privileged containers controls the machine, and every other workspace's work on it. Grant host paths as narrowly as possible (/datasets, not /).

Confinement#

Everything you do in a workspace — from the console, astra or the API — is done as you, with your role in that workspace. Astraeus authorises each request as that role inside the workspace's namespace, and refuses:

  • paths that name another namespace's objects (403 NAMESPACE_FORBIDDEN);
  • bodies that reference objects outside the namespace — a credential, a drive, a run;
  • host paths or privileged work the workspace was not granted (403 HOST_ACCESS_FORBIDDEN);
  • actions the role does not allow (403 RBAC_FORBIDDEN).

Listings are filtered to the namespace. Another workspace's work on a shared machine appears only as taken — its GPUs and size, never whose.

Create one#

Create a workspace, then give it access to a cluster. You must be an organisation owner or admin.

  1. Open the organisation (its name in the top bar) → Workspaces → New workspace.
  2. Enter a Name (Vision research) and a Short name (vision: 2 to 40 lower-case letters, digits and dashes), then Create workspace. The console opens its Settings.
  3. Choose Give access to a cluster. Pick the Cluster, set the quota (GPUs 16, CPU cores, Memory 512Gi, Workers; empty is unlimited), the Weight, the Pools (pool=a100), the Max priority and any host access, then Give access.

Adding the workspace's first machine (Add a machine) also gives it access, with no limits, to the organisation's only cluster or to Astraeus Cloud.

$ CONSOLE=https://console.astralyx.cloud/api/v1
$ curl -sS -X POST "$CONSOLE/orgs/acme/workspaces" \
    -H "Authorization: Bearer $ASTRAEUS_TOKEN" -H 'content-type: application/json' \
    -d '{"slug": "vision", "name": "Vision research"}'
$ curl -sS -X POST "$CONSOLE/orgs/acme/workspaces/vision/clusters" \
    -H "Authorization: Bearer $ASTRAEUS_TOKEN" -H 'content-type: application/json' \
    -d '{
          "cluster": "default",
          "quota": {"gpus": 16, "memory_bytes": 549755813888},
          "weight": 2,
          "node_selector": {"pool": "a100"},
          "max_priority": 10,
          "host_access": {"paths": ["/datasets"]}
        }'
{"cluster": "default", "namespace": "ws-3f9a1c0b7e24"}

quota takes gpus, cpu_cores, memory_bytes and tasks; an absent one is unlimited. See the REST API.

There is no CLI command to create workspaces.