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:

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": "3f9cb197-8c9a-4ff8-8d8a-0a9f3ab2c84a",
    "name": "test",
    "generated_name": "test-5f44ef9d",
    "version": "1.20.0-k3s1",
    "kubernetes_version": "1.20.0-k3s1",
    "status": "BUILDING",
    "ready": false,
    "num_target_nodes": 2,
    "target_nodes_size": "g3.k3s.medium",
    "built_at": "2021-09-06T09:13:03.132+01:00",
    "kubeconfig": null,
    "api_endpoint": "",
    "firewall_id": "3f8f07bb-3d0c-4d73-ab91-c336b0693f0c",
    "legacy": false,
    "dns_entry": "3f9cb197-8c9a-4ff8-8d8a-0a9f3ab2c84a.k8s.civo.com",
    "tags": [
        "first",
        "second"
    ],
    "created_at": "2021-09-06T09:13:02.000+01:00",
    "upgrade_available_to": null,
    "master_ip": null,
    "instances": [],
    "installed_applications": [
        {
            "id": "88fce556-f8c5-4c6d-9a42-0f95c78bd8d3",
            "cluster": null,
            "name": "Linkerd",
            "application": null,
            "version": "Latest",
            "maintainer": "hello@buoyant.io",
            "dependencies": null,
            "description": "Linkerd is a service mesh, giving you runtime debugging, observability, reliability, and security.",
            "url": "https://linkerd.io",
            "category": "architecture",
            "installed": false,
            "image_url": "https://api.civo.com/k3s-marketplace/linkerd.png",
            "plan": "Linkerd & Jaeger",
            "configuration": {
                "LINKERD": {
                    "value": "linkerdjaeger"
                }
            },
            "title": null,
            "created_at": "2021-09-06T09:13:02.843+01:00",
            "updated_at": null,
            "kubernetes_yaml": "",
            "install_script": "#!/bin/bash\n\ncurl -sL https://run.linkerd.io/install | sh\nexport PATH=$PATH:$HOME/.linkerd2/bin\n\nlinkerd check --pre && linkerd install | kubectl apply -f -\ncase $LINKERD in\n  linkerd)\n    linkerd check || exit 1\n    ;;\n  linkerdjaeger)  \n    linkerd check || exit 1\n    linkerd jaeger install | kubectl apply -f -\n    linkerd check || exit 1\n    ;;\n  linkerdviz)\n    linkerd check || exit 1\n    linkerd viz install | kubectl apply -f -\n    linkerd check || exit 1\n    ;;\n  theworks)\n    linkerd check || exit 1\n    linkerd viz install | kubectl apply -f -\n    linkerd check || exit 1\n    linkerd jaeger install | kubectl apply -f -\n    linkerd check || exit 1\n    ;;\nesac\n",
            "post_install": "## Linkerd service mesh\n\n### External access\n\nDepending on the plan you selected you may or may not have access to the Dashboard. as of Linkerd 2.10 the Linkerd dashboard has been moved into the Viz extension.\n\nThe Linkerd dashboard is not available to the public by default, but if you installed Linkerd-viz and the linkerd client utility, you can open a tunnel to it easily:\n\n```bash\nlinkerd viz dashboard\n```\n\nThis will automatically open the Linkerd dashboard in your browser, or you can visit http://127.0.0.1:50750\n\n### Usage instructions\n\nLinkerd provides instructions on [installing a demo application](https://linkerd.io/2/getting-started/#step-5-install-the-demo-app) that uses Linkerd on their site. It's worth a read and a play with service meshes to get the hang of how/when they are of benefit.\n\nLinkerd's minimal install is comfortable on a cluster as small as a single node extra small instance. A single node cluster of size small or greater can accomodate installing Linkerd and any extensions you like.\n",
            "resource_script": "",
            "pre_install_script": ""
        }
    ],
    "master_ids": [],
    "network_id": "fb3cdfff-66ba-4048-9f37-8625237cbe67",
    "namespace": "cust-433e075e-808d-default",
    "pools": [],
    "required_pools": [
        {
            "id": "9c60850d-ceef-47f7-8886-23b13da77bfe",
            "count": 2,
            "size": "g3.k3s.medium"
        }
    ],
    "volumes": null
}

Example of creating a Kubernetes cluster

• Curl
• Node.js
• Ruby

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/kubernetes/clusters \
  -d "name=mycluster&num_target_nodes=3&target_nodes_size=g3.small&applications=&network_id=52b22474-a16e-15c1-66d2-6f4c341cee70&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',
  {
    form: {
      name: "mycluster",
      target_nodes_size: "g3.small",
      network_id: "52b22474-a16e-15c1-66d2-6f4c341cee70",
      instance_firewall: "72b22484-a16e-15c1-66d2-3f4c341cee90",
      firewall_rule: [],
      num_target_nodes: 3,
      applications: "cert-manager"
    }
  },
  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',
  'name=mycluster&target_nodes_size=g3.small&network_id=52b22474-a16e-15c1-66d2-6f4c341cee70&applications=cert-manager&num_target_nodes=3&instance_firewall=71b22474-a16e-35c1-66d2-8f4c341cee70&firewall_rule=443',
  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
• Node.js
• Ruby

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
• Node.js
• Ruby

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

Response

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

Example of scaling a cluster

• Curl
• Node.js
• Ruby

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

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

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
• Node.js
• Ruby

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
• Node.js
• Ruby

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

Response

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

{
  "result": "success"
}

Example of recycling a node

• Curl
• Node.js
• Ruby

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
• Node.js
• Ruby

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)