Skip to main content

CORDON A KUBERNETES NODE FOR MAINTENANCE

This guide shows you how to stop a Kubernetes node from receiving new pods before maintenance, see which workloads are still on it, and return it to service afterwards. The examples use the worker-3 node on the prod-cluster context.

Prerequisites

  • A kubeconfig with a prod-cluster context that can read and patch nodes and list pods in all namespaces
  • A Swamp repository

Pull the extension

swamp extension pull @swamp/kubernetes

You will see output like:

INF extension·pull: Pulling "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/kubernetes"@"2026.10.13.1"
INF extension·pull: Extracted 50 files:

Use a node behavior for the cluster

The steps below use a behavior named prod-nodes of type @swamp/kubernetes/node. If you do not have one, create it as described in Create and Run a Behavior. Nodes are cluster-scoped, so the type has no namespace argument and only the context is needed:

globalArguments:
  context: prod-cluster

Sync the node inventory

swamp behavior run prod-nodes list

This fetches every node in the cluster and writes a node resource for each live node. It also removes the stored records of nodes that have left the cluster.

Check the node

swamp behavior run prod-nodes get --input nodeName=worker-3

This fetches worker-3's conditions, capacity, allocatable resources, taints and node info and writes them as a node resource. Check this output for existing taints before you add your own.

Cordon the node

swamp behavior run prod-nodes cordon --input nodeName=worker-3

This sets spec.unschedulable to true on worker-3, so the scheduler stops placing new pods on it.

See which pods are still running

swamp behavior run prod-nodes getPodsOnNode --input nodeName=worker-3

This lists every pod running on worker-3 across all namespaces and writes a nodePod resource for each. Use this list to decide which workloads need attention before the maintenance starts.

Taint the node

swamp behavior run prod-nodes taint \
    --input nodeName=worker-3 \
    --input key=maintenance \
    --input value=true \
    --input effect=NoSchedule

This adds a maintenance=true taint with the NoSchedule effect to worker-3, so the node's state records why it is out of service. To also evict pods that do not tolerate the taint, use the NoExecute effect.

Return the node to service

When the maintenance is finished, remove the taint by its key:

swamp behavior run prod-nodes untaint --input nodeName=worker-3 --input key=maintenance

This removes the maintenance taint from worker-3.

Then uncordon the node:

swamp behavior run prod-nodes uncordon --input nodeName=worker-3

This sets spec.unschedulable to false on worker-3, so the scheduler can place pods on it again.