Kubernetes Lables & Selectors & Annotations

Labels and Selectors | Kubernetes
Annotations | Kubernetes

一、Lables vs Annotations

Labels ，标签，附加到对象（eg:pods）的键值对。Labels 用于定义对象的标识属性，对用户很有意义，但是不直接表示核心系统的语义。Labels 可以被用于组织和选择对象的子集。Labels可以在创建时候添加到对象，然后可以随时添加、修改。

每个对象都可以有一组 Key/Value Lables 定义；但是对于该对象，每个Key必须是唯一的。

"metadata": {
  "labels": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

Annotations ，注释。用于将非标识元数据附加到对象。客户端可以检索到该元数据，比如tools软件和libratries库。与Lables类似，也是键值对：

"metadata": {
  "annotations": {
    "key1" : "value1",
    "key2" : "value2"
  }
}

可以记录在 annotations 的一些范例：

声明配置层管理的 Fields 。将这些 fields 作为 annotations 添加，可以区分默认值是由客户端还是由服务器端设置，可以区分是自生的fields还是auto-sizing or auto-scaling系统设置的fields。
编译、版本、镜像信息，比如时间戳、版本ID、git 分支、PR 编号、镜像哈希、注册地址。
日志、监控、分析、审计仓库的指针。
用户debug调试的客户端库or工具，比如name, version, build 信息。
用户来源 or 工具/系统来源，比如来自其他生态组件的相关对象的URLs。
轻量的 roolout 工具元数据：比如，config or checkpoints。
负责人的联系电话，或者指定可以找到该信息的目录入口，比如团队web站点。

二、Lables & Annotations 语法和字符集

Lables syntax-and-character-set
Annotations syntax-and-character-set

都是键值对结构。都由两个片段组成：prefix（可选） and name，以 (/)分隔。

Name必选。要求少于63字符，以字母、数字([a-z0-9A-Z])作为开头、结尾，中间可以包含中横线 (-)，下划线 (_)，点号 (.)以及字母、数字。

Prefix可选。 Prefix必须是DNS子域：以点(.)分隔，不超过253字符，后缀反斜号 (/) 的DNS标签。

如果省略prefix，将被假设用户私有。自动化系统组件 (e.g. kube-scheduler, kube-controller-manager, kube-apiserver, kubectl, or other third-party automation) 必须指派一个prefix。

kubernetes.io/ 和 k8s.io/ 是 Kubernetes 核心组件的预留 prefixes 。

如下某Pod的配置范例：

apiVersion: v1
kind: Pod
metadata:
  name: label-demo
  labels:
    environment: production
    app: nginx
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

apiVersion: v1
kind: Pod
metadata:
  name: annotations-demo
  annotations:
    imageregistry: "https://hub.docker.com/"
spec:
  containers:
  - name: nginx
    image: nginx:1.14.2
    ports:
    - containerPort: 80

三、为什么使用 Lables

Labels 允许用户将其组织结构以松散耦合的方式映射到系统对象上，而不需要客户端存储该映射。

Service deployments 和 batch processing pipelines 通常是多维实体 (e.g., 多区域部署，多版本跟踪，多层，每层多服务。)。管理通常需要交叉操作，这打破了严格的层次结构的封装，特别是由基础架构而不是由用户决定的层次结构。

范例标签：

"release" : "stable", "release" : "canary"
"environment" : "dev", "environment" : "qa", "environment" : "production"
"tier" : "frontend", "tier" : "backend", "tier" : "cache"
"partition" : "customerA", "partition" : "customerB"
"track" : "daily", "track" : "weekly"

更多范例参见常用 Labels。

四、Label selectors 标签选择器

不同于 names and UIDs，标签不提供唯一性。通常，我们期望很多对象带有同一标签。

通过Label selectors，客户端/用户可以识别一组对象。Label selector 是Kubernetes核心分组原语。

API 支持两种类型的 selectors： equality-based (基于等式) and set-based（基于集合）。一个 label selector 可以有多个需求组成，以逗号分隔。多个需求，都必须满足，所以逗号就起到了逻辑AND (&&) 运算符的作用。

空选择器或未定义选择器的语义取决于上下文，使用了选择器的API类型应记录其合法性和含义。

注意： 对于一些API类型，比如ReplicaSets，在同一个命名空间下两个实例的 label selectors 不能重叠，否则控制器会识别为冲突指令，无法确定该存在多少副本。

警告： 无论是 equality-based 还是 set-based 条件，都不会存在逻辑 OR (||) 运算符。

Equality-based requirement

基于 Equality-（等号） or inequality-（不等号）的需求条件，允许通过lable的键值来过滤。匹配对象必须满足所有指定的标签约束，尽管它们也可能有其他标签。允许三种运算符=，==，!=。前面两个代表等于，第三个代表不等于。范例：

environment = production
tier != frontend

上选择器通过key 等于 environment and value 等于 production 来选择资源。
下选择器通过key 等于 tier and value 不等于 frontend，以及不存在tier key标签的条件来选择资源。
可以通过如下来选择 production 排除 frontend ： environment=production,tier!=frontend。

基于等式标签需求的一个场景是，Pods选择node的选择标准。比如，如下范例Pod通过标签"accelerator=nvidia-tesla-p100"选择nodes。

apiVersion: v1
kind: Pod
metadata:
  name: cuda-test
spec:
  containers:
    - name: cuda-test
      image: "k8s.gcr.io/cuda-vector-add:v0.1"
      resources:
        limits:
          nvidia.com/gpu: 1
  nodeSelector:
    accelerator: nvidia-tesla-p100

Set-based requirement

基于集合的标签需求允许根据value的集合来过滤key。支持三种运算符：in，notin ， exists (only the key identifier)。如下：

environment in (production, qa)
tier notin (frontend, backend)
partition
!partition

第一范例，选择 key 等于 environment , value 等于production 或者 qa 的资源。
第二返利，选择 key 等于 tier ，value 不等于frontend 和 backend ，以及所有不包含tier key标签的资源。
第三范例，选择包含key partition 的标签的资源；没有选择value。
第四范例，选择不包含key partition 的标签的资源；没有选择value。

同样，逗号分隔符作为 AND 运算符。所以，通过partition key (no matter the value) 以及 environment 不是 qa 作为条件过滤，可以归纳为partition,environment notin (qa)。基于集合的标签选择器是等式的一般表现形式，因为 environment=production 等价于 environment in (production)； != 等价于 notin。

基于集合的需求可以混合使用基于等式的需求。范例： partition in (customerA, customerB),environment!=qa

API

LIST and WATCH filtering

LIST and WATCH 操作可以通过查询参数指定标签选择器来过滤对象。两种需求都满足：

基于等式需求：?labelSelector=environment%3Dproduction,tier%3Dfrontend
基于集合需求：?labelSelector=environment+in+%28production%2Cqa%29%2Ctier+in+%28frontend%29

范例：

kubectl get pods -l environment=production,tier=frontend
kubectl get pods -l 'environment in (production),tier in (frontend)'
kubectl get pods -l 'environment in (production, qa)'
kubectl get pods -l 'environment,environment notin (frontend)'

Set references in API objects

一些Kubernetes对象，比如 services 和 replicationcontrollers，使用标签选择器来设置其他资源集合，比如 pods。

1. Service and ReplicationController

Service 目标的 pods 集合通过标签选择器来定义。相似的，replicationcontroller 应该管理的pods数量也通过标签选择器定义。

标签选择器使用maps定义，以json或yaml文件的格式，仅支持基于等式的需求：

"selector": {
    "component" : "redis",
}

selector:
    component: redis

该选择器等价于 component=redis or component in (redis)。

2. Resources that support set-based requirements

更新一些资源，比如Job, Deployment, ReplicaSet, and DaemonSet，还支持基于集合的需求。

selector:
  matchLabels:
    component: redis
  matchExpressions:
    - {key: tier, operator: In, values: [cache]}
    - {key: environment, operator: NotIn, values: [dev]}

matchLabels 是{key,value}的一个映射。 matchLabels 映射内的一个{key,value} 等同于matchExpressions下的一个元素，matchExpressions下 key 是 "key"， operator 是 "In"，values 属组值包含 "value"。

matchExpressions 是pod选择器需求的列表。合法元算符包括 In, NotIn, Exists, and DoesNotExist。假如是 In and NotIn，value 集合不能为空。

matchLabels 和 matchExpressions 所有的需求，都必须是与运算 -- 它们必须全部满足。

3. Selecting sets of nodes

选择over标签的一个用例是约束pod可以调度到的节点集。请参阅node selection 。