容器与云原生 / 系统课时

YAML 资源清单结构

YAML 资源清单结构

Kubernetes YAML 清单是提交 API 对象的常用载体。本课将用一个可创建的 Pod 文件说明顶层字段、嵌套规格、列表和字符串的组织方式,并建立从编写、校验到提交结果检查的完整流程。

学习目标

  • 正确组织 apiVersion、kind、metadata 与 spec。
  • 掌握 YAML 缩进、映射、列表和字符串的常见写法。
  • 能使用 kubectl 提交清单并验证创建结果。

顶层字段决定对象身份

一份单对象清单通常从四个顶层字段开始。apiVersion 指定 API 组和版本,kind 指定资源类型,metadata 提供名称与标签,spec 描述该类型的期望配置。字段名称区分大小写,Deployment 不能写成 deployment。

metadata.name 是对象名称,metadata.namespace 可显式指定命名空间;省略时由命令上下文决定。labels 适合用于选择、分组和查询,值应保持短小稳定。annotations 不参与选择,适合保存说明、外部系统标识或工具元数据。

缩进和列表如何表达层级

YAML 使用空格表达嵌套关系,建议统一使用两个空格,不要混入制表符。键值映射写成 key: value,对象列表以 - 开头。Pod 的 containers 是列表,即使只有一个容器也必须保留列表结构;容器的 ports 又是该容器内部的列表。

布尔值、数字和字符串会被解析为不同类型。镜像标签、版本号、看起来像布尔值的普通文本,必要时应使用引号固定为字符串。包含冒号、井号或前后空格的值也应加引号,避免被 YAML 解析器误解。

编写一个完整 Pod 清单

将下面内容保存为 pod.yaml。这个清单创建一个运行 Nginx 的 Pod,并通过标签标识应用与环境。

yaml
apiVersion: v1
kind: Pod
metadata:
  name: yaml-demo
  labels:
    app: yaml-demo
    environment: learning
  annotations:
    lesson: "yaml-resource-manifest"
spec:
  containers:
    - name: web
      image: nginx:1.27
      ports:
        - name: http
          containerPort: 80
  restartPolicy: Always

spec.containers 中的每一项都必须有容器名称和镜像。containerPort 只声明容器监听端口,不会自动创建 Service,也不会把端口暴露到集群外部。restartPolicy: Always 是 Pod 的默认策略,这里显式写出便于理解。

提交并验证结果

在已连接 Kubernetes 集群、当前命名空间具有创建 Pod 权限的前提下执行:

bash
kubectl apply -f pod.yaml
kubectl get pod yaml-demo

预期输出如下。READY 和 STATUS 在镜像拉取期间可能短暂显示其他值,AGE 会随时间变化。

text
pod/yaml-demo created
NAME        READY   STATUS    RESTARTS   AGE
yaml-demo   1/1     Running   0          <TIME>

提交前可先运行 kubectl apply --dry-run=server -f pod.yaml,让 API Server 按当前集群的资源模式和准入策略验证清单。客户端 YAML 能成功解析,不代表字段一定属于该 kind;服务端验证才能发现版本不支持、字段拼写错误或策略拒绝等问题。

常见结构错误

缩进错误会改变父子关系,最常见的是把 image 与 containers 放到同一层。把只接受对象的字段写成列表,或把列表字段漏掉 -,也会导致解码失败。遇到报错时应从提示的字段路径回到清单,逐层核对缩进和数据类型。

另一个常见问题是 apiVersion 与 kind 不匹配,例如 Deployment 应使用 apps/v1,而 Pod 使用 v1。对于 Deployment,还必须保证 spec.selector.matchLabels 与 spec.template.metadata.labels 一致,否则 API Server 会拒绝创建。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

YAML 资源清单结构

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通