kubectl get --field-selector

kubectl Field Selectors Reference

Field selectors filter Kubernetes resources by their built-in spec and status fields. Unlike label selectors which filter by user-defined metadata, field selectors query the actual resource properties such as pod status, node name, or namespace.

Supported Fields by Resource Type

Not all fields support field selectors. Here are the commonly supported ones:

All Resources

# By name
kubectl get pods --field-selector=metadata.name=my-pod

# By namespace
kubectl get pods --field-selector=metadata.namespace=production -A

Pods

# By phase
kubectl get pods --field-selector=status.phase=Running
kubectl get pods --field-selector=status.phase=Pending
kubectl get pods --field-selector=status.phase=Failed
kubectl get pods --field-selector=status.phase=Succeeded

# By node
kubectl get pods --field-selector=spec.nodeName=worker-1

# By service account
kubectl get pods --field-selector=spec.serviceAccountName=my-sa

# By restart policy
kubectl get pods --field-selector=spec.restartPolicy=Always

Nodes

# By name
kubectl get nodes --field-selector=metadata.name=worker-1

# By spec.unschedulable
kubectl get nodes --field-selector=spec.unschedulable=true

Events

# Events are the most common field-selector use case
kubectl get events --field-selector=involvedObject.name=my-pod
kubectl get events --field-selector=involvedObject.kind=Pod
kubectl get events --field-selector=reason=Killing
kubectl get events --field-selector=type=Warning
kubectl get events --field-selector=involvedObject.namespace=production

Services

# By type
kubectl get services --field-selector=spec.type=LoadBalancer
kubectl get services --field-selector=spec.type=ClusterIP

Operators

Field selectors support only equality operators:

| Operator | Description | Example | |----------|-------------|---------| | = | Equal | status.phase=Running | | == | Equal (same as =) | status.phase==Running | | != | Not equal | status.phase!=Running |

Set-based operators (in, notin) are not supported for field selectors.

Combining Field Selectors

Use commas for AND logic:

# Running pods on a specific node
kubectl get pods --field-selector=status.phase=Running,spec.nodeName=worker-1

# Failed pods in a specific namespace
kubectl get pods --field-selector=status.phase=Failed,metadata.namespace=production -A

Combining with Label Selectors

Field selectors and label selectors can be used together:

# Running pods with app=nginx label
kubectl get pods --field-selector=status.phase=Running -l app=nginx

# Pending pods for a specific team
kubectl get pods --field-selector=status.phase=Pending -l team=backend

# Events for pods with a specific label on a specific node
kubectl get pods --field-selector=spec.nodeName=worker-1 -l tier=frontend

Common Use Cases

Finding Problematic Pods

# All non-running pods
kubectl get pods --field-selector=status.phase!=Running -A

# All failed pods
kubectl get pods --field-selector=status.phase=Failed -A

# All pending pods (likely scheduling issues)
kubectl get pods --field-selector=status.phase=Pending -A

Node Troubleshooting

# All pods on a troubled node
kubectl get pods --field-selector=spec.nodeName=troubled-node -A

# Count pods per node
for node in $(kubectl get nodes -o name | cut -d/ -f2); do
  count=$(kubectl get pods --field-selector=spec.nodeName="$node" -A --no-headers | wc -l)
  echo "$node: $count pods"
done

Event Investigation

# Recent warnings
kubectl get events --field-selector=type=Warning --sort-by=.lastTimestamp

# Events for a specific deployment's pods
kubectl get events --field-selector=involvedObject.kind=Pod -n production

# OOMKilled events
kubectl get events --field-selector=reason=OOMKilling

# Scheduling failures
kubectl get events --field-selector=reason=FailedScheduling

Completed Job Cleanup

# Find completed pods (from finished Jobs)
kubectl get pods --field-selector=status.phase=Succeeded -A

# Delete them
kubectl delete pods --field-selector=status.phase=Succeeded -A

Server-Side vs Client-Side Filtering

Field selectors are processed server-side, which provides performance benefits:

# Server-side filtering (efficient)
kubectl get pods --field-selector=status.phase=Running

# Client-side filtering (fetches all pods, then filters)
kubectl get pods | grep Running

# Server-side is especially important with large clusters
kubectl get pods --field-selector=spec.nodeName=worker-1 -A  # Only matching pods transferred
kubectl get pods -A | grep worker-1                          # All pods transferred, then filtered

Discovering Supported Fields

There is no built-in command to list supported field selectors. The best approaches are:

# Trial and error
kubectl get pods --field-selector=spec.containers.image=nginx
# Error: field label not supported: spec.containers.image

# Check the Kubernetes API documentation for each resource type

# Or use the API directly
kubectl get --raw /api/v1/pods?fieldSelector=status.phase=Running | jq '.items | length'

Limitations

• Only a limited subset of fields is indexed and queryable.
• Complex nested fields (like container images or resource limits) are not supported.
• Only equality operators are available (no in, notin, >, <).
• For queries that field selectors cannot handle, use -o json with jq for client-side processing.

Despite these limitations, field selectors are essential for efficient cluster monitoring, troubleshooting, and automation at scale.