Node Management

Overview

PodWarden provides node-level operations for K8s cluster maintenance — cordoning, draining, and workload migration. These are available from the cluster detail page and through the API.

Cordon & Uncordon

Cordoning a node marks it as unschedulable. Existing pods continue running, but the Kubernetes scheduler won't place new pods on it.

Cordoning is non-disruptive. Use it as the first step before draining or when you want to temporarily stop scheduling without evicting running workloads.

Draining a Node

Draining evicts all pods from a node, moving them to other nodes in the cluster. PodWarden automatically cordons the node before draining.

Options

What happens during drain

1. Node is cordoned (if not already)
2. All non-DaemonSet pods are evicted via the Kubernetes eviction API
3. Kubernetes respects PodDisruptionBudgets during eviction
4. Evicted pods are rescheduled to other available nodes

Workload Migration

To move a deployment from one node to another:

1. Cordon the source node
2. Drain the source node (evicts all pods)
3. Update placement on the deployment to target the new node
4. Redeploy the workload

Persistent volume handling

With Longhorn distributed storage (the default for PodWarden-managed clusters), persistent volumes are replicated across nodes. Migration does not require manual data copying — Longhorn handles volume availability on the target node.

Without Longhorn (e.g., local-path provisioner), volumes are pinned to a single node. Migration requires manual data handling or using undeploy → change placement → redeploy, which creates new empty PVCs on the target node.

Pre-flight checks

Before deploying to a new node, PodWarden checks:

• PV node affinity: If the persistent volume has a node affinity constraint, PodWarden verifies the target node is in the allowed list. Returns a 409 Conflict if the node is incompatible.

kubectl get pods -n longhorn-system -o wide | grep <target-node-name>

Post-deploy health check

After deploying to the new node, PodWarden polls pod readiness for up to 90 seconds. If pods don't reach a healthy state, the deployment status transitions to error with a diagnostic message.

Force-Delete Stuck Namespaces

Occasionally a Kubernetes namespace gets stuck in Terminating state — typically because a finalizer can't complete (e.g. Longhorn namespace after an unclean uninstall). PodWarden provides a force-delete operation that removes finalizers and deletes the namespace.

When to use: Only when a namespace has been stuck in Terminating for several minutes and you've confirmed the underlying resources are gone or no longer needed.

Protected namespaces: default, kube-system, kube-public, and kube-node-lease cannot be force-deleted.

DELETE /clusters/{cluster_id}/namespaces/{namespace}?force=true

Requires the admin role.

API Reference

All node management endpoints require the operator role.

POST /clusters/{cluster_id}/nodes/{node_name}/cordon
POST /clusters/{cluster_id}/nodes/{node_name}/uncordon
POST /clusters/{cluster_id}/nodes/{node_name}/drain

  Body (drain only):
  {
    "force": false,
    "ignore_daemonsets": true,
    "delete_emptydir_data": true,
    "timeout_seconds": 120
  }

DELETE /clusters/{cluster_id}/nodes/{node_name}

DELETE /clusters/{cluster_id}/namespaces/{namespace}?force=true

Related docs

• Clusters — Cluster detail page with node list
• Storage — Volume types and StorageClass provisioners
• Infrastructure Canvas — Visual topology with pod placement edges
• Networking — Mixed network considerations for node placement