Kubernetes API 详解

Kubernetes (K8s) 的 API 是其核心设计，所有操作（如创建、更新、删除资源）都通过 API 完成。以下是 Kubernetes API 的详细介绍与总结：

1. Kubernetes API 概述

• 作用：Kubernetes API 是集群的“控制平面”，用于管理集群状态、配置资源、监控操作等。
• 设计原则：
  • 声明式 API：用户声明期望状态（如 YAML/JSON 文件），系统负责协调实际状态。
  • RESTful 风格：通过 HTTP 方法（GET/POST/PUT/DELETE）操作资源。
  • 可扩展性：支持自定义资源（CRD）和聚合 API。

2. API 核心概念

(1) API 资源（Resources）

• Kubernetes 中的一切（如 Pod、Service、Deployment）都是通过 API 资源表示的。
• 资源通过 API Group 分类：
  • 核心组（Core Group）：如 v1 版本的 Pod、Node、Namespace（无组名，例如 api/v1/pods）。
  • 命名组（Named Groups）：如 apps/v1（Deployment）、networking.k8s.io/v1（Ingress）。
  • 自定义组（Custom Groups）：用户通过 CRD 定义的资源（如 example.com/v1）。

(2) API 版本（Versioning）

• Alpha 版本（如 v1alpha1）：默认禁用，可能不兼容后续版本。
• Beta 版本（如 v1beta1）：默认启用，但后续可能修改。
• 稳定版本（如 v1）：生产环境推荐使用。

(3) API 路径结构

• 标准路径格式：/apis/<group>/<version>/namespaces/<namespace>/<resource>
  • 例如：/apis/apps/v1/namespaces/default/deployments
• 核心组路径：/api/v1/namespaces/default/pods

3. API 请求与响应

• HTTP 方法：
  • GET：查询资源。
  • POST：创建资源。
  • PUT：更新资源。
  • DELETE：删除资源。
  • PATCH：部分更新（支持 JSON Patch、Strategic Merge Patch）。
• 响应格式：通常是 JSON 或 YAML（通过 Accept 头指定）。

示例：创建一个 Pod

# 请求体（YAML）
apiVersion: v1
kind: Pod
metadata:
  name: nginx
spec:
  containers:
  - name: nginx
    image: nginx:latest

|

# 使用 kubectl 或直接调用 API
kubectl apply -f pod.yaml
# 或
curl -X POST -H "Content-Type: application/yaml" --data-binary @pod.yaml http://localhost:8080/api/v1/namespaces/default/pods

4. API 访问方式

(1) kubectl

• 封装了 API 请求的工具（如 kubectl get pods 对应 GET /api/v1/pods）。
• 支持 --v=6 以上日志级别查看实际 API 请求。

(2) 直接访问 API

• 本地代理：kubectl proxy 启动代理后通过 http://localhost:8001 访问。
• 编程调用：使用官方客户端库（如 Go Client、Python Client）。

(3) 认证与授权

• 认证（Authentication）：支持 TLS 证书、Bearer Token、Basic Auth 等。
• 授权（Authorization）：通过 RBAC（Role-Based Access Control）限制权限。

5. 高级特性

(1) Watch 机制

• 监听资源变化（如 kubectl get pods --watch 对应 GET /api/v1/pods?watch=true）。
• 用于实现控制器（Controller）的协调循环。

(2) 字段选择器（Field Selector）

• 过滤特定字段的资源（如 kubectl get pods --field-selector=status.phase=Running）。

(3) 标签选择器（Label Selector）

• 按标签过滤资源（如 kubectl get pods -l app=nginx）。

(4) 子资源（Subresources）

• 如 Pods/log（获取日志）、Pods/exec（进入容器）、Deployments/scale（扩缩容）。

6. 自定义资源（CRD）

• 允许用户扩展 API，定义自己的资源类型。

• 示例：定义一个 CronTab 资源：

  apiVersion: apiextensions.k8s.io/v1
  kind: CustomResourceDefinition
  metadata:
    name: crontabs.stable.example.com
  spec:
    group: stable.example.com
    versions:
      - name: v1
        served: true
        storage: true
    scope: Namespaced
    names:
      plural: crontabs
      singular: crontab
      kind: CronTab
  

7. 调试 API

• 查看 API 文档：

  kubectl proxy &
  curl http://localhost:8001/openapi/v2 > swagger.json
  

• 查看所有 API 资源：

  kubectl api-resources
  kubectl api-versions