Skip to content

How to change the max-pods limit in an RKE2 or K3s cluster

Article Number: 000021093

Environment

  • Rancher v2.6+
  • A standalone or Rancher-provisioned RKE2/K3s cluster

Situation

The existing RKE2/K3s cluster's pod limit has been exhausted and needs to be increased.

Resolution

When looking to change the max-pods for a node, make sure to take into account the number of IP addresses available from each nodes node CIDR, as this will limit the number of pods that can be scheduled on a node. Changing the node CIDR config in an existing cluster is not supported. If you need to increase the node-cidr-mask-size (and/or cluster_cidr) you will need to provision a fresh cluster, per the article How to setup your network CIDR for a large cluster.

Standalone RKE2/K3s clusters

In a standalone cluster, the configuration needs to be applied per node:

  1. Configure the kubelet's max-pods argument in the RKE2 or K3s configuration file (/etc/rancher/rke2/config.yaml or /etc/rancher/k3s/config.yaml) per the following example:

kubelet-arg:
  - "max-pods=200"
2. After updating the configuration file, you will need to restart the RKE2/K3s service to apply the changes:

  • On RKE2 server nodes: systemctl restart rke2-server
  • On RKE2 worker nodes: systemctl restart rke2-agent
  • On K3s server nodes: systemctl restart k3s
  • On K3s worker nodes: systemctl restart k3s-agent

Rancher-provisioned RKE2/K3s clusters

In a Rancher-provisioned cluster, the configuration can be managed at the cluster-level within Rancher:

  1. Navigate to Cluster Management within the Rancher UI and click Edit Config for the relevant RKE2/K3s cluster
  2. Under Cluster Configuration click Advanced
  3. Under For all machines, use the Kubelet args: in the section Additional Kubelet Args click Add Argument
  4. Enter the desired max-pods value, for example max-pods=200
  5. Click Save to apply the change