kubectl explain

When to Use kubectl explain

kubectl explain is your built-in API reference. Instead of searching documentation online, you can query the API server directly for field definitions, types, and descriptions. This is particularly useful during exams (CKA/CKAD) where internet access is restricted, and in air-gapped environments.

Navigating Resource Structure

Use dot notation to drill into nested fields:

# Top-level resource overview
kubectl explain pod

# Pod specification
kubectl explain pod.spec

# Container specification within a pod
kubectl explain pod.spec.containers

# Liveness probe configuration
kubectl explain pod.spec.containers.livenessProbe

# HTTP GET probe details
kubectl explain pod.spec.containers.livenessProbe.httpGet

Each level shows the field type, description, and available sub-fields. This is how you discover the correct YAML path for any configuration option.

Recursive View

The --recursive flag shows the entire resource structure as an indented tree. This gives you a bird's eye view of all available fields:

# See every field in a deployment
kubectl explain deployment --recursive

# See all pod spec fields
kubectl explain pod.spec --recursive

# Pipe through less for easier navigation
kubectl explain deployment --recursive | less

# Search for a specific field name
kubectl explain deployment --recursive | grep -i affinity

The recursive view does not show descriptions, only field names and types. Use it to find the field path, then query that path specifically for details.

Practical Examples

When writing YAML manifests, use explain to verify correct field names and types:

# How to configure resource limits?
kubectl explain pod.spec.containers.resources
kubectl explain pod.spec.containers.resources.limits

# What fields does a volume mount have?
kubectl explain pod.spec.containers.volumeMounts

# How to configure a deployment strategy?
kubectl explain deployment.spec.strategy
kubectl explain deployment.spec.strategy.rollingUpdate

# What types of volumes are available?
kubectl explain pod.spec.volumes

# How to configure a service's external traffic policy?
kubectl explain service.spec.externalTrafficPolicy

# What fields does an ingress rule have?
kubectl explain ingress.spec.rules

API Version Disambiguation

Some resources exist in multiple API groups. Use --api-version to specify which version you want:

# Explain deployment in apps/v1
kubectl explain deployment --api-version=apps/v1

# Explain HorizontalPodAutoscaler in different versions
kubectl explain hpa --api-version=autoscaling/v2
kubectl explain hpa --api-version=autoscaling/v1

# CronJob in batch/v1
kubectl explain cronjob --api-version=batch/v1

Working with CRDs

Custom Resource Definitions that include an OpenAPI schema can be explored with explain just like built-in resources:

# Explain a custom resource
kubectl explain certificate
kubectl explain certificate.spec
kubectl explain certificate.spec.issuerRef

The quality of explain output for CRDs depends on how well the CRD author documented the schema. Some CRDs have detailed descriptions, while others have minimal information.

Discovering Available Resources

Combine explain with api-resources to explore the cluster:

# List all available resource types
kubectl api-resources

# List resources in a specific API group
kubectl api-resources --api-group=apps

# Then explain any resource you find
kubectl explain statefulset.spec.volumeClaimTemplates

Using explain in Scripts

While explain is primarily an interactive tool, you can use it in scripts to validate field paths:

# Check if a field exists before using it
if kubectl explain pod.spec.containers.startupProbe &>/dev/null; then
  echo "startupProbe is available in this cluster version"
fi

CKA/CKAD Exam Tips

In certification exams, kubectl explain is your primary documentation source:

# Quickly find probe configuration
kubectl explain pod.spec.containers.readinessProbe

# Find volume types
kubectl explain pod.spec.volumes --recursive

# Check PersistentVolumeClaim fields
kubectl explain pvc.spec

# Find affinity and anti-affinity options
kubectl explain pod.spec.affinity
kubectl explain pod.spec.affinity.podAntiAffinity

Master the dot notation navigation and the --recursive flag. Together, they let you find any field path without external documentation. Start with --recursive to find the general path, then query the specific field for type and description details.