【Kubernetes | Pod 系列】Pod的 YAML 清单文件详解

3. Pod的 YAML 清单文件

3.1 获取资源对象 YAML

在 Kubernetes 中快速获取资源对象的 YAML 清单文件，以 Pod 为例，使用命令

kubectl run pod1 --image=nginx --dry-run=client -o yaml > pod1.yaml

此时，在当前目录下已经创建了一个最简单的 YAML 清单文件，其内容如下所示

apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: pod1
  name: pod1
spec:
  containers:
  - image: nginx
    name: pod1
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

3.2 解析 YAML 清单文件

该 YAML 文件定义了一个 Pod 的属性。在K8S中所有的对象资源的 YAML 清单中都包含 五个基本属性：

• apiVersion：表示对象资源的 API 版本，不同资源的 apiVersion 不一样。
• kind：表示K8S中的对象资源种类，K8S中有很多对象资源，例如：Pod，Deployment，Service，Namespace等。
• metadata：记录了对象资源的元数据，元数据字段下也包含多个属性。
• spec：表示规约，定义对象资源一些属性。
• status：记录了当前对象资源的状态参数。

（1）apiVersion

apiVersion: v1

apiVersion 顾名思义 API 版本其参数值的默认形式为：GROUP/VERSION，例如：policy.k8s.io/v1。

其中 GROUP 表示 API 组，即一组一起公开的资源。其中 核心（core） 也被称为 legacy组， 核心组并不作为 apiVersion 字段的一部分，所以其在 YAML 清单中的表现为： apiVersion: v1。

查看 Kubernetes API 中全部的 API 组

• 查阅 Kubernetes API 参考文档 。
• 使用 kubelet 工具在 Master 节点中使用命令：kubectl api-versions，关于示例请查阅博文【输出内容详细版】查看Kubernetes集群基本信息（初学者版） 中的【5. 查看可用的 API 版本】

VERSION 表示 API组的迭代版本。不同 API 版本代表着不同稳定性和支持级别。Kubernetes API 组的级别（稳定性）分为3类：

• Alpha：版本名称包含 alpha（例如：v1alpha1）。
• Beta：版本名称包含 beta（例如：v2beta3）。
• Stable：版本名称如 vX，其中 X 为整数。

Alpha 级别是最不稳定的，该级别的 API 默认被禁用且必须在 kube-apiserver 配置中显式启用才能使用。启动Alpha 级别的 API 可能会暴露出 Bug。由于缺陷风险增加和缺乏长期支持，建议该类 API 仅用于短期测试集群。

Beta 级别是相对稳定的，该功能被很好的测试过。启用某个特性被认为是安全的。内置的 Beta API 版本默认被禁用且必须在 kube-apiserver 配置中显式启用才能使用。该类 API 也不建议生产使用。后续发布版本可能会有不兼容的变动。 一旦 Beta API 版本被弃用且不再提供服务， 则使用 Beta API 版本的用户需要转为使用后续的 Beta 或 Stable API 版本。

Stable 级别是稳定版的 API。特性的 Stable 版本会出现在后续很多版本的发布软件中。 Stable API 版本仍然适用于 Kubernetes 主要版本范围内的所有后续发布， 并且 Kubernetes 的主要版本当前没有移除 Stable API 的修订计划。

（2）kind

kind: Pod

Kind 表示 K8S 中对象资源的类型。例如 Pod, ReplicationController, Service, Namespace, Node。在 K8S 中每个 API 组下又划分很多对象资源，为了区分它们的不同，使用 Kind 参数标识每个受支持的资源类型。

查看 Kubernetes 中全部的对象资源类型

使用命令：kubectl api-resources。关于示例请查阅博文【输出内容详细版】查看Kubernetes集群基本信息（初学者版） 中的【4. 查看可用的 API 资源】。

（3）metadata

metadata:					#元数据字段
  creationTimestamp: null	#
  labels:					#标签字段，一个资源对象可以有多个标签，可根据标签来筛选
    run: pod1				#标签1
  name: pod1				#定义Pod名称
  namespace: default		#定义pod(资源对象)所在的命名空间。默认为当前命名空间。

关于资源的元数据，例如它的名称、类型、api 版本、注释和标签。这包含可能由最终用户和系统更新的字段（例如注释）。

K8S中的每个对象种类都必须有一个名为 metadata（元数据）的嵌套字段来保存该对象资源的，并且必须包含以下元数据（必选）：

• namespace（名字空间）：名字空间是一个与DNS兼容的标签，对象资源被细分到其中。默认的命名空间是 “default”。
• name（名称）：对象资源名称，在当前的命名空间中唯一的标识这个对象资源。这个值在检索单个对象时用于检索路径上。
• uid：一个在时间和空间上唯一的值（通常是RFC 4122生成的标识符），用于区分被删除和重新创建的具有相同名称的对象。

每个对象资源又可以包含以下元数据（可选）：

• resourceVersion：用于识别对象的内部版本，用于记录该资源对象何时被更新过。

• generation：表示所需状态的特定生成的序列号。由系统设置，每个资源单调递增。可以进行比较，比如RAW和WAW的一致性。之后博文会以例子解释

• creationTimestamp：用于记录对象被创建的日期和时间，详见 RFC 3339

• deletionTimestamp：该日期和时间之后，对象资源将被删除。这个字段由服务器在用户请求优雅删除时设置，而不是由客户端直接设置。之后博文会以例子解释

• labels：其值是键值对，用于区分组织和分类对象。通俗点说是给对象资源打标签，可用于筛选。

• annotations：其值也是键值对，对象设置了该字段后可被外部工具用来存储和检索关于此对象的任意元数据。之后博文会以例子解释

（4）spec

spec:
  containers:
  - image: nginx
    name: pod1
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always

spec 规范是由用户自定义，描述了对象资源创建后的期望状态。spec 规范是对期望状态的完整描述，包括由用户提供的配置设置、由系统扩展的默认值，以及由其他生态系统组件（如调度器、自动缩放器）创建后初始化或以其他方式改变的属性，并与 API 对象一起被持久化在稳定存储中。如果spec 规范被删除，该对象将被从 K8S 中清除。

此字段在创建或更新对象时填写。

spec 定义Pod一些属性信息，包括container（容器），DNS策略（dnspolicy），重启策略（restartpolicy）。

用户被授予对 spec 的完全写权限。而相关的控制器被授予对 spec 的只读权限。

（5）status

status: {}

由服务器填写的，报告了系统的当前状态。在大多数情况下，用户不需要更改它。我们在 spec 中填入了对象资源创建后的期望状态，status 则是对象资源实际被创建后的状态。如果 spec 中的值与 status 中的值一致，说明该对象资源正常运行，状态良好。如果不一致，说明该对象资源是有问题的。

用户被授予对 status 的只读权限。而相关的控制器被授予对 status 的完全写权限。

示例中的 status 为一个空字典是正常现象，因为此时 Pod 对象还未创建，所以 status 为空。

3.3 K8S中 YAML 文件语法

关于 YAML 的语法，需要记住以下几点

• 大小写敏感。
• 通过缩进表示层级关系。
• 对于缩进敏感，不支持tab缩进，只支持空格键。（缩进的空格数目不重要，相同层级左对齐即可）
• 使用 # 表示注释。
• 可与json格式转换，支持字典数据类型与列表数据类型。

（1）空格缩进，禁止tab

YAML 文件对缩进的要求很严格，禁止使用tab代替缩进，要使用空格缩进。

缩进的空格数目不重要，只需要相同层级左对齐即可。为了保持 YAML 清单的赏心悦目，一般默认每个缩进为两个空格。

metadata:
  creationTimestamp: null
  labels:
    run: pod1
  name: pod1

（2）参数名遵循驼峰命名法

K8S 对象清单中每个参数名首字母小写，后面的每个单词的首字母都要大写

apiVersion: v1

（3）参数值大小写随意，关键字除外

K8S 对象清单中的参数值在一般情况下可以随意大小写，但如果该参数值是关键字则必须首字母大写。

关键字的意思是：有些参数值是固定的，可能一个参数的值只有三个关键字可选。这三个关键字是被写死的。

spec:
  containers:
  ...
    name: pod2
    ...
  dnsPolicy: ClusterFirst
  restartPolicy: Always

（4）字典与列表的区别

在 YAML 清单中，一般状态下的格式是字典类型，而如同：- image 属于列表。

spec:
  containers:		    #container字段，定义容器属性
  - image: nginx	    #定义容器使用的镜像
    name: vmware-nginx  #定义容器名称
    resources: {}	    #定义容器的计算资源约束，例如最多能消耗多少cpu或内存
  - image: tomcat 	    #定义第二个容器
    name: vmware-tmcat  #容器名称不能重复
    resources: {}

上述示例可表示为

{'spec': {'containers': [{'image': 'nginx','name': 'vmware-nginx','resources': {},},
                         {'image': 'tomcat','name': 'vmware-tmcat','resources': {},}
                        ],
         }
}

与 - image: nginx中 image 参数左对齐平级的参数都在同一个列表下，直至遇到下一个 - xxx 参数。

• 最外层是字典A：{'spec': {字典B}}，即 spec 参数的值为一个字典。
• 字典B：{'containers': [列表A]}，即 containers 参数值为一个列表。
• 列表A：[{字典C}, {字典D}]，即列表A中两个元素是两个字典。
• 字典C定义了容器vmware-nginx。字典D定义了容器vmware-tmcat 。

我们可以简单将 YAML 文件理解为字典与列表的嵌套集合，字典中嵌套列表，列表中嵌套字典，两者相互嵌套。

请大家务必搞清 K8S 对象 YAML 文件的各项参数与其值的嵌套关系，在后续进阶博客中，我们会使用编程语言的客户端来对 K8S 对象的增删改查进行细微操控。
其中的难点是对 YAML 文件中字典与列表嵌套关系的理解。

3.3 查看 YAML 清单中参数关键字

除了使用K8S官方文档中给出的 YAML 对象清单之外，我们还可以借助 kubectl 工具提供 查询K8S 对象结构（YAML 清单）。使用命令

kubectl explain object_name

以对象 Pod 为例

查看 Pod 对象结构下存在的属性

kubectl explain pod #或者kubectl explain pods

如下图所示：

• 红框位置表示字段名
• 黄框位置表示该字段值的数据类型
• 篮筐位置表示该字段的含义，以及涉及到的K8S文档

查看对象 Pod 的 spec 字段下的属性

查看某一对象或字段下的属性，使用英文符号的句号 . 连接。

Pod 的 spec 字段下有很多属性。

kubectl explain pod.spec

查看 Pod 的 spec 字段下 containers 参数的属性

kubectl explain pod.spec.containers

其它的资源对象的参数关键字仿照例子查询即可。

参考资料

• Kubernetes Documentation：https://kubernetes.io/docs/home/
• Kubernetes Github：https://github.com/kubernetes/kubernetes