Skip to Content

Clusters

The clusters operations of the v1 API.

GET
/v1/clusters

Try it: use a key with the least scope; requests go straight from your browser to the API. The key stays in this tab's memory and is gone on reload.

Organization owners and admins see every cluster of the organization, other members the clusters of their environments. Deleted clusters are left out. Ordered by creation time, oldest first. Cursor paginated.

Authorization

api_key
headerAuthorizationBearer <alc_ API key>

An A-Line.cloud API key, sent as Authorization: Bearer alc_.... Create keys in the dashboard; sessions are not accepted on /v1.

Query Parameters

cursor?|

Opaque cursor from the previous page's next_cursor.

limit?|

Page size, 1 to 100 (default 25).

Formatuint
Range0 <= value

Response Body

A page of clusters

application/json
  1. response

One page of a v1 list.

data*array<>

The items, in the documented order.

has_more*boolean

Whether more items follow this page.

next_cursor?|

Pass as cursor to get the next page; null on the last page.

Example Request
curl 'https://api.a-line.cloud/v1/clusters' \  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
Example Response
{  "data": [    {      "capacity_wait": [        {          "alternatives": [            "string"          ],          "checked_at": "2019-08-24T14:15:22Z",          "count": 0,          "location": "string",          "next_check_at": "2019-08-24T14:15:22Z",          "node_type": "string",          "pool": "string",          "role": "string",          "since": "2019-08-24T14:15:22Z",          "status": "string"        }      ],      "created_at": "2019-08-24T14:15:22Z",      "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "price_confirmation": [        {          "count": 0,          "location": "string",          "new": {            "hourly_price": "string",            "monthly_price": "string",            "setup_fee": "string"          },          "node_type": "string",          "old": {            "max_hourly_price": "string",            "max_monthly_price": "string",            "max_setup_fee": "string"          },          "pool": "string",          "pool_id": "bd9ee216-b2f2-496a-bbe1-31b86a2c3c43",          "role": "string",          "since": "2019-08-24T14:15:22Z"        }      ],      "provider": "string",      "region": "string",      "state": "string"    }  ],  "has_more": true,  "next_cursor": "string"}
POST
/v1/clusters

Try it: use a key with the least scope; requests go straight from your browser to the API. The key stays in this tab's memory and is gone on reload.

The cluster starts in provisioning; its servers are ordered in the background. The balance must cover the first hours of the order. Send an Idempotency-Key to make a retry safe.

Authorization

api_key
headerAuthorizationBearer <alc_ API key>

An A-Line.cloud API key, sent as Authorization: Bearer alc_.... Create keys in the dashboard; sessions are not accepted on /v1.

Header Parameters

Idempotency-Key?string

Optional client-chosen key (1-255 visible ASCII characters). A retry with the same key and body within 24 hours replays the first response instead of creating again; the same key with a different body is a 422, and a retry while the first request still runs is a 409.

Request Body

A cluster to create.

application/json
  1. body

A cluster to create.

environment_id*string

The environment the cluster belongs to.

Formatuuid
load_balancers?array<string>

Load balancer type ids for ingress load balancers.

Default[]
name*string

The cluster's name: 1-64 lowercase letters, digits or hyphens, not reserved. Unique in the organization.

network?|

Custom address ranges; omitted ranges take the defaults.

Defaultnull
pools*array<>

The node pools; one must have the control_plane role.

provider*string

The provider (hetzner, ...).

region*string

The provider region (fsn1, ...).

tos_acceptance?|

Acceptance of the provider's current terms of service; required on providers with terms.

Defaultnull

Response Body

The created cluster

application/json
  1. response

A cluster, as the public API shows it.

capacity_wait*array<>

Servers not created yet, grouped per pool and reason; empty when none wait.

created_at*string

When the cluster was created (RFC 3339, UTC).

Formatdate-time
environment_id*string

The environment the cluster belongs to.

Formatuuid
id*string

The cluster id.

Formatuuid
name*string

The cluster's name.

price_confirmation*array<>

Servers held because the price went above the pool's caps.

provider*string

The provider (hetzner, ...). New values may appear.

region*string

The provider region.

state*string

The lifecycle state (provisioning, running, ...). New values may appear.

Example Request
curl -X POST 'https://api.a-line.cloud/v1/clusters' \  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key' \  -H 'Content-Type: application/json' \  -d '{"environment_id":"00000000-0000-4000-8000-000000000001","name":"example","pools":[],"provider":"example","region":"example"}'
Example Response
{  "capacity_wait": [    {      "alternatives": [        "string"      ],      "checked_at": "2019-08-24T14:15:22Z",      "count": 0,      "location": "string",      "next_check_at": "2019-08-24T14:15:22Z",      "node_type": "string",      "pool": "string",      "role": "string",      "since": "2019-08-24T14:15:22Z",      "status": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "price_confirmation": [    {      "count": 0,      "location": "string",      "new": {        "hourly_price": "string",        "monthly_price": "string",        "setup_fee": "string"      },      "node_type": "string",      "old": {        "max_hourly_price": "string",        "max_monthly_price": "string",        "max_setup_fee": "string"      },      "pool": "string",      "pool_id": "bd9ee216-b2f2-496a-bbe1-31b86a2c3c43",      "role": "string",      "since": "2019-08-24T14:15:22Z"    }  ],  "provider": "string",  "region": "string",  "state": "string"}
GET
/v1/clusters/{cluster_id}

Try it: use a key with the least scope; requests go straight from your browser to the API. The key stays in this tab's memory and is gone on reload.

Authorization

api_key
headerAuthorizationBearer <alc_ API key>

An A-Line.cloud API key, sent as Authorization: Bearer alc_.... Create keys in the dashboard; sessions are not accepted on /v1.

Path Parameters

cluster_id*string

The cluster UUID

Formatuuid

Response Body

The cluster

application/json
  1. response

A cluster, as the public API shows it.

capacity_wait*array<>

Servers not created yet, grouped per pool and reason; empty when none wait.

created_at*string

When the cluster was created (RFC 3339, UTC).

Formatdate-time
environment_id*string

The environment the cluster belongs to.

Formatuuid
id*string

The cluster id.

Formatuuid
name*string

The cluster's name.

price_confirmation*array<>

Servers held because the price went above the pool's caps.

provider*string

The provider (hetzner, ...). New values may appear.

region*string

The provider region.

state*string

The lifecycle state (provisioning, running, ...). New values may appear.

Example Request
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001' \  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
Example Response
{  "capacity_wait": [    {      "alternatives": [        "string"      ],      "checked_at": "2019-08-24T14:15:22Z",      "count": 0,      "location": "string",      "next_check_at": "2019-08-24T14:15:22Z",      "node_type": "string",      "pool": "string",      "role": "string",      "since": "2019-08-24T14:15:22Z",      "status": "string"    }  ],  "created_at": "2019-08-24T14:15:22Z",  "environment_id": "40ef0e48-a11f-4963-a229-e396c9f7e7c4",  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "name": "string",  "price_confirmation": [    {      "count": 0,      "location": "string",      "new": {        "hourly_price": "string",        "monthly_price": "string",        "setup_fee": "string"      },      "node_type": "string",      "old": {        "max_hourly_price": "string",        "max_monthly_price": "string",        "max_setup_fee": "string"      },      "pool": "string",      "pool_id": "bd9ee216-b2f2-496a-bbe1-31b86a2c3c43",      "role": "string",      "since": "2019-08-24T14:15:22Z"    }  ],  "provider": "string",  "region": "string",  "state": "string"}
DELETE
/v1/clusters/{cluster_id}

Try it: use a key with the least scope; requests go straight from your browser to the API. The key stays in this tab's memory and is gone on reload.

The cluster moves to deleting and its servers are removed in the background; deleting a cluster already deleting answers the same. Deletes stay open on a blocked billing account.

Authorization

api_key
headerAuthorizationBearer <alc_ API key>

An A-Line.cloud API key, sent as Authorization: Bearer alc_.... Create keys in the dashboard; sessions are not accepted on /v1.

Path Parameters

cluster_id*string

The cluster UUID

Formatuuid

Query Parameters

acknowledge_commitment?boolean

Remove committed monthly machines although they stay billed to the end of their term.

Defaultfalse
acknowledge_iac?boolean

Delete although a file of the infra link still defines the cluster (the link then proposes creating it again).

Defaultfalse
confirm?|

The cluster's name, required when volumes go with it. Deleting volumes needs a signed-in user's step-up: an API key sending it gets 403 step_up_unavailable.

Defaultnull

Response Body

The cluster is being deleted

application/json
  1. response

A cluster accepted for deletion.

id*string

The cluster id.

Formatuuid
state*string

Always deleting: the servers are removed in the background.

warnings*array<string>

What to know about the delete (an infra link file that still defines it, ...).

Example Request
curl -X DELETE 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001' \  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
Example Response
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "state": "string",  "warnings": [    "string"  ]}
GET
/v1/clusters/{cluster_id}/nodes

Try it: use a key with the least scope; requests go straight from your browser to the API. The key stays in this tab's memory and is gone on reload.

The nodes that are not deleted, with their pool's name and addresses. Ordered by creation time, oldest first. Cursor paginated.

Authorization

api_key
headerAuthorizationBearer <alc_ API key>

An A-Line.cloud API key, sent as Authorization: Bearer alc_.... Create keys in the dashboard; sessions are not accepted on /v1.

Path Parameters

cluster_id*string

The cluster UUID

Formatuuid

Query Parameters

cursor?|

Opaque cursor from the previous page's next_cursor.

limit?|

Page size, 1 to 100 (default 25).

Formatuint
Range0 <= value

Response Body

A page of nodes

application/json
  1. response

One page of a v1 list.

data*array<>

The items, in the documented order.

has_more*boolean

Whether more items follow this page.

next_cursor?|

Pass as cursor to get the next page; null on the last page.

Example Request
curl 'https://api.a-line.cloud/v1/clusters/00000000-0000-4000-8000-000000000001/nodes' \  -H 'Authorization: Bearer alc_test_EXAMPLE_not_a_real_key'
Example Response
{  "data": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "kubernetes_name": "string",      "pool": "string",      "private_ip": "string",      "public_ip": "string",      "public_ipv6": "string",      "role": "string",      "state": "string",      "static_address": true    }  ],  "has_more": true,  "next_cursor": "string"}

On this page