kubectl version

When to Use kubectl version

kubectl version displays the version of both the kubectl client binary and the Kubernetes API server. This is one of the first commands to run when setting up a new environment or troubleshooting compatibility issues.

Reading the Output

kubectl version
# Client Version: v1.29.2
# Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
# Server Version: v1.28.5

The key fields are:

• Client Version: Your local kubectl binary version.
• Server Version: The Kubernetes API server version.
• Kustomize Version: The embedded kustomize version (since kubectl includes kustomize).

Version Skew Policy

Kubernetes enforces a version skew policy. kubectl is supported within one minor version of the API server:

| kubectl Version | Supported Server Versions | |-----------------|--------------------------| | v1.29 | v1.28, v1.29, v1.30 | | v1.28 | v1.27, v1.28, v1.29 |

Operating outside this range is unsupported and can cause:

• Missing or changed command flags
• API version mismatches
• Incorrect resource schema handling

JSON Output for Scripting

For CI/CD pipelines, JSON output provides structured data:

# Get server version as JSON
kubectl version -o json

# Extract specific fields
kubectl version -o json | jq -r '.serverVersion.gitVersion'
# Output: v1.28.5

# Check minor version
kubectl version -o json | jq -r '.serverVersion.minor'
# Output: 28

Version Checking in Scripts

Automate version compatibility checks:

#!/bin/bash
CLIENT=$(kubectl version -o json | jq -r '.clientVersion.minor' | tr -d '+')
SERVER=$(kubectl version -o json | jq -r '.serverVersion.minor' | tr -d '+')
DIFF=$((CLIENT - SERVER))

if [ ${DIFF#-} -gt 1 ]; then
  echo "WARNING: Version skew too large (client: 1.$CLIENT, server: 1.$SERVER)"
  echo "Please update kubectl to a compatible version."
  exit 1
fi
echo "Version compatibility OK (client: 1.$CLIENT, server: 1.$SERVER)"

Client-Only Version Check

When you cannot reach the server (offline, VPN disconnected), use --client:

# Works without server connectivity
kubectl version --client
# Client Version: v1.29.2

# Useful for verifying kubectl installation
which kubectl && kubectl version --client

Managing Multiple kubectl Versions

When managing clusters at different versions, consider version managers:

# Check current version
kubectl version --client

# Using asdf for version management
asdf list kubectl
asdf local kubectl 1.28.5

# Using specific binary paths
/usr/local/bin/kubectl-1.28 version --client
/usr/local/bin/kubectl-1.29 version --client

Upgrade Planning

Before upgrading a cluster, check the current versions:

# Current state
kubectl version -o json | jq '{client: .clientVersion.gitVersion, server: .serverVersion.gitVersion}'

# After cluster upgrade, verify
kubectl version

# Update kubectl if needed to stay within skew
# macOS
brew upgrade kubectl

# Linux
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"

Relationship to API Versions

The server's Kubernetes version determines which API versions are available:

# Check server version
kubectl version -o json | jq -r '.serverVersion.gitVersion'
# v1.28.5

# Then check available APIs
kubectl api-versions | sort

Certain API versions are added or removed between Kubernetes releases. Always consult the Kubernetes changelog when planning upgrades, and use kubectl api-versions to verify availability.

Troubleshooting Connection Issues

If kubectl version fails to show server information:

# This means the API server is unreachable
kubectl version
# Client Version: v1.29.2
# Unable to connect to the server: dial tcp 10.0.0.1:6443: connect: connection refused

# Debug steps:
# 1. Check your kubeconfig
kubectl config view --minify
# 2. Check connectivity
curl -k https://10.0.0.1:6443/healthz
# 3. Check VPN or network
ping 10.0.0.1