concepts/overview/working-with-objects/annotations/

Annotations

You can use Kubernetes annotations to attach arbitrary non-identifying metadata to objects. Clients such as tools and libraries can retrieve this metadata 可以使用kubernetes注释将任意非标识元数据附加到对象。工具和库等客户端可以检索此元数据。

• Attaching metadata to objects
• Syntax and character set
• What's next

Attaching metadata to objects 将元数据附加到对象

可以使用标签或注释将元数据附加到kubernetes对象。标签可用于选择对象和查找满足特定条件的对象集合。相反，注释不用于标识和选择对象。注释中的元数据可以是小的或大的、结构化的或非结构化的，并且可以包含标签不允许的字符。
注释和标签一样，是键/值映射：

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

Here are some examples of information that could be recorded in annotations:

• Fields managed by a declarative configuration layer. Attaching these fields as annotations distinguishes them from default values set by clients or servers, and from auto-generated fields and fields set by auto-sizing or auto-scaling systems.
• Build, release, or image information like timestamps, release IDs, git branch, PR numbers, image hashes, and registry address.
• Pointers to logging, monitoring, analytics, or audit repositories.
• Client library or tool information that can be used for debugging purposes: for example, name, version, and build information.
• User or tool/system provenance information, such as URLs of related objects from other ecosystem components.
• Lightweight rollout tool metadata: for example, config or checkpoints.
• Phone or pager numbers of persons responsible, or directory entries that specify where that information can be found, such as a team web site.
• Directives from the end-user to the implementations to modify behavior or engage non-standard features.

Instead of using annotations, you could store this type of information in an external database or directory, but that would make it much harder to produce shared client libraries and tools for deployment, management, introspection, and the like.

以下是一些可以记录在注释中的信息示例：
-由声明性配置层管理的字段。将这些字段附加为注释可以将它们与客户端或服务器设置的默认值以及自动生成的字段和由自动调整大小或自动缩放系统设置的字段区分开来。
-生成、发布或图像信息，如时间戳、发布ID、Git分支、PR编号、图像哈希和注册表地址。
-指向日志记录、监视、分析或审核存储库的指针。
-可用于调试目的的客户端库或工具信息：例如，名称、版本和生成信息。
-用户或工具/系统来源信息，例如来自其他生态系统组件的相关对象的url。
-轻量级卷展栏工具元数据：例如，配置或检查点。
-负责人的电话号码或寻呼机号码，或指定在哪里可以找到该信息的目录项，例如团队网站。
-从最终用户到实现的指令，以修改行为或使用非标准功能。
与使用注释不同，您可以将此类信息存储在外部数据库或目录中，但这将使生成用于部署、管理、内省等的共享客户端库和工具变得更加困难。

Syntax and character set

Annotations are key/value pairs. Valid annotation keys have two segments: an optional prefix and name, separated by a slash (/). The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character ([a-z0-9A-Z]) with dashes (-), underscores (_), dots (.), and alphanumerics between. The prefix is optional. If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (.), not longer than 253 characters in total, followed by a slash (/).

If the prefix is omitted, the annotation Key is presumed to be private to the user. Automated system components (e.g. kube-scheduler, kube-controller-manager, kube-apiserver, kubectl, or other third-party automation) which add annotations to end-user objects must specify a prefix.

The kubernetes.io/ and k8s.io/ prefixes are reserved for Kubernetes core components.

For example, here’s the configuration file for a Pod that has the annotation imageregistry: https://hub.docker.com/ :

注释是键/值对。有效的注释键有两个段：可选的前缀和名称，用斜线（/）分隔。名称段是必需的，必须不超过63个字符，以字母数字字符（[A-Z0-9A-Z]）开头和结尾，中间有破折号（-）、下划线（u）、点（.）和字母数字。前缀是可选的。如果指定，前缀必须是DNS子域：由点（.）分隔的一系列DNS标签，总共不超过253个字符，后跟斜杠（/）。
如果省略前缀，则注释键被假定为用户专用。向最终用户对象添加注释的自动化系统组件（例如kube调度器、kube控制器管理器、kube apiserver、kubectl或其他第三方自动化）必须指定前缀。
kubernetes.io/和k8s.io/前缀是为kubernetes核心组件保留的。
例如，下面是一个pod的配置文件，其中包含注释imageregistry:https://hub.docker.com/：

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

What's next

Learn more about Labels and Selectors.

本作品采用《CC 协议》，转载必须注明作者和本文链接