Kubernetes进阶实战（第2版）
上QQ阅读APP看书，第一时间看更新
上一章目录下一章

3.6　资源注解

除了标签之外，Kubernetes的API对象还支持使用资源注解（annotations）。类似于标签，注解也是键值型数据，不过它不能用作标签，也不能用于挑选API对象。资源注解的核心目的是为资源提供“元数据”信息，但注解的值不受字符数量的限制，它可大可小，可以是结构化或非结构化形式，也支持在标签中禁用其他字符。

资源注解可由用户手动添加，也可由工具程序自动附加并使用。在Kubernetes的新版本（Alpha或Beta阶段）中计划为某资源引入新字段时常以注解方式提供，以避免字段名称变更、增删等变动给用户带去困扰，一旦确定使用这些新增字段，则将其引入资源规范中并淘汰相关的注解信息。另外，为资源添加注解也可让其他用户快速了解资源的相关信息，例如创建者身份等。以下为常用的场景案例。

▪由声明式配置（例如apply命令）管理的字段：将这些字段定义为注解，有助于识别由服务器或客户端设定的默认值、系统自动生成的字段以及由自动伸缩系统生成的字段。

▪构建、发行或镜像相关的信息，例如时间戳、发行ID、Git分支、PR号码、镜像哈希及仓库地址等。

▪指向日志、监控、分析或审计仓库的指针。

▪由客户端库或工具程序生成的用于调试目的的信息：例如名称、版本、构建信息等。

▪用户或工具程序的来源地信息，例如来自其他生态系统组件的相关对象的URL。

▪轻量化滚动升级工具的元数据，例如config及checkpoints。

▪相关人员的电话号码等联系信息，或指向类似信息的可寻址的目录条目，例如网站站点。

kubectl get -o yaml和kubectl describe命令均能显示资源的注解信息。例如，下面的命令打印出了节点对象k8s-master01.ilinux.io的注解信息：

~ $ kubectl get nodes k8s-master01.ilinux.io -o yaml    
apiVersion: v1
kind: Node
metadata:
  annotations:
    flannel.alpha.coreos.com/backend-data: '{"VtepMAC":"da:49:da:c7:8c:a1"}'
    flannel.alpha.coreos.com/backend-type: vxlan
    flannel.alpha.coreos.com/kube-subnet-manager: "true"
    flannel.alpha.coreos.com/public-ip: 172.29.9.1
    kubeadm.alpha.kubernetes.io/cri-socket: /var/run/dockershim.sock
    node.alpha.kubernetes.io/ttl: "0"
    volumes.kubernetes.io/controller-managed-attach-detach: "true"
  creationTimestamp: "2020-02-16T06:23:03Z"
  ……

annotations可在资源创建时由metadata.annotations字段指定，也可随时按需在活动的资源上使用kubectl annotate命令进行添加。例如，可以使用下面的命令为eshop名称空间添加注解：

~$ kubectl annotate namespaces/eshop ilinux.io/created-by='cluster admin'
namespace/eshop annotated

删除活动对象上的注解时同样要使用kubectl annotate命令，但仅需指定注解键名并紧跟一个减号“–”即可。例如，下面的命令会删除eshop名称空间中的ilinux.io/created-by注解：

~$ kubectl annotate namespaces/eshop ilinux.io/created-by-
namespace/eshop annotated

有些应用程序还支持通过注解信息进行高级配置，例如ingress-nginx提供了众多专用的注解，以允许用户向应用注入指定的高级配置。在下面配置清单中的Ingress资源示例中，注解nginx.org/server-snippets还使用了多行值的格式。

apiVersion: networking.k8s.io/v1beta1
kind: Ingress
metadata:
  name: cafe-ingress-with-annotations
  annotations:
    nginx.org/proxy-connect-timeout: "30s"
    nginx.org/proxy-read-timeout: "20s"
    nginx.org/client-max-body-size: "4m"
    nginx.org/server-snippets: |
      location / {
        return 302 /somewhere;
      }
spec:
  rules:
  ……

Nginx的Ingress Controller对应的Pod对象在读取Ingress配置清单时会将注解中给定的配置转换为Nginx程序的配置信息，并由相应的进程加载使用。

上一章目录下一章