Kubernetes资源清单全解析

Kubernetes资源管理指南摘要：Kubernetes采用JSON/YAML格式定义资源对象，标准结构包含apiVersion、kind、metadata、spec和status五大字段。YAML是主要配置语言，需注意大小写敏感和空格缩进。资源管理支持三种方式：1)指令式命令快速操作；2)指令式配置基于文件操作；3)声明式配置（推荐生产使用）通过apply实现幂等性更新。开发时可利用--dry

zz-zjx

654人浏览 · 2025-12-25 15:13:06

zz-zjx · 2025-12-25 15:13:06 发布

一、资源清单格式

Kubernetes API 仅接受和返回 JSON 格式的数据对象。为方便用户，API Server 支持接收 YAML 格式的 POST 请求，并在内部自动转换为 JSON。

所有 Kubernetes 资源对象均遵循统一结构，包含以下一级字段：

apiVersion：API 版本（如 v1、apps/v1）
kind：资源类型（如 Pod、Deployment）
metadata：元数据（名称、命名空间、标签等）
spec：用户期望的状态（由用户定义）
status：当前实际状态（由系统维护，只读）

注意：部分“数据类”资源（如 ConfigMap、Secret、Endpoints）没有 spec 和 status 字段。

1 YAML 格式说明

YAML 是 Kubernetes 最常用的资源配置语言，特点如下：

大小写敏感
使用空格缩进表示层级（禁止 Tab）
同级元素左对齐即可，空格数不强制
# 开头为注释

基本结构

1. Maps（键值对）

key: value

嵌套示例：

metadata:
  name: mysql
  namespace: default

2. Lists（列表）

args:
  - sleep
  - "1000"
  - message

所有 Kubernetes 清单均由 Maps 与 Lists 组合而成。

可用 http://www.yamllint.com/ 验证语法。

2 资源配置清单结构

标准清单包含五大顶级字段：

字段	说明
`apiVersion`	API 组/版本，如 `apps/v1`
`kind`	资源类型，如 `Pod`、`Service`
`metadata`	元数据（名称、命名空间、标签等）
`spec`	用户定义的目标状态（核心字段）
`status`	系统维护的实际状态（只读）

字段名：小驼峰（如 creationTimestamp）
字段值（枚举类）：大驼峰（如 IfNotPresent, Active）

可通过以下命令查看现有资源的清单：

kubectl get TYPE/NAME -o yaml
kubectl get TYPE/NAME -o json

3 apiVersion 与 kind

`apiVersion`

格式：[GROUP/]VERSION

核心资源（如 Pod、Namespace）属于 v1（无组名）
其他资源带组名，如 apps/v1、networking.k8s.io/v1

查看支持的版本：

kubectl api-versions

`kind`

表示资源类型，如 Pod、Deployment、Service 等。

查看所有资源类型：

kubectl api-resources
# 查看指定组的资源
kubectl api-resources --api-group=apps

4 metadata 字段

描述资源的元信息，包含：

必填字段

name：资源名称（同类型+同命名空间内唯一）
namespace：所属命名空间（默认 default）
uid：系统生成的唯一标识（区分重建对象）

可选字段

labels：键值对，用于标签选择器
annotations：非标识性元数据（不可用于选择）
resourceVersion：内部版本号（用于检测变更）
creationTimestamp / deletionTimestamp：时间戳
generation：目标状态代数

5 spec 与 status

`spec`

必须字段（除数据类资源外）
定义用户期望状态
不同资源差异极大（如 Pod 的容器定义，Deployment 的副本数）
使用 kubectl explain KIND.spec 查看帮助

`status`

由 Controller Manager 自动维护
记录当前真实状态
用户不可修改

控制器持续比对 spec 与 status，确保两者一致。

6 获取清单帮助

命令行帮助

# 查看资源整体结构
kubectl explain pods

# 查看嵌套字段
kubectl explain pods.spec.containers.ports.containerPort

# 指定 API 版本（如 HPA 有 v1/v2）
kubectl explain hpa --api-version=autoscaling/v2

所有可通过 kubectl api-resources 列出的资源都支持 explain。

二、创建资源清单文件

1 使用 `--dry-run` 生成模板

# 模拟创建并输出 YAML
kubectl create namespace test --dry-run=client -o yaml

# 保存为文件
kubectl create deploy nginx --image=nginx --dry-run=client -o yaml > nginx-deploy.yaml

推荐方式：快速生成合法模板，再按需修改。

2 从现有资源导出

kubectl get pod my-pod -o yaml > my-pod.yaml

导出的 YAML 包含系统字段（如 status、resourceVersion），部署前建议清理。

3 从 Docker Compose 转换

使用 Kompose 工具：

官网：http://kompose.io
文档：Kubernetes 官方指南

kompose convert -f docker-compose.yml

总结建议：

日常开发优先使用 YAML + kubectl explain + --dry-run
复杂资源可先部署再导出修改
始终验证 YAML 语法，避免缩进错误

4.通过 Visual Studio Code 自动生成 YAML文件

1 安装 Visual Studio Code

Download Visual Studio Code - Mac, Linux, Windows

2 安装扩展 YAML (redhat)

3 安装扩展 Kubernetes Templates

4 创建 YAML后缀的文件

创建文件后,在内容器输入相创建的资源类型,选中后自动生成YAML模板

三、资源对象的管理方式

Kubernetes API Server 基于 声明式编程（Declarative） 设计：用户只需定义期望状态，系统自动执行操作使实际状态趋近该目标。例如，若 Deployment 期望 3 个 Pod，而当前只有 2 个，系统会自动创建第 3 个。

同时，Kubernetes 也支持 指令式操作（Imperative），即通过命令直接执行具体动作（如创建、删除）。

kubectl 提供三类资源管理方式：

1. 指令式命令（Imperative Commands）

命令示例：kubectl run、expose、delete、get
特点：
- 直接通过命令行参数操作资源
- 适合一次性、临时任务
- 不依赖配置文件
缺点：难以版本控制，不适合复杂或重复部署

示例：

kubectl run nginx --image=nginx --replicas=3

2. 指令式对象配置（Imperative Object Configuration）

命令示例：kubectl create、delete、replace、edit
特点：
- 基于 YAML/JSON 配置文件操作
- 每次操作直接作用于集群中的活动对象
缺点：
- 无幂等性：重复执行可能报错（如 create 已存在资源）
- 会丢失对象当前状态（如 replace 完全覆盖）
- 不推荐用于生产环境

示例：

kubectl create -f deploy.yaml
kubectl replace -f deploy.yaml

3. 声明式对象配置（Declarative Object Configuration）

核心命令：kubectl apply、patch
特点：
- 提交配置清单，由系统自动计算差异并应用变更
- 支持目录批量操作：
```
kubectl apply -f file.yaml
kubectl apply -f ./configs/
kubectl apply -f https://example.com/deploy.yaml
```
- 每次 apply 会将配置快照存入对象注解：
  kubectl.kubernetes.io/last-applied-configuration
- 通过三方比对（当前状态、上次配置、新配置）实现精准更新
优点：
- 幂等性：可安全重复执行
- 支持 GitOps 和版本控制
- 生产环境强烈推荐