Pod Node Assignment & Manual Scheduling

Pod node assignment in Kubernetes is a time-sensitive operation that must be handled differently depending on the pod’s lifecycle stage. At creation time, you can pin a pod to a specific node directly in its manifest. Once a pod is running, reassignment requires a different approach through the API. Understanding these constraints helps avoid pods stuck in a pending state and ensures workloads land on the intended infrastructure.

Assigning a Node at Creation Time

You can assign a node to a pod by setting the nodeName field in the pod spec. This assignment is only valid during creation time; Kubernetes does not allow you to change the nodeName on an already-running pod through a simple update.

apiVersion: v1
kind: Pod
metadata:
  name: my-pod
  labels:
    app: web
spec:
  nodeName: worker-node-1
  containers:
    - name: my-container
      image: nginx:1.25
      ports:
        - containerPort: 80

In the example above, the pod is explicitly bound to worker-node-1 at creation time. The scheduler will not be involved in placing this pod because the target node is already specified.

The Role of the Scheduler

When a pod does not specify a nodeName, the cluster scheduler is responsible for selecting an appropriate node based on resource availability, affinity rules, and other constraints. If no scheduler is running in the cluster, a pod without an explicit node assignment will remain in a Pending state indefinitely.

Reassigning a Running Pod

If a pod is already running and you need to move it to a different node, you cannot simply update the nodeName field. Instead, you must create a Binding object and submit it through the Kubernetes API. This tells the API server to reassign the pod to the target node.

apiVersion: v1
kind: Binding
metadata:
  name: my-pod
target:
  kind: Node
  name: worker-node-2

You can apply this binding object with:

kubectl apply -f binding.yaml --namespace default

Key Takeaways

• Node assignment via nodeName is only effective at pod creation time.
• Without a scheduler, pods without an explicit node assignment will stay in Pending state.
• Moving a running pod requires a Binding object submitted through the API.
• Always verify your cluster has a scheduler running if you rely on automatic pod placement.

• Technology
• How-To

• Kubernetes
• SysAdmin