Overview

The cloudscale API enables you to interact with all cloudscale offerings, such as creating and scaling a server, retrieving metrics for Object Storage buckets, creating and managing load balancers. If you need help, please do not hesitate to contact us by creating a support ticket in our Cloud Control Panel.

Introduction

The cloudscale API is an HTTPS API following the REST principles. Resources (e.g. servers or Floating IPs) are represented by unique URLs and can be created, listed, controlled and deleted by sending HTTP requests to those URLs. Errors are returned as standard HTTP status codes.

In the following examples, we are going to use the command line tool curl, that is available for most UNIX and Linux operating systems as well as Microsoft Windows.

Tools

Before you continue: cloudscale maintains a number of external tools based on the cloudscale API. Depending on your needs, it might be easier to use one of them instead of relying directly on the API.

Name	Language / Platform	Description
cloudscale-cli	Command Line Interface Client	Interact with the cloudscale API from your shell.
cloudscale-python-sdk	Python	An SDK to use the cloudscale REST API with Python 3
cloudscale_ch.cloud	Ansible	Interact with the cloudscale API using our Ansible Collection
terraform-provider-cloudscale	Terraform	Interact with the cloudscale API from Terraform
Docker Machine Driver	Docker	Docker machine driver for cloudscale
csi-cloudscale	Kubernetes	Container Storage Interface (CSI) plugin for cloudscale
cloudscale-cloud-controller-manager	Kubernetes	Cloud Controller Manager (CCM) for cloudscale
ui-driver-cloudscale	Rancher 2.x	Deploy and manage a Kubernetes cluster using Rancher 2.x on cloudscale
cloudscale-go-sdk	Go	An SDK to use the cloudscale REST API with Go Language

Authentication

Each request is authenticated by sending an API token in the request's header. API tokens can be generated and revoked in our Cloud Control Panel and must be kept secret!

An API token is a simple, long string of characters that identifies which user account and what permissions are granted to the requests. The token needs to be specified in the Authorization header of each request with a prefix word called Bearer. curl uses the -H option for this:

$ curl -i -H 'Authorization: Bearer HELPIMTRAPPEDINATOKENGENERATOR' ...

You can make your life easier by storing the header value in a shell variable. The examples on this page will use that variable instead so make sure to set it when trying the examples.

$ AUTH_HEADER='Authorization: Bearer HELPIMTRAPPEDINATOKENGENERATOR'
$ curl -i -H "$AUTH_HEADER" ...

When a token is generated, it can be granted either read-only or read-write access. Read-only access only allows you to use the GET method. This means that data can be read, but no changes or actions are possible. Read-write access allows the POST, PATCH and DELETE methods to be used as well.

HTTP Requests

The API exports resources such as flavors, servers and images. A complete list of all exported resource types is always published on this page.

To list all instances of a resource type, send a GET request to the type's URL.

$ curl -i -H "$AUTH_HEADER" -X GET https://api.cloudscale.ch/v1/flavors

However, most operations apply to a single instance only, for that reason each instance has its own URL. A GET request can be sent to a resource's own URL to retrieve information on that particular instance.

$ curl -i -H "$AUTH_HEADER" -X GET https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc

Generally the HTTP methods have the following meaning for each resource type:

GET /v1/<type>: Retrieve a list of instances.
POST /v1/<type>: Create a new instance of this type.
GET /v1/<type>/<ref>: Retrieve a single resource. The same format is used as when listing all instances.
DELETE /v1/<type>/<ref>: Destroy an instance.
PATCH /v1/<type>/<ref>: Update a single resource.
POST /v1/<type>/<ref>/<action>: Perform an action on the specific instance.

curl uses the -X option to specify the HTTP method. The default method is GET.

$ curl -i -H "$AUTH_HEADER" -X POST

HTTP Response Codes

200 OK

This response status code is used for successful queries. The resulting data is returned in the response's body. It happens e.g. when you receive a list of servers.

201 Created

For requests that create a new resource, this response status code signifies that the resource was created successfully. An example would be creating a server. A representation of the new resource is returned in the body of the response.

The URL used to access the new resource is contained in the Location header of the response.

204 No Content

For requests that initiate an action, this response status code signifies that the request was accepted and is already being operated on. An example would be restarting a server. The response has no body.

HTTP Error Codes

HTTP status codes starting at 400 and 500 are used to report errors. Such a response contains a human-readable description of the cause.

400 Bad Request

The request could not be processed because some data sent to the API was invalid. The body of the response will contain a description of the problem.

401 Unauthorized

The response status code is used when a request was not properly authorized with an API token. Either no token was specified in the Authorization header or the specified token does not exist or has been revoked. The body of the response will contain a description of the problem.

403 Forbidden

The request could not be processed because the necessary permissions were not granted. There are several potential causes for this problem:

Insufficient funds: The account associated with the provided API token does not have enough funds to launch a server with the requested configuration. Increasing your account's balance will solve this problem.
No access to a resource: The account associated with the provided API token is not allowed to access the resource which was specified in the request's URL. Try to create an API token with an account that has access to that resource.
Read-only token used for modification: An API token which only allows read access was provided for a request which performs a modification or action. You will need to use or create a token with read-write access for this request.

404 Not Found

This status code is returned when the requested resource type, instance or action could not be found. For example, accessing a server after it has been deleted produces this error.

405 Method Not Allowed

This status code is returned when the wrong HTTP method is used to perform an action or request data.

For example to request a list of flavors, only a GET request may be used. To reboot a server, only a POST request may be used. Any other method will lead to this error.

The exception to this is the HEAD method. This method can be used on all existing resource types, instance and action URLs and will, among other information, return a list of allowed methods in the Allow header.

Clause	Description
`tag:key`	Include only resources that are associated with a tag matching the given `key`.
`tag:key=value`	Include only resources that are associated with a tag matching the given `key` and `value`.

Regions and Zones

cloudscale provides services from different locations which are organized into regions and zones. A region consists of one to many zones.

All resources that are provided by cloudscale (e.g. flavors) or that you create as a customer (e.g. servers) are either:

Global resources marked with
Regional resources marked with
Zonal resources marked with

We currently provide the following (publicly available) regions and zones:

Slug	Region / City	Map	Available Zones
rma	Rümlang (ZH)	Open	rma1
lpg	Lupfig (AG)	Open	lpg1

List Regions

GET /v1/regions

List all available regions.

Name	Type	Description
slug	string	A unique string identifying the region within the API.
zones	list of zone stubs	The zones that are part of this region.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/regions

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "slug": "rma",
    "zones": [
      {
        "slug": "rma1"
      }
    ]
  },
  {
    "slug": "lpg",
    "zones": [
      {
        "slug": "lpg1"
      }
    ]
  }
]

Servers

Servers are zonal resources

Manage servers on the distributed compute platform. Servers can be created, listed, and deleted as well as renamed, scaled, started, stopped, and rebooted.

List Servers

GET /v1/servers?{query_string}

List all servers.

Tag predicates can be used in the query_string to filter servers by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server.
name	string	The display name of the server.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the server. Can be `"changing"`, `"running"` or `"stopped"`.
zone	zone stub	The zone in which the server is located.
flavor	flavor object	The flavor of the server.
image	image object	The image or custom image of the server.
volumes	list of volume objects	A list of volume objects describing the volumes that are attached to the server. The `href` and `uuid` of a volume object will be `null` until the volume has been allocated.
interfaces	list of interface objects	A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints	list of strings	A list of SSH host key fingerprints. Will be `null` until the host keys could be retrieved from the server.
ssh_host_keys	list of strings	A list of SSH host keys. Will be `null` until the host keys could be retrieved from the server.
anti_affinity_with	list of server objects	A list of server objects describing the servers that are part of the same anti-affinity group. Deprecated: use `server_groups` instead.
tags	tags object	The tags assigned to the server.
server_groups	list of server groups	A list of server group objects describing the server groups that the server is part of. Currently, a server can only be a member of one group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/servers

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name": "db-master",
    "created_at": "2019-05-27T16:45:32.241824Z",
    "status": "running",
    "zone": {
      "slug": "lpg1"
    },
    "flavor": {
      "slug": "flex-4-2",
      "name": "Flex-4-2",
      "vcpu_count": 2,
      "memory_gb": 4
    },
    "image": {
      "slug": "debian-10",
      "name": "Debian 10.2",
      "operating_system": "Debian",
      "default_username": "debian"
    },
    "volumes": [
      {
        "href": "https://api.cloudscale.ch/v1/volumes/42424242-4242-4242-4242-424242424242",
        "uuid": "42424242-4242-4242-4242-424242424242",
        "name": "db-master-root",
        "size_gb": 50,
        "type": "ssd"
      }
    ],
    "interfaces": [
      {
        "type": "public",
        "network": {
          "href": "https://api.cloudscale.ch/v1/networks/36dac305-0207-42e7-8f69-5154b99f0965",
          "uuid": "36dac305-0207-42e7-8f69-5154b99f0965",
          "name": "ext-net3"
        },
        "mac_address": "41:42:43:44:45:46",
        "addresses": [
          {
            "version": 4,
            "address": "185.98.122.110",
            "prefix_length": "24",
            "gateway": "185.98.122.1",
            "reverse_ptr": "185-98-122-110.cust.cloudscale.ch",
            "subnet": {
              "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
              "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
              "cidr": "185.98.122.0/24"
            }
          }
        ]
      },
    ],
    "ssh_fingerprints": [
      "ecdsa-sha2-nistp256 SHA256:xE11KE3xi8QVXk7bdmN/nWa7r0Iq2FnrqcYe/9wPzU8",
      "ecdsa-sha2-nistp256 f4:bc:da:49:50:9a:f2:f3:fe:f0:21:68:cc:41:f1:e6",
      "ssh-rsa SHA256:wFDYZXQkXmmFeAs/5vAF2iEodribKtNJF7INMqEi6UE",
      "ssh-rsa 8d:55:1d:67:2a:5b:84:71:b6:84:4f:13:e5:65:ea:de"
    ],
    "ssh_host_keys": [
      "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFEepRNW5hDct4AdJ8oYsb4lNP5E9XY5fnz3ZvgNCEv7m48+bhUjJXUPuamWix3zigp2lgJHC6SChI/okJ41GUY=",
      "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDz2r+mG5MdYv1idI9xzlhYMap7Oa+Q5tccSvagkHzQQRUkaUD3rP4I3/nLqkMJxbeVXw+Mg2T6dO02HaNnq5fZsSXkB3lFcEgtPOaVhjQZkenhW3wFDqKW38t9/iYgzcslMBWe7OK7661al4cbAHuLKmmqAKX9G+HLMdQNsqeF/plKXHBcZzuYZ8wV/obWmton0zhbkzcdpo3egew61xWwe53YuQvJHttKFtNaiBl+2s5sE84how5HvItGf3exAHK3GFdsWTPBYensj4RoSfLW07RwEsmIxbuCFL2DkvCFFOOJYFuZkRMvJbf9DbETuXauKYadWZDM2oMSThqhpVqx"
    ],
    "server_groups": [],
    "anti_affinity_with": [],
    "tags": {}
  }
]

Get a Server

GET /v1/servers/{uuid}

Get a server by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server.
name	string	The display name of the server.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the server. Can be `"changing"`, `"running"` or `"stopped"`.
zone	zone stub	The zone in which the server is located.
flavor	flavor object	The flavor of the server.
image	image object	The image or custom image of the server.
volumes	list of volume objects	A list of volume objects describing the volumes that are attached to the server. The `href` and `uuid` of a volume object will be `null` until the volume has been allocated.
interfaces	list of interface objects	A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints	list of strings	A list of SSH host key fingerprints. Will be `null` until the host keys could be retrieved from the server.
ssh_host_keys	list of strings	A list of SSH host keys. Will be `null` until the host keys could be retrieved from the server.
anti_affinity_with	list of server objects	A list of server objects describing the servers that are part of the same anti-affinity group. Deprecated: use `server_groups` instead.
tags	tags object	The tags assigned to the server.
server_groups	list of server groups	A list of server group objects describing the server groups that the server is part of. Currently, a server can only be a member of one group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/servers/cfde831a-4e87-4a75-960f-89b0148aa2cc",
  "uuid": "cfde831a-4e87-4a75-960f-89b0148aa2cc",
  "name": "its-a-me-mario.cloudscale.ch",
  "created_at": "2019-05-27T16:45:32.241824Z",
  "status": "running",
  "zone": {
    "slug": "lpg1"
  },
  "flavor": {
    "slug": "flex-4-2",
    "name": "Flex-4-2",
    "vcpu_count": 2,
    "memory_gb": 4
  },
  "image": {
    "slug": "ubuntu-18.04",
    "name": "Ubuntu 18.04 LTS (2018-06-13)",
    "operating_system": "Ubuntu",
    "default_username": "ubuntu"
  },
  "volumes": [
    {
      "href": "https://api.cloudscale.ch/v1/volumes/42424242-4242-4242-4242-424242424242",
      "uuid": "42424242-4242-4242-4242-424242424242",
      "name": "its-a-me-mario.cloudscale.ch-root",
      "size_gb": 50,
      "type": "ssd"
    }
  ],
  "interfaces": [
    {
      "type": "public",
      "network": {
        "href": "https://api.cloudscale.ch/v1/networks/36dac305-0207-42e7-8f69-5154b99f0965",
        "uuid": "36dac305-0207-42e7-8f69-5154b99f0965",
        "name": "ext-net3"
      },
      "mac_address": "41:42:43:44:45:46",
      "addresses": [
        {
          "version": 4,
          "address": "185.98.122.110",
          "prefix_length": "24",
          "gateway": "185.98.122.1",
          "reverse_ptr": "185-98-122-110.cust.cloudscale.ch",
          "subnet": {
            "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
            "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
            "cidr": "185.98.122.0/24"
          }
        }
      ]
    },
  ],
  "ssh_fingerprints": [
    "ecdsa-sha2-nistp256 SHA256:xE11KE3xi8QVXk7bdmN/nWa7r0Iq2FnrqcYe/9wPzU8",
    "ecdsa-sha2-nistp256 f4:bc:da:49:50:9a:f2:f3:fe:f0:21:68:cc:41:f1:e6",
    "ssh-rsa SHA256:wFDYZXQkXmmFeAs/5vAF2iEodribKtNJF7INMqEi6UE",
    "ssh-rsa 8d:55:1d:67:2a:5b:84:71:b6:84:4f:13:e5:65:ea:de"
  ],
  "ssh_host_keys": [
    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBFEepRNW5hDct4AdJ8oYsb4lNP5E9XY5fnz3ZvgNCEv7m48+bhUjJXUPuamWix3zigp2lgJHC6SChI/okJ41GUY=",
    "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDz2r+mG5MdYv1idI9xzlhYMap7Oa+Q5tccSvagkHzQQRUkaUD3rP4I3/nLqkMJxbeVXw+Mg2T6dO02HaNnq5fZsSXkB3lFcEgtPOaVhjQZkenhW3wFDqKW38t9/iYgzcslMBWe7OK7661al4cbAHuLKmmqAKX9G+HLMdQNsqeF/plKXHBcZzuYZ8wV/obWmton0zhbkzcdpo3egew61xWwe53YuQvJHttKFtNaiBl+2s5sE84how5HvItGf3exAHK3GFdsWTPBYensj4RoSfLW07RwEsmIxbuCFL2DkvCFFOOJYFuZkRMvJbf9DbETuXauKYadWZDM2oMSThqhpVqx"
  ],
  "server_groups": [],
  "anti_affinity_with": [],
  "tags": {}
}

Create a Server

POST /v1/servers

Create a server with the specified attributes.

The call completes immediately. After that, the compute, storage, and network resources will be allocated and the boot process starts.

Name	Type	Description
name	string	The name of the server. For a new server, the name has to be a valid host name or a fully qualified domain name (FQDN). In case of an FQDN, the reverse PTR for the public IP address(es) will be set accordingly.
zone	zone slug	The slug of the zone in which the new server will be created. The default zone is the one defined in the project settings.
flavor	flavor slug	The slug of the flavor of the new server. In order to change the flavor, the server must be in `"stopped"` state.
image	string	The base image to be used for the server. For images provided by cloudscale: the image’s `slug`. For custom images: the image’s `slug` prefixed with `custom:` (e.g. `custom:ubuntu-foo`), or its UUID. If multiple custom images with the same slug exist, the newest custom image will be used.
volumes	list of volume objects	A list of volume objects specifying the volumes to be created and attached to the new server. A volume object has the attributes `size_gb` and `type`. Default is `[]`.
interfaces	list of interface objects	A list of interface objects specifying the interfaces to be attached to the server. See here for details. Warning: We recommend to not update interfaces while a server is under production workload as short losses of connectivity might occur.
anti_affinity_with	UUID	The UUID identifying another server to create an anti-affinity group with or add it to the same group as that server. Deprecated: use `server_groups` instead.
tags	tags object	The tags assigned to the server. Default is `{}`.
ssh_keys	list of strings	A list of SSH public keys to be placed on the new server. Use the full content of your .pub file here. Default is `[]`.
password	string	The password of the default user of the new server. When omitted, no password will be set.
use_public_network	boolean	Attach a public network interface to the new server. Can be `true`or `false`. Can not be used together with `interfaces`. Default is `true`.
use_private_network	boolean	Attach a private network interface to the new server. Can be `true` or `false` (default). If you have no private networks, a private network will be created. If you have one or more private network the oldest one will be used. Can not be used together with `interfaces`. Default is `false`.
use_ipv6	boolean	Enable IPv6 on the public network interface of the new server. Can be `true` or `false`. Default is `true`.
volume_size_gb	integer	The size of the root volume in GiB (1024³) of the new server. Default is `10`.
bulk_volume_size_gb	integer	The size of the bulk volume in GiB (1024³) of the new server. Default is `null` in which case no bulk storage will be attached to the new server. Deprecated: use `volumes` instead.
server_groups	list of UUIDs	A list of UUIDs identifying the server groups to which the new server will be added.
user_data	string	Depending on your image choice you can use either cloud-init (YAML) or Ignition (JSON). If you are using a custom image it is also possible to pass an arbitrary string when using `pass-through` user data handling (see here). Use only if you are an advanced user. User data may not be bigger than 44.0 kB.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server.
name	string	The display name of the server.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the server. Can be `"changing"`, `"running"` or `"stopped"`.
zone	zone stub	The zone in which the server is located.
flavor	flavor object	The flavor of the server.
image	image object	The image or custom image of the server.
volumes	list of volume objects	A list of volume objects describing the volumes that are attached to the server. The `href` and `uuid` of a volume object will be `null` until the volume has been allocated.
interfaces	list of interface objects	A list of interface objects describing the interfaces that are attached to the server, including assigned IP addresses.
ssh_fingerprints	list of strings	A list of SSH host key fingerprints. Will be `null` until the host keys could be retrieved from the server.
ssh_host_keys	list of strings	A list of SSH host keys. Will be `null` until the host keys could be retrieved from the server.
anti_affinity_with	list of server objects	A list of server objects describing the servers that are part of the same anti-affinity group. Deprecated: use `server_groups` instead.
tags	tags object	The tags assigned to the server.
server_groups	list of server groups	A list of server group objects describing the server groups that the server is part of. Currently, a server can only be a member of one group.

Most Common Errors

You don't have enough credits. Please recharge your account.
The name of the server is not a valid host name or FQDN.
The image or flavor slug is not valid (please verify that the slug still exists).
The size of the root volume is not in the range of 10 GB to 2000 GB.
The size of an SSD volume is not a multiple of 1 GB or exceeds your current quota.
The size of a bulk volume is not a multiple of 100 GB or exceeds your current quota.
Your SSH public keys are invalid.
The provided password is less than 8 characters long and/or contains non-alphanumeric characters.

`interfaces` Attribute Specification

If you have advanced networking requirements you can use the interfaces attribute to configure the networking of your server when creating or updating a server. If you are using only a single private network, you can use the simpler use_public_network and use_private_network flags instead.

The value of the interfaces attribute must always be a list containing interface objects. The order of the objects does not imply that these interfaces will appear in the same order in your server (as eth0, eth1, etc.). Please use udev rules for this.

The following tables give an overview of different use cases and the corresponding schemas of the interface object. See also the Using Additional Interfaces example.

Creating a Public Network Interface

For public network interfaces the network interface object always uses the following schema and the magic value "public".

`{"network": "public"}`	Create a public network interface with an automatically assigned IPv4 address and an IPv6 address if `use_ipv6` is set to `true`.

Creating a Private Network Interface

For private network interfaces three cases are distinguished.

Allocate a Random IP Address from DHCP Range

These schemas can only be used if there is a subnet configured on the network.

`{"network": "UUID1"}`	Create a private network interface on the network identified by `"UUID1"`. The interface will automatically be assigned an address from the DHCP range of the network's subnet.
`{"addresses": [{"subnet": "UUID2"}]}`	Create a private network interface on the network on which the subnet identified by `"UUID2"` is configured. The interface will automatically be assigned an address from the DHCP range of the subnet.
`{"network": "UUID3", "addresses": [{"subnet": "UUID4"}]}`	This is equivalent to the schema defined above. It is only valid if the subnet identified by `"UUID4"` is configured on the network identified by `"UUID3"`.

Use a Specific IP Address from Subnet Range

These schemas can only be used if there is a subnet configured on the network.

`{"addresses": [{"subnet": "UUID5", "address": "A.B.C.D"}]}`	Create a private network interface on the network on which the subnet identified by `"UUID5"` is configured. The interface will be assigned the address A.B.C.D.
`{"network": "UUID6"", "addresses": [{"subnet": "UUID7", "address": "A.B.C.D"}]}`	This is equivalent to the schema defined above. It is only valid if the subnet identified by `"UUID7"` is configured on the network identified by `"UUID6"`.

Do not Assign an Address

This schema can be used for both networks with and without a configured subnet.

`{"network": "UUID8", "addresses": []}`	Create a private network interface on the network identified by `"UUID8"`. No IP address will be assigned using DHCP.

Request

$ # With the syntax @.ssh/id_rsa.pub, curl will read the SSH key from that file and upload it. You can specify -F ssh_keys="<..." multiple times to upload multiple keys.
$ curl -i -H "$AUTH_HEADER" -F name=db-master -F zone=lpg1 -F flavor=flex-4-2 -F image=debian-10 -F volume_size_gb=50 -F ssh_keys="<.ssh/id_rsa.pub" https://api.cloudscale.ch/v1/servers

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1

{
  "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
  "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
  "name": "db-master",
  "created_at": "2019-05-27T16:45:32.241824Z",
  "status": "changing",
  "zone": {
    "slug": "lpg1"
  },
  "flavor": {
    "slug": "flex-4-2",
    "name": "Flex-4-2",
    "vcpu_count": 2,
    "memory_gb": 4
  },
  "image": {
    "slug": "debian-10",
    "name": "Debian 10 (2018-02-02)",
    "operating_system": "Debian",
    "default_username": "debian"
  },
  "volumes": [
    {
      "href": null,
      "uuid": null,
      "name": "db-master-root",
      "size_gb": 50,
      "type": "ssd"
    }
  ],
  "interfaces": [
    {
      "type": "public",
      "network": {
        "href": "https://api.cloudscale.ch/v1/networks/36dac305-0207-42e7-8f69-5154b99f0965",
        "uuid": "36dac305-0207-42e7-8f69-5154b99f0965",
        "name": "ext-net3"
      },
      "mac_address": "41:42:43:44:45:46",
      "addresses": [
        {
          "version": 4,
          "address": "185.98.122.110",
          "prefix_length": "24",
          "gateway": "185.98.122.1",
          "reverse_ptr": "185-98-122-110.cust.cloudscale.ch",
          "subnet": {
            "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
            "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
            "cidr": "185.98.122.0/24"
          }
        }
      ]
    },
  ],
  "ssh_fingerprints": null,
  "ssh_host_keys": null,
  "server_groups": [],
  "anti_affinity_with": [],
  "tags": {}
}

Using Anti-Affinity

$ curl -i -H "$AUTH_HEADER" -F name=db-slave -F zone=lpg1 -F flavor=flex-4-2 -F image=debian-10 -F volume_size_gb=50 -F ssh_keys="<.ssh/id_rsa.pub" -F server_groups=4699d737-da8a-45a3-931e-c41602cc8431 https://api.cloudscale.ch/v1/servers

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

{
  /* See first example of this section for the rest of the response. */
  "server_groups": [
    {
      "href": "https://api.cloudscale.ch/v1/server-groups/4699d737-da8a-45a3-931e-c41602cc8431",
      "uuid": "4699d737-da8a-45a3-931e-c41602cc8431",
      "name" "db-group"
    }
  ],
  "anti_affinity_with": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "name": "db-master"
    }
  ],
  "tags": {}
}

Using Additional Volumes

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
    --data '{"name": "db-master", "zone": "lpg1", "flavor": "flex-4-2", "image": "debian-10", "volume_size_gb": 100, "volumes": [{"size_gb": 150, "type": "ssd"}, {"size_gb": 200, "type": "bulk"}], "ssh_keys": ["'"$(cat ~/.ssh/id_rsa.pub)"'"]}' https://api.cloudscale.ch/v1/servers

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/7298adae-7856-492f-a2be-ee910ad48d97

{
  /* See first example of this section for the rest of the response. */
  "volumes": [
    {
      "href": null,
      "uuid": null,
      "name": "db-master-root",
      "size_gb": 100,
      "type": "ssd"
    },
    {
      "href": null,
      "uuid": null,
      "name": "db-master-ssd1",
      "size_gb": 150,
      "type": "ssd"
    },
    {
      "href": null,
      "uuid": null,
      "name": "db-master-bulk1",
      "size_gb": 200,
      "type": "bulk"
    }
  ]
}

Using Additional Interfaces

This example adds two interfaces:

A public interface with IPv4/IPv6
A private interface on a specific private network with an IPv4 address

The addresses are chosen by the subnets that are defined in a network.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
    --data '{"name": "db-master", "zone": "lpg1", "flavor": "flex-4-2", "image": "debian-10", "volume_size_gb": 100, "interfaces": [{"network": "public"}, {"network": "2db69ba3-1864-4608-853a-0771b6885a3a"}], "ssh_keys": ["'"$(cat ~/.ssh/id_rsa.pub)"'"]}' https://api.cloudscale.ch/v1/servers

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/servers/7298adae-7856-492f-a2be-ee910ad48d97

{
  /* See first example of this section for the rest of the response. */
  "interfaces": [
    {
      "type": "public",
      "network": {
        "href": "https://api.cloudscale.ch/v1/networks/36dac305-0207-42e7-8f69-5154b99f0965",
        "uuid": "36dac305-0207-42e7-8f69-5154b99f0965",
        "name": "ext-net3"
      },
      "addresses": [
        {
          "version": 4,
          "address": "185.98.122.110",
          "prefix_length": "24",
          "gateway": "185.98.122.1",
          "reverse_ptr": "185-98-122-110.cust.cloudscale.ch",
          "subnet": {
            "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
            "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
            "cidr": "185.98.122.0/24"
          }
        }
      ]
    },
    {
      "type": "private",
      "network": {
        "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
        "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
        "name": "backend_communication"
      },
      "addresses": [
        {
          "version": 4,
          "address": "172.16.1.253",
          "prefix_length": "24",
          "gateway": "172.16.1.1",
          "reverse_ptr": null,
          "subnet": {
            "href": "https://api.cloudscale.ch/v1/subnets/4a47e742-79ac-11ea-bc55-0242ac130003",
            "uuid": "4a47e742-79ac-11ea-bc55-0242ac130003",
            "cidr": "172.16.1.0/24"
          }
        }
      ]
    }
  ]
}

Reboot a Server

POST /v1/servers/{uuid}/reboot

Initiates a reboot of the server. Services will be shut down cleanly, if the server responds to ACPI events.

The status attribute of the server will transition through "changing" and return to "running" after the server has been rebooted.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/reboot

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8

Start a Server

POST /v1/servers/{uuid}/start

Initiates the boot process of the server.

The status attribute of the server will change from "stopped" to "running" once the server has been powered on.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/start

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8

Stop a Server

POST /v1/servers/{uuid}/stop

Initiates a shutdown of the server. Services will be shut down cleanly, if the server responds to ACPI events.

The status attribute of the server will change from "running" to "stopped" after the server has been powered off.

Request

$ curl -i -H "$AUTH_HEADER" -X POST https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1/stop

Response

HTTP/1.0 204 No Content
Allow: POST, OPTIONS
Content-Type: text/html; charset=utf-8

Update a Server

PATCH /v1/servers/{uuid}

Update properties of a server.

Name	Type	Description
name	string	The name of the server. For a new server, the name has to be a valid host name or a fully qualified domain name (FQDN). In case of an FQDN, the reverse PTR for the public IP address(es) will be set accordingly.
flavor	flavor slug	The slug of the flavor of the new server. In order to change the flavor, the server must be in `"stopped"` state.
interfaces	list of interface objects	A list of interface objects specifying the interfaces to be attached to the server. See here for details. Warning: We recommend to not update interfaces while a server is under production workload as short losses of connectivity might occur.
tags	tags object	The tags assigned to the server.

Important Notes

Attributes can only be updated one at a time to avoid inconsistencies.

Changing Flavors

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F flavor=flex-32-16 https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Modifying Interfaces

It is possible to modify interfaces the exact same way that they are created.

Request

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" -X PATCH \
  --data '{"interfaces": [{"network": "public"}, {"network": "2db69ba3-1864-4608-853a-0771b6885a3a", "addresses": []}]}' https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Server

DELETE /v1/servers/{uuid}

Delete a server along with its root volume.

Important Notes

The root volume of the server will be erased permanently.
Floating IPs will not be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/servers/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Server Groups

Server Groups are zonal resources

Manage server groups, which provide a mechanism to group servers according to a certain placement policy. Currently, the following types of server groups are supported:

"anti-affinity": Ensures that each server in the server group runs on a different physical host than the other servers.

List Server Groups

GET /v1/server-groups?{query_string}

List all server groups.

Tag predicates can be used in the query_string to filter server groups by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server group.
name	string	The display name of the server group.
servers	list of server objects	A list of servers that are part of the server group.
type	string	The type of the server group. Currently, the only supported type is `"anti-affinity"`.
zone	zone stub	The zone in which the server group is located.
tags	tags object	The tags assigned to the server group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/server-groups

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

[
  {
    "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
    "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
    "name": "load balancers",
    "type": "anti-affinity",
    "servers": [
      {
        "href": "https://api.cloudscale.ch/v1/servers/32d2f586-14ff-4da9-81df-134ca45d635f",
        "uuid": "32d2f586-14ff-4da9-81df-134ca45d635f",
        "name": "tesla"
      },
      {
        "href": "https://api.cloudscale.ch/v1/servers/375870c2-d4ee-49af-a048-efcf59ef14ef",
        "uuid": "375870c2-d4ee-49af-a048-efcf59ef14ef",
        "name": "edison"
      }
    ],
    "zone": {
      "slug": "rma1"
    },
    "tags": {}
  }
]

Get a Server Group

GET /v1/server-groups/{uuid}

Get a server group by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server group.
name	string	The display name of the server group.
servers	list of server objects	A list of servers that are part of the server group.
type	string	The type of the server group. Currently, the only supported type is `"anti-affinity"`.
zone	zone stub	The zone in which the server group is located.
tags	tags object	The tags assigned to the server group.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "name": "load balancers",
  "type": "anti-affinity",
  "servers": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/32d2f586-14ff-4da9-81df-134ca45d635f",
      "uuid": "32d2f586-14ff-4da9-81df-134ca45d635f",
      "name": "tesla"
    },
    {
      "href": "https://api.cloudscale.ch/v1/servers/375870c2-d4ee-49af-a048-efcf59ef14ef",
      "uuid": "375870c2-d4ee-49af-a048-efcf59ef14ef",
      "name": "edison"
    }
  ],
  "zone": {
    "slug": "rma1"
  },
  "tags": {}
}

Create a Server Group

POST /v1/server-groups

Create a server group with the specified attributes.

Name	Type	Description
name	string	The display name of the server group.
type	string	The type of the new server group. Currently, the only supported type is `"anti-affinity"`.
zone	zone slug	The slug of the zone in which the new server group will be created. The default zone is the one defined in the project settings.
tags	tags object	The tags assigned to the server group. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the server group.
name	string	The display name of the server group.
servers	list of server objects	A list of servers that are part of the server group.
type	string	The type of the server group. Currently, the only supported type is `"anti-affinity"`.
zone	zone stub	The zone in which the server group is located.
tags	tags object	The tags assigned to the server group.

Request

$ curl -i -H "$AUTH_HEADER" -F name='load balancers' -F zone=rma1 -F type='anti-affinity' https://api.cloudscale.ch/v1/server-groups

Response

HTTP/1.0 201 Created
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c
Allow: GET, POST, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "uuid": "e3b63018-fad6-45f2-9f57-3ea0da726d8c",
  "name": "load balancers",
  "type": "anti-affinity",
  "servers": [],
  "zone": {
    "slug": "rma1"
  },
  "tags": {}
}

Update a Server Group

PATCH /v1/server-groups/{uuid}

Update the properties of a server group.

Name	Type	Description
name	string	The display name of the server group.
tags	tags object	The tags assigned to the server group.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name='current' https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

Delete a Server Group

DELETE /v1/server-groups/{uuid}

Delete a server group.

Most Common Errors

There are still servers associated with the server group. Only empty server groups can be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/server-groups/e3b63018-fad6-45f2-9f57-3ea0da726d8c

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

Flavors

Flavors are zonal resources

Flavors represent different combinations of memory and vCPUs or dedicated cores that can be used when creating a new server. Flavors are identified by their slug, which has to be specified when creating a new or scaling an existing server.

We currently provide the following (publicly available) flavors:

Slug	Description
flex-4-1	Flex-4-1 (4 GB memory, 1 vCPU)
flex-4-2	Flex-4-2 (4 GB memory, 2 vCPUs)
flex-4-4	Flex-4-4 (4 GB memory, 4 vCPUs)
flex-8-2	Flex-8-2 (8 GB memory, 2 vCPUs)
flex-8-4	Flex-8-4 (8 GB memory, 4 vCPUs)
flex-8-8	Flex-8-8 (8 GB memory, 8 vCPUs)
flex-12-3	Flex-12-3 (12 GB memory, 3 vCPUs)
flex-12-6	Flex-12-6 (12 GB memory, 6 vCPUs)
flex-12-12	Flex-12-12 (12 GB memory, 12 vCPUs)
flex-16-4	Flex-16-4 (16 GB memory, 4 vCPUs)
flex-16-8	Flex-16-8 (16 GB memory, 8 vCPUs)
flex-16-16	Flex-16-16 (16 GB memory, 16 vCPUs)
flex-24-6	Flex-24-6 (24 GB memory, 6 vCPUs)
flex-24-12	Flex-24-12 (24 GB memory, 12 vCPUs)
flex-24-24	Flex-24-24 (24 GB memory, 24 vCPUs)
flex-32-8	Flex-32-8 (32 GB memory, 8 vCPUs)
flex-32-16	Flex-32-16 (32 GB memory, 16 vCPUs)
flex-32-32	Flex-32-32 (32 GB memory, 32 vCPUs)
flex-48-12	Flex-48-12 (48 GB memory, 12 vCPUs)
flex-48-24	Flex-48-24 (48 GB memory, 24 vCPUs)
flex-48-48	Flex-48-48 (48 GB memory, 48 vCPUs)
flex-64-16	Flex-64-16 (64 GB memory, 16 vCPUs)
flex-64-32	Flex-64-32 (64 GB memory, 32 vCPUs)
flex-64-64	Flex-64-64 (64 GB memory, 64 vCPUs)
flex-96-24	Flex-96-24 (96 GB memory, 24 vCPUs)
flex-96-48	Flex-96-48 (96 GB memory, 48 vCPUs)
flex-96-96	Flex-96-96 (96 GB memory, 96 vCPUs)
flex-128-32	Flex-128-32 (128 GB memory, 32 vCPUs)
flex-128-64	Flex-128-64 (128 GB memory, 64 vCPUs)
flex-160-40	Flex-160-40 (160 GB memory, 40 vCPUs)
flex-160-80	Flex-160-80 (160 GB memory, 80 vCPUs)
flex-192-48	Flex-192-48 (192 GB memory, 48 vCPUs)
flex-192-96	Flex-192-96 (192 GB memory, 96 vCPUs)
plus-4-2	Plus-4-2 (4 GB memory, 2 dedicated cores)
plus-8-2	Plus-8-2 (8 GB memory, 2 dedicated cores)
plus-8-4	Plus-8-4 (8 GB memory, 4 dedicated cores)
plus-12-3	Plus-12-3 (12 GB memory, 3 dedicated cores)
plus-12-6	Plus-12-6 (12 GB memory, 6 dedicated cores)
plus-16-2	Plus-16-2 (16 GB memory, 2 dedicated cores)
plus-16-4	Plus-16-4 (16 GB memory, 4 dedicated cores)
plus-16-8	Plus-16-8 (16 GB memory, 8 dedicated cores)
plus-24-3	Plus-24-3 (24 GB memory, 3 dedicated cores)
plus-24-6	Plus-24-6 (24 GB memory, 6 dedicated cores)
plus-24-12	Plus-24-12 (24 GB memory, 12 dedicated cores)
plus-32-4	Plus-32-4 (32 GB memory, 4 dedicated cores)
plus-32-8	Plus-32-8 (32 GB memory, 8 dedicated cores)
plus-32-16	Plus-32-16 (32 GB memory, 16 dedicated cores)
plus-48-6	Plus-48-6 (48 GB memory, 6 dedicated cores)
plus-48-12	Plus-48-12 (48 GB memory, 12 dedicated cores)
plus-48-24	Plus-48-24 (48 GB memory, 24 dedicated cores)
plus-64-8	Plus-64-8 (64 GB memory, 8 dedicated cores)
plus-64-16	Plus-64-16 (64 GB memory, 16 dedicated cores)
plus-64-32	Plus-64-32 (64 GB memory, 32 dedicated cores)
plus-96-12	Plus-96-12 (96 GB memory, 12 dedicated cores)
plus-96-24	Plus-96-24 (96 GB memory, 24 dedicated cores)
plus-96-48	Plus-96-48 (96 GB memory, 48 dedicated cores)
plus-128-16	Plus-128-16 (128 GB memory, 16 dedicated cores)
plus-128-32	Plus-128-32 (128 GB memory, 32 dedicated cores)
plus-128-64	Plus-128-64 (128 GB memory, 64 dedicated cores)
plus-160-20	Plus-160-20 (160 GB memory, 20 dedicated cores)
plus-160-40	Plus-160-40 (160 GB memory, 40 dedicated cores)
plus-160-80	Plus-160-80 (160 GB memory, 80 dedicated cores)
plus-192-24	Plus-192-24 (192 GB memory, 24 dedicated cores)
plus-192-48	Plus-192-48 (192 GB memory, 48 dedicated cores)
plus-192-96	Plus-192-96 (192 GB memory, 96 dedicated cores)

Hint: Flavors with up to 112 shared vCPUs or dedicated cores and up to 896 GB memory are available upon request.

List Flavors

GET /v1/flavors

List all available flavors.

Name	Type	Description
slug	string	A unique string identifying the flavor within the API.
name	string	The display name of the flavor.
vcpu_count	integer	The number of vCPUs or dedicated cores provided by the flavor.
memory_gb	integer	The amount of memory in GiB (1024³) provided by the flavor.
zones	list of zone stubs	List of zones in which the flavor is available.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/flavors

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "slug": "flex-4-1",
    "name": "Flex-4-1",
    "vcpu_count": 1,
    "memory_gb": 4,
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  {
    "slug": "flex-4-2",
    "name": "Flex-4-2",
    "vcpu_count": 2,
    "memory_gb": 4,
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  {
    "slug": "flex-4-4",
    "name": "Flex-4-4",
    "vcpu_count": 4,
    "memory_gb": 4,
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  /* ... */
  {
    "slug": "plus-192-96",
    "name": "Plus-192-96",
    "vcpu_count": 96,
    "memory_gb": 192,
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  }
]

Images

Images are zonal resources

Images provide pre-installed operating systems and are used when creating new servers. Separate images are provided for different major versions of each available operating system.

Images are identified by their slug, which has to be specified when creating a new server. We regularly update images to provide minor release upgrades and to keep pre-installed packages at a recent version. If we do a minor release upgrade, the slug of an image will not change, but you will automatically get the latest minor release when creating a new server.

We currently provide the following (publicly available) images:

Slug	Description
arch-24.09	Arch 24.09
centos-7	CentOS 7
centos-8	CentOS 8
centos-stream-9	CentOS Stream 9
debian-10	Debian 10
debian-11	Debian 11
debian-12	Debian 12
fcos-stable	Fedora FCOS 40 (stable)
flatcar-stable	Flatcar 3815.2.5 (stable)
opnsense-23.7	OPNsense 23.7
pfsense-2.7.0	pfSense 2.7.0
ubuntu-20.04	Ubuntu 20.04 LTS
ubuntu-22.04	Ubuntu 22.04 LTS
ubuntu-24.04	Ubuntu 24.04 LTS

The following images are retired. They are no longer supported, and we do not recommend using them.

Slug	Description
ubuntu-18.04	Ubuntu 18.04 LTS

List Images

GET /v1/images

List all images.

Name	Type	Description
slug	string	A unique string identifying the image within the API.
name	string	The display name of the image including its release version.
operating_system	string	The display name of the distribution without a release or version number.
default_username	string	The name of the user that has been set up during server creation and can be used when logging in for the first time.
zones	list of zone stubs	List of zones in which the image is available.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/images

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "slug": "ubuntu-18.04",
    "name": "Ubuntu 18.04 LTS",
    "operating_system": "Ubuntu",
    "default_username": "ubuntu",
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  {
    "slug": "ubuntu-16.04",
    "name": "Ubuntu 16.04 LTS",
    "operating_system": "Ubuntu",
    "default_username": "ubuntu",
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  {
    "slug": "debian-10",
    "name": "Debian 10.2",
    "operating_system": "Debian",
    "default_username": "debian",
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  },
  {
    "slug": "centos-7",
    "name": "CentOS 7",
    "operating_system": "CentOS",
    "default_username": "centos",
    "zones": [
      {
        "slug": "rma1"
      },
      {
        "slug": "lpg1"
      }
    ]
  }
  /* ... */
]

Custom Images

Custom Images are zonal resources

Like images, you can use custom images to start servers. To start a server you have to provide either the custom image UUID or the custom image slug, prefixed with custom:.

Custom Image Objects

Manage custom images on the distributed compute platform. Custom images can be imported, listed, modified and deleted.

List Custom Images

GET /v1/custom-images?{query_string}

List all custom images.

Tag predicates can be used in the query_string to filter custom images by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	string	The unique identifier of the custom image.
name	string	The display name of the custom image.
created_at	datetime	The creation date and time of the resource.
slug	string	A string identifying the custom image for use within the API.
size_gb	integer	The size of the custom image, after internal conversion to "raw" format, rounded up to the next GiB (1024³).
checksums	checksums object	The checksums of the custom image, after internal conversion to "raw" format, as key and value pairs. The algorithm (e.g. `sha256`) name is in the key and the checksum in the value. The set of algorithms used might change in the future.
user_data_handling	string	How `user_data` will be handled when creating a server. There are currently two options: `"pass-through"` and `"extend-cloud-config"`. See here for details.
firmware_type	string	The firmware type that will be used for servers created with the custom image. Currently the following types are supported: `"bios"`, `"uefi"`.
zones	list of zone stubs	List of zones in which the custom image is available.
tags	tags object	The tags assigned to the custom image.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/custom-images

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a",
    "created_at": "2020-05-29T13:18:42.511407Z",
    "uuid": "11111111-1864-4608-853a-0771b6885a3a",
    "name": "my-foo",
    "slug": "foo",
    "size_gb": 5,
    "checksums": {
      "md5": "5b3a1f21cde154cfb522b582f44f1a87",
      "sha256": "5b03bcbd00b687e08791694e47d235a487c294e58ca3b1af704120123aa3f4e6"
    },
    "user_data_handling": "pass-through",
    "firmware_type": "bios",
    "zones": [
      {
        "slug": "lpg1"
      }
    ],
    "tags": {}
  }
]

Get a Custom Image

GET /v1/custom-images/{uuid}

Get a custom image by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	string	The unique identifier of the custom image.
name	string	The display name of the custom image.
created_at	datetime	The creation date and time of the resource.
slug	string	A string identifying the custom image for use within the API.
size_gb	integer	The size of the custom image, after internal conversion to "raw" format, rounded up to the next GiB (1024³).
checksums	checksums object	The checksums of the custom image, after internal conversion to "raw" format, as key and value pairs. The algorithm (e.g. `sha256`) name is in the key and the checksum in the value. The set of algorithms used might change in the future.
user_data_handling	string	How `user_data` will be handled when creating a server. There are currently two options: `"pass-through"` and `"extend-cloud-config"`. See here for details.
firmware_type	string	The firmware type that will be used for servers created with the custom image. Currently the following types are supported: `"bios"`, `"uefi"`.
zones	list of zone stubs	List of zones in which the custom image is available.
tags	tags object	The tags assigned to the custom image.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a",
  "created_at": "2020-05-29T13:18:42.511407Z",
  "uuid": "11111111-1864-4608-853a-0771b6885a3a",
  "name": "my-foo",
  "slug": "foo",
  "size_gb": 5,
  "checksums": {
    "md5": "5b3a1f21cde154cfb522b582f44f1a87",
    "sha256": "5b03bcbd00b687e08791694e47d235a487c294e58ca3b1af704120123aa3f4e6"
  },
  "user_data_handling": "pass-through",
  "firmware_type": "bios",
  "zones": [
    {
      "slug": "lpg1"
    }
  ],
  "tags": {}
}

Update a Custom Image

PATCH /v1/custom-images/{uuid}

Update the properties of a custom image.

Name	Type	Description
name	string	The display name of the custom image.
slug	string	A string identifying the custom image for use within the API.
user_data_handling	string	How `user_data` will be handled when creating a server. There are currently two options: `"pass-through"` and `"extend-cloud-config"`. See here for details.
tags	tags object	The tags assigned to the custom image.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name=second-name https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Custom Image

DELETE /v1/custom-images/{uuid}

Delete a custom image.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Custom Image Imports

Initiate custom images imports on the distributed compute platform.

List Import Status

GET /v1/custom-images/import?{query_string}

List custom image imports of the last 7 days.

Tag predicates can be used in the query_string to filter Custom Image Imports by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	string	The unique identifier of the custom image import.
custom_image	image object	Identifies the custom image being imported. This information is only valid once the `status` property of the import turns to `"success"`.
url	string	The URL used to download the image.
status	string	Values are one of `"started"`, `"in_progress"`, `"failed"`, `"success"`.
error_message	string	Displays an error message if the status is `"failed"`.
tags	tags object	The tags assigned to the custom image.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/custom-images/import

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/custom-images/import/11111111-1864-4608-853a-0771b6885a3a",
    "uuid": "11111111-1864-4608-853a-0771b6885a3a",
    "custom_image": {
        "href": "https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a",
        "uuid": "11111111-1864-4608-853a-0771b6885a3a",
        "name": "my-foo"
    },
    "url": "https://example.com/foo.raw",
    "status": "in_progress",
    "error_message": "",
    "tags": {}
  }
]

Get Import Status

GET /v1/custom-images/import/{uuid}

Get a custom image import by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	string	The unique identifier of the custom image import.
custom_image	image object	Identifies the custom image being imported. This information is only valid once the `status` property of the import turns to `"success"`.
url	string	The URL used to download the image.
status	string	Values are one of `"started"`, `"in_progress"`, `"failed"`, `"success"`.
error_message	string	Displays an error message if the status is `"failed"`.
tags	tags object	The tags assigned to the custom image.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/custom-images/import/11111111-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/custom-images/import/11111111-1864-4608-853a-0771b6885a3a",
  "uuid": "11111111-1864-4608-853a-0771b6885a3a",
  "custom_image": {
      "href": "https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a",
      "uuid": "11111111-1864-4608-853a-0771b6885a3a",
      "name": "my-foo"
  },
  "url": "https://example.com/foo.raw",
  "status": "in_progress",
  "error_message": "",
  "tags": {}
}

Import a Custom Image

POST /v1/custom-images/import

Download and import a custom image from a URL. Currently, the following formats are supported: raw, qcow2.

When importing an image provided by a third party, a file name containing "OpenStack" or "cloud" usually indicates the right version.

Name	Type	Description
url	string	The URL used to download the image.
name	string	The display name of the custom image.
slug	string	A string identifying the custom image for use within the API. Default is `null`.
user_data_handling	string	How `user_data` will be handled when creating a server. There are currently two options: `"pass-through"` and `"extend-cloud-config"`. See here for details.
zones	list of strings	Specify zones in which the custom image will be available.
source_format	string	The file format of the image referenced in the `url`. Currently the following formats are supported: `"raw"`, `"qcow2"`. (Note: This field was ignored and deprecated for some time, but was reintroduced in July 2024 as a breaking change.) Default is `"raw"`.
firmware_type	string	The firmware type that will be used for servers created with the custom image. Currently the following types are supported: `"bios"`, `"uefi"`. For firmware type UEFI, please note that UEFI variables, like the boot order, are not guaranteed to be persistent. Default is `"bios"`.
tags	tags object	The tags assigned to the custom image. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	string	The unique identifier of the custom image import.
custom_image	image object	Identifies the custom image being imported. This information is only valid once the `status` property of the import turns to `"success"`.
url	string	The URL used to download the image.
status	string	Values are one of `"started"`, `"in_progress"`, `"failed"`, `"success"`.
error_message	string	Displays an error message if the status is `"failed"`.
tags	tags object	The tags assigned to the custom image.

Most Common Errors

In case of an HTTP error, you will see the corresponding status code in error_message.
If the file size exceeds 250 GB, the import will end up in "failed" state.

Integrating Custom Images with cloudscale Infrastructure

The cloudscale IaaS Platform makes metadata available to all servers. Metadata can be used to bootstrap your server at first boot or obtain information about the server from within the server itself.

In addition to the metadata provided by the platform, you have the possibility to inject your own data. This feature is called user_data.

Accessing Metadata and Metadata Formats

There are two primary ways to access the metadata:

Access the metadata service at 169.254.169.254 using HTTP.
Access the files from the read-only config drive. You can identify the config drive by the label "config-2" if your operating system supports labels.

Both the metadata service and config drive provide the metadata in two formats:

OpenStack format metadata (primary metadata format):
- Using the metadata service this format is available at http://169.254.169.254/openstack
- On the config drive this format is in the top-level openstack directory
EC2-compatible metadata (intended for images designed for EC2):
- Using the metadata service this format is available at http://169.254.169.254
- On the config drive this format is in the top-level ec2 directory

For both OpenStack and EC2-compatible formats, metadata is available in multiple format versions. You can query the available versions by curl http://169.254.169.254, curl http://169.254.169.254/openstack and find . -maxdepth 2 respectively. We recommend to always rely on the most-recent version available.

If you are interested in more in-depth information please refer to this document or contact support.

Handling of User Data

For custom images you upload to the cloudscale IaaS platform, you can define how the cloudscale IaaS platform should handle the user_data you provide when creating a server. Currently, the following options are available:

Mode	`pass-through`	`extend-cloud-config`
Description	`user_data` that you provide when launching a server is passed through without any modifications.	Similar to the behavior of cloudscale's public images supporting `cloud-init`. `user_data` that you provide when launching a server is extended by some information such as the server hostname, SSH keys and password.
When to use	The custom image does not use `cloud-init` or a compatible cloud-config format, or you do not want your `user_data` to be touched by the cloudsdcale IaaS platform.	The custom image uses `cloud-init` or a compatible `cloud-config` format and you want to use convenience features such as specifying SSH keys and passwords from the API or GUI.
Requirements for the `user_data` input	No particular format required. Any character string is accepted.	The first line must be `#cloud-config`. The whole string must represent valid YAML. The YAML provided must be a dictionary.
Configuring access to the server	The configuration must be injected using `user_data`, or the image must use a hard-coded password or built-in SSH keys.	You can optionally set SSH keys and passwords from the API or GUI.
Manipulations applied to the `user_data`	None	`password:` is set if a password is given. `ssh_authorized_keys:` gets appended the selected SSH keys. `fqdn:` gets set to the server name if not already provided in `user_data`

Request

$ curl -i -H "$AUTH_HEADER" -F url=https://example.com/foo.raw -F name=my-foo -F zones=lpg1 -F slug=foo -F source_format=raw -F user_data_handling=pass-through https://api.cloudscale.ch/v1/custom-images/import

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/custom-images/import/11111111-1864-4608-853a-0771b6885a3a

{
  "href": "https://api.cloudscale.ch/v1/custom-images/import/11111111-1864-4608-853a-0771b6885a3a",
  "uuid": "11111111-1864-4608-853a-0771b6885a3a",
  "custom_image": {
      "href": "https://api.cloudscale.ch/v1/custom-images/11111111-1864-4608-853a-0771b6885a3a",
      "uuid": "11111111-1864-4608-853a-0771b6885a3a",
      "name": "my-foo"
  },
  "url": "https://example.com/foo.raw",
  "status": "in_progress",
  "error_message": "",
  "tags": {}
}

Volumes

Volumes are zonal resources

Manage volumes on the distributed storage clusters. Volumes can be created, listed, and deleted as well as renamed, scaled, and attached to different servers.

Currently, the following volume types are supported:

"ssd" for maximum performance and minimal latency
"bulk" for your big chunks of data

List Volumes

GET /v1/volumes?{query_string}

List all volumes.

Tag predicates can be used in the query_string to filter volumes by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the volume.
name	string	The display name of the volume.
created_at	datetime	The creation date and time of the resource.
size_gb	integer	The size of the volume in GiB (1024³).
type	string	There are currently two options: `"ssd"` and `"bulk"`.
servers	list of server objects	A list of servers that the volume is attached to. Currently, a volume can only be attached to a single server.
server_uuids	list of UUIDs	A list of server UUIDs that the volume is attached to. Deprecated: Use `servers` instead.
tags	tags object	The tags assigned to the volume.
zone	zone stub	The zone in which the volume is located.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/volumes

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
    "created_at": "2019-05-29T13:18:42.511407Z",
    "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
    "name": "capitano-root",
    "zone": {
      "slug": "lpg1"
    },
    "size_gb": 150,
    "type": "ssd",
    "servers": [
      {
        "href": "https://api.cloudscale.ch/v1/servers/9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
        "uuid": "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
        "name": "my-server"
      }
    ],
    "server_uuids": [
      "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
    ],
    "tags": {}
  }
]

Get a Volume

GET /v1/volumes/{uuid}

Get a volume by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the volume.
name	string	The display name of the volume.
created_at	datetime	The creation date and time of the resource.
size_gb	integer	The size of the volume in GiB (1024³).
type	string	There are currently two options: `"ssd"` and `"bulk"`.
servers	list of server objects	A list of servers that the volume is attached to. Currently, a volume can only be attached to a single server.
server_uuids	list of UUIDs	A list of server UUIDs that the volume is attached to. Deprecated: Use `servers` instead.
tags	tags object	The tags assigned to the volume.
zone	zone stub	The zone in which the volume is located.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "capitano-root",
  "zone": {
    "slug": "lpg1"
  },
  "size_gb": 150,
  "type": "ssd",
  "servers": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
      "uuid": "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
      "name": "my-server"
    }
  ],
  "server_uuids": [
    "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
  ],
  "tags": {}
}

Create a Volume

POST /v1/volumes

Create a volume with the specified attributes.

Name	Type	Description
name	string	The display name of the volume.
size_gb	integer	The size of the volume in GiB (1024³).
type	string	There are currently two options: `"ssd"` and `"bulk"`. Default is `"ssd"`.
servers	list of UUIDs	A list of server UUIDs that the volume should be attached to. Currently, a volume can only be attached to a single server.
server_uuids	list of UUIDs	A list of server UUIDs that the volume is attached to. Deprecated: Use `servers` instead.
tags	tags object	The tags assigned to the volume. Default is `{}`.
zone	zone slug	The slug of the zone in which the new volume will be created. The default zone is the one defined in the project settings.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the volume.
name	string	The display name of the volume.
created_at	datetime	The creation date and time of the resource.
size_gb	integer	The size of the volume in GiB (1024³).
type	string	There are currently two options: `"ssd"` and `"bulk"`.
servers	list of server objects	A list of servers that the volume is attached to. Currently, a volume can only be attached to a single server.
server_uuids	list of UUIDs	A list of server UUIDs that the volume is attached to. Deprecated: Use `servers` instead.
tags	tags object	The tags assigned to the volume.
zone	zone stub	The zone in which the volume is located.

Most Common Errors

There are a variety of errors that can occur if you try to create a volume without the proper arguments. Those errors are mostly self-explanatory. However, there are a few more common errors:

You do not have enough credits. Please add more funds to your account.
The size of an SSD volume is not a multiple of 1 GB or exceeds your current quota.
The size of a bulk volume is not a multiple of 100 GB or exceeds your current quota.

Request

$ curl -i -H "$AUTH_HEADER" -F size_gb=150 -F name=my-volume-name -F zone=lpg1 -F type=ssd -F servers=9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7 https://api.cloudscale.ch/v1/volumes

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a

{
  "href": "https://api.cloudscale.ch/v1/volumes/2db69ba3-1864-4608-853a-0771b6885a3a",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "my-volume-name",
  "zone": {
    "slug": "lpg1"
  },
  "size_gb": 150,
  "type": "ssd",
  "servers": [
    {
      "href": "https://api.cloudscale.ch/v1/servers/9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
      "uuid": "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7",
      "name": "my-server"
    }
  ],
  "server_uuids": [
    "9e1f9a7f-e8d0-4086-ad7e-fea161d7c5f7"
  ],
  "tags": {}
}

Update a Volume

PATCH /v1/volumes/{uuid}

Update the properties of a volume.

Name	Type	Description
name	string	The display name of the volume.
size_gb	integer	The size of the volume in GiB (1024³).
type	string	There are currently two options: `"ssd"` and `"bulk"`.
servers	list of UUIDs	A list of server UUIDs that the volume should be attached to. Currently, a volume can only be attached to a single server.
server_uuids	list of UUIDs	A list of server UUIDs that the volume is attached to. Deprecated: Use `servers` instead.
tags	tags object	The tags assigned to the volume.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F size_gb=100 https://api.cloudscale.ch/v1/volumes/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Detaching an Existing Volume

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" -X PATCH \
    --data '{ "servers": [] }' https://api.cloudscale.ch/v1/volumes/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Delete a Volume

DELETE /v1/volumes/{uuid}

Delete a volume and permanently destroy all of its data.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/volumes/12345678-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Floating IPs

Floating IPs are regional or global resources

Floating IPs are IP addresses or networks that can be moved between servers. Possible use cases include: High-availability, non-disruptive maintenance, multiple IPs per server, or re-using the same IP after replacing a server.

Currently, the following Floating IP types are supported:

"regional" usable in just one region
"global" usable in all regions

List Floating IPs

GET /v1/floating-ips?{query_string}

List all Floating IPs.

Tag predicates can be used in the query_string to filter Floating IPs by tag.

Name	Type	Description
href	URL	The URL of the resource.
network	string	The Floating IP in CIDR notation.
created_at	datetime	The creation date and time of the resource.
ip_version	integer	The IP version of the Floating IP. Can be either `4` or `6`.
server	server object	The destination server of the Floating IP. This is `null` if the Floating IP has been created without a server, with a load balancer or the server has been deleted.
load_balancer	load balancer object	The destination load balancer of the Floating IP. This is `null` if the Floating IP has been created without a load balancer, the load balancer has been deleted or the Floating IP is assigned to a server.
type	string	The type of the Floating IP. There are currently two options: `"regional"` and `"global"`.
region	region object	The region in which the Regional Floating IP is located. `null` for Global Floating IPs.
next_hop	string	The destination IP address of the Floating IP.
reverse_ptr	string	The reverse pointer of the Floating IP.
tags	tags object	The tags assigned to the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/floating-ips

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
    "created_at": "2019-05-29T13:18:42.505197Z",
    "network": "192.0.2.123/32",
    "ip_version": 4,
    "server": {
      "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
      "name": "db-master"
    },
    "load_balancer": null,
    "region": {
      "slug": "lpg"
    },
    "type": "regional",
    "next_hop": "198.51.100.1",
    "reverse_ptr": "192.0.2.123.cust.cloudscale.ch",
    "tags": {}
  }
]

Get a Floating IP

GET /v1/floating-ips/{network_id}

Get a Floating IP by its network ID.

Name	Type	Description
href	URL	The URL of the resource.
network	string	The Floating IP in CIDR notation.
created_at	datetime	The creation date and time of the resource.
ip_version	integer	The IP version of the Floating IP. Can be either `4` or `6`.
server	server object	The destination server of the Floating IP. This is `null` if the Floating IP has been created without a server, with a load balancer or the server has been deleted.
load_balancer	load balancer object	The destination load balancer of the Floating IP. This is `null` if the Floating IP has been created without a load balancer, the load balancer has been deleted or the Floating IP is assigned to a server.
type	string	The type of the Floating IP. There are currently two options: `"regional"` and `"global"`.
region	region object	The region in which the Regional Floating IP is located. `null` for Global Floating IPs.
next_hop	string	The destination IP address of the Floating IP.
reverse_ptr	string	The reverse pointer of the Floating IP.
tags	tags object	The tags assigned to the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 200 OK
Allow: GET, POST, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "192.0.2.123/32",
  "ip_version": 4,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name": "db-master"
  },
  "load_balancer": null,
  "region": {
    "slug": "lpg"
  },
  "type": "regional",
  "next_hop": "198.51.100.1",
  "reverse_ptr": "192.0.2.123.cust.cloudscale.ch",
  "tags": {}
}

Create a Floating IP

POST /v1/floating-ips

Create a Floating IP with the specified attributes.

Name	Type	Description
ip_version	integer	The IP version of the Floating IP. Can be either `4` or `6`.
server	UUID	The destination server of the Floating IP. Default is `null`.
load_balancer	UUID	The destination load balancer of the Floating IP. Note: This attribute can only be set if `prefix_length` is 32 for IPv4 or 128 for IPv6. Default is `null`.
type	string	The type of the new Floating IP. There are currently two options: `"regional"` and `"global"`. Default is `"regional"`.
region	region slug	The slug of the region in which the new Regional Floating IP will be created. Must be omitted for Global Floating IPs. For Regional Floating IPs, default is the region of the project default zone.
reverse_ptr	string	The reverse pointer of the Floating IP.
prefix_length	integer	The prefix length of the new Floating IP. Default is `32` for IPv4 and `128` for IPv6. Additionally, the prefix length `56` is supported for IPv6 only.
tags	tags object	The tags assigned to the Floating IP. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
network	string	The Floating IP in CIDR notation.
created_at	datetime	The creation date and time of the resource.
ip_version	integer	The IP version of the Floating IP. Can be either `4` or `6`.
server	server object	The destination server of the Floating IP. This is `null` if the Floating IP has been created without a server, with a load balancer or the server has been deleted.
load_balancer	load balancer object	The destination load balancer of the Floating IP. This is `null` if the Floating IP has been created without a load balancer, the load balancer has been deleted or the Floating IP is assigned to a server.
type	string	The type of the Floating IP. There are currently two options: `"regional"` and `"global"`.
region	region object	The region in which the Regional Floating IP is located. `null` for Global Floating IPs.
next_hop	string	The destination IP address of the Floating IP.
reverse_ptr	string	The reverse pointer of the Floating IP.
tags	tags object	The tags assigned to the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" -F type=regional -F ip_version=6 -F region=lpg -F server=47cec963-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/2001:db8::cafe

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/2001:db8::cafe",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "2001:db8::cafe/128",
  "ip_version": 6,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47cec963-fcd2-482f-bdb6-24461b2d47b1",
    "name": "db-master"
  },
  "load_balancer": null,
  "region": {
    "slug": "lpg"
  },
  "type": "regional",
  "next_hop": "2001:db8:dead:beef::42",
  "reverse_ptr": "null",
  "tags": {}
}

Update a Floating IP (Deprecated)

POST /v1/floating-ips/{network_id} Deprecated

Deprecated, might be removed in future API versions.

The POST method on this URL has been deprecated in favor of the PATCH method.

Update the properties of a Floating IP.

Name	Type	Description
server	UUID	The new destination server of the Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" -F server=47777777-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 200 OK
Allow: GET, POST, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

{
  "href": "https://api.cloudscale.ch/v1/floating-ips/192.0.2.123",
  "created_at": "2019-05-29T13:18:42.505197Z",
  "network": "192.0.2.123/32",
  "ip_version": 4,
  "server": {
    "href": "https://api.cloudscale.ch/v1/servers/47777777-fcd2-482f-bdb6-24461b2d47b1",
    "uuid": "47777777-fcd2-482f-bdb6-24461b2d47b1",
    "name": "db-master"
  },
  "load_balancer": null,
  "region": {
    "slug": "lpg"
  },
  "type": "regional",
  "next_hop": "198.51.100.1",
  "reverse_ptr": "192.0.2.123.cust.cloudscale.ch",
  "tags": {}
}

Update a Floating IP

PATCH /v1/floating-ips/{network_id}

Update the properties of a Floating IP.

Name	Type	Description
server	UUID	The destination server of the Floating IP. Default is `null`.
load_balancer	UUID	The destination load balancer of the Floating IP. Note: This attribute can only be set if `prefix_length` is 32 for IPv4 or 128 for IPv6. Default is `null`.
reverse_ptr	string	The reverse pointer of the Floating IP.
tags	tags object	The tags assigned to the Floating IP.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F server=47777777-fcd2-482f-bdb6-24461b2d47b1 https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 204 No Content
Allow: GET, POST, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Delete a Floating IP

DELETE /v1/floating-ips/{network_id}

Delete a Floating IP.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/floating-ips/192.0.2.123

Response

HTTP/1.0 204 No Content
Allow: GET, POST, DELETE, HEAD, OPTIONS
Content-Type: application/json

Networks

Networks are zonal resources

Manage private networks. Networks can be created, listed, deleted and changed.

List Networks

GET /v1/networks?{query_string}

List all networks.

Tag predicates can be used in the query_string to filter networks by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the network.
name	string	The display name of the network.
created_at	datetime	The creation date and time of the resource.
zone	zone stub	The zone in which the network is located.
mtu	integer	The MTU size for the network.
subnets	list of subnet objects	A list of the subnets that are used in this network.
tags	tags object	The tags assigned to the network.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/networks

Response

HTTP/1.0 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
    "created_at": "2019-05-29T13:18:42.511407Z",
    "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
    "name": "my-network-name",
    "zone": {
      "slug": "lpg1"
    },
    "mtu": 9000,
    "subnets": [
      {
        "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
        "uuid": "33333333-1864-4608-853a-0771b6885a3a",
        "cidr": "172.16.0.0/24"
      }
    ],
    "tags": {}
  }
]

Get a Network

GET /v1/networks/{uuid}

Get a Network by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the network.
name	string	The display name of the network.
created_at	datetime	The creation date and time of the resource.
zone	zone stub	The zone in which the network is located.
mtu	integer	The MTU size for the network.
subnets	list of subnet objects	A list of the subnets that are used in this network.
tags	tags object	The tags assigned to the network.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "my-network-name",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "zone": {
    "slug": "lpg1"
  },
  "mtu": 9000,
  "subnets": [
    {
      "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
      "uuid": "33333333-1864-4608-853a-0771b6885a3a",
      "cidr": "172.16.0.0/24"
    }
  ],
  "tags": {}
}

Create a Network

POST /v1/networks

Create a network with the specified attributes.

Name	Type	Description
name	string	The display name of the network.
zone	zone slug	The slug of the zone in which the new network will be created. The default zone is the one defined in the project settings.
mtu	integer	The MTU size for the network. Default is `9000`.
auto_create_ipv4_subnet	boolean	If `true` an IPv4 subnet will automatically be created in the network. Default is `true`.
tags	tags object	The tags assigned to the network. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the network.
name	string	The display name of the network.
created_at	datetime	The creation date and time of the resource.
zone	zone stub	The zone in which the network is located.
mtu	integer	The MTU size for the network.
subnets	list of subnet objects	A list of the subnets that are used in this network.
tags	tags object	The tags assigned to the network.

Request

$ curl -i -H "$AUTH_HEADER" -F name=my-network-name -F zone=lpg1 -F mtu=9000 https://api.cloudscale.ch/v1/networks

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a

{
  "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
  "created_at": "2019-05-29T13:18:42.511407Z",
  "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
  "name": "my-network-name",
  "zone": {
    "slug": "lpg1"
  },
  "mtu": 9000,
  "subnets": [
    {
      "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
      "uuid": "33333333-1864-4608-853a-0771b6885a3a",
      "cidr": "172.16.0.0/24"
    }
  ],
  "tags": {}
}

Update a Network

PATCH /v1/networks/{uuid}

Update the properties of a network.

Name	Type	Description
name	string	The display name of the network.
mtu	integer	The MTU size for the network.
tags	tags object	The tags assigned to the network.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F mtu=1500 https://api.cloudscale.ch/v1/networks/4328e7a2-5d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Network

DELETE /v1/networks/{uuid}

This is only possible if no server is part of the network. Automatically deletes subnets that are configured on this network.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/networks/12345678-9d03-4b7a-8a5d-0b9d6c8abd45

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Subnets

Subnets are zonal resources

Manage subnets for private networks. Subnets can be created, changed, listed and deleted.

List Subnets

GET /v1/subnets?{query_string}

List all subnets.

Tag predicates can be used in the query_string to filter subnets by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the subnet.
cidr	string	The address range in CIDR notation. Must be at least /24.
network	network object	The network of the subnet.
gateway_address	string	The gateway address of the subnet. `null` means that no gateway is used.
dns_servers	list of strings	A list of DNS resolver IP addresses, that act as DNS servers.
tags	tags object	The tags assigned to the subnet.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/subnets

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
    "uuid": "33333333-1864-4608-853a-0771b6885a3a",
    "cidr": "192.168.42.0/24",
    "network": {
      "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
      "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
      "name": "my-network-name"
    },
    "gateway_address": null,
    "dns_servers": ["185.79.232.101", "185.79.232.102"],
    "tags": {}
  }
]

Get a Subnet

GET /v1/subnets/{uuid}

Get a subnet by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the subnet.
cidr	string	The address range in CIDR notation. Must be at least /24.
network	network object	The network of the subnet.
gateway_address	string	The gateway address of the subnet. `null` means that no gateway is used.
dns_servers	list of strings	A list of DNS resolver IP addresses, that act as DNS servers.
tags	tags object	The tags assigned to the subnet.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
  "uuid": "33333333-1864-4608-853a-0771b6885a3a",
  "cidr": "192.168.42.0/24",
  "network": {
    "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
    "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
    "name": "my-network-name",
  },
  "gateway_address": null,
  "dns_servers": ["185.79.232.101", "185.79.232.102"],
  "tags": {}
}

Create a Subnet

POST /v1/subnets

Create a subnet with the specified attributes.

Name	Type	Description
cidr	string	The address range in CIDR notation. Must be at least /24.
network	UUID	The network of the subnet.
gateway_address	string	The gateway address of the subnet. `null` means that no gateway is used. Cannot be within the DHCP range, which is the lowest `.101`-`.254` in the subnet. Default is `null`.
dns_servers	list of strings	A list of DNS resolver IP addresses for the subnet. Pass an empty list to remove all DNS resolvers. Default is `null` in which case the cloudscale default resolvers are used.
tags	tags object	The tags assigned to the subnet. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the subnet.
cidr	string	The address range in CIDR notation. Must be at least /24.
network	network object	The network of the subnet.
gateway_address	string	The gateway address of the subnet. `null` means that no gateway is used.
dns_servers	list of strings	A list of DNS resolver IP addresses, that act as DNS servers.
tags	tags object	The tags assigned to the subnet.

Request

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" --data '{ "cidr": "192.168.42.0/24", "network": "2db69ba3-1864-4608-853a-0771b6885a3a"}' https://api.cloudscale.ch/v1/subnets

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a

{
  "href": "https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a",
  "uuid": "33333333-1864-4608-853a-0771b6885a3a",
  "cidr": "192.168.42.0/24",
  "network": {
    "href": "https://api.cloudscale.ch/v1/networks/2db69ba3-1864-4608-853a-0771b6885a3a",
    "uuid": "2db69ba3-1864-4608-853a-0771b6885a3a",
    "name": "my-network-name"
  },
  "gateway_address": null,
  "dns_servers": ["185.79.232.101", "185.79.232.102"],
  "tags": {}
}

Update a Subnet

PATCH /v1/subnets/{uuid}

Update the properties of a subnet.

Name	Type	Description
network	UUID	The network of the subnet.
gateway_address	string	The gateway address of the subnet. `null` means that no gateway is used. Cannot be within the DHCP range, which is the lowest `.101`-`.254` in the subnet.
dns_servers	list of strings	A list of DNS resolver IP addresses for the subnet. Pass an empty list to remove all DNS resolvers. Default is `null` in which case the cloudscale default resolvers are used.
tags	tags object	The tags assigned to the subnet.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
   -X PATCH --data '{ "gateway_address": "192.168.42.1"}' https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Updating DNS Servers

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
    -X PATCH --data '{ "dns_servers": ["192.168.42.11", "192.168.42.12"]}' https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Subnet

DELETE /v1/subnets/{uuid}

This is only possible if no server is part of the subnet.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/subnets/33333333-1864-4608-853a-0771b6885a3a

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Load Balancers

Load Balancers are zonal resources

A load balancer is a complex object that consists of several components. Each component supports a range of configuration options and protocols. An operational load balancer is composed of:

The main load balancer: represents the virtual network device and is assigned VIP addresses (virtual IP addresses) through which incoming traffic is received. Load balancers are available in different flavors.
One or many pools per load balancer: a group of servers that handle incoming traffic. Traffic is distributed according to the algorithm set on the pool.
One or many pool members per pool: the individual servers in a pool.
One or many listeners per pool: defines the protocol and port to be used for incoming traffic. Traffic is then distributed within the associated pool.
Optionally a health monitor per pool: defines how to periodically check the health of the pool members of the associated pool. If a pool member is not considered healthy, it will not be forwarded any traffic from the load balancer.

Load Balancer Objects

Manage load balancers on the distributed compute platform. Load balancers can be created, listed, modified and deleted.

Load Balancer Flavors

We currently provide the following (publicly available) flavors:

Slug	Description
lb-standard	LB-Standard

List Load Balancers

GET /v1/load-balancers?{query_string}

List all load balancers.

Tag predicates can be used in the query_string to filter load balancers by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the load balancer.
name	string	The display name of the load balancer.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the load balancer. Can be `"changing"`, `"degraded"`, `"running"`, `"stopped"`, `"error"`, `"unknown"`.
zone	zone stub	The zone in which the load balancer is located.
flavor	load balancer flavor object	The flavor of the load balancer.
vip_addresses	list of VIP address objects	A list of VIP address objects describing the addresses that are assigned to the load balancer.
tags	tags object	The tags assigned to the load balancer.

Statuses

The statuses of a load balancer are detailed in the following table:

status	Description
`changing`	The load balancer is being created or updated.
`degraded`	One or more enabled pool members are not operating normally or a listener has reached its connection limit.
`running`	The load balancer is working normally.
`stopped`	The load balancer has been stopped, please contact support.
`error`	All enabled pool members are not operating normally or another problem has occurred. Please contact support if the problem persists.
`unknown`	There are temporary internal issues in the zone of this load balancer.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/load-balancers/0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f",
    "uuid": "0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f",
    "name": "web-lb",
    "created_at": "2023-02-07T15:32:02.308041Z",
    "status": "running",
    "zone": {
      "slug": "lpg1"
    },
    "flavor": {
      "slug": "lb-standard",
      "name": "LB-Standard"
    },
    "vip_addresses": [
      {
        "version": 4,
        "address": "192.0.2.110",
        "subnet": {
          "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
          "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
          "cidr": "192.0.2.0/24"
        }
      },
      {
        "version": 6,
        "address": "2001:db8:85a3:8d3:1319:8a2e:370:7348",
        "subnet": {
          "href": "https://api.cloudscale.ch/v1/subnets/a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
          "uuid": "a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
          "cidr": "2001:db8:85a3:8d3::/64"
        }
      }
    ],
    "tags": {}
  }
]

Get a Load Balancer

GET /v1/load-balancers/{uuid}

Get a load balancer by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the load balancer.
name	string	The display name of the load balancer.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the load balancer. Can be `"changing"`, `"degraded"`, `"running"`, `"stopped"`, `"error"`, `"unknown"`.
zone	zone stub	The zone in which the load balancer is located.
flavor	load balancer flavor object	The flavor of the load balancer.
vip_addresses	list of VIP address objects	A list of VIP address objects describing the addresses that are assigned to the load balancer.
tags	tags object	The tags assigned to the load balancer.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f",
  "uuid": "0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f",
  "name": "web-lb",
  "created_at": "2023-02-07T15:32:02.308041Z",
  "status": "running",
  "zone": {
    "slug": "lpg1"
  },
  "flavor": {
    "slug": "lb-standard",
    "name": "LB-Standard"
  },
  "vip_addresses": [
    {
      "version": 4,
      "address": "192.0.2.110",
      "subnet": {
        "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
        "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
        "cidr": "192.0.2.0/24"
      }
    },
    {
      "version": 6,
      "address": "2001:db8:85a3:8d3:1319:8a2e:370:7348",
      "subnet": {
        "href": "https://api.cloudscale.ch/v1/subnets/a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
        "uuid": "a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
        "cidr": "2001:db8:85a3:8d3::/64"
      }
    }
  ],
  "tags": {}
}

Create a Load Balancer

POST /v1/load-balancers

Create a load balancer with the specified attributes.

Name	Type	Description
name	string	The display name of the load balancer.
zone	zone slug	The slug of the zone in which the new load balancer will be created.
flavor	flavor slug	The flavor of the load balancer.
vip_addresses	list of VIP address objects	A list of VIP address objects specifying the VIP addresses to be configured on the load balancer. See here for details. Default is to assign a public IPv4 and IPv6 address.
tags	tags object	The tags assigned to the load balancer. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the load balancer.
name	string	The display name of the load balancer.
created_at	datetime	The creation date and time of the resource.
status	string	The current status of the load balancer. Can be `"changing"`, `"degraded"`, `"running"`, `"stopped"`, `"error"`, `"unknown"`.
zone	zone stub	The zone in which the load balancer is located.
flavor	load balancer flavor object	The flavor of the load balancer.
vip_addresses	list of VIP address objects	A list of VIP address objects describing the addresses that are assigned to the load balancer.
tags	tags object	The tags assigned to the load balancer.

`vip_addresses` Attribute Specification

The VIP addresses (virtual IP addresses) through which incoming traffic is received can either be allocated in the public network (facing the internet) or in the subnet of a private network. This behavior is controlled through the vip_addresses attribute, which can be specified when creating a load balancer.

vip_addresses must either be absent or the value must be a list containing VIP address objects. (Currently, specifying 1 VIP address object is supported.)

The following table gives an overview of different use cases and the corresponding schemas of the vip_addresses attribute. See also the Using a Private Network example.

not specified (default)	Create an IPv4 and an IPv6 VIP address on the public network.
`[{"subnet": "UUID1"}]`	Create a VIP address on the subnet identified by `"UUID1"` and use an address from the DHCP range of the subnet.
`[{"subnet": "UUID2", "address": "A.B.C.D"}]`	Create a VIP address on the subnet identified by `"UUID2"` and use address A.B.C.D.

Request

$ curl -i -H "$AUTH_HEADER" -F name=web-lb -F flavor=lb-standard -F zone=lpg1 https://api.cloudscale.ch/v1/load-balancers

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/514064c2-cfd4-4b0c-8a4b-c68c552ff84f

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/514064c2-cfd4-4b0c-8a4b-c68c552ff84f",
  "uuid": "514064c2-cfd4-4b0c-8a4b-c68c552ff84f",
  "name": "web-lb",
  "created_at": "2023-02-07T15:59:12.788718Z",
  "status": "changing",
  "zone": {
    "slug": "lpg1"
  },
  "flavor": {
    "slug": "lb-standard",
    "name": "LB-Standard"
  },
  "vip_addresses": [
    {
      "version": 4,
      "address": "192.0.2.110",
      "subnet": {
        "href": "https://api.cloudscale.ch/v1/subnets/92c70b2f-99cb-4811-8823-3d46572006e4",
        "uuid": "92c70b2f-99cb-4811-8823-3d46572006e4",
        "cidr": "192.0.2.0/24"
      }
    },
    {
      "version": 6,
      "address": "2001:db8:85a3:8d3:1319:8a2e:370:7348",
      "subnet": {
        "href": "https://api.cloudscale.ch/v1/subnets/a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
        "uuid": "a5f66ceb-75bf-465a-9ce6-8a6d601a62fb",
        "cidr": "2001:db8:85a3:8d3::/64"
      }
    }
  ],
  "tags": {}
}

Using a Private Network

This creates a load balancer that receives traffic from a private network.

$ curl -i -H "$AUTH_HEADER" \
    -H "Content-Type: application/json" --data '{"name": "web-lb", "flavor": "lb-standard", "vip_addresses": [{"subnet": "15e061ac-c98a-4a26-85df-b25d47801e99", "address": "172.29.177.11"}], "zone": "rma1"}' https://api.cloudscale.ch/v1/load-balancers

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/c337b7a8-b275-4cfc-9b14-e80ade7783f6

{
  /* See first example of this section for the rest of the response. */
  "vip_addresses": [
    {
      "version": 4,
      "address": "172.29.177.11",
      "subnet": {
        "href": "https://api.cloudscale.ch/v1/subnets/15e061ac-c98a-4a26-85df-b25d47801e99",
        "uuid": "15e061ac-c98a-4a26-85df-b25d47801e99",
        "cidr": "172.29.177.0/24"
      }
    }
  ]
}

Update a Load Balancer

PATCH /v1/load-balancers/{uuid}

Update the properties of a load balancer.

Name	Type	Description
name	string	The display name of the load balancer.
tags	tags object	The tags assigned to the load balancer.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name=web-lb https://api.cloudscale.ch/v1/load-balancers/0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Load Balancer

DELETE /v1/load-balancers/{uuid}

Delete a load balancer. Automatically deletes pools, listeners and health monitors that are configured on this load balancer.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/load-balancers/0f62e0a7-f459-4fc4-9c25-9e57b6cb4b2f

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Load Balancer Pools

Manage load balancer pools on the distributed compute platform. Load balancer pools can be created, listed, modified and deleted.

The algorithms and protocols supported by load balancer pools are detailed in the following tables.

Pool Algorithms

The algorithm of the pool defines how traffic is distributed between pool members.

Algorithm	Description
`round_robin`	New traffic is distributed between the pool members in a cyclic manner.
`least_connections`	New traffic is sent to the pool member with the least active connections. This results in a more even distribution of traffic, even if there is high variability in connection lifetime.
`source_ip`	The pool member is selected based on the traffic's source IP to maintain session persistence across multiple requests.

Pool Protocols

The protocol configured on the pool defines how traffic is transmitted between the load balancer and the pool members.

Protocol	Description
`tcp`	A new TCP connection is opened between the load balancer and the pool member. The original TCP connection parameters such as the source IP and source port are not available to the pool members. There are no special requirements for the pool members in regard to how they handle traffic.
`proxy`	The original TCP connection parameters such as the source IP and source port are made available to the pool members using the PROXY protocol version 1. The pool members must be configured to accept connections using the PROXY protocol.
`proxyv2`	The original TCP connection parameters such as the source IP and source port are made available to the pool members using the PROXY protocol version 2. The pool members must be configured to accept connections using the PROXY protocol.

List Pools

GET /v1/load-balancers/pools?{query_string}

List all load balancer pools.

Tag predicates can be used in the query_string to filter load balancer pools by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool.
name	string	The display name of the pool.
created_at	datetime	The creation date and time of the resource.
load_balancer	load balancer object	The load balancer of the pool.
algorithm	string	The algorithm according to which the incoming traffic is distributed between the pool members. Currently the following algorithms are supported: `"round_robin"`, `"least_connections"`, `"source_ip"`.
protocol	string	The protocol used for traffic between the load balancer and the pool members. Currently the following protocols are supported: `"tcp"`, `"proxy"`, `"proxyv2"`.
tags	tags object	The tags assigned to the load balancer pool.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/pools

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/1563703b-46b6-4618-9eb0-3dd554d1e8d0",
    "uuid": "1563703b-46b6-4618-9eb0-3dd554d1e8d0",
    "name": "web-lb-pool",
    "created_at": "2023-02-17T12:36:54.901740Z",
    "load_balancer": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
      "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
      "name": "web-lb"
    },
    "algorithm": "round_robin",
    "protocol": "proxyv2",
    "tags": {}
  }
]

Get a Pool

GET /v1/load-balancers/pools/{uuid}

Get a load balancer pool by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool.
name	string	The display name of the pool.
created_at	datetime	The creation date and time of the resource.
load_balancer	load balancer object	The load balancer of the pool.
algorithm	string	The algorithm according to which the incoming traffic is distributed between the pool members. Currently the following algorithms are supported: `"round_robin"`, `"least_connections"`, `"source_ip"`.
protocol	string	The protocol used for traffic between the load balancer and the pool members. Currently the following protocols are supported: `"tcp"`, `"proxy"`, `"proxyv2"`.
tags	tags object	The tags assigned to the load balancer pool.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/pools/1563703b-46b6-4618-9eb0-3dd554d1e8d0

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/pools/1563703b-46b6-4618-9eb0-3dd554d1e8d0",
  "uuid": "1563703b-46b6-4618-9eb0-3dd554d1e8d0",
  "name": "web-lb-pool",
  "created_at": "2023-02-17T12:36:54.901740Z",
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "algorithm": "round_robin",
  "protocol": "proxyv2",
  "tags": {}
}

Create a Pool

POST /v1/load-balancers/pools

Create a load balancer pool with the specified attributes.

Name	Type	Description
name	string	The display name of the pool.
load_balancer	UUID	The load balancer of the pool.
algorithm	string	The algorithm according to which the incoming traffic is distributed between the pool members. Currently the following algorithms are supported: `"round_robin"`, `"least_connections"`, `"source_ip"`.
protocol	string	The protocol used for traffic between the load balancer and the pool members. Currently the following protocols are supported: `"tcp"`, `"proxy"`, `"proxyv2"`.
tags	tags object	The tags assigned to the load balancer pool. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool.
name	string	The display name of the pool.
created_at	datetime	The creation date and time of the resource.
load_balancer	load balancer object	The load balancer of the pool.
algorithm	string	The algorithm according to which the incoming traffic is distributed between the pool members. Currently the following algorithms are supported: `"round_robin"`, `"least_connections"`, `"source_ip"`.
protocol	string	The protocol used for traffic between the load balancer and the pool members. Currently the following protocols are supported: `"tcp"`, `"proxy"`, `"proxyv2"`.
tags	tags object	The tags assigned to the load balancer pool.

Request

$ curl -i -H "$AUTH_HEADER" -F name='swimming-pool' -F algorithm='round_robin' -F load_balancer='15264769-ac69-4809-a8e4-4d73f8f92496' -F protocol='tcp' https://api.cloudscale.ch/v1/load-balancers/pools

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/pools/3d41b118-f95c-4897-ad74-2260fea783fc

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/pools/3d41b118-f95c-4897-ad74-2260fea783fc",
  "uuid": "3d41b118-f95c-4897-ad74-2260fea783fc",
  "name": "swimming-pool",
  "created_at": "2023-02-17T16:11:45.146723Z",
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "algorithm": "round_robin",
  "protocol": "tcp",
  "tags": {}
}

Update a Pool

PATCH /v1/load-balancers/pools/{uuid}

Update the properties of a load balancer pool.

Name	Type	Description
name	string	The display name of the pool.
tags	tags object	The tags assigned to the load balancer pool.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name='new-name' https://api.cloudscale.ch/v1/load-balancers/pools/3d41b118-f95c-4897-ad74-2260fea783fc

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Pool

DELETE /v1/load-balancers/pools/{uuid}

Delete a load balancer pool. Automatically deletes listeners and health monitors that are configured on this pool.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/load-balancers/pools/3d41b118-f95c-4897-ad74-2260fea783fc

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Load Balancer Pool Members

Manage load balancer pool members on the distributed compute platform. Load balancer pool members can be created, listed, modified and deleted.

List Pool Members

GET /v1/load-balancers/pools/{pool_uuid}/members?{query_string}

List all pool members in the specified load balancer pool.

Tag predicates can be used in the query_string to filter load balancer pool members by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool member.
name	string	The display name of the pool member.
enabled	boolean	Pool member will not receive traffic if `false`.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the pool member.
load_balancer	load balancer object	The load balancer of the pool member.
protocol_port	integer	The port to which actual traffic is sent.
monitor_port	integer	The port to which health monitor checks are sent. If not specified, `protocol_port` will be used.
address	string	The IP address to which traffic is sent.
subnet	subnet object	The subnet in a private network in which `address` is located. This value reflects the subnet as specified when creating the pool member and is not guaranteed to be suitable for correct operation.
monitor_status	string	The status of the pool's health monitor check for this member. A listener is required to ensure that the `monitor_status` is correctly reported. Can be `"up"`, `"down"`, `"changing"`, `"no_monitor"`, `"unknown"`.
tags	tags object	The tags assigned to the load balancer pool member.

Statuses

The status of a pool member indicates the result of the health monitor check for the member.

monitor_status	Description
`up`	The member is passing the health monitor check.
`down`	The member is failing the health monitor check.
`changing`	The member is being created or updated.
`no_monitor`	No health monitor is configured.
`unknown`	There are temporary internal issues in the zone of this load balancer.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/a7a88e66-0fc5-48c8-862a-ee5dff3ba6ef",
    "uuid": "a7a88e66-0fc5-48c8-862a-ee5dff3ba6ef",
    "name": "web-lb-pool-member-0",
    "enabled": true,
    "created_at": "2023-02-21T13:11:48.118903Z",
    "pool": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c",
      "uuid": "20a7eb11-3e17-4177-b46d-36e13b101d1c",
      "name": "web-lb-pool"
    },
    "load_balancer": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
      "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
      "name": "web-lb"
    },
    "protocol_port": 8080,
    "monitor_port": null,
    "address": "10.11.12.107",
    "subnet": {
      "href": "https://api.cloudscale.ch/v1/subnets/70d282ab-2a01-4abb-ada5-34e56a5a7eee",
      "uuid": "70d282ab-2a01-4abb-ada5-34e56a5a7eee",
      "cidr": "10.11.12.0/24"
    },
    "monitor_status": "up",
    "tags": {}
  }
]

Get a Pool Member

GET /v1/load-balancers/pools/{pool_uuid}/members/{uuid}

Get a load balancer pool member by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool member.
name	string	The display name of the pool member.
enabled	boolean	Pool member will not receive traffic if `false`.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the pool member.
load_balancer	load balancer object	The load balancer of the pool member.
protocol_port	integer	The port to which actual traffic is sent.
monitor_port	integer	The port to which health monitor checks are sent. If not specified, `protocol_port` will be used.
address	string	The IP address to which traffic is sent.
subnet	subnet object	The subnet in a private network in which `address` is located. This value reflects the subnet as specified when creating the pool member and is not guaranteed to be suitable for correct operation.
monitor_status	string	The status of the pool's health monitor check for this member. A listener is required to ensure that the `monitor_status` is correctly reported. Can be `"up"`, `"down"`, `"changing"`, `"no_monitor"`, `"unknown"`.
tags	tags object	The tags assigned to the load balancer pool member.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/a7a88e66-0fc5-48c8-862a-ee5dff3ba6ef

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/a7a88e66-0fc5-48c8-862a-ee5dff3ba6ef",
  "uuid": "a7a88e66-0fc5-48c8-862a-ee5dff3ba6ef",
  "name": "web-lb-pool-member-0",
  "enabled": true,
  "created_at": "2023-02-21T13:11:48.118903Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c",
    "uuid": "20a7eb11-3e17-4177-b46d-36e13b101d1c",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "protocol_port": 8080,
  "monitor_port": null,
  "address": "10.11.12.107",
  "subnet": {
    "href": "https://api.cloudscale.ch/v1/subnets/70d282ab-2a01-4abb-ada5-34e56a5a7eee",
    "uuid": "70d282ab-2a01-4abb-ada5-34e56a5a7eee",
    "cidr": "10.11.12.0/24"
  },
  "monitor_status": "up",
  "tags": {}
}

Create a Pool Member

POST /v1/load-balancers/pools/{pool_uuid}/members

Create a load balancer pool member with the specified attributes.

Name	Type	Description
name	string	The display name of the pool member.
enabled	boolean	Pool member will not receive traffic if `false`. Default is `true`.
protocol_port	integer	The port to which actual traffic is sent.
monitor_port	integer	The port to which health monitor checks are sent. If not specified, `protocol_port` will be used. Default is `null`.
address	string	The IP address to which traffic is sent.
subnet	UUID	The subnet of the address must be specified here.
tags	tags object	The tags assigned to the load balancer pool member. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the pool member.
name	string	The display name of the pool member.
enabled	boolean	Pool member will not receive traffic if `false`.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the pool member.
load_balancer	load balancer object	The load balancer of the pool member.
protocol_port	integer	The port to which actual traffic is sent.
monitor_port	integer	The port to which health monitor checks are sent. If not specified, `protocol_port` will be used.
address	string	The IP address to which traffic is sent.
subnet	subnet object	The subnet in a private network in which `address` is located. This value reflects the subnet as specified when creating the pool member and is not guaranteed to be suitable for correct operation.
monitor_status	string	The status of the pool's health monitor check for this member. A listener is required to ensure that the `monitor_status` is correctly reported. Can be `"up"`, `"down"`, `"changing"`, `"no_monitor"`, `"unknown"`.
tags	tags object	The tags assigned to the load balancer pool member.

Request

$ curl -i -H "$AUTH_HEADER" -F name='new-member' -F protocol_port='8080' -F address='10.11.12.3' -F subnet='70d282ab-2a01-4abb-ada5-34e56a5a7eee' https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/b9991773-857d-47f6-b20b-0a03709529a9

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/b9991773-857d-47f6-b20b-0a03709529a9",
  "uuid": "b9991773-857d-47f6-b20b-0a03709529a9",
  "name": "new-member",
  "enabled": true,
  "created_at": "2023-02-21T15:42:50.972189Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c",
    "uuid": "20a7eb11-3e17-4177-b46d-36e13b101d1c",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "protocol_port": 8080,
  "monitor_port": null,
  "address": "10.11.12.3",
  "subnet": {
    "href": "https://api.cloudscale.ch/v1/subnets/70d282ab-2a01-4abb-ada5-34e56a5a7eee",
    "uuid": "70d282ab-2a01-4abb-ada5-34e56a5a7eee",
    "cidr": "10.11.12.0/24"
  },
  "monitor_status": "down",
  "tags": {}
}

Update a Pool Member

PATCH /v1/load-balancers/pools/{pool_uuid}/members/{uuid}

Update the properties of a load balancer pool member.

Name	Type	Description
name	string	The display name of the pool member.
enabled	boolean	Pool member will not receive traffic if `false`.
tags	tags object	The tags assigned to the load balancer pool member.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name='new-name' https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/b9991773-857d-47f6-b20b-0a03709529a9

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Pool Member

DELETE /v1/load-balancers/pools/{pool_uuid}/members/{uuid}

Delete a load balancer pool member.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/load-balancers/pools/20a7eb11-3e17-4177-b46d-36e13b101d1c/members/b9991773-857d-47f6-b20b-0a03709529a9

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Load Balancer Listeners

Manage load balancer listeners on the distributed compute platform. Load balancer listeners can be created, listed, modified and deleted.

The protocols supported by load balancer listeners are detailed in the following table.

Listener Protocols

The protocol configured on the listener defines how traffic is received from clients.

Protocol	Description
`tcp`	TCP

List Listeners

GET /v1/load-balancers/listeners?{query_string}

List all load balancer listeners.

Tag predicates can be used in the query_string to filter load balancer listeners by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the listener.
name	string	The display name of the listener.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the listener. Can currently not be `null`.
load_balancer	load balancer object	The load balancer of the listener.
protocol	string	The protocol used for receiving traffic. Currently the following protocols are supported: `"tcp"`.
protocol_port	integer	The port on which traffic is received.
allowed_cidrs	list of strings	Restrict the allowed source IPs for this listener. `[]` means that any source IP is allowed. If the list is non-empty, traffic from source IPs not included is denied.
timeout_client_data_ms	integer	Client inactivity timeout in milliseconds.
timeout_member_connect_ms	integer	Pool member connection timeout in milliseconds.
timeout_member_data_ms	integer	Pool member inactivity timeout in milliseconds.
tags	tags object	The tags assigned to the load balancer listener.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/listeners

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/load-balancers/listeners/ed900813-0270-4ddb-ad90-6a7690edfb3f",
    "uuid": "ed900813-0270-4ddb-ad90-6a7690edfb3f",
    "name": "web-lb-listener",
    "created_at": "2023-02-22T09:55:44.431932Z",
    "pool": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
      "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
      "name": "web-lb-pool"
    },
    "load_balancer": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
      "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
      "name": "web-lb"
    },
    "protocol": "tcp",
    "protocol_port": 80,
    "allowed_cidrs": [],
    "timeout_client_data_ms": 50000,
    "timeout_member_connect_ms": 5000,
    "timeout_member_data_ms": 50000,
    "timeout_tcp_inspect_ms": 0,
    "tags": {}
  }
]

Get a Listener

GET /v1/load-balancers/listeners/{uuid}

Get a load balancer listener by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the listener.
name	string	The display name of the listener.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the listener. Can currently not be `null`.
load_balancer	load balancer object	The load balancer of the listener.
protocol	string	The protocol used for receiving traffic. Currently the following protocols are supported: `"tcp"`.
protocol_port	integer	The port on which traffic is received.
allowed_cidrs	list of strings	Restrict the allowed source IPs for this listener. `[]` means that any source IP is allowed. If the list is non-empty, traffic from source IPs not included is denied.
timeout_client_data_ms	integer	Client inactivity timeout in milliseconds.
timeout_member_connect_ms	integer	Pool member connection timeout in milliseconds.
timeout_member_data_ms	integer	Pool member inactivity timeout in milliseconds.
tags	tags object	The tags assigned to the load balancer listener.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/listeners/ed900813-0270-4ddb-ad90-6a7690edfb3f

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/listeners/ed900813-0270-4ddb-ad90-6a7690edfb3f",
  "uuid": "ed900813-0270-4ddb-ad90-6a7690edfb3f",
  "name": "web-lb-listener",
  "created_at": "2023-02-22T09:55:44.431932Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "protocol": "tcp",
  "protocol_port": 80,
  "allowed_cidrs": [],
  "timeout_client_data_ms": 50000,
  "timeout_member_connect_ms": 5000,
  "timeout_member_data_ms": 50000,
  "timeout_tcp_inspect_ms": 0,
  "tags": {}
}

Create a Listener

POST /v1/load-balancers/listeners

Create a load balancer listener with the specified attributes.

Name	Type	Description
name	string	The display name of the listener.
pool	UUID	The pool of the listener. Can currently not be `null`.
protocol	string	The protocol used for receiving traffic. Currently the following protocols are supported: `"tcp"`.
protocol_port	integer	The port on which traffic is received.
allowed_cidrs	list of strings	Restrict the allowed source IPs for this listener. `[]` means that any source IP is allowed. If the list is non-empty, traffic from source IPs not included is denied. Default is `[]`.
timeout_client_data_ms	integer	Client inactivity timeout in milliseconds. Default is `50000`.
timeout_member_connect_ms	integer	Pool member connection timeout in milliseconds. Default is `5000`.
timeout_member_data_ms	integer	Pool member inactivity timeout in milliseconds. Default is `50000`.
tags	tags object	The tags assigned to the load balancer listener. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the listener.
name	string	The display name of the listener.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the listener. Can currently not be `null`.
load_balancer	load balancer object	The load balancer of the listener.
protocol	string	The protocol used for receiving traffic. Currently the following protocols are supported: `"tcp"`.
protocol_port	integer	The port on which traffic is received.
allowed_cidrs	list of strings	Restrict the allowed source IPs for this listener. `[]` means that any source IP is allowed. If the list is non-empty, traffic from source IPs not included is denied.
timeout_client_data_ms	integer	Client inactivity timeout in milliseconds.
timeout_member_connect_ms	integer	Pool member connection timeout in milliseconds.
timeout_member_data_ms	integer	Pool member inactivity timeout in milliseconds.
tags	tags object	The tags assigned to the load balancer listener.

Request

$ curl -i -H "$AUTH_HEADER" -F name='new-listener' -F pool='618a6cc8-d757-4fab-aa10-d49dc47e667b' -F protocol='tcp' -F protocol_port=1337 https://api.cloudscale.ch/v1/load-balancers/listeners

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/listeners/9fa91f17-fdb4-431f-8a59-78473f64e661

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/listeners/9fa91f17-fdb4-431f-8a59-78473f64e661",
  "uuid": "9fa91f17-fdb4-431f-8a59-78473f64e661",
  "name": "new-listener",
  "created_at": "2023-02-22T10:01:48.839090Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "protocol": "tcp",
  "protocol_port": 1337,
  "allowed_cidrs": [],
  "timeout_client_data_ms": 50000,
  "timeout_member_connect_ms": 5000,
  "timeout_member_data_ms": 50000,
  "timeout_tcp_inspect_ms": 0,
  "tags": {}
}

Using `allowed_cidrs`

The use of lists in requests with Content-Type: multipart/form-data is not supported. Use Content-Type: application/json instead.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
    --data '{"name": "new-listener", "pool": "618a6cc8-d757-4fab-aa10-d49dc47e667b", "protocol": "tcp", "protocol_port": 1338, "allowed_cidrs": ["192.168.3.0/24", "2001:db8:85a3:8d3::/64"]}' https://api.cloudscale.ch/v1/load-balancers/listeners

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/listeners/9fa91f17-fdb4-431f-8a59-78473f64e661

{
  /* See first example of this section for the rest of the response. */
  "allowed_cidrs": [
    "192.168.3.0/24",
    "2001:db8:85a3:8d3::/64"
  ],
}

Update a Listener

PATCH /v1/load-balancers/listeners/{uuid}

Update the properties of a load balancer listener.

Name	Type	Description
name	string	The display name of the listener.
allowed_cidrs	list of strings	Restrict the allowed source IPs for this listener. `[]` means that any source IP is allowed. If the list is non-empty, traffic from source IPs not included is denied.
timeout_client_data_ms	integer	Client inactivity timeout in milliseconds.
timeout_member_connect_ms	integer	Pool member connection timeout in milliseconds.
timeout_member_data_ms	integer	Pool member inactivity timeout in milliseconds.
tags	tags object	The tags assigned to the load balancer listener.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F name='new-name' https://api.cloudscale.ch/v1/load-balancers/listeners/ed900813-0270-4ddb-ad90-6a7690edfb3f

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Listener

DELETE /v1/load-balancers/listeners/{uuid}

Delete a load balancer listener.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/load-balancers/listeners/3d41b118-f95c-4897-ad74-2260fea783fc

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Load Balancer Health Monitors

Manage load balancer health monitors on the distributed compute platform. Load balancer health monitors can be created, listed, modified and deleted.

Important Note

Health monitors only become effective once a listener is configured for the same pool. Without a listener, health monitors are not able to correctly report the status of pool members.

Health Monitor Types

The type configured on the health monitor defines which mechanism is used to check the health of pool members.

Type	Description
`ping`	Verify pool member health by sending an ICMP echo request.
`tcp`	Verify pool member health by opening and closing a TCP connection without sending any data.
`http`	Verify pool member health by sending an HTTP request. The HTTP method, URL used and expected status codes can be configured using the http attribute.
`https`	HTTPS health monitors are similar to HTTP health monitors. (If pool members require a client TLS certificate, however, checks will fail; TLS-HELLO is recommended in this case.)
`tls-hello`	Verify pool member health by checking the response to TLS client hello messages.

List Health Monitors

GET /v1/load-balancers/health-monitors?{query_string}

List all load balancer health monitors.

Tag predicates can be used in the query_string to filter load balancer health monitors by tag.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the health monitor.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the health monitor.
load_balancer	load balancer object	The load balancer of the health monitor.
delay_s	integer	The delay between two successive checks in seconds.
timeout_s	integer	The maximum time allowed for an individual check in seconds.
up_threshold	integer	The number of checks that need to be successful before the `monitor_status` of a pool member changes to `"up"`.
down_threshold	integer	The number of checks that need to fail before the `monitor_status` of a pool member changes to `"down"`.
type	string	The type of the health monitor. Currently the following mechanisms are supported: `"ping"`, `"tcp"`, `"http"`, `"https"`, `"tls-hello"`.
http	http options object	Advanced options for health monitors with type `"http"` or `"https"`.
tags	tags object	The tags assigned to the load balancer health monitor.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/health-monitors

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

[
  {
    "href": "https://api.cloudscale.ch/v1/load-balancers/health-monitors/ee4952d4-2eba-4dec-8957-7911b3ce245b",
    "uuid": "ee4952d4-2eba-4dec-8957-7911b3ce245b",
    "created_at": "2023-02-22T09:55:38.285018Z",
    "pool": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
      "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
      "name": "web-lb-pool"
    },
    "load_balancer": {
      "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
      "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
      "name": "web-lb"
    },
    "delay_s": 2,
    "timeout_s": 1,
    "up_threshold": 2,
    "down_threshold": 3,
    "type": "http",
    "http": {
      "expected_codes": [
        "200"
      ],
      "method": "GET",
      "url_path": "/",
      "version": "1.0",
      "host": null
    },
    "tags": {}
  }
]

Get a Health Monitor

GET /v1/load-balancers/health-monitors/{uuid}

Get a load balancer health monitor by its UUID.

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the health monitor.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the health monitor.
load_balancer	load balancer object	The load balancer of the health monitor.
delay_s	integer	The delay between two successive checks in seconds.
timeout_s	integer	The maximum time allowed for an individual check in seconds.
up_threshold	integer	The number of checks that need to be successful before the `monitor_status` of a pool member changes to `"up"`.
down_threshold	integer	The number of checks that need to fail before the `monitor_status` of a pool member changes to `"down"`.
type	string	The type of the health monitor. Currently the following mechanisms are supported: `"ping"`, `"tcp"`, `"http"`, `"https"`, `"tls-hello"`.
http	http options object	Advanced options for health monitors with type `"http"` or `"https"`.
tags	tags object	The tags assigned to the load balancer health monitor.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/load-balancers/health-monitors/ee4952d4-2eba-4dec-8957-7911b3ce245b

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/health-monitors/ee4952d4-2eba-4dec-8957-7911b3ce245b",
  "uuid": "ee4952d4-2eba-4dec-8957-7911b3ce245b",
  "created_at": "2023-02-22T09:55:38.285018Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "delay_s": 2,
  "timeout_s": 1,
  "up_threshold": 2,
  "down_threshold": 3,
  "type": "http",
  "http": {
    "expected_codes": [
      "200"
    ],
    "method": "GET",
    "url_path": "/",
    "version": "1.0",
    "host": null
  },
  "tags": {}
}

Create a Health Monitor

POST /v1/load-balancers/health-monitors

Create a load balancer health monitor with the specified attributes.

Name	Type	Description
pool	UUID	The pool of the health monitor.
delay_s	integer	The delay between two successive checks in seconds. Default is `2`.
timeout_s	integer	The maximum time allowed for an individual check in seconds. Default is `1`.
up_threshold	integer	The number of checks that need to be successful before the `monitor_status` of a pool member changes to `"up"`. Default is `2`.
down_threshold	integer	The number of checks that need to fail before the `monitor_status` of a pool member changes to `"down"`. Default is `3`.
type	string	The type of the health monitor. Currently the following mechanisms are supported: `"ping"`, `"tcp"`, `"http"`, `"https"`, `"tls-hello"`.
http	http options object	Advanced options for health monitors with type `"http"` or `"https"`. Default is `null`.
tags	tags object	The tags assigned to the load balancer health monitor. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
uuid	UUID	The unique identifier of the health monitor.
created_at	datetime	The creation date and time of the resource.
pool	load balancer pool object	The pool of the health monitor.
load_balancer	load balancer object	The load balancer of the health monitor.
delay_s	integer	The delay between two successive checks in seconds.
timeout_s	integer	The maximum time allowed for an individual check in seconds.
up_threshold	integer	The number of checks that need to be successful before the `monitor_status` of a pool member changes to `"up"`.
down_threshold	integer	The number of checks that need to fail before the `monitor_status` of a pool member changes to `"down"`.
type	string	The type of the health monitor. Currently the following mechanisms are supported: `"ping"`, `"tcp"`, `"http"`, `"https"`, `"tls-hello"`.
http	http options object	Advanced options for health monitors with type `"http"` or `"https"`.
tags	tags object	The tags assigned to the load balancer health monitor.

`http` Attribute Specification

The http attribute holds the advanced configuration parameters for health monitors of type http and https. The following table gives an overview of the schema of the http attribute. See also the Using HTTP Options example.

Name	Type	Description
expected_codes	list of strings	The HTTP status codes allowed for a check to be considered successful. Can either be a list of status codes, for example `["200", "202"]`, or a list containing a single range, for example `["200-204"]`. Default is `["200"]`.
method	string	The HTTP method used for the check. Currently the following methods are supported: `"CONNECT"`, `"DELETE"`, `"GET"`, `"HEAD"`, `"OPTIONS"`, `"PATCH"`, `"POST"`, `"PUT"`, `"TRACE"`. Default is `"GET"`.
url_path	string	The URL used for the check. Default is `"/"`.
version	string	The HTTP version used for the check. Currently the following methods are supported: `"1.0"`, `"1.1"`. Default is `"1.1"`.
host	string	The server name in the HTTP `Host:` header used for the check. Requires `version` to be set to `"1.1"`. Default is `null`.

Request

$ curl -i -H "$AUTH_HEADER" -F pool='618a6cc8-d757-4fab-aa10-d49dc47e667b' -F type='tcp'  https://api.cloudscale.ch/v1/load-balancers/health-monitors

Response

HTTP/1.0 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/health-monitors/52ea5829-d188-48e7-81fa-b10ca5b9b993

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/health-monitors/52ea5829-d188-48e7-81fa-b10ca5b9b993",
  "uuid": "52ea5829-d188-48e7-81fa-b10ca5b9b993",
  "created_at": "2023-02-22T12:08:39.584905Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "delay_s": 2,
  "timeout_s": 1,
  "up_threshold": 2,
  "down_threshold": 3,
  "type": "tcp",
  "http": null,
  "tags": {}
}

Using HTTP Options

This creates a load balancer health monitor that sends HTTP probes.

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" \
    --data '{"pool": "618a6cc8-d757-4fab-aa10-d49dc47e667b", "type": "http", "http": {"expected_codes": ["200", "418"]}}' https://api.cloudscale.ch/v1/load-balancers/health-monitors

HTTP/1.0 201 Created
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/load-balancers/health-monitors/60c7d526-f09f-4582-b106-44d4b70d03a6

{
  "href": "https://api.cloudscale.ch/v1/load-balancers/health-monitors/60c7d526-f09f-4582-b106-44d4b70d03a6",
  "uuid": "60c7d526-f09f-4582-b106-44d4b70d03a6",
  "created_at": "2023-02-22T12:17:12.315518Z",
  "pool": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/pools/618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "uuid": "618a6cc8-d757-4fab-aa10-d49dc47e667b",
    "name": "web-lb-pool"
  },
  "load_balancer": {
    "href": "https://api.cloudscale.ch/v1/load-balancers/15264769-ac69-4809-a8e4-4d73f8f92496",
    "uuid": "15264769-ac69-4809-a8e4-4d73f8f92496",
    "name": "web-lb"
  },
  "delay_s": 2,
  "timeout_s": 1,
  "up_threshold": 2,
  "down_threshold": 3,
  "type": "http",
  "http": {
    "expected_codes": [
      "200",
      "418"
    ],
    "method": "GET",
    "url_path": "/",
    "version": "1.1",
    "host": null
  },
  "tags": {}
}

Update a Health Monitor

PATCH /v1/load-balancers/health-monitors/{uuid}

Update the properties of a load balancer health monitor.

Name	Type	Description
delay_s	integer	The delay between two successive checks in seconds.
timeout_s	integer	The maximum time allowed for an individual check in seconds.
up_threshold	integer	The number of checks that need to be successful before the `monitor_status` of a pool member changes to `"up"`.
down_threshold	integer	The number of checks that need to fail before the `monitor_status` of a pool member changes to `"down"`.
http	http options object	Advanced options for health monitors with type `"http"` or `"https"`.
tags	tags object	The tags assigned to the load balancer health monitor.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F delay_s=3 https://api.cloudscale.ch/v1/load-balancers/health-monitors/ee4952d4-2eba-4dec-8957-7911b3ce245b

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Delete a Health Monitor

DELETE /v1/load-balancers/health-monitors/{uuid}

Delete a load balancer health monitor.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/load-balancers/health-monitors/ee4952d4-2eba-4dec-8957-7911b3ce245b

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Objects Users

Objects Users are global resources

Manage users of the S3-compatible object storage.

List Objects Users

GET /v1/objects-users?{query_string}

List all objects users.

Tag predicates can be used in the query_string to filter objects users by tag.

Name	Type	Description
href	URL	The URL of the resource.
id	string	The unique identifier of the objects user.
display_name	string	The display name of the objects user.
keys	list of key objects	A list of key objects containing the access and secret keys associated with the objects user. The secret keys are set to `null` when accessing the API with a read-only token.
tags	tags object	The tags assigned to the objects user.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/objects-users

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

[
  {
    "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
    "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
    "display_name": "alan",
    "keys": [
      {
        "access_key": "0ZTAIBKSGYBRHQ09G11W",
        "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
      }
    ],
    "tags": {}
  }
]

Get an Objects User

GET /v1/objects-users/{id}

Get an objects user by its ID.

Name	Type	Description
href	URL	The URL of the resource.
id	string	The unique identifier of the objects user.
display_name	string	The display name of the objects user.
keys	list of key objects	A list of key objects containing the access and secret keys associated with the objects user. The secret keys are set to `null` when accessing the API with a read-only token.
tags	tags object	The tags assigned to the objects user.

Request

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "display_name": "alan",
  "keys": [
    {
      "access_key": "0ZTAIBKSGYBRHQ09G11W",
      "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
    }
  ],
  "tags": {}
}

Create an Objects User

POST /v1/objects-users

Create an objects user with the specified attributes.

Name	Type	Description
display_name	string	The display name of the objects user.
tags	tags object	The tags assigned to the objects user. Default is `{}`.

The returned object contains the following information:

Name	Type	Description
href	URL	The URL of the resource.
id	string	The unique identifier of the objects user.
display_name	string	The display name of the objects user.
keys	list of key objects	A list of key objects containing the access and secret keys associated with the objects user. The secret keys are set to `null` when accessing the API with a read-only token.
tags	tags object	The tags assigned to the objects user.

Request

$ curl -i -H "$AUTH_HEADER" -F display_name=alan https://api.cloudscale.ch/v1/objects-users

Response

HTTP/1.0 201 Created
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15
Allow: GET, POST, HEAD, OPTIONS

{
  "href": "https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "id": "6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15",
  "display_name": "alan",
  "keys": [
    {
      "access_key": "0ZTAIBKSGYBRHQ09G11W",
      "secret_key": "bn2ufcwbIa0ARLc5CLRSlVaCfFxPHOpHmjKiH34T"
    }
  ],
  "tags": {}
}

Update an Objects User

PATCH /v1/objects-users/{id}

Update the properties of an objects user.

Name	Type	Description
display_name	string	The display name of the objects user.
tags	tags object	The tags assigned to the objects user.

Important Note

Attributes can only be updated one at a time to avoid inconsistencies.

Request

$ curl -i -H "$AUTH_HEADER" -X PATCH -F display_name=turing https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 204 No Content
Content-Type: application/json
Allow: GET, PATCH, DELETE, HEAD, OPTIONS

Delete an Objects User

DELETE /v1/objects-users/{id}

Delete an objects user.

Most Common Errors

There are still buckets associated with the objects user. Only objects users without buckets can be deleted.

Request

$ curl -i -H "$AUTH_HEADER" -X DELETE https://api.cloudscale.ch/v1/objects-users/6fe39134bf4178747eebc429f82cfafdd08891d4279d0d899bc4012db1db6a15

Response

HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Metrics

The metrics end-point can be used to collect usage information on cloud resources. We currently provide metrics for the following resource types:

`resource_type`	Description
`buckets`	Metrics for buckets on our S3-compatible object storage.

Get Metrics

GET /v1/metrics/{resource_type}?{query_string}

Get the metrics for subjects of resource_type (see all available types here). Use the query_string to define the metrics time range and filter the subjects included. The parameters that can be used in the query_string are detailed in the table below.

When forming complex expressions using multiple parameters, the following rules apply:

First, parameters of the same type are combined using OR operators.
Then, parameters of different types are combined using AND operators.

`resource_type`	Query Parameter Name	Type	Allowed Multiplicities	Description
all	start	ISO 8601 date	1	Start of the metrics time range. 00:00:00 local time in Europe/Zurich time zone on the date specified will be used.
all	end	ISO 8601 date	1	End of the metrics time range. 24:00:00 local time in Europe/Zurich time zone on the date specified (i.e. including that day) will be used.
`buckets`	bucket_name	string	0...*	Filter subjects by bucket name. Can be repeated in order to search for multiple buckets.
`buckets`	objects_user_id	string	0...*	Filter subjects by the bucket owner's unique identifier. Can be repeated in order to search for multiple bucket owners.

The returned object contains the following information:

Name	Type	Description
start	datetime	Start of the metrics time range in ISO 8601 date format (timezone is UTC).
end	datetime	End of the metrics time range in ISO 8601 date format (timezone is UTC).
data	list of data objects	A list of data objects, one for each subject of the given `resource_type` matching your query. Each data object has a `subject` and a `time_series` attribute. See below for details.

The returned subject objects uniquely identify the metrics subject. The attributes of the subject objects depend on the resource_type:

`resource_type`	Name	Type	Description
`buckets`	name	string	The name of the bucket.
`buckets`	objects_user_id	string	The unique identifier of the objects user owning the bucket.

The returned time_series are lists of objects describing the intervals in your metrics range. Currently, there is always a single interval equal to the metrics time range returned. The interval object has the start, end and usage attributes. The attributes of the usage objects depend on the resource_type:

`resource_type`	Name	Type	Description
`buckets`	requests	integer	The number of requests made in the interval.
`buckets`	object_count	integer	The average object count in the interval. For time ranges in the future, including the remaining hours of the current day, the object count is assumed to be zero when calculating the average.
`buckets`	storage_bytes	integer	The average amount of data stored in the interval. For time ranges in the future, including the remaining hours of the current day, the amount of data stored is assumed to be zero when calculating the average.
`buckets`	received_bytes	integer	The total amount of data received in the interval.
`buckets`	sent_bytes	integer	The total amount of data sent in the interval.

Request

$ curl -i -H "$AUTH_HEADER" "https://api.cloudscale.ch/v1/metrics/buckets?start=2019-03-19&end=2019-03-20"

Response

HTTP/1.0 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
  "start": "2019-03-18T23:00:00Z",
  "end": "2019-03-20T23:00:00Z",
  "data": [
    {
      "subject": {
        "name": "Carmichael",
        "objects_user_id": "2b44ef90ff15f010dc013f8d32612e07d7734e5f5581d0c94be56780b0dcd58a"
      },
      "time_series": [
        {
          "start": "2019-03-18T23:00:00Z",
          "end": "2019-03-20T23:00:00Z",
          "usage": {
            "requests": 561,
            "object_count": 1105,
            "storage_bytes": 1729,
            "received_bytes": 2465,
            "sent_bytes": 2821
          }
        }
      ]
    },
    {
      "subject": {
        "name": "StellaOctangula",
        "objects_user_id": "2b44ef90ff15f010dc013f8d32612e07d7734e5f5581d0c94be56780b0dcd58a"
      },
      "time_series": [
        {
          "start": "2019-03-18T23:00:00Z",
          "end": "2019-03-20T23:00:00Z",
          "usage": {
            "requests": 1,
            "object_count": 14,
            "storage_bytes": 51,
            "received_bytes": 124,
            "sent_bytes": 426
          }
        }
      ]
    }
  ]
}

Overview

Introduction

Tools

Authentication

HTTP Requests

HTTP Response Codes

200 OK

201 Created

204 No Content

HTTP Error Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

405 Method Not Allowed

Tags

About Tags

Taggable Resource Types

Working with Tags

Retrieving Tags

Setting Tags

Filtering Resources by Tag

Regions and Zones

List Regions

Request

Response

Servers

List Servers

Request

Response

Get a Server

Request

Response

Create a Server

Most Common Errors

interfaces Attribute Specification

Creating a Public Network Interface

Creating a Private Network Interface

Allocate a Random IP Address from DHCP Range

Use a Specific IP Address from Subnet Range

Do not Assign an Address

Request

Response

Using Anti-Affinity

Using Additional Volumes

Using Additional Interfaces

Reboot a Server

Request

Response

Start a Server

Request

Response

Stop a Server

Request

Response

Update a Server

Important Notes

Changing Flavors

Request

Response

Modifying Interfaces

Request

Response

Delete a Server

Important Notes

Request

Response

Server Groups

List Server Groups

Request

Response

Get a Server Group

Request

Response

Create a Server Group

Request

Response

Update a Server Group

Important Note

Request

`interfaces` Attribute Specification