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). 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": "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",
"master_ip": "your.cluster.ip.address",
"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/kubernetes/clusters \
-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/kubernetes/clusters',
{
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/kubernetes/clusters',
'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 paginated JSON array of cluster objects, like the JSON described for the `create` call above wrapped in:
{
"page": 1,
"per_page": 100000000,
"pages": 1,
"items": [
// ...
]
}
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/kubernetes/clusters/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. |
node_destroy | if you are scaling down by one, you can give a hint on the node's name to be destroyed. |
kubernetes_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/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: "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)