Resolving "Volume Node Affinity Conflict" in Kubernetes

Last updated: June 25, 2026

Issue

When deploying a pod, it may remain in a Pending state with the warning:

"1 node(s) had volume node affinity conflict."

This warning indicates that the Persistent Volume (PV) does not meet the node affinity requirements for the node where the pod is scheduled, preventing the pod from accessing the specified storage.

Cause

This issue often arises when:

The Persistent Volume (PV) and the pod are scheduled in different zones or regions, which can happen in multi-zone or multi-region clusters.
The StorageClass for the Persistent Volume Claim (PVC) is set up with volumeBindingMode: Immediate, which binds the volume before the pod is scheduled. This can result in the volume being created in a location that is incompatible with the pod’s node.

Solution

To resolve this issue, follow these steps:

Check Persistent Volume and PVC Locations:
- Use the following commands to identify the PVs and check their properties:
```
kubectl get pvc -n 
kubectl get pv
kubectl describe pv         
```
Verify that the PV's node affinity matches the zone or region of the node where the pod is scheduled.

Set Up a Single-Zone Storage Class:

Define a StorageClass restricted to a single availability zone or region to ensure compatibility.

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: single-zone-storage
provisioner: kubernetes.io/aws-ebs # Adjust based on your cloud provider
parameters:
  type: gp2 # Example for AWS
  encrypted: "true" # If encryption is needed
volumeBindingMode: WaitForFirstConsumer
allowedTopologies:
  - matchLabelExpressions:
      - key: failure-domain.beta.kubernetes.io/zone
        values:
          -  # Example: us-east-1a

volumeBindingMode: WaitForFirstConsumer defers binding the volume until the pod is scheduled, ensuring that the volume is created in a compatible zone.

Update and Reapply Your Resources:

If the current PVC uses an incompatible StorageClass, delete the PVC and PV, update the StorageClass, and reapply the configuration with the WaitForFirstConsumer setting.
Re-deploy the Pod:

Once the compatible StorageClass is configured, redeploy the pod, ensuring the volume is now in an accessible location.

Additional Notes

Multi-Zone Clusters: In multi-zone clusters, configuring StorageClasses with specific availability zones helps prevent node affinity conflicts.
Cloud-Specific Requirements: For cloud environments (e.g., AWS, GCP, Azure), verify specific configurations, as they may have unique StorageClass parameters and provisioning methods.

Related Commands

kubectl get pv
kubectl describe pv