Skip to content

19. 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-ha",
    "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 - 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.
authentication An authentication configuration array no List of OIDC authentication issuer configurations to provision on the cluster. See Cluster authentication.

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-ha",
    "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.

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.
custom_plan A custom plan object no Node group custom plan properties. Required when plan is set as "custom".
cloud_native_plan A cloud native plan object no Node group cloud native plan properties. Required when a cloud native plan is used in "plan" field, for e.g. "CLOUDNATIVE-48xCPU-384GB"
gpu_plan A GPU plan object no Node group GPU plan properties. Required when a GPU plan is used in "plan" field, for e.g. "GPU-12xCPU-128GB-1xL40s".
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.
node_updates A node updates (beta) object no Configure unattended updates for nodes in this 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.

Delete node group node

Deletes a single node {node_name} from the node group by given Kubernetes cluster {uuid} and {node_group_name}. Node group is scaled down by one and selected node is removed from the group. Once removed from the group, node server is deleted.

Request

DELETE /1.3/kubernetes/{uuid}/node-groups/{node_group_name}/{node_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.

Cluster authentication

Beta release

OIDC cluster authentication is currently in public beta and subject to changes. Hub, CLI, and Terraform provider support are not yet available. Please contact Support to share feedback or report issues (We'd love to hear your opinion)

Warning

OIDC requests are routed through worker nodes to make source IP addresses more predictable, without nodes OIDC authentication will become unavailable

In addition to the certificate-based admin kubeconfig, a cluster can be configured with one or more OpenID Connect (OIDC) issuers, letting users authenticate to the cluster's Kubernetes API using tokens from an external OIDC identity provider (e.g. Keycloak, Okta) instead of the static admin credentials. Cluster authentication requires Kubernetes 1.34 or newer.

Each issuer is stored as a named authentication issuer configuration entry, mapping to the native kube-apiserver AuthenticationConfiguration (apiserver.config.k8s.io/v1). The full set of issuers is validated together with the upstream apiserver library before being applied, so an invalid entry never reaches the control plane.

Entries can be managed individually (POST/GET/PUT/DELETE on a named entry), replaced as a whole set (PUT on the collection), or imported from a native apiserver YAML document. Unless noted otherwise, all endpoints below can also return 404 Not Found / RESOURCE_NOT_FOUND if the cluster does not exist, and 422 Unprocessable Entity / INVALID_REQUEST if the cluster's Kubernetes version does not support authentication configuration.

Updates take up to a minute to take action in your cluster.

List cluster authentication entries

Returns all OIDC authentication issuer configurations for the cluster identified by given {uuid}.

Request

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

Normal response

HTTP/1.1 200 OK

[
  {
    "name": "keycloak",
    "issuer_url": "https://keycloak.example.com/realms/example",
    "audiences": ["0Bje..."]
  }
]

Create a cluster authentication entry

Creates a new OIDC authentication issuer configuration. The new entry is validated together with the cluster's existing entries before being applied.

Request

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

{
  "name": "keycloak",
  "issuer_url": "https://keycloak.example.com/realms/example",
  "audiences": ["0Bje..."],
  "claim_mappings": {
    "username": {
      "claim": "email",
      "prefix": "oidc:"
    },
    "groups": {
      "claim": "groups",
      "prefix": ""
    }
  }
}

See authentication issuer config for the full list of attributes.

Normal response

HTTP/1.1 201 Created

The created authentication issuer config is returned.

Error response

HTTP status Error code Description
409 Conflict CONFLICT An authentication entry with this name already exists.

Replace the full cluster authentication configuration

Replaces the entire set of OIDC authentication issuer configurations for the cluster with the supplied JSON list of issuers. The full set is validated before being applied. An empty list clears all issuers.

Request

PUT /1.3/kubernetes/{uuid}/authentication HTTP/1.1

[
  {
    "name": "keycloak",
    "issuer_url": "https://keycloak.example.com/realms/example",
    "audiences": ["24cOYwiODoDAkda6rTRO"]
  }
]

Normal response

HTTP/1.1 200 OK

The full authentication configuration is returned.

Get a cluster authentication entry

Returns a single OIDC authentication issuer configuration by given {name}.

Request

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

Normal response

HTTP/1.1 200 OK

The requested authentication issuer config is returned.

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Authentication entry not found.

Replace a cluster authentication entry

Replaces an existing OIDC authentication issuer configuration. The name in the path is authoritative and overrides any name given in the request body. The updated entry is validated together with the cluster's other entries before being applied.

Request

PUT /1.3/kubernetes/{uuid}/authentication/{name} HTTP/1.1

{
  "name": "keycloak",
  "issuer_url": "https://keycloak.example.com/realms/example",
  "audiences": ["24cOYwiODoDAkda6rTRO", "12hjYwiODoDAkda6rTRO"]
}

Normal response

HTTP/1.1 200 OK

The updated authentication issuer config is returned.

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Authentication entry not found.

Delete a cluster authentication entry

Removes an OIDC authentication issuer configuration by given {name}.

Request

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

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status Error code Description
404 Not Found RESOURCE_NOT_FOUND Authentication entry not found.

Import a full cluster authentication configuration

Replaces the entire set of OIDC authentication issuer configurations for the cluster with a supplied native kube-apiserver apiserver.config.k8s.io/v1 AuthenticationConfiguration YAML document. This is intended for users migrating from a self-hosted cluster who already have an apiserver authentication configuration. The top-level anonymous field is not supported, and any document that cannot be fully represented as issuer entries is rejected.

Issuers are named deterministically from their issuer URL host (e.g. keycloak.example.com becomes keycloak-example-com, truncated to 63 characters); collisions within the document are resolved with an incrementing numeric suffix (-2, -3, ...).

Request

PUT /1.3/kubernetes/{uuid}/authentication/import HTTP/1.1
Content-Type: application/yaml

apiVersion: apiserver.config.k8s.io/v1
kind: AuthenticationConfiguration
jwt:
  - issuer:
      url: https://keycloak.example.com/realms/example
      audiences:
        - 24cOYwiODoDAkda6rTRO
    claimMappings:
      username:
        claim: email
        prefix: "oidc:"

Normal response

HTTP/1.1 200 OK

The resulting authentication configuration is returned as JSON (not YAML).

Get OIDC kubeconfig

Returns a kubeconfig for the cluster specified by the {name} path parameter, using its configured OIDC issuer. Authentication relies on the kubelogin (kubectl oidc-login) exec credential plugin, which must be installed on the client. No long-lived credential or OIDC client secret is embedded; provider-specific kubelogin flags (e.g. --oidc-client-secret) are not injected by the server either, and the returned kubeconfig includes comments describing how to add them.

Request

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

Parameters

Parameter In Required Description
audience query no Which of the issuer's configured audiences to use as the OIDC client id in the generated kubeconfig. When omitted, the issuer's first audience is used. Must match one of the issuer's audiences.

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-oidc\n    name: example-cluster-1-oidc\ncurrent-context: example-cluster-1-oidc\nkind: Config\nusers:\n  - name: example-cluster-1-oidc\n    user:\n      exec:\n        apiVersion: client.authentication.k8s.io/v1\n        command: kubectl\n        args:\n          - oidc-login\n          - get-token\n          - --oidc-issuer-url=https://keycloak.example.com/realms/example\n          - --oidc-client-id=24cOYwiODoDAkda6rTRO\n          - --oidc-extra-scope=openid\n          - --oidc-extra-scope=email\n          - --oidc-extra-scope=profile\n"
}

If the issuer has a certificate_authority configured, an additional --certificate-authority-data=... argument is included.

Error response

HTTP status Error code Description
400 Bad request INVALID_REQUEST Validation error, e.g. the requested audience is not configured.
404 Not Found RESOURCE_NOT_FOUND Authentication entry not found.
409 Conflict CONFLICT The cluster's Kubernetes version does not support this operation.
503 Service Unavailable NOT_READY The cluster is not yet running.

Authentication configuration

An authentication configuration is a JSON array of authentication issuer config objects. It represents the full set of OIDC issuers configured on a cluster. See Cluster authentication for the endpoints that manage it.

Authentication issuer config

A single OIDC issuer configuration. Maps to a JWT authenticator entry of the native kube-apiserver AuthenticationConfiguration.

Attributes

Attribute Accepted value Required Description
name 1-63 lowercase letters, numbers & -. Cannot start or end with - yes Unique name of the issuer entry within the cluster. Used as the {name} path parameter of the per-entry endpoints.
issuer_url URL yes OIDC issuer URL (the iss claim value). Must use https.
audiences An array of 1 or more strings yes Accepted audiences for tokens from this issuer. The first audience is used as the OIDC client id in generated kubeconfigs by default; the OIDC kubeconfig endpoint's audience query parameter can select a different one.
discovery_url URL no Override for the OIDC discovery endpoint, when it is not served at {issuer_url}/.well-known/openid-configuration.
audience_match_policy MatchAny / "" no Policy for matching token audiences. Defaults to "" (required when more than one audience is configured, in which case MatchAny must be used).
certificate_authority string no Base64-encoded PEM certificate authority bundle used to validate the issuer's TLS certificate, for issuers served behind a private CA.
claim_mappings A claim mappings object no Rules for mapping token claims to Kubernetes user attributes.
claim_validation_rules An array of claim validation rule objects no Rules validating individual token claims before the token is accepted.
user_validation_rules An array of user validation rule objects no Rules validating the final authenticated user.

Claim mappings

Rules for mapping token claims to Kubernetes user attributes.

Attributes

Attribute Accepted value Required Description
username A prefixed claim or expression no Maps the user's username.
groups A prefixed claim or expression no Maps the user's groups.
uid A claim or expression no Maps the user's UID.
extra An array of extra mapping objects no Maps token claims to extra user attributes.

Prefixed claim or expression

Maps a user attribute from either a JWT claim (optionally prefixed) or a CEL expression. claim/prefix and expression are mutually exclusive.

Attributes

Attribute Accepted value Required Description
claim string no JWT claim to use. Mutually exclusive with expression.
prefix string no Prefix prepended to the claim's value. Must be set (may be empty) when claim is set. Mutually exclusive with expression.
expression string no CEL expression producing the attribute value. Mutually exclusive with claim and prefix.

Claim or expression

Maps a user attribute from either a JWT claim or a CEL expression. claim and expression are mutually exclusive.

Attributes

Attribute Accepted value Required Description
claim string no JWT claim to use. Mutually exclusive with expression.
expression string no CEL expression producing the attribute value. Mutually exclusive with claim.

Extra mapping

Maps a token claim to an extra user attribute using a CEL expression.

Attributes

Attribute Accepted value Required Description
key string yes Domain-prefixed, lowercase key for the extra attribute, e.g. example.org/foo.
value_expression string yes CEL expression producing the extra attribute value (string or string array).

Claim validation rule

A rule validating a token claim. Either provide claim + required_value for a simple equality check, or an expression for a CEL-based check.

Attributes

Attribute Accepted value Required Description
claim string no Name of the claim to validate. Used together with required_value.
required_value string no Value the claim must equal. Used together with claim.
expression string no CEL expression that must evaluate to true, e.g. claims.email_verified == true'.
message string no Human-readable message returned when the rule fails.

User validation rule

A CEL expression applied to the final authenticated user.

Attributes

Attribute Accepted value Required Description
expression string yes CEL expression that must evaluate to true, e.g. !user.username.startsWith('system:').
message string no Human-readable message returned when the rule fails.

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.

Custom plan

Custom plan allows you to specify exact resource requirements for nodes in a node group.

Attributes

Attribute Accepted value Required Description
cores positive integer yes The number of CPU cores.
memory positive integer yes The amount of memory in megabytes.
storage_size positive integer yes The size of the storage device in gigabytes.
storage_tier maxiops / standard / archive no The storage tier.

Cloud native plan

Cloud native plan allows you to specify storage configuration for nodes when using cloud native plans (e.g., "CLOUDNATIVE-48xCPU-384GB").

Attributes

Attribute Accepted value Required Description
storage_size positive integer yes The size of the storage device in gigabytes.
storage_tier maxiops / standard / archive no The storage tier.

GPU plan

GPU plan allows you to specify storage configuration for nodes when using GPU plans (e.g., "GPU-12xCPU-128GB-1xL40s").

Attributes

Attribute Accepted value Required Description
storage_size positive integer yes The size of the storage device in gigabytes.
storage_tier maxiops / standard / archive no The storage tier.

Node updates (Beta)

Node updates allows you to configure unattended OS package updates for nodes. Only patch and security updates that doesn't require node restart are applied.

Feature is available from cluster version 1.35 onwards.

Attributes

Attribute Accepted value Required Description
kubernetes_patches Boolean yes Include Kubernetes patch updates for kubeadm, kubectl and kubelet packages.
schedule_time Time string yes Time of the day when updates are applied in UTC e.g. 14:00.
schedule_dow From Monday to Sunday and daily yes Day of the week. Use daily to apply updates everyday.