Skip to content

20. Managed Kubernetes

Kubernetes is a container orchestration system for automating, managing and scaling software deployment.

Managed Kubernetes allows you to easily create Kubernetes clusters without having to take care about low level details.

Instructions and sample code for using Managed Kubernetes as a developer is available in uks-instructions GitHub repository.

List plans

Returns a list of available Kubernetes cluster plans.

Request

GET /1.3/kubernetes/plans HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "name": "dev-md",
    "max_nodes": 30,
    "deprecated": false
  },
  {
    "name": "prod-md",
    "max_nodes": 120,
    "deprecated": false
  }
]

Create cluster

Creates a new Kubernetes cluster.

Request

POST /1.3/kubernetes HTTP/1.1

{
  "control_plane_ip_filter": [],
  "name": "example-cluster-1",
  "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
  "network_cidr": "172.16.0.0/24",
  "node_groups": [
    {
      "count": 3,
      "labels": [
        {
          "key": "team",
          "value": "development"
        }
      ],
      "name": "example-node-group-1",
      "plan": "4xCPU-8GB",
      "ssh_keys": [
        "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
        "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
      ]
    }
  ],
  "plan": "dev-md",
  "private_node_groups": false,
  "zone": "fi-hel2",
  "labels": [
    {
      "key": "env",
      "value": "staging"
    },
    {
      "key": "app",
      "value": "cats-dating-app"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
control_plane_ip_filter An array of 0 or more IP addresses or IP ranges in CIDR format no IP addresses or IP ranges in CIDR format which are allowed to access the cluster control plane. Defaults to null on POST request, which implies no IP filtering is in place and access from any source is accepted. To explicitly allow access from any source, use ["0.0.0.0/0"]. To deny access from all sources, use []. Values set here do not restrict access to node groups or exposed Kubernetes services.
name 3-55 lowercase letters, numbers & -. Cannot start or end with with - yes The name of the Kubernetes cluster must be unique within customer account.
network A valid network identifier in UUID format yes Network UUID where node groups will provisioned. Must reside in Kubernetes cluster zone.
network_cidr IP range in CIDR format yes IP range of the given network.
zone A valid zone identifier, e.g. fi-hel2 yes Zone in which the Kubernetes cluster will be hosted, e.g. fi-hel2.
node_groups An array of 0 or more node group objects no See node groups.
plan Name of the plan to use for the cluster control plane. See list plans for querying available plans. no Plan for the clusters control plane. Defaults to dev-md.
private_node_groups boolean no Enable private node groups. Defaults to false. Enabling private node groups requires a network that is routed through NAT gateway.
labels An array of labels no List of labels added to this cluster. Please note those labels are only present on cluster API resource, they do not get propagated to any resources inside your cluster
storage_encryption A valid storage encryption strategy, e.g. data-at-rest no Default storage encryption strategy for all nodes in the cluster. Currently only data at rest encryption is supported.

Normal response

HTTP/1.1 201 Created

{
  "control_plane_ip_filter": [],
  "labels": [
    {
      "key": "env",
      "value": "staging"
    },
    {
      "key": "app",
      "value": "cats-dating-app"
    }
  ],
  "name": "example-cluster-1",
  "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
  "network_cidr": "172.16.0.0/24",
  "node_groups": [
    {
      "count": 3,
      "kubelet_args": [],
      "labels": [
        {
          "key": "team",
          "value": "development"
        }
      ],
      "name": "example-node-group-1",
      "plan": "4xCPU-8GB",
      "ssh_keys": [
        "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
        "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
      ],
      "state": "pending",
      "storage": "01000000-0000-4000-8000-000160010100",
      "taints": [],
      "anti_affinity": false,
      "utility_network_access": true
    }
  ],
  "state": "pending",
  "plan": "dev-md",
  "private_node_groups": false,
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "zone": "fi-hel2"
}

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad request INVALID_REQUEST Validation error.
422 Unprocessable entity INVALID_REQUEST Validation error.

List clusters

Returns a list of Kubernetes clusters.

Request

GET /1.3/kubernetes HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "control_plane_ip_filter": [],
    "labels": [
      {
        "key": "env",
        "value": "staging"
      },
      {
        "key": "app",
        "value": "cats-dating-app"
      }
    ],
    "name": "example-cluster-1",
    "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
    "network_cidr": "172.16.0.0/24",
    "node_groups": [
      {
        "count": 3,
        "kubelet_args": [],
        "labels": [
          {
            "key": "team",
            "value": "development"
          }
        ],
        "name": "example-node-group-1",
        "plan": "4xCPU-8GB",
        "ssh_keys": [
          "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
          "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
        ],
        "state": "running",
        "storage": "01000000-0000-4000-8000-000160010100",
        "taints": [],
        "anti_affinity": false,
        "utility_network_access": true
      }
    ],
    "state": "running",
    "plan": "dev-md",
    "private_node_groups": false,
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "zone": "fi-hel2"
  },
  {
    "control_plane_ip_filter": [
      "0.0.0.0/0"
    ],
    "name": "example-cluster-2",
    "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
    "network_cidr": "172.17.0.0/24",
    "node_groups": [],
    "state": "pending",
    "plan": "prod-md",
    "private_node_groups": true,
    "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "zone": "de-fra1"
  }
]

Get cluster details

Returns Kubernetes cluster details by given {uuid}.

Request

GET /1.3/kubernetes/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "control_plane_ip_filter": [
    "0.0.0.0/0"
  ],
  "labels": [
    {
      "key": "env",
      "value": "staging"
    },
    {
      "key": "app",
      "value": "cats-dating-app"
    }
  ],
  "name": "example-cluster-1",
  "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
  "network_cidr": "172.16.0.0/24",
  "node_groups": [
    {
      "count": 3,
      "kubelet_args": [],
      "labels": [
        {
          "key": "team",
          "value": "development"
        }
      ],
      "name": "example-node-group-1",
      "plan": "4xCPU-8GB",
      "ssh_keys": [
        "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
        "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
      ],
      "state": "running",
      "storage": "01000000-0000-4000-8000-000160010100",
      "taints": [],
      "anti_affinity": false,
      "utility_network_access": true
    }
  ],
  "state": "running",
  "plan": "dev-md",
  "private_node_groups": false,
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "zone": "fi-hel2"
}

Notes:

  • Please see state description.

Modify cluster

Modifies an existing Kubernetes cluster by given {uuid}.

Request

PATCH /1.3/kubernetes/{uuid} HTTP/1.1

{
  "control_plane_ip_filter": ["0.0.0.0/0"],
  "labels": [
    {
      "key": "env",
      "value": "production"
    },
    {
      "key": "app",
      "value": "dogs-dating-app"
    }
  ]
}

Attributes

Attribute Accepted value Required Description
control_plane_ip_filter An array of 0 or more IP addresses or IP ranges in CIDR format. null is not accepted in PATCH request yes IP addresses or IP ranges in CIDR format which are allowed to access the cluster control plane. To allow access from any source, use ["0.0.0.0/0"]. To deny access from all sources, use []. Values set here do not restrict access to node groups or exposed Kubernetes services.
labels An array of updated labels. no The new labels array will overwrite existing one, so you always need to send full array. Send null or empty array to delete all labels.

Normal response

HTTP/1.1 200 OK

{
  "control_plane_ip_filter": [
    "0.0.0.0/0"
  ],
  "labels": [
    {
      "key": "env",
      "value": "production"
    },
    {
      "key": "app",
      "value": "dogs-dating-app"
    }
  ],
  "name": "example-cluster-1",
  "network": "03a85f64-5717-4562-b3fc-2c963f66afa6",
  "network_cidr": "172.16.0.0/24",
  "node_groups": [
    {
      "count": 3,
      "kubelet_args": [],
      "labels": [
        {
          "key": "team",
          "value": "development"
        }
      ],
      "name": "example-node-group-1",
      "plan": "4xCPU-8GB",
      "ssh_keys": [
        "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
        "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
      ],
      "state": "running",
      "storage": "01000000-0000-4000-8000-000160010100",
      "taints": [],
      "anti_affinity": false,
      "utility_network_access": true
    }
  ],
  "state": "running",
  "plan": "dev-md",
  "private_node_groups": false,
  "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "zone": "fi-hel2"
}

Notes:

  • Please see state description.

Error response

HTTP status Error code Description
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster or node group not found.
422 Unprocessable entity INVALID_REQUEST Validation error.

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster not found.

Get available upgrades

Returns list of available versions that can be used to upgrade the cluster.

Request

GET /1.3/kubernetes/{uuid}/available-upgrades HTTP/1.1

Normal response

{
  "versions": ["1.31"]
}

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster not found.

Upgrade cluster

Upgrades an existing Kubernetes cluster to specific version.

Request

POST /1.3/kubernetes/{uuid}/upgrade HTTP/1.1

{
  "version": "1.31",
  "strategy": {
    "type": "manual"
  }
}

Attributes

Attribute Accepted value Required Description
version Version string yes Cluster version to upgrade to.
strategy strategy object no Node group upgrade strategy. Manual strategy is used by default.

Normal response

HTTP/1.1 202 Accepted

{
  "version": "1.31",
  "strategy": {
    "type": "manual"
  }
}

Error response

HTTP status Error code Description
400 Bad Request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster or node group not found.
422 Unprocessable entity INVALID_REQUEST Validation error.

Get kubeconfig

Returns kubeconfig for Kubernetes cluster by given {uuid}.

See Organizing Cluster Access Using kubeconfig Files (kubernetes.io).

Request

GET /1.3/kubernetes/{uuid}/kubeconfig HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "kubeconfig": "apiVersion: v1\nclusters:\n  - cluster:\n      certificate-authority-data: BASE64\n      server: https://server:6443\n    name: example-cluster-1\ncontexts:\n  - context:\n      cluster: example-cluster-1\n      user: example-cluster-1-admin\n    name: example-cluster-1-admin@example-cluster-1\ncurrent-context: example-cluster-1-admin@example-cluster-1\nkind: Config\npreferences: {}\nusers:\n  - name: example-cluster-1-admin\n    user:\n      client-certificate-data: BASE64\n      client-key-data: BASE64\n"
}

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster not found.

Delete cluster

Deletes an existing Kubernetes cluster by given {uuid}.

Request

DELETE /1.3/kubernetes/{uuid} HTTP/1.1

Normal response

HTTP/1.1 202 Accepted

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster not found.

Create node group

Creates a new node group to an existing Kubernetes cluster. Cluster is identified by given {uuid}.

Request

POST /1.3/kubernetes/{uuid}/node-groups HTTP/1.1

{
  "anti_affinity": true,
  "count": 9,
  "kubelet_args": [
    {
      "key": "log-flush-frequency",
      "value": "5s"
    }
  ],
  "labels": [
    {
      "key": "team",
      "value": "qa"
    }
  ],
  "name": "example-node-group-2",
  "plan": "4xCPU-8GB",
  "ssh_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
    "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
  ],
  "storage": "01000000-0000-4000-8000-000160010100",
  "taints": [
    {
      "effect": "NoSchedule",
      "key": "team",
      "value": "qa"
    }
  ],
  "utility_network_access": true
}

Attributes

Attribute Accepted value Required Description
count >= 0 yes Number of nodes.
name 1-63 lowercase letters, numbers & -. Cannot start or end with - yes The name of the node group must be unique within Kubernetes cluster.
plan A valid plan identifier yes Server plan used for each node.
anti_affinity boolean no Anti-affinity policy. Nodes will try to avoid underlying UpCloud hosts that already have nodes from the same node group during the start or creation phase.
kubelet_args An array of 0 or more kubelet argument objects no See Kubelet arguments. All parameter keys must be specified without the -- (double hyphens) prefix.
labels An array of 0 or more label objects no See Labels.
ssh_keys An array of 0-32 strings no Public SSH keys for remote node access.
storage A valid storage UUID no Storage template for node provisioning.
taints An array of 0 or more taint objects no See Taints.
utility_network_access boolean no Create utility network interfaces for each node. Defaults to true.
storage_encryption A valid storage encryption strategy, e.g. data-at-rest no Storage encryption strategy for the nodes in this group. Use value none to overwrite cluster-level encryption in a single node group.

Normal response

HTTP/1.1 201 Created

{
  "anti_affinity": true,
  "count": 9,
  "kubelet_args": [
    {
      "key": "log-flush-frequency",
      "value": "5s"
    }
  ],
  "labels": [
    {
      "key": "team",
      "value": "qa"
    }
  ],
  "name": "example-node-group-2",
  "plan": "4xCPU-8GB",
  "ssh_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
    "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
  ],
  "state": "pending",
  "storage": "01000000-0000-4000-8000-000160010100",
  "taints": [
    {
      "effect": "NoSchedule",
      "key": "team",
      "value": "qa"
    }
  ],
  "utility_network_access": true
}

Error response

HTTP status Error code Description
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
400 Bad request INVALID_REQUEST Validation error.
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster not found.
422 Unprocessable entity INVALID_REQUEST Validation error.

List node groups

Returns a list of available node groups of an existing Kubernetes cluster. Cluster is identified by given {uuid}.

A node group is a uniform set of worker nodes attached to a cluster.

Request

GET /1.3/kubernetes/{uuid}/node-groups HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "anti_affinity": false,
    "count": 3,
    "kubelet_args": [],
    "labels": [
      {
        "key": "team",
        "value": "development"
      }
    ],
    "name": "example-node-group-1",
    "plan": "4xCPU-8GB",
    "ssh_keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
      "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
    ],
    "state": "running",
    "storage": "01000000-0000-4000-8000-000160010100",
    "taints": [],
    "utility_network_access": true
  },
  {
    "anti_affinity": true,
    "count": 9,
    "kubelet_args": [
      {
        "key": "log-flush-frequency",
        "value": "5s"
      }
    ],
    "labels": [
      {
        "key": "team",
        "value": "qa"
      }
    ],
    "name": "example-node-group-2",
    "plan": "4xCPU-8GB",
    "ssh_keys": [
      "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
      "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
    ],
    "state": "running",
    "storage": "01000000-0000-4000-8000-000160010100",
    "taints": [
      {
        "effect": "NoSchedule",
        "key": "team",
        "value": "qa"
      }
    ],
    "utility_network_access": false
  }
]

Get node group details

Returns node group details by given {node_group_name}. Cluster is identified by given {uuid}.

Request

GET /1.3/kubernetes/{uuid}/node-groups/{node_group_name} HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "anti_affinity_status": true,
  "count": 2,
  "kubelet_args": [
    {
      "key": "log-flush-frequency",
      "value": "5s"
    }
  ],
  "labels": [
    {
      "key": "team",
      "value": "qa"
    }
  ],
  "name": "example-node-group-2",
  "plan": "4xCPU-8GB",
  "ssh_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
    "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
  ],
  "state": "running",
  "storage": "01000000-0000-4000-8000-000160010100",
  "taints": [
    {
      "effect": "NoSchedule",
      "key": "team",
      "value": "qa"
    }
  ],
  "utility_network_access": true,
  "nodes": [
    {
      "uuid": "564c8cd9-bc16-4f89-a328-daf3f138cc44",
      "name": "example-fzwwt-8smpz",
      "state": "running",
      "kubelet_version": "1.30"
    },
    {
      "uuid": "2e8039c6-95d4-41a9-92ca-46808f560abb",
      "name": "example-fzwwt-zmjfs",
      "state": "running",
      "kubelet_version": "1.30"
    }
  ]
}

Notes:

  • Please see state description.
  • Please see node description.

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster or node group not found.

Modify node group

Modifies an existing node group by given Kubernetes cluster {uuid} and {node_group_name}.

Request

PATCH /1.3/kubernetes/{uuid}/node-groups/{node_group_name} HTTP/1.1

{
  "count": 15
}

Attributes

Attribute Accepted value Required Description
count >= 0 yes Number of nodes.

Normal response

HTTP/1.1 200 OK

{
  "anti_affinity": true,
  "count": 15,
  "kubelet_args": [
    {
      "key": "log-flush-frequency",
      "value": "5s"
    }
  ],
  "labels": [
    {
      "key": "team",
      "value": "qa"
    }
  ],
  "name": "example-node-group-2",
  "plan": "4xCPU-8GB",
  "ssh_keys": [
    "ssh-rsa AAAAB3NzaC1yc2EAA[...]ptshi44x [email protected]",
    "ssh-dss AAAAB3NzaC1kc3MAA[...]VHRzAA== [email protected]"
  ],
  "state": "running",
  "storage": "01000000-0000-4000-8000-000160010100",
  "taints": [
    {
      "effect": "NoSchedule",
      "key": "team",
      "value": "qa"
    }
  ],
  "utility_network_access": true
}

Error response

HTTP status Error code Description
400 Bad Request INVALID_REQUEST Validation error.
402 Payment required INSUFFICIENT_CREDITS Customer account does not have enough credits for the requested action.
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster or node group not found.
422 Unprocessable entity INVALID_REQUEST Validation error.

Delete node group

Deletes an existing node group by given Kubernetes cluster {uuid} and {node_group_name}.

Request

DELETE /1.3/kubernetes/{uuid}/node-groups/{node_group_name} HTTP/1.1

Normal response

HTTP/1.1 202 Accepted

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Kubernetes cluster or node group not found.

Kubelet argument

Kubelet argument presented as a key-value pair. See kubelet options (kubernetes.io).

Attributes

Attribute Accepted value Required Description
key string yes Key representing the kubelet argument, without -- (double hyphens) prefix
value string yes Key representing the value

Label

Label presented as a key-value pair for classifying the resource.

Attributes

Labels are key/value pairs.

Attribute Accepted value Required Description
key 2-32 printable ASCII characters (range 0x20-0x7E), must not start with _ yes Label key
value 0-63 letters, numbers, - & _. Cannot start or end with - or _ yes Label value

Taint

Taint allows a node to repel a set of pods. See Taints and Tolerations (kubernetes.io).

Attributes

Attribute Accepted value Required Description
effect NoExecute / NoSchedule / PreferNoSchedule yes Key representing the effect
key 0-255 characters yes Key representing the taint
value 0-255 characters yes Key representing the value

State

State indicates the current operational, effective state of the given resource, either a Kubernetes cluster or a node group. Managed by the system.

State Description
pending Indicates newly created resource or started reconfiguration.
running Resource is up and running.
terminating Termination is in progress.
failed Indicates an internal system failure.
unknown Resource state is unknown.

Node

Node contains status information about single node.

Attribute Description Required
id Server UUID of the node. yes
name Name of the node. yes
state State of the node. yes
kubelet_version Kubelet version running on the node, when using default storage templates (experimental). no

Upgrade strategy

Node group upgrade strategy defines how node groups are upgraded to match cluster version. Manual strategy is used by default.

Attribute Accepted value Required Description
type manual / rolling-update yes Upgrade strategy type.

Strategy types

type Description
manual Upgrade your nodes manually at your convenience by re-creating the node groups.
rolling-update We'll automatically upgrade your nodes, one at the time per node group.