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": "development",
"server_number": 1,
"max_nodes": 50
},
{
"name": "production-small",
"server_number": 3,
"max_nodes": 200
}
]
Create cluster
Creates a new Kubernetes cluster.
Request
{
"control_plane_ip_filter": [],
"name": "example-cluster-1",
"network": "3fa85f64-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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
]
}
],
"plan": "development",
"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 development. |
| 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 |
Normal response
{
"control_plane_ip_filter": [],
"labels": [
{
"key": "env",
"value": "staging"
},
{
"key": "app",
"value": "cats-dating-app"
}
],
"name": "example-cluster-1",
"network": "3fa85f64-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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"state": "pending",
"storage": "01000000-0000-4000-8000-000160010100",
"taints": [],
"anti_affinity": false,
"utility_network_access": true
}
],
"state": "pending",
"plan": "development",
"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": "3fa85f64-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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"state": "running",
"storage": "01000000-0000-4000-8000-000160010100",
"taints": [],
"anti_affinity": false,
"utility_network_access": true
}
],
"state": "running",
"plan": "development",
"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": "22a85f64-5717-4562-b3fc-2c963f66afa6",
"network_cidr": "172.17.0.0/24",
"node_groups": [],
"state": "pending",
"plan": "production-small",
"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": "3fa85f64-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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"state": "running",
"storage": "01000000-0000-4000-8000-000160010100",
"taints": [],
"anti_affinity": false,
"utility_network_access": true
}
],
"state": "running",
"plan": "development",
"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 overrite 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": "3fa85f64-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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"state": "running",
"storage": "01000000-0000-4000-8000-000160010100",
"taints": [],
"anti_affinity": false,
"utility_network_access": true
}
],
"state": "running",
"plan": "development",
"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 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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"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. |
| 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. |
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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"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": 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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"state": "running",
"storage": "01000000-0000-4000-8000-000160010100",
"taints": [
{
"effect": "NoSchedule",
"key": "team",
"value": "qa"
}
],
"utility_network_access": true
}
Notes:
- Please see state 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
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-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG0LHaiLjqyWm3P+HSy2GxbZ4HU+HQ3LZ5fA51+Kp9Yi"
],
"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 |
| 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 | 1-32 letters, numbers, - & _. Cannot start or end with - or _ |
yes | Key representing the label |
| value | 0-63 letters, numbers, - & _. Cannot start or end with - or _ |
yes | Key representing the 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. |