kubectl compatibility — the operator client

kubectl is the operator’s client. The skew policy treats kubectl like the control plane’s stateless components: within 1 minor of the apiserver, either direction. The best practice, however, is to keep kubectl aligned with the apiserver minor. This lesson walks the policy, the failure modes, and the operational discipline.

The compatibility policy

kubectl: 1.33.x, 1.34.x, 1.35.x → all OK with apiserver 1.34.x
kubectl: 1.32.x → INVALID (2 minor behind)
kubectl: 1.36.x → INVALID (2 minor ahead)

The kubectl skew is symmetric: within 1 minor, either direction.

flowchart LR
    A[apiserver 1.34] --> B[kubectl 1.33]
    A --> C[kubectl 1.34]
    A --> D[kubectl 1.35]
    A -.-> E[kubectl 1.32 INVALID]
    A -.-> F[kubectl 1.36 INVALID]

Why the best practice is alignment

The kubectl client uses the apiserver’s API surface. A kubectl 1.35 with an apiserver 1.34 may use features the 1.34 apiserver does not have:

kubectl 1.35 apply -f manifest.yaml
# The manifest uses an API version introduced in 1.35

If the apiserver is 1.34, the API version is not supported, and the apply fails with no matches for kind ....

A kubectl 1.33 with an apiserver 1.34 can still apply the manifest if the features it uses are in 1.34. Older kubectl lacks features, but the features it has are present in the newer apiserver.

The kubectl upgrade

The kubectl upgrade is binary:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install -y kubectl=1.34.1-1.34

# RHEL/Fedora
sudo yum install -y kubectl-1.34.1-1.34

# macOS (Homebrew)
brew install kubectl@1.34
brew link --force kubectl@1.34

# Direct download
curl -LO "https://dl.k8s.io/release/v1.34.1/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

The kubectl binary is replaced; the previous version is backed up.

The version check

kubectl version

Client Version: v1.34.1
Kustomize Version: v5.7.1
Server Version: v1.34.1

The client and server versions are aligned. The --short flag that used to produce this output was deprecated in 1.24 and removed in 1.28; on a 1.34 kubectl it fails with error: unknown flag: --short.

kubectl version -o json

The same versions in a structured form, which is what to parse when the check runs in a script.

The kubectl across the team

A team has multiple operators. The kubectl version may differ across operators:

Operator A: kubectl 1.34.1
Operator B: kubectl 1.33.5
Operator C: kubectl 1.35.0

The skew policy allows all three. The best practice is to align the team’s kubectl along with the cluster upgrade.

The kubectl in CI/CD

CI/CD pipelines run kubectl in containers. The image’s kubectl version is fixed:

FROM registry.k8s.io/kubectl:v1.34.1 as kubectl

The CI pipeline’s kubectl version is part of the deliverable. A kubectl major upgrade is a CI/CD pipeline change.

The kubectl and apiserver discovery

kubectl discovers the apiserver’s version via the /version endpoint:

kubectl get --raw=/version

{
  "major": "1",
  "minor": "34",
  "gitVersion": "v1.34.1",
  ...
}

The kubectl client compares its own version to the server’s version and warns if they are out of skew:

kubectl version

WARNING: version difference between client (1.35.0) and server (1.34.1) exceeds the supported minor skew

The warning is informational; kubectl does not refuse to operate, but the operator should be aware that some features may not work.

The kubectl and kubeconfig

The kubeconfig does not pin the kubectl version. The apiserver’s version is independent of the kubectl version that uses the kubeconfig. The kubectl upgrade is a local action; the kubeconfig is unaffected.

The discipline

• Pin the kubectl version in CI/CD. The pipeline uses a specific kubectl image.
• Keep operator workstations aligned. The team’s kubectl matches the cluster’s apiserver.
• Update kubectl alongside the cluster. The kubectl upgrade is part of the upgrade plan.
• Watch the kubectl version warning. kubectl version shows the skew.
• Document the kubectl version in the runbook. The kubectl version, the apiserver version, the policy.

Cross-course references

• The Terraform course covers Kubernetes provider version pinning.
• The Ansible course covers module version pinning.
• The Linux course covers binary version management.

Quiz

Production discipline

• Pin kubectl in CI/CD. The pipeline uses a specific kubectl image.
• Keep operator workstations aligned. The team’s kubectl matches the cluster’s apiserver.
• Update kubectl alongside the cluster. Part of the upgrade plan.
• Watch the version warning. kubectl version shows the skew.
• Document the kubectl version in the runbook. The kubectl version, the apiserver version, the policy.

The kubectl is the operator’s window into the cluster. Operating it well is keeping it aligned with the apiserver and the team’s collective kubectl version.