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	a name for your cluster, must be unique within your account (required)
num_target_nodes	the number of instances to create (optional, the default at the time of writing is 3)
target_nodes_size	the size of each node (optional, the default is currently `g2.small`)
kubernetes_version	the version of k3s to install (optional, the default is currently the latest available)
tags	a space separated list of tags, to be used freely as required (optional)
applications	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`.

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

{
  "id": "69a23478-a89e-41d2-97b1-6f4c341cee70",
  "name": "your-cluster-name",
  "version": "2",
  "status": "ACTIVE",
  "ready": true,
  "num_target_nodes": 1,
  "target_nodes_size": "g2.xsmall",
  "built_at": "2019-09-23T13:04:23.000+01:00",
  "kubeconfig": "YAML_VERSION_OF_KUBECONFIG_HERE\n",
  "kubernetes_version": "0.8.1",
  "api_endpoint": "https://your.cluster.ip.address:6443",
  "dns_entry": "69a23478-a89e-41d2-97b1-6f4c341cee70.k8s.civo.com",
  "tags": [],
  "created_at": "2019-09-23T13:02:59.000+01:00",
  "instances": [{
    "hostname": "kube-master-HEXDIGITS",
    "size": "g2.xsmall",
    "region": "lon1",
    "created_at": "2019-09-23T13:03:00.000+01:00",
    "status": "ACTIVE",
    "firewall_id": "5f0ba9ed-5ca7-4e14-9a09-449a84196d64",
    "public_ip": "your.cluster.ip.address",
    "tags": ["civo-kubernetes:installed", "civo-kubernetes:master"]
  }],
  "installed_applications": [{
    "application": "Traefik",
    "title": null,
    "version": "(default)",
    "dependencies": null,
    "maintainer": "@Rancher_Labs",
    "description": "A reverse proxy/load-balancer that's easy, dynamic, automatic, fast, full-featured, open source, production proven and provides metrics.",
    "post_install": "Some documentation here\n",
    "installed": true,
    "url": "https://traefik.io",
    "category": "architecture",
    "updated_at": "2019-09-23T13:02:59.000+01:00",
    "image_url": "https://api.civo.com/k3s-marketplace/traefik.png",
    "plan": null,
    "configuration": {}
  }]
}

Example of creating a Kubernetes cluster

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/instances \
  -d "name=mycluster&num_target_nodes=3&target_nodes_size=g2.small"

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/instances',
  {
    form: {
      name: "mycluster",
      target_nodes_size: "g2.small",
      num_target_nodes: 3
    }
  },
  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/instances',
  'name=mycluster&target_nodes_size=g2.small&num_target_nodes=3',
  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 request requires no parameters.

Response

The response is a JSON array of cluster objects, like the JSON described for the `create` call above.

Example of listing clusters

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/kubernetes/clusters

// 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',
  {},
  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', 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 only the ID parameter in the URL.

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',
  {},
  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/instances/12345', headers)

Updating a cluster

A user can update a cluster to rename it, scale the number of nodes in the cluster, 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.

Name	Description
name	the cluster's new name
num_target_nodes	how many nodes should the cluster scale to.
version	the version of k3s to upgrade to.
applications	a comma separated list of applications to install. Spaces within application names are fine, but shouldn't be either side of the comma.

Response

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

Example of scaling a cluster

curl -H "Authorization: bearer 12345" \
  -X PUT https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614 \
  -d num_target_nodes=5

// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.put(
  'https://api.civo.com/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614',
  {
    "num_target_nodes": 5
  },
  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.put('/v2/kubernetes/clusters/4a07ac84-70f8-11e5-8fe9-5cf9389be614',
  {num_target_nodes: 5}, headers)

Listing marketplace applications

A user can install applications in to their cluster from the marketplace using the `update` call above.

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 operation doesn't require any additional parameters.

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

// 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',
  {},
  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', {}, 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

This operation requires a hostname parameter containing the name of the node to recycle.

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/instances/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/instances/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: "0.9.1",
    type: "stable",
    default: true
  },
  {
    version: "0.8.1",
    type: "legacy",
  }
]

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)