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:

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:

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.

Tags

Tags allow you to assign custom metadata to resources (such as servers or Floating IPs).

About Tags

Tags are the preferred way if you want to e.g. group your resources by environment, project or customer, or simply add some plain text information to a resource. Tags do not have any semantic meaning to the Cloud Control Panel or cloudscale API.

A tag consists of two strings denoted as key and value. The following limitations apply:

Taggable Resource Types

Currently, the following resource types support tags:

Working with Tags

In principle, tags can be operated on just like any other resource attribute.

Retrieving Tags

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/{taggable_resource_type}/5287965b-6248-4aec-85ad-52db73e31a76
HTTP/1.0 200 OK
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json
Location: https://api.cloudscale.ch/v1/{taggable_resource_type}/5287965b-6248-4aec-85ad-52db73e31a76

{
  /* other attributes */
  "tags": {
    "project": "gemini",
    "status": "launched"
  }
}

When retrieving a resource the response includes a tags attribute. The value is set to an object containing the tag key and value pairs. This object is referred to as tags object:

{
  /* ... */
  "tags": {
    "key": "value",
    /* ... */
  }
}

Setting Tags

$ curl -i -H "$AUTH_HEADER" -H "Content-Type: application/json" -X PATCH --data '{ "tags": { "project": "gemini", "status": "completed" }}' https://api.cloudscale.ch/v1/{taggable_resource_type}/5287965b-6248-4aec-85ad-52db73e31a76
HTTP/1.0 204 No Content
Allow: GET, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

Tags can be updated by sending an HTTP PATCH request containing the updated tags object to the resource URL. Note that all tags which should not be modified must be respecified. If you pass an empty object ({}) all tags are removed.

Filtering Resources by Tag

$ curl -i -H "$AUTH_HEADER" https://api.cloudscale.ch/v1/server-groups?tag:project=apollo
HTTP/1.0 200 OK
Content-Type: application/json
Allow: GET, POST, HEAD, OPTIONS

[
  {
    /* other attributes */
    "tags": {
      "project": "apollo",
      "status": "completed"
    }
  }
]

When listing resources of a taggable type, a filter criterion can be specified in the HTTP GET request's query string to filter resources by their tag. A filter criterion can consist of the following filter clauses:

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.

Currently, a filter criterion can consist of at most one filter clause. More sophisticated criteria and additional filter clauses might be supported in the future.

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:

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 trueor 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 (10243) of the new server. Default is 10.

bulk_volume_size_gb integer

The size of the bulk volume in GiB (10243) 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:

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 (10243) 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-23.05 Arch 23.05
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 38 (stable)
flatcar-stable Flatcar 3510.2.6 (stable)
opnsense-23.7 OPNsense 23.7
pfsense-2.7.0 pfSense 2.7.0
ubuntu-18.04 Ubuntu 18.04 LTS
ubuntu-20.04 Ubuntu 20.04 LTS
ubuntu-22.04 Ubuntu 22.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 (10243).

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 (10243).

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

Deprecated: this field no longer needs to be specified and will be ignored. The image format is detected automatically. 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:

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 (10243).

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 (10243).

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 (10243).

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 (10243).

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 (10243).

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:

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 new Floating IP. By default, a Floating IP without a next hop is created.

load_balancer UUID

The destination load balancer of the new Floating IP. By default, a Floating IP without a next hop is created.

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 new Floating IP. By default, a Floating IP without a next hop is created.

load_balancer UUID

The destination load balancer of the new Floating IP. By default, a Floating IP without a next hop is created.

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:

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
          }
        }
      ]
    }
  ]
}