《 Kubernetes进阶实战》一3.2.4资源配置清单格式文档

3.2.4 资源配置清单格式文档

       定义资源配置清单时，尽管apiVersion、kind和metadata有章可循，但spec字段对不同的资源来说却是千差万别的，因此用户需要参考Kubernetes API的参考文档来了解各种可用属性字段。好在，Kubernetes在系统上内建了相关的文档，用户可以使用“kubectl explain”命令直接获取相关的使用帮助，它将根据给出的对象类型或相应的嵌套字段来显示相关的下一级文档。例如，要了解Pod资源的一级字段，可以使用类似如下的命令，命令结果会输出支持使用的各一组字段及其说明：
             ~]$ kubectl explain pods
        需要了解某一级字段表示的对象之下的二级对象字段时，只需要指定其一级字段的对象名称即可，三级和四级字段对象等的查看方式依此类推。例如查看Pod资源的Spec对象支持嵌套使用的二级字段，可使用类似如下的命令：
                 ~]$ kubectl explain pods.spec
                 RESOURCE: spec <Object>

                 DESCRIPTION:
                 Specification of the desired behavior of the pod. ……

                 PodSpec is a description of a pod.

                 FIELDS:
                 activeDeadlineSeconds        <integer>
                 Optional duration in seconds the pod may be active on the node relative to
                 StartTime before the system will actively try to mark it failed and kill
                 associated containers. Value must be a positive integer.
                 ……
                 containers   <[]Object> -required-
                 List of containers belonging to the pod. Containers cannot currently be
                 added or removed. There must be at least one container in a Pod. Cannot
                 be updated.
                 ……
       对象的spec字段的文档通常包含RESOURCE、DESCRIPTION和FIELDS几节，其中FIELDS节中给出了可嵌套使用的字段、数据类型及功能描述。例如，上面命令的结果显示在FIELDS中的containers字段的数据类型是一个对象列表（[]Object），而且是一个必选字段。任何值为对象类型数据的字段都会嵌套一到多个下一级字段，例如，Pod对象中的每个容器也是对象类型数据，它同样包含嵌套字段，但容器不支持单独创建，而是要包含于Pod对象的上下文中，其详细信息可通过三级字段来获取，命令及其结果示例如下：
                       ~]$ kubectl explain pods.spec.containers
                       RESOURCE: containers <[]Object>

                       DESCRIPTION:
                             List of containers belonging to the pod. Containers cannot currently be added
                       or removed. There must be at least one container in a Pod. Cannot be updated.

                       A single application container that you want to run within a pod.

                   FIELDS:
                       args <[]string>
                       Arguments to the entrypoint. The docker image's CMD is used if this is not
                         provided. ……

                        command      <[]string>
                        Entrypoint array. Not executed within a shell. The docker image's
                        ENTRYPOINT is used if this is not provided. ……

                        env  <[]Object>
                        List of environment variables to set in the container. Cannot be updated.

                        ……
       内建文档大大降低了用户手动创建资源配置清单的难度，尝试使用某个资源类型时，explain也的确是用户的常用命令之一。熟悉各常用字段的功用之后，以同类型的现有活动对象的清单为模板可以更快地生成目标资源的配置文件，命令格式为“kubectl get TYPE NAME -o yaml --export”，其中--export选项用于省略输出由系统生成的信息。例如，基于现在的Deployment资源对象myapp生成配置模板deploy-demo.yaml文件，可以使用如下命令：
                      ~]$ kubectl get deployment myapp -o yaml --export > deploy-demo.yaml
       通过资源清单文件管理资源对象较之直接通过命令行进行操作有着诸多优势，具体包括命令行的操作方式仅支持部分资源对象的部分属性，而资源清单支持配置资源的所有属性字段，而且使用配置清单文件还能够进行版本追踪、复审等高级功能的操作。本书后续章节中的大部分资源管理操作都会借助于资源配置文件进行。