【Docker学习】docker run的–annotation选项

–annotation选项

作用：这是在Docker的api1.43+提供的一个功能，向容器添加一个注解（传递给OCI运行时）。

官方网站的文档对–annotation选项惜墨如金，没有用例，也没有过多解释。因此想要学到这个选项的实际作用，还要自己来。

要想了解这个选项的用法，还要先了解OCI运行时。

OCI运行时，全称是Open Container Initiative，直译为开放容器倡议，相当于是针对容器开源的一个标准。官网是开放容器倡议 – 开放容器倡议 (opencontainers.org)。以下是官网直译：

开放容器倡议（Open Container Initiative，OCI）是一个轻量级的、开放式的治理结构（项目），在Linux基金会的支持下成立，专门用于创建围绕容器格式和运行时的开放行业标准。OCI于2015年6月22日由Docker、CoreOS以及容器行业的其他领导者共同发起。

OCI目前包含三个规范：运行时规范（runtime-spec）、镜像规范（image-spec）和分发规范（distribution-spec）。运行时规范概述了如何运行一个在磁盘上解包的“文件系统包”。在较高层面上，OCI实现会下载一个OCI镜像，然后将该镜像解包成一个OCI运行时文件系统包。此时，OCI运行时包将由OCI运行时执行。

这个整个工作流程应该支持用户从容器引擎如Docker和rkt中期望的UX：主要是能够不带任何额外参数运行一个镜像：

docker run example.com/org/app:v1.0.0<br>rkt run example.com/org/app,version=v1.0.0

为了支持这种UX，OCI镜像格式包含足够的信息来在目标平台上启动应用程序（例如命令、参数、环境变量等）。此规范定义了如何创建OCI镜像，这通常由构建系统完成，并输出镜像清单、文件系统（层）序列化以及镜像配置。在较高层面上，镜像清单包含关于镜像内容和依赖关系的元数据，包括一个或多个文件系统序列化存档的内容可寻址身份，这些存档将被解包以构成最终的可运行文件系统。镜像配置包括应用程序参数、环境等信息。镜像清单、镜像配置和一个或多个文件系统序列化的组合称为OCI镜像。

Docker将其容器格式和运行时runC捐赠给OCI，作为这一新努力的基石。您现在可以在https://github.com/opencontainers/runc找到它。

分发规范于2020年5月达到v1.0版本，并作为标准化分发容器镜像API的努力被引入OCI。然而，该规范被设计得足够通用，可以作为任何类型内容的分发机制。

开放容器倡议是一个用于创建容器开放行业标准的开放式治理结构。与开放容器倡议相关的项目可以在https://github.com/opencontainers找到，我们建议您加入https://www.opencontainers.org/community的社区。

备注：

上文中的UX，是用户体验（User Experience）的缩写，它是指用户在使用产品、服务或系统过程中的感受和体验。UX设计关注的是如何通过设计来提升用户的满意度和愉悦感，确保产品在使用过程中直观、易用并且能够满足用户的需求。

UX设计包括多个方面，如：

1. 可用性（Usability）：产品是否易于使用，用户能否轻松完成任务。
2. 交互设计（Interaction Design）：用户与产品交互的方式和过程。
3. 信息架构（Information Architecture）：如何组织和呈现信息，以便用户能够轻松找到和理解。
4. 视觉设计（Visual Design）：产品的外观和视觉风格，包括颜色、字体、布局等。
5. 内容策略（Content Strategy）：产品中内容的规划、创建和管理。
6. 用户研究（User Research）：通过研究用户的行为、需求和反馈来指导设计决策。
7. 前端开发（Front-end Development）：将设计转化为用户可以交互的实际界面。

UX设计的目标是创建一个无缝、直观且令人愉悦的用户体验，从而提高用户对产品的满意度和忠诚度。在软件开发、网站设计和产品设计中，UX都是一个至关重要的方面。

好了，下面我们就是实际操作一下，看看这个–annotation怎么用。

使用上一讲用到的alpine，将要启动的这个容器注入注解，其中注解也要是一个key，value形式，key和value都是字符串。命令如下：

docker run -dit --annotation org.opencontainers.image.url="skycreator.top" alpine

我们使用ps和inspect查看容器

在容器的配置中，”HostConfig”的块里，可以看到Annotations有我注入的注解。

关于注解

规范的几个组件，如镜像清单（Image Manifests）和描述符（Descriptors），都包含一个可选的注解（annotations）属性，其格式是通用的，并在本节中进行了定义。

这个属性包含任意元数据。

规则 

1.注解必须是一个键值映射，其中键和值都必须是字符串。 

2.虽然值必须存在，但它可以是空字符串。 

3.键在这个映射中必须是唯一的，最佳实践是对键进行命名空间划分。 

4.键应该使用反向域名表示法命名 – 例如 com.example.myKey。 

5.前缀 org.opencontainers 保留给在开放容器倡议（OCI）规范中定义的键，其他规范和扩展不得使用。

6.使用 org.opencontainers.image 命名空间的键保留给 OCI 镜像规范使用，其他规范和扩展不得使用，包括其他 OCI 规范。 

7.如果没有注解，则此属性必须不存在或为空映射。 

8.消费者在遇到未知注解键时不得生成错误。

预定义的注解键 

本规范定义了以下注解键，旨在但不仅限于用于镜像索引、镜像清单和描述符的作者。

• org.opencontainers.image.created 镜像构建的日期和时间，符合 RFC 3339。
• org.opencontainers.image.authors 负责镜像的人员或组织的联系信息（自由格式字符串）
• org.opencontainers.image.url 获取镜像更多信息（URL）的URL。
• org.opencontainers.image.documentation 获取镜像文档的URL（字符串）
• org.opencontainers.image.source 获取构建镜像的源代码的URL（字符串）
• org.opencontainers.image.version 打包软件的版本
  • 版本可能与源代码仓库中的标签或标记匹配 
  • 版本可能是语义版本兼容的
• org.opencontainers.image.revision 打包软件的源代码控制修订标识符。
• org.opencontainers.image.vendor 分发实体、组织或个人的名称。
• org.opencontainers.image.licenses 包含软件分发的许可（SPDX 许可表达式）。
• org.opencontainers.image.ref.name 目标引用的名称（字符串）。
  • 应在镜像布局中的 index.json 上的描述符上考虑有效。
  • 值的字母数字字符集应符合 A-Za-z0-9 的字母数字和分隔符集合 -._:@/+。
  • 引用必须符合以下语法：

ref ::= component (“/” component)* 
component ::= alphanum (separator alphanum)* 
alphanum ::= [A-Za-z0-9]+ 
separator ::= [-._:@+] | “–”

• org.opencontainers.image.title 镜像的人类可读标题（字符串）
• org.opencontainers.image.description 镜像中打包软件的人类可读描述（字符串）
• org.opencontainers.image.base.digest 镜像基础的镜像摘要（字符串）
  • 这应该是与镜像共享零索引层的直接镜像，例如来自 Dockerfile FROM 语句。
  • 这不应该引用用于生成镜像内容的任何其他镜像（例如，多阶段 Dockerfile 构建）。 
• org.opencontainers.image.base.name 镜像基础的镜像引用（字符串）
  • 这应该是 distribution/distribution 定义的格式的镜像引用。 
  • 这应该是一个完全限定的引用名，不带任何假定的默认注册表。 （例如，registry.example.com/my-org/my-image:tag 而不是 my-org/my-image:tag）。 
  • 这应该是与镜像共享零索引层的直接镜像，例如来自 Dockerfile FROM 语句。 
  • 这不应该引用用于生成镜像内容的任何其他镜像（例如，多阶段 Dockerfile 构建）。 
  • 如果指定了 image.base.name 注解，则 image.base.digest 注解应该是 image.ref.name 注解引用的清单的摘要。

与标签架构的向后兼容性 

标签架构定义了许多用于容器镜像的常规标签，现在这些标签已经被以 org.opencontainers.image 开头的注解所取代。

尽管鼓励用户使用 org.opencontainers.image 键，但工具可以选择支持使用 org.label-schema 前缀的兼容注解，如下所示。