API

Kubernetes

Kubernetes clusters are a number of instances on the Civo cloud platform running the Kubernetes cloud orchestration platform.


Create a cluster

Any user can create a cluster, providing it's within their quota. The size of the instances is from a list of sizes.

Clusters are created by sending a POST request to https://api.civo.com/v2/kubernetes/clusters.

Request

The following parameter(s) should be sent along with the request:

Name Description
name (required) a name for your cluster, must be unique within your account
region (required) the identifier for the region, from the current region list
network_id (required) network ID for the network in which you wish to install the cluster
cni_plugin (optional) You can use a custom CNI in the cluster. You can select between flannel and cilium. By default, if the field is not set, flannel will be used.
pools (optional) the desired state of node pools in the cluster as a JSON array. If provided, create pools and nodes in those pools to match to match the amount provided. Each pool is a JSON object with id of the pool (must be unique across pools), size (immutable once a pool is created), from the available sizes and count of nodes. E.g.:
[
  {
	"id": "abc-123",
	"size": "g4s.kube.medium",
	"count": 3
  },
  {
	"id": "def-456",
	"size": "g4s.kube.large",
	"count": 3
  }
]
kubernetes_version (optional) the version of K3s to install (default is the latest currently available)
tags (optional) a space separated list of tags, to be used freely as required
instance_firewall (optional) an existing firewall ID. If you set this as empty, then you must set firewall_rule
firewall_rule (optional) a semi-colon separated list of new firewall rules to be created. Within a firewall rule, you can use comma separator for multiple ports to have same CIDR. Valid formats:
  • PORT[-PORT][:IP_OR_CIDR][;...]
  • PORT[,PORT...][:IP_OR_CIDR][;...]
  • all
So the following would all be valid:
  • 443;80;6443
  • 3000-3100:10.0.0.0/16
  • 443,80,6443:0.0.0.0/0;8080:1.2.3.4
  • all
If all, it means open all ports as usual (except for the UDP VXLan port). Otherwise it's a semi-colon separated list of start_port with an optional -end_port and :CIDR (which may be a plain IP - in which case we will append /32 for it or a full CIDR notation containing a / and number). When there is no plain IP or CIDR notation is provided, we will set it to 0.0.0.0/0.
applications (optional) a comma separated list of applications to install. Spaces within application names are fine, but shouldn't be either side of the comma. If you want to remove a default installed application, prefix it with a "-", e.g. -traefik. For application that supports plan, you can use "application_name:plan format, e.g. MariaDB:5GB or Linkerd:Linkerd & Jaeger.

Response

The response is a JSON object that describes the initial setup of the cluster, future calls to get clusters may return more information (as underlying nodes are created, applications are installed, etc). The only difference in the details sent in is that instead of applications, you receive an installed_applications object, which has the name of the application, post_install content, etc. The configuration object of each application is a simple key/value listing of the configuration applied to the application, e.g. plan size, randomly generated passwords, etc.

{
    "id": "2843e46e-7f87-4c8b-864e-1e85505ee70b",
    "name": "APIcreationtest",
    "version": "1.22.2-k3s1",
    "status": "BUILDING",
    "ready": false,
    "num_target_nodes": 1,
    "target_nodes_size": "g4s.kube.small",
    "built_at": "0001-01-01T00:00:00Z",
    "kubernetes_version": "1.22.2-k3s1",
    "api_endpoint": "https://:6443",
    "dns_entry": "2843e46e-7f87-4c8b-864e-1e85505ee70b.k8s.civo.com",
    "created_at": "2022-03-29T14:24:41Z",
    "master_ip": "",
    "pools": null,
    "required_pools": [
        {
            "id": "1324f075-59ae-41f4-9914-28a913a7198e",
            "size": "g4s.kube.small",
            "count": 1
        }
    ],
    "firewall_id": "8a78773c-9dd1-43c0-8a8a-8864cc1cf14f",
    "master_ipv6": "",
    "network_id": "c926e021-2897-48de-9e3a-2bbb439c546a",
    "namespace": "cust-616eb954-808d-default",
    "size": "g4s.kube.small",
    "count": 0,
    "kubeconfig": null,
    "instances": null,
    "installed_applications": null,
    "ccm_installed": "true"
}

Example of creating a Kubernetes cluster

curl --location --request POST -H "Authorization: bearer 12345" -H 'Content-Type: application/json' \
  https://api.civo.com/v2/kubernetes/clusters \
  --data-raw '{
    "pools":[
      {
        "id": "abc-123",
        "size": "g4s.kube.medium",
        "count": 1
      }
    ],
    "network_id": "52b22474-a16e-15c1-66d2-6f4c341cee70",
    "region": "lon1",
    "name": "mycluster",
    "instance_firewall": "71b22474-a16e-35c1-66d2-8f4c341cee70",
    "firewall_rule": "443"
  }'
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/kubernetes/clusters',
  {
    body: JSON.stringify({
      name: "mycluster",
      region: "lon1"
      network_id: "52b22474-a16e-15c1-66d2-6f4c341cee70",
      instance_firewall: "72b22484-a16e-15c1-66d2-3f4c341cee90",
      firewall_rule: [],
      applications: "cert-manager",
      pools: [
         {
            "id": "abc-123",
            "size": "g4s.kube.medium",
            "count": 1
        }
      ]
    })
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/json'
}

request.body = JSON.dump({
  "name": "mycluster",
  "region": "lon1",
  "network_id": "52b22474-a16e-15c1-66d2-6f4c341cee70",
  "applications": "cert-manager",
  "pools": [
    {
      "id": "abc-123",
      "size": "g4s.kube.medium",
      "count": 1
    }
  ],
  "instance_firewall": "71b22474-a16e-35c1-66d2-8f4c341cee70"
})

resp, data = http.post('/v2/kubernetes/clusters', request, headers)

List clusters

A list of clusters accessible from an account is available by sending a GET request to https://api.civo.com/v2/kubernetes/clusters.

Request

This operation requires a region parameter (query string) containing the name of the region to search.

Response

The response is a paginated JSON array of cluster objects, like the JSON described for the create call above wrapped in:

{
  "page": 1,
  "per_page": null,
  "pages": 1,
  "items": [
    // ...
  ]
}

Example of listing clusters

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/kubernetes/clusters&region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/kubernetes/clusters',
  {
    form: {
      region: "NYC1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/kubernetes/clusters?region=NYC1', headers)

Retrieving a cluster

A single cluster's details are available by sending a GET request to https://api.civo.com/v2/kubernetes/clusters/:id.

Request

This request requires the ID parameter in the URL (query string) and a region parameter containing the name of the region to search.

Response

The response is a JSON object that describes the details for the cluster as described under the create call above.

Example of retrieving a cluster

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/kubernetes/clusters/12345
    
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/kubernetes/clusters/12345',
  {
    form: {
      region: "NYC1"
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/kubernetes/clusters/12345?region=NYC1', headers)

Updating a cluster

A user can update a cluster to rename it, scale the number of nodes in the cluster's node pools, add or remove node pools, upgrade to a newer version of K3s (downgrading is not supported) or install an application from the Marketplace.

Clusters are updated by sending a PUT request to https://api.civo.com/v2/kubernetes/clusters/:id.

Request

This operation requires one of the following parameters, plus a region parameter containing the name of the region where the cluster is running.

Name Description
name (optional) the cluster's new name
pools (optional) the desired state of node pools in the cluster as a JSON array. If provided, will be used to add or delete node(s) in pool(s) to match the amount provided. Each pool is a JSON object with id of the pool (must be unique across pools), size (immutable once a pool is created), from the available sizes and count of nodes. E.g.:
[
  {
	"id": "abc-123",
	"size": "g4s.kube.medium",
	"count": 3
  },
  {
	"id": "def-123",
	"size": "g4s.kube.large",
	"count": 3
  }
]
If provided, the pools can be used to scale the pool up/down by changing the count, add a new pool by including an additional object with id, size and count alongside existing pools, or delete a pool entirely by not providing that pool in the request.
Please note that this means if the pools parameter is provided, but empty, the cluster will delete the pools.
kubernetes_version (optional) the version of K3s to upgrade to
applications (optional) a comma separated list of applications to install. Spaces within application names are fine, but shouldn't be either side of the comma.
region (required) the identifier for the region where the cluster is running, from the current region list

Response

The response is a JSON object that contains the updated cluster information (same as create).

Example of scaling a cluster

curl -H "Authorization: bearer 12345" \
  -H 'Content-Type: application/json' \
  -X PUT https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614 \
  -d '{
    "region": "nyc1",
    "pools": [
        {
            "id": "1",
            "size": "g4s.kube.medium",
            "count": 5
        }
    ]
}'
// At a shell prompt run:
// npm init -y
// npm i --save request
// This example assumes there is a pool with an id of "1" running the specified type of nodes. We are scaling the pool up to 5.

var request = require('request');

request.put(
  'https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614',
  {
    "pools":[
    {
	    "id": "1",
	    "size": "g4s.kube.medium",
	    "count": 5
    }],
    "region": "nyc1"
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
# This example assumes there is a pool with an id of "1" running the specified type of nodes. We are scaling the pool up to 5.
require 'net/http'
require 'json'

url = URI("https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Put.new(url)
request["Authorization"] = "Bearer 12345"
request["Content-Type"] = "application/json"
request.body = JSON.dump({
  "region": "nyc1",
  "pools": [
    {
      "id": "1",
      "size": "g4s.kube.medium",
      "count": 5
    }
  ]
})
response = https.request(request)

Listing marketplace applications

A user can install applications in to their cluster.

The choices for available applications can be found by sending a GET request to https://api.civo.com/v2/kubernetes/applications.

Request

This operation doesn't require any additional parameters.

Response

The response is a JSON object that returns the applications in the marketplace.

[{
  "name": "MariaDB",
  "title": null,
  "version": "10.4.7",
  "default": null,
  "dependencies": ["Longhorn"],
  "maintainer": "hello@civo.com",
  "description": "MariaDB is a community-developed fork of MySQL intended to remain free under the GNU GPL.",
  "post_install": "Instructions go here\n",
  "url": "https://mariadb.com",
  "category": "database",
  "image_url": "https://api.civo.com/k3s-marketplace/mariadb.png",
  "plans": [{
    "label": "5GB",
    "configuration": {
      "VOLUME_SIZE": {
        "value": "5Gi"
      }
    }
  }, {
    "label": "10GB",
    "configuration": {
      "VOLUME_SIZE": {
        "value": "10Gi"
      }
    }
  }]
}]

Example of listing marketplace applications

curl -H "Authorization: bearer 12345" \
  -X POST https://api.civo.com/v2/kubernetes/applications
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/kubernetes/applications',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/kubernetes/applications', {}, headers)

Deleting a cluster

A user can delete a cluster and all underlying nodes.

Clusters are deleted by sending a DELETE request to https://api.civo.com/v2/kubernetes/clusters/:id.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the cluster is running.

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of deleting a cluster

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614?region=NYC1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614?region=NYC1',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614?region=NYC1', {}, headers)

Recycle a node

A user can delete and recreate one of the underlying nodes, if it's having a problem. Nodes are recycled by sending a POST request to https://api.civo.com/v2/kubernetes/clusters/:id/recycle.

Request

Name Description
hostname (required) the instance's hostname to recycle
region (required) the identifier for the region, from the current region list

Response

The response is a JSON object that simply acknowledges the request.

{
  "result": "success"
}

Example of recycling a node

curl -H "Authorization: bearer 12345" \
  -X POST https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614/recycle \
  -d hostname=node-1234
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614/recycle',
  {"hostname": "node-1234"},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614/recycle',
  {hostname: "node-1234"}, headers)

List available versions

A list of versions available to install isavailable by sending a GET request to https://api.civo.com/v2/kubernetes/versions.

Request

This request requires no parameters.

Response

The response is a JSON array of versions available, containing at minimum:

[
    {
        "version": "1.20.0+k3s1",
        "flat_version": "1.20.0-k3s1",
        "label": "v1.20.0+k3s1",
        "type": "stable",
        "default": true
    },
    {
        "version": "1.20.0+k3s2",
        "flat_version": "1.20.0-k3s2",
        "label": "v1.20.0+k3s2",
        "type": "deprecated"
    }
]

Example of listing versions

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/kubernetes/versions
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/kubernetes/versions',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/kubernetes/versions', headers)