Bring a workspace up

Bearer PAT authentication; RBAC permission workspaces.use. Brings the caller’s workspace for a repository and kind up, or answers the live one: 201 with a workspace this call created (placed on the repository’s CI cluster, else the organisation’s CI pool, else its pipeline cluster, and provisioning until a read finds its pod ready), 200 with the existing one. A ready workspace whose profile changed, and a failed one, are replaced.

POST /api/v1/org/workspaces

Bring a workspace up

Python

import requests

url = "https://platform.ankra.app/api/v1/org/workspaces"

payload = {
    "idle_ttl_hours": 360,
    "kind": "<string>",
    "name": "<string>",
    "owner": "<string>",
    "repository_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

200

{
  "cluster_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idle_ttl_hours": 123,
  "image": "<string>",
  "image_source": "repository_profile",
  "isolation": "vm",
  "isolation_note": "<string>",
  "kind": "<string>",
  "last_error": "<string>",
  "last_used_at": "2023-11-07T05:31:56Z",
  "namespace": "<string>",
  "organisation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "pod_name": "<string>",
  "progress_message": "<string>",
  "purpose": "member",
  "repository_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "runtime_class_name": "<string>",
  "sandbox_environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "spec_hash": "<string>",
  "status": "provisioning",
  "updated_at": "2023-11-07T05:31:56Z",
  "user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-ankra-organisation-id · string

PAT organisation override.

Body

application/json

Names the repository by repository_id, or by provider, owner and name as its git remote reads.

idle_ttl_hours · integer

How long a workspace this call creates lives unused (1-720, default 24).

Required range: 1 <= x <= 720

kind · string

The workspace profile to build from (default default).

name · string

owner · string

provider · enum<string>

Available options: github, gitlab, bitbucket_cloud

repository_id · string<uuid>

Response

200

application/json

The live workspace, already up

An Ankra Workspace: a member's pod on the organisation's CI pool that commands for one repository run in.

cluster_id · string<uuid> | null · required

The cluster the workspace was placed on, once, at its first bring-up.

created_at · string<date-time> · required

expires_at · string<date-time> | null · required

When the platform removes the workspace if nothing uses it first.

id · string<uuid> · required

idle_ttl_hours · integer · required

How long the workspace lives unused.

image · string | null · required

The toolchain image its main container runs.

image_source · enum<string> | null · required

Where the image came from.

Available options: repository_profile, pipeline_stage, pipeline_defaults, null

isolation · enum<string> | null · required

What the workspace pod runs behind: vm (a Kata Containers RuntimeClass, a virtual machine per pod), gvisor (a gVisor RuntimeClass, a user-space kernel) or container (the node's default runtime, sharing the host kernel). Null for a workspace created before this was recorded, which is unknown rather than container.

Available options: vm, gvisor, container, null

isolation_note · string | null · required

Why the isolation is container (the cluster offers no sandbox RuntimeClass, or its RuntimeClasses could not be read when the workspace was created), or that a sandbox was chosen from less than the cluster's whole answer (a listing cut short, a RuntimeClass that could not be used). Null when the choice was made from a complete, clean read.

kind · string · required

The workspace profile it was built from.

last_error · string | null · required

Why the workspace failed, or why the platform removed it.

last_used_at · string<date-time> · required

namespace · string | null · required

The Kubernetes namespace it runs in.

organisation_id · string<uuid> · required

pod_name · string | null · required

The pod commands run in.

progress_message · string | null · required

What a provisioning workspace is waiting on, as this read found its pod: the scheduler's reason it has no node yet, a container restarting, the readiness check's last answer. Null when there is nothing to report, on every status but provisioning, and in listings.

purpose · enum<string> · required

member for a member's own workspace (the one ankra workspace up and ankra exec reach); run for a workspace that belongs to one unattended run of Ankra AI, created for it and torn down when it ends.

Available options: member, run

repository_id · string<uuid> · required

runtime_class_name · string | null · required

The RuntimeClass the workspace pod runs under; null under the node's default runtime.

sandbox_environment_id · string<uuid> | null · required

The sandbox environment that owns its namespace.

spec_hash · string | null · required

SHA-256 of the objects it was rendered from.

status · enum<string> · required

Where the workspace is in its life. paused is a workspace unused for an hour whose pod was stopped and whose volume was kept; its owner's next use brings it back through provisioning.

Available options: provisioning, ready, paused, failed, tearing_down, destroyed

updated_at · string<date-time> · required

user_id · string<uuid> · required

The member the workspace belongs to.