Skip to content

Kubernetes Clusters

Kubernetes clusters run on your organization's infrastructure. The platform provisions the control plane and the worker nodes, installs networking and cloud integration, and runs scaling and upgrades for you. You work with the cluster through kubectl and deploy to it from Applications.

Your clusters are under MANAGED SERVICES > Kubernetes in the console.

Key features

  • Two control plane options: run the control plane on dedicated VMs on your infrastructure (Standalone) or let the platform host it (Hosted).
  • Node pools: groups of worker nodes of one size, with a fixed node count or the Cluster Autoscaler.
  • Guided upgrades: the console offers only the Kubernetes versions your cluster can move to.
  • Built-in add-ons: pod networking, cloud integration and the Cluster Autoscaler, plus optional persistent storage.
  • Monitoring: cluster and per-node metrics in the console.
  • Ready for applications: every cluster is a deployment target in Applications.

Before you start

  • Kubernetes set up on a service config. An organization administrator sets up Kubernetes clusters on a service config of the infrastructure. That setup also decides which external network your clusters attach to. See Kubernetes clusters.
  • Node images in the cloud. Each Kubernetes version needs its tagged node image in the cloud. See Prepare the Kubernetes node images.
  • Sizes in the catalog. Control plane and node pool sizes come from the sizes enabled in the infrastructure's Catalog.
  • Quota and permissions. See Quotas and Permissions.

Standalone or Hosted control plane

You choose where the control plane runs when you create the cluster. You can't change it afterwards.

Standalone Hosted
Where it runs Dedicated VMs on your infrastructure On the platform, outside your infrastructure
What you choose Its size and 1 or 3 nodes Nothing; the platform runs it highly available
Later changes Scale, resize and upgrade Upgrade only
Node quota Its nodes count Its nodes don't count

Pick Standalone for dedicated control plane VMs you size yourself; choose 3 nodes for high availability (with 1 node, the cluster's API stops if that node fails). Pick Hosted to keep your infrastructure for worker nodes only. The console labels the two types SCP and HCP.

Create a cluster

  1. Go to MANAGED SERVICES > Kubernetes and click Create Cluster.
  2. Choose the project, the infrastructure and a service config with Kubernetes set up. Service configs you can't use are shown disabled, with the reason.
  3. Pick the Kubernetes version. Versions read like 1.32.3 (platform v5): the Kubernetes release plus a platform number, which goes up when the bundled add-ons are updated without a Kubernetes change.
  4. Choose Standalone or Hosted, and decide on the add-ons:
    • Monitoring is on by default and can be switched on or off later.
    • Storage (CSI) is off by default. It can be enabled later but never disabled. See Storage (CSI).
  5. For a Standalone control plane, pick its size and 1 or 3 nodes.
  6. Add at least one node pool: a name, a size, and either a fixed node count or Autoscale with a minimum and maximum.
  7. Review the totals and click Create cluster.

The name is optional; a cluster without one is shown by its ID. Cluster and node pool names use lowercase letters, numbers and hyphens, start and end with a letter or number, and are at most 63 characters. Node pool names must be unique within the cluster.

The cluster goes through Pending and Creating to Active. A cluster has two indicators: its status (the platform's view of the last operation, see Lifecycle states) and its health, which shows whether the platform can currently reach the cluster's Kubernetes API. A node pool shows unhealthy while it scales or upgrades.

Connect with kubectl

Download the cluster's kubeconfig with Kubeconfig on the cluster's page and use it with kubectl or any Kubernetes tool. It becomes available once the cluster is active and healthy.

The kubeconfig is an administrator (cluster-admin) credential. Everyone who downloads it gets the same one; it isn't tied to your user, and removing someone's platform permissions doesn't revoke a copy they already downloaded. There is no way to revoke a downloaded copy from the platform; it stays valid until its certificate expires, and if yours stops working, download a fresh one. For per-person access that you can take away, create your own users or service accounts inside the cluster.

On a Standalone cluster the API address in the kubeconfig is on the infrastructure's external network.

The kubeconfig is a credential

Anyone with the file has full access to the cluster. Store it safely and share it only with people who should manage the cluster. Downloading it needs its own permission, so you can let people see a cluster without giving them access to it (see Permissions).

Change a cluster

Day-2 changes are on the cluster's Overview tab under Available Operations, and on each pool's card on the Node Pools tab. Changes need the cluster to be Active and healthy; node pool changes also need the pool to be active and healthy. If the cluster is Degraded, run Sync first. Only one operation runs at a time on a cluster and its node pools; wait for it to finish, or cancel it from Action History.

Control plane

Manage control plane lets you:

  • Scale (Standalone only): switch between 1 and 3 nodes. This moves your node quota up or down.
  • Resize (Standalone only): move the control plane VMs to another size. The new size's disk can't be smaller than the current one. Resizing replaces the control plane VMs.
  • Upgrade: move to a newer Kubernetes version. See Upgrade Kubernetes.

Each change briefly affects the cluster's API and takes a few minutes.

Node pools

  • Add a pool with Add Node Pool. A new pool starts at the control plane's version.
  • Change the node count with Manage nodes: set a fixed count, or turn on Autoscale with a minimum and maximum. Each pool has between 1 and 20 nodes, for the fixed count and for the autoscaler's maximum. Your platform operator may set a lower limit; asking for more is refused with the limit in the message.
  • Change the node size by adding a pool with the new size and then deleting the old one. A pool's size is fixed when you create it.
  • Delete a pool with Delete Node Pool. Its nodes are removed and Kubernetes reschedules their workloads onto the remaining pools, if they have room. Deleting the last pool leaves the cluster with no worker nodes, so your workloads stop until you add a pool.

Name and description

Edit Cluster changes the name and description.

Upgrade Kubernetes

Upgrade the control plane first, then each node pool. Upgrades can't be undone.

  1. In Manage control plane, pick a newer version under Upgrade.
  2. On the Node Pools tab, click Upgrade node pool on each pool to bring it to the control plane's version. Nodes are replaced one at a time: a new node is added, then an old one is drained and removed. Workloads with a single replica restart on another node, so expect a short interruption for them; a PodDisruptionBudget that forbids any eviction stalls the upgrade. Expect 15 to 30 minutes per pool, depending on its size.

The console offers only versions your cluster can move to:

  • Forward only: no downgrades, and no move to a new major version.
  • One minor version at a time (for example 1.32 to 1.33). Newer patch and platform releases of your current minor version are offered too.
  • Node pools can't fall more than one minor version behind the control plane. If a pool would, that version isn't offered until you upgrade the pool.

The console tells you when a newer patch or platform release of the cluster's current minor version exists, and when a node pool runs an older version than the control plane. Newer minor versions aren't flagged; check Manage control plane for those.

Add-ons

Every cluster comes with:

  • Pod networking (Flannel). Kubernetes NetworkPolicy resources are accepted but have no effect: traffic between pods isn't restricted by them.
  • Cloud integration: connects the cluster to your infrastructure, for example to create load balancers for Services of type LoadBalancer.
  • Cluster Autoscaler: resizes node pools that have Autoscale on.

The add-on versions come with the cluster's platform version and can't be configured per cluster. Storage is the one optional add-on.

Storage (CSI)

Storage (CSI) installs a storage driver so workloads can create persistent volumes. Turn it on when you create the cluster, or later with Enable CSI on the Overview tab. Either way it needs an infrastructure that provides block storage. Once on, it can't be turned off, because removing the driver could strand the volumes it created.

A cluster with Storage (CSI) gets these storage classes:

  • Always: csi-cinder-sc-delete and csi-cinder-sc-retain. They use your cloud's default volume type, can't expand volumes, and neither is the default class.
  • One per volume type selected on the infrastructure (see Storage (volume types)). The infrastructure's default volume type becomes the cluster's default class.

No volume types, no default storage class

If the infrastructure offers no volume types, the cluster has no default storage class, so volume claims that don't name a class stay pending. Name one of the two classes above in your claims, or ask an organization administrator to add a volume type and then run Sync.

When the volume types change, a running cluster picks up the change on its next control plane change or Sync; node pool operations don't apply it. If a volume type is removed, existing volumes keep working, but new volumes can't use that class.

Clusters without a load balancer

If the Control Plane card shows LB off, the cluster has no load balancer: Services of type LoadBalancer stay pending (use NodePort or an ingress instead), and on a Standalone cluster the API is reached through a floating IP on one control plane node, so API access stops if that node fails.

Cluster networking

Every cluster uses the same internal ranges, which you can't change: pods 10.244.0.0/16, services 10.96.0.0/12, service domain cluster.local. Avoid these ranges for networks your pods need to reach.

Monitoring and metrics

With monitoring on, the cluster's Metrics tab shows cluster-wide charts (nodes, pods, CPU and memory) and per-node charts (CPU, load, memory, filesystem, disk and network I/O, uptime) over the last 1 hour to 7 days. It's on by default; switch it with Enable Monitoring / Disable Monitoring on the Overview tab. The first data points take a few minutes to appear after you create the cluster or turn monitoring on.

The node picker lists the nodes that report metrics, so an empty list doesn't mean the cluster has no nodes.

Deploy applications to the cluster

Every cluster you create is added to Applications in the same project, and you can deploy to it once its control plane is ready. It is added without capabilities, so container apps get no HTTP ingress or Gateway API routes and Helm charts that use capability placeholders fail; see Kubernetes clusters you create. Deleting the cluster removes it from Applications and disconnects the instances that ran on it.

Delete a cluster

Click Delete on the cluster's page and confirm. Deleting removes the control plane, all node pools and everything running on the cluster. It can't be undone. You can delete a cluster while it is Active, Degraded or in Error.

The cluster that runs a Fully managed PostgreSQL setup isn't in your Kubernetes list and can't be deleted this way; see The cluster behind Fully managed.

Lifecycle states

Clusters and node pools use the resource statuses. On a Degraded cluster, only Sync, Delete and Delete Node Pool are offered. A cluster in Error (creating or deleting failed, or a creation was cancelled) can only be deleted.

Sync (on the cluster) and Sync Node Pool (on a pool) re-apply the desired configuration. Use them to recover a Degraded resource or to pick up infrastructure changes. Action History, on the cluster and on each pool, lists every operation and lets you cancel one that is still running.

Quotas

Each cluster uses one managed-kubernetes-clusters unit, plus managed-kubernetes-nodes for the Standalone control plane nodes and each node pool's node count (its maximum when autoscaling). The wizard shows the totals before you create. See What each quota counts.

Permissions

Task Permission
Find clusters in the list mks_list
See a cluster without its credentials mks_metadata_get
Download the kubeconfig mks_kubeconfig_get
See metrics mks_metrics_get
Create a cluster, add a node pool mks_create
Scale or resize the control plane mks_controlplane_resize_update
Upgrade the control plane mks_controlplane_upgrade_update
Scale a node pool mks_nodepool_scale_update
Upgrade a node pool mks_nodepool_upgrade_update
Enable Storage (CSI) mks_csi_update
Switch monitoring mks_monitoring_update
Edit name and description mks_metadata_update
Sync, cancel an action mks_action_update
Delete a cluster or a node pool mks_delete

mks_get includes the metadata, kubeconfig and metrics reads; mks_update includes every change. The create form also needs some organization-level permissions to pick where the cluster runs: see What project members typically need. Full list: Permissions Reference.

Next steps