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.

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": "development",
    "server_number": 1,
    "max_nodes": 50
  },
  {
    "name": "production-small",
    "server_number": 3,
    "max_nodes": 200
  }
]

Create cluster

Creates a new Kubernetes cluster.

Request

POST /1.3/kubernetes HTTP/1.1

{
  "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"
}

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 de-fra1, fi-hel2, nl-ams1, sg-sin1, uk-lon1, us-chi1 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.

Normal response

HTTP/1.1 201 Created

{
  "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,
      "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

GET /1.3/kubernetes HTTP/1.1

Normal response

HTTP/1.1 200 OK

[
  {
    "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,
        "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

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

Normal response

HTTP/1.1 200 OK

{
  "control_plane_ip_filter": [
    "0.0.0.0/0"
  ],
  "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

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

{
  "control_plane_ip_filter": ["0.0.0.0/0"]
}

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.

Normal response

HTTP/1.1 200 OK

{
  "control_plane_ip_filter": [
    "0.0.0.0/0"
  ],
  "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

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-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 noe 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

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

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

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": 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

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

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