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
Normal response
[
{
"name": "dev-md",
"max_nodes": 30,
"deprecated": false
},
{
"name": "prod-md",
"max_nodes": 120,
"deprecated": false
}
]
Create cluster
Creates a new Kubernetes cluster.
Request
{
"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
{
"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
Normal response
[
{
"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
Normal response
{
"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
{
"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
{
"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
Normal response
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
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
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
Normal response
{
"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
Normal response
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
{
"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
{
"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
Normal response
[
{
"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
Normal response
{
"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:
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
Attributes
Attribute | Accepted value | Required | Description |
---|---|---|---|
count | >= 0 | yes | Number of nodes. |
Normal response
{
"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
Normal response
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. |