Kubernetes Python Client

Warnings

• breaking Client major version must match Kubernetes server minor version. Client 35.x works with k8s 1.35. Mismatched versions cause ApiException or missing API objects.
  Fix: Match client version to your cluster: k8s 1.28 → pip install 'kubernetes>=28,<29'. Check compatibility matrix at github.com/kubernetes-client/python
• breaking Version numbers jumped from 12.x to 17.x — not a typo. Versions 13-16 were skipped to align with Kubernetes minor versions.
  Fix: This is intentional. Client version N corresponds to Kubernetes 1.N.
• breaking Direct exec/attach calls (v1.connect_get_namespaced_pod_exec()) removed in v4. Must use stream.stream() wrapper.
  Fix: from kubernetes import stream; stream.stream(v1.connect_get_namespaced_pod_exec, pod_name, namespace, command=[...])
• gotcha load_kube_config() fails inside Kubernetes pods. load_incluster_config() fails outside pods. Code using only one will break in the other environment.
  Fix: try: config.load_incluster_config() except ConfigException: config.load_kube_config()
• gotcha load_incluster_config() raises ConfigException 'Service host/port is not set' when KUBERNETES_SERVICE_HOST env var is missing — i.e. when not running inside a pod.
  Fix: Catch config.ConfigException when trying incluster config, then fall back to kube_config.
• gotcha list_* API calls return a V1PodList with .items — not a plain list. Must iterate .items not the response object itself.
  Fix: for pod in v1.list_pod_for_all_namespaces().items: — not for pod in v1.list_pod_for_all_namespaces():
• gotcha Watch API streams indefinitely unless stopped or _request_timeout is set. Omitting timeout in production causes memory leaks.
  Fix: w = watch.Watch(); for event in w.stream(v1.list_namespace, _request_timeout=60): — always set _request_timeout.

Install

• pip install kubernetes Python

Imports

• config loading (local + in-cluster)

  from kubernetes import client, config
  
  # Correct: handle both local and in-cluster
  try:
      config.load_incluster_config()  # running inside a pod
  except config.ConfigException:
      config.load_kube_config()  # running locally
  
  v1 = client.CoreV1Api()
  pods = v1.list_pod_for_all_namespaces(watch=False)
  for pod in pods.items:
      print(f'{pod.metadata.namespace}/{pod.metadata.name}')

  load_kube_config() fails inside Kubernetes pods (no ~/.kube/config). load_incluster_config() fails locally (no service account token). Use try/except to handle both environments.
• exec into pod (stream module)

  from kubernetes import client, config, stream
  
  config.load_kube_config()
  v1 = client.CoreV1Api()
  
  # Must use stream() wrapper for exec/attach
  resp = stream.stream(
      v1.connect_get_namespaced_pod_exec,
      'my-pod',
      'default',
      command=['ls', '/'],
      stderr=True,
      stdin=False,
      stdout=True,
      tty=False
  )
  print(resp)

  Direct exec/attach calls removed in v4. Must use stream.stream() wrapper. Raises TypeError or unexpected errors without the wrapper.

Quickstart

Kubernetes Python client — list pods and deployments with dual config loading.

# pip install kubernetes
from kubernetes import client, config

# Load config — handles both local and in-pod
try:
    config.load_incluster_config()
except config.ConfigException:
    config.load_kube_config()

# Core API — pods, namespaces, nodes
v1 = client.CoreV1Api()

# List pods in all namespaces
pods = v1.list_pod_for_all_namespaces(watch=False)
for pod in pods.items:
    print(f'{pod.metadata.namespace}/{pod.metadata.name}: {pod.status.phase}')

# Apps API — deployments
apps_v1 = client.AppsV1Api()
deployments = apps_v1.list_deployment_for_all_namespaces()
for d in deployments.items:
    print(f'{d.metadata.name}: {d.spec.replicas} replicas')

# Get specific pod
pod = v1.read_namespaced_pod(name='my-pod', namespace='default')
print(pod.status.pod_ip)