kubernetes-python

用途

Kubernetes Python Client 是 Kubernetes 官方 Python 客户端库（由 SIG API Machinery 维护），提供对 Kubernetes API 的编程访问，用于自动化、自定义工具开发和应用集成。

主要能力

• 完整 API 覆盖：支持所有 Kubernetes 资源类型。
• 多种认证方式：本地 kubeconfig、集群内配置、指定 context。
• 按资源类型划分的 API 客户端：
  • CoreV1Api：Pods、Services、ConfigMaps、Secrets、Namespaces、PVCs
  • AppsV1Api：Deployments、StatefulSets、DaemonSets、ReplicaSets
  • BatchV1Api：Jobs、CronJobs
  • NetworkingV1Api：Ingresses、NetworkPolicies
  • CustomObjectsApi：自定义资源（CRD）
• 实时 watch/stream 能力，支持 ADDED、MODIFIED、DELETED、ERROR 事件类型。
• 完整 CRD 支持。
• 生产级模式：超时配置、大列表分页、服务端过滤、错误处理、幂等创建或更新。

使用方式

安装：

pip install kubernetes

基本用法：

from kubernetes import client, config

# 加载 kubeconfig
config.load_kube_config()

# 创建 API 客户端
v1 = client.CoreV1Api()

# 列出 Pod
pods = v1.list_pod_for_all_namespaces(limit=10)
for pod in pods.items:
    print(f"{pod.metadata.namespace}/{pod.metadata.name}")

客户端初始化模式：

• 本地开发（使用 kubeconfig）：config.load_kube_config()
• 集群内（运行在 Kubernetes 中）：config.load_incluster_config()
• 指定 context：config.load_kube_config(context='production-cluster')

常见操作包括：创建 Deployment、读取资源（支持 label_selector 与 field_selector）、更新资源（patch 部分更新优先，replace 全量更新）、删除资源（可设置 grace_period_seconds）、错误处理（捕获 ApiException，按 status 判断 404/403 等）、幂等创建或更新模式、watch 资源变化、操作 ConfigMap 与 Secret（Secret 数据需 base64 编码）、操作自定义资源。

生产模式：

• 超时配置：_request_timeout=10
• 分页：使用 limit 与 _continue 令牌循环获取
• 服务端过滤：使用 field_selector 而非客户端过滤

适用场景

• 集群自动化管理与批量操作
• 自定义运维工具与平台开发
• 应用与 Kubernetes API 集成
• 实时监控资源变化
• 管理自定义资源（CRD）

限制与注意事项

• 自动生成的代码，Python 风格较弱。
• 在超大规模集群（3000+ 资源）中性能可能下降。
• 无原生异步支持（可使用 kubernetes_asyncio 包）。
• EKS 需要手动刷新令牌（15 分钟过期）。
• 版本兼容性：客户端版本应与 Kubernetes 集群版本匹配（如 29.y.z 对应 K8s 1.29 完全一致，30.y.z 对应 K8s 1.30，31.y.z 对应 K8s 1.31；相邻版本多数 API 可用，部分新增或移除）。

安全最佳实践

• 最小权限：应用绝不使用 cluster-admin。
• RBAC：尽可能使用命名空间级 Roles 而非 ClusterRoles。
• Secrets：不要记录 secret 数据，从环境变量加载凭据。
• SSL 验证：生产环境始终验证 SSL（verify_ssl=True）。
• 集群内配置：集群内应用使用 service account。

参考链接

• GitHub：https://github.com/kubernetes-client/python
• 文档：https://kubernetes.readthedocs.io/
• PyPI：https://pypi.org/project/kubernetes/
• 示例：https://github.com/kubernetes-client/python/tree/master/examples