镜像 [image.openshift.io/v1] - 镜像 API | API 参考 | OpenShift Container Platform 4.17

规格
API端点

描述: 镜像是容器镜像及其元数据在特定时间点的不可变表示。镜像的命名是通过对其内容（元数据和内容）进行哈希计算得到的，任何格式、内容或元数据的更改都会导致新的名称。镜像资源主要供集群管理员和集群镜像注册表等集成使用——最终用户通过 imagestreamtags 或 imagestreamimages 资源访问镜像。虽然镜像元数据存储在 API 中，但任何实现容器镜像注册表 API 的集成都必须为原始清单数据、镜像配置和层内容提供自己的存储。

兼容性级别 1：在主要版本中稳定至少 12 个月或 3 个次要版本（以较长者为准）。
类型: 对象

规范

属性类型描述

属性	类型	描述
`apiVersion`	`字符串`	APIVersion 定义了此对象表示的版本化模式。服务器应将识别的模式转换为最新的内部值，并可能拒绝无法识别的值。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`dockerImageConfig`	`字符串`	DockerImageConfig 是运行时用于设置容器的 JSON 数据块。这是清单模式 v2 的一部分。当镜像表示清单列表时，将不会设置此值。
`dockerImageLayers`	`数组`	DockerImageLayers 表示镜像中的层。如果镜像未定义该数据或镜像表示清单列表，则可能未设置此值。
`dockerImageLayers[]`	`对象`	ImageLayer 表示镜像的单个层。一些镜像可能有多个层，一些可能没有。
`dockerImageManifest`	`字符串`	DockerImageManifest 是清单的原始 JSON 数据。
`dockerImageManifestMediaType`	`字符串`	DockerImageManifestMediaType 指定清单的 mediaType。这是清单模式 v2 的一部分。
`dockerImageManifests`	`数组`	DockerImageManifests 在镜像表示清单列表时保存有关子清单的信息。当此字段存在时，不应指定 DockerImageLayers。
`dockerImageManifests[]`	`对象`	ImageManifest 表示清单列表的子清单。Digest 字段指向常规 Image 对象。
`dockerImageMetadata`	`RawExtension`	DockerImageMetadata 包含有关此镜像的元数据。
`dockerImageMetadataVersion`	`字符串`	DockerImageMetadataVersion 传达对象的版本，如果为空，则默认为“1.0”。
`dockerImageReference`	`字符串`	DockerImageReference 是可用于拉取此镜像的字符串。
`dockerImageSignatures`	`数组 (字符串)`	DockerImageSignatures 将签名作为不透明的 Blob 提供。这是清单模式 v1 的一部分。
`kind`	`字符串`	Kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出这一点。不能更新。使用驼峰命名法。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata`	`ObjectMeta_v2`	metadata 是标准对象的元数据。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
`signatures`	`数组`	Signatures 保存镜像的所有签名。
`signatures[]`	`对象`	ImageSignature 保存镜像的签名。只要签名受信任，它就可以验证镜像身份和可能的其它声明。基于此信息，可以将可运行的镜像限制为与集群范围策略匹配的镜像。客户端进行镜像验证时应解析必需字段。其它字段由服务器从签名的内容中解析。它们仅用于提供信息。兼容性级别 1：在主要版本中稳定至少 12 个月或 3 个次要版本（以较长者为准）。

apiVersion

字符串

APIVersion 定义了此对象表示的版本化模式。服务器应将识别的模式转换为最新的内部值，并可能拒绝无法识别的值。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

dockerImageConfig

字符串

DockerImageConfig 是运行时用于设置容器的 JSON 数据块。这是清单模式 v2 的一部分。当镜像表示清单列表时，将不会设置此值。

dockerImageLayers

数组

DockerImageLayers 表示镜像中的层。如果镜像未定义该数据或镜像表示清单列表，则可能未设置此值。

dockerImageLayers[]

对象

ImageLayer 表示镜像的单个层。一些镜像可能有多个层，一些可能没有。

dockerImageManifest

字符串

DockerImageManifest 是清单的原始 JSON 数据。

dockerImageManifestMediaType

字符串

DockerImageManifestMediaType 指定清单的 mediaType。这是清单模式 v2 的一部分。

dockerImageManifests

数组

DockerImageManifests 在镜像表示清单列表时保存有关子清单的信息。当此字段存在时，不应指定 DockerImageLayers。

dockerImageManifests[]

对象

ImageManifest 表示清单列表的子清单。Digest 字段指向常规 Image 对象。

dockerImageMetadata

RawExtension

DockerImageMetadata 包含有关此镜像的元数据。

dockerImageMetadataVersion

字符串

DockerImageMetadataVersion 传达对象的版本，如果为空，则默认为“1.0”。

dockerImageReference

字符串

DockerImageReference 是可用于拉取此镜像的字符串。

dockerImageSignatures

数组 (字符串)

DockerImageSignatures 将签名作为不透明的 Blob 提供。这是清单模式 v1 的一部分。

kind

字符串

Kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出这一点。不能更新。使用驼峰命名法。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds

metadata

ObjectMeta_v2

metadata 是标准对象的元数据。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

signatures

数组

Signatures 保存镜像的所有签名。

signatures[]

对象

ImageSignature 保存镜像的签名。只要签名受信任，它就可以验证镜像身份和可能的其它声明。基于此信息，可以将可运行的镜像限制为与集群范围策略匹配的镜像。客户端进行镜像验证时应解析必需字段。其它字段由服务器从签名的内容中解析。它们仅用于提供信息。

兼容性级别 1：在主要版本中稳定至少 12 个月或 3 个次要版本（以较长者为准）。

.dockerImageLayers

描述: DockerImageLayers 表示镜像中的层。如果镜像未定义该数据或镜像表示清单列表，则可能未设置此值。
类型: 数组

.dockerImageLayers[]

描述

ImageLayer 表示镜像的单个层。一些镜像可能有多个层，一些可能没有。

类型

对象

必需

name
size
mediaType

属性类型描述

属性	类型	描述
`mediaType`	`字符串`	引用的对象的 MediaType。
`name`	`字符串`	由底层存储定义的层的名称。
`size`	`整数`	由底层存储定义的层的以字节为单位的大小。

mediaType

字符串

引用的对象的 MediaType。

name

字符串

由底层存储定义的层的名称。

size

整数

由底层存储定义的层的以字节为单位的大小。

.dockerImageManifests

描述: DockerImageManifests 在镜像表示清单列表时保存有关子清单的信息。当此字段存在时，不应指定 DockerImageLayers。
类型: 数组

.dockerImageManifests[]

描述

ImageManifest 表示清单列表的子清单。Digest 字段指向常规 Image 对象。

类型

对象

必需

digest
mediaType
manifestSize
architecture
os

属性类型描述

属性	类型	描述
`architecture`	`字符串`	Architecture 指定支持的 CPU 架构，例如 `amd64` 或 `ppc64le`。
`digest`	`字符串`	Digest 是清单的唯一标识符。它指的是一个 Image 对象。
`manifestSize`	`整数`	ManifestSize 代表原始对象内容的大小（以字节为单位）。
`mediaType`	`字符串`	MediaType 定义清单的类型，可能的值为 application/vnd.oci.image.manifest.v1+json、application/vnd.docker.distribution.manifest.v2+json 或 application/vnd.docker.distribution.manifest.v1+json。
`os`	`字符串`	OS 指定操作系统，例如 `linux`。
`variant`	`字符串`	Variant 是一个可选字段，表示 CPU 的变体，例如 v6 指定 ARM CPU 的特定 CPU 变体。

architecture

字符串

Architecture 指定支持的 CPU 架构，例如 amd64 或 ppc64le。

digest

字符串

Digest 是清单的唯一标识符。它指的是一个 Image 对象。

manifestSize

整数

ManifestSize 代表原始对象内容的大小（以字节为单位）。

mediaType

字符串

MediaType 定义清单的类型，可能的值为 application/vnd.oci.image.manifest.v1+json、application/vnd.docker.distribution.manifest.v2+json 或 application/vnd.docker.distribution.manifest.v1+json。

os

字符串

OS 指定操作系统，例如 linux。

variant

字符串

Variant 是一个可选字段，表示 CPU 的变体，例如 v6 指定 ARM CPU 的特定 CPU 变体。

.signatures

描述: Signatures 保存镜像的所有签名。
类型: 数组

.signatures[]

描述

兼容性级别 1：在主要版本中稳定至少 12 个月或 3 个次要版本（以较长者为准）。

类型

对象

必需

type
content

属性类型描述

属性	类型	描述
`apiVersion`	`字符串`	APIVersion 定义了此对象表示的版本化模式。服务器应将识别的模式转换为最新的内部值，并可能拒绝无法识别的值。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
`conditions`	`数组`	Conditions 代表对签名的当前状态的最新可用观察结果。
`conditions[]`	`对象`	SignatureCondition 描述特定时间特定类型的镜像签名条件。
`content`	`字符串`	必需：一个不透明的二进制字符串，它是镜像的签名。
`created`	`时间`	如果指定，则为签名的创建时间。
`imageIdentity`	`字符串`	表示镜像身份的人类可读字符串。它可以是产品名称和版本，或者镜像拉取规范（例如，“registry.access.redhat.com/rhel7/rhel:7.2”）。
`issuedBy`	`对象`	SignatureIssuer 保存有关签名证书或密钥颁发者的信息。
`issuedTo`	`对象`	SignatureSubject 保存有关创建签名的人员或实体的信息。
`kind`	`字符串`	Kind 是一个字符串值，表示此对象表示的 REST 资源。服务器可以从客户端提交请求的端点推断出这一点。不能更新。使用驼峰命名法。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
`metadata`	`ObjectMeta_v2`	metadata 是标准对象的元数据。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata
`signedClaims`	`对象 (字符串)`	包含来自签名的声明。
`type`	`字符串`	必需：描述存储的 Blob 的类型。

apiVersion

字符串

conditions

数组

Conditions 代表对签名的当前状态的最新可用观察结果。

conditions[]

对象

SignatureCondition 描述特定时间特定类型的镜像签名条件。

content

字符串

必需：一个不透明的二进制字符串，它是镜像的签名。

created

时间

如果指定，则为签名的创建时间。

imageIdentity

字符串

表示镜像身份的人类可读字符串。它可以是产品名称和版本，或者镜像拉取规范（例如，“registry.access.redhat.com/rhel7/rhel:7.2”）。

issuedBy

对象

SignatureIssuer 保存有关签名证书或密钥颁发者的信息。

issuedTo

对象

SignatureSubject 保存有关创建签名的人员或实体的信息。

kind

字符串

metadata

ObjectMeta_v2

metadata 是标准对象的元数据。更多信息：https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

signedClaims

对象 (字符串)

包含来自签名的声明。

type

字符串

必需：描述存储的 Blob 的类型。

.signatures[].conditions

描述: Conditions 代表对签名的当前状态的最新可用观察结果。
类型: 数组

.signatures[].conditions[]

描述

SignatureCondition 描述特定时间特定类型的镜像签名条件。

类型

对象

必需

type
status

属性类型描述

属性	类型	描述
`lastProbeTime`	`时间`	最后一次检查条件的时间。
`lastTransitionTime`	`时间`	条件从一个状态转换到另一个状态的最后时间。
`message`	`字符串`	指示上次转换详细信息的人类可读消息。
`reason`	`字符串`	条件最后一次转换的（简短）原因。
`status`	`字符串`	条件的状态，True、False、Unknown 之一。
`type`	`字符串`	签名条件的类型，Complete 或 Failed。

lastProbeTime

时间

最后一次检查条件的时间。

lastTransitionTime

时间

条件从一个状态转换到另一个状态的最后时间。

message

字符串

指示上次转换详细信息的人类可读消息。

reason

字符串

条件最后一次转换的（简短）原因。

status

字符串

条件的状态，True、False、Unknown 之一。

type

字符串

签名条件的类型，Complete 或 Failed。

.signatures[].issuedBy

描述: SignatureIssuer 保存有关签名证书或密钥颁发者的信息。
类型: 对象

属性类型描述

属性	类型	描述
`commonName`	`字符串`	公用名（例如 openshift-signing-service）。
`organization`	`字符串`	组织名称。

commonName

字符串

公用名（例如 openshift-signing-service）。

organization

字符串

组织名称。

.signatures[].issuedTo

描述

SignatureSubject 保存有关创建签名的人员或实体的信息。

类型

对象

必需

publicKeyID

属性类型描述

属性	类型	描述
`commonName`	`字符串`	公用名（例如 openshift-signing-service）。
`organization`	`字符串`	组织名称。
`publicKeyID`	`字符串`	如果存在，这是一个人类可读的公共密钥 ID，属于用于验证图像签名的主体。它应该包含公共密钥指纹的至少最低 64 位（例如：0x685ebe62bf278440）。

commonName

字符串

公用名（例如 openshift-signing-service）。

organization

字符串

组织名称。

publicKeyID

字符串

如果存在，这是一个人类可读的公共密钥 ID，属于用于验证图像签名的主体。它应该包含公共密钥指纹的至少最低 64 位（例如：0x685ebe62bf278440）。

API 端点

提供以下 API 端点

/apis/image.openshift.io/v1/images
- DELETE：删除 Image 集合
- GET：列出或监视 Image 类型对象
- POST：创建 Image
/apis/image.openshift.io/v1/watch/images
- GET：监视 Image 列表的单个更改。已弃用：改用列表操作中的“watch”参数。
/apis/image.openshift.io/v1/images/{name}
- DELETE：删除 Image
- GET：读取指定的 Image
- PATCH：部分更新指定的 Image
- PUT：替换指定的 Image
/apis/image.openshift.io/v1/watch/images/{name}
- GET：监视 Image 类型对象的更改。已弃用：改用列表操作中的“watch”参数，并使用“fieldSelector”参数将其过滤为单个项目。

/apis/image.openshift.io/v1/images

HTTP 方法: DELETE
描述: 删除 Image 集合

表 1. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段

表 2. HTTP 响应
HTTP 代码	响应体
200 - OK	`Status_v5` 模式
401 - 未授权	空

HTTP 方法: GET
描述: 列出或监视 Image 类型对象

表 3. HTTP 响应
HTTP 代码	响应体
200 - OK	`ImageList` 模式
401 - 未授权	空

HTTP 方法: POST
描述: 创建 Image

表 4. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的所有重复字段中的最后一个字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段以及遇到的每个重复字段，这都将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍然会成功，并且只会保留任何重复字段中的最后一个字段。这是 v1.23+ 的默认值 - Strict：如果从对象中删除任何未知字段，或者存在任何重复字段，这将使请求失败并出现 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 5. 请求体参数
参数	类型	描述
`body`	`Image` 模式

表 6. HTTP 响应
HTTP 代码	响应体
200 - OK	`Image` 模式
201 - 已创建	`Image` 模式
202 - 已接受	`Image` 模式
401 - 未授权	空

/apis/image.openshift.io/v1/watch/images

HTTP 方法: GET
描述: 监视 Image 列表的单个更改。已弃用：改用列表操作中的“watch”参数。

表 7. HTTP 响应
HTTP 代码	响应体
200 - OK	`WatchEvent` 模式
401 - 未授权	空

/apis/image.openshift.io/v1/images/{name}

表 8. 全局路径参数
参数	类型	描述
`name`	`字符串`	Image 的名称

HTTP 方法: DELETE
描述: 删除 Image

表 9. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段

表 10. HTTP 响应
HTTP 代码	响应体
200 - OK	`Status_v5` 模式
202 - 已接受	`Status_v5` 模式
401 - 未授权	空

HTTP 方法: GET
描述: 读取指定的 Image

表 11. HTTP 响应
HTTP 代码	响应体
200 - OK	`Image` 模式
401 - 未授权	空

HTTP 方法: PATCH
描述: 部分更新指定的 Image

表 12. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的所有重复字段中的最后一个字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段以及遇到的每个重复字段，这都将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍然会成功，并且只会保留任何重复字段中的最后一个字段。这是 v1.23+ 的默认值 - Strict：如果从对象中删除任何未知字段，或者存在任何重复字段，这将使请求失败并出现 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 13. HTTP 响应
HTTP 代码	响应体
200 - OK	`Image` 模式
201 - 已创建	`Image` 模式
401 - 未授权	空

HTTP 方法: PUT
描述: 替换指定的 Image

表 14. 查询参数
参数	类型	描述
`dryRun`	`字符串`	如果存在，则表示不应持久化修改。无效或无法识别的 dryRun 指令将导致错误响应，并且不会进一步处理请求。有效值为：- All：将处理所有 dry run 阶段
`fieldValidation`	`字符串`	fieldValidation 指示服务器如何处理请求 (POST/PUT/PATCH) 中包含未知或重复字段的对象。有效值为：- Ignore：这将忽略从对象中静默删除的任何未知字段，并将忽略解码器遇到的所有重复字段中的最后一个字段。这是 v1.23 之前的默认行为。- Warn：对于从对象中删除的每个未知字段以及遇到的每个重复字段，这都将通过标准警告响应标头发送警告。如果没有任何其他错误，请求仍然会成功，并且只会保留任何重复字段中的最后一个字段。这是 v1.23+ 的默认值 - Strict：如果从对象中删除任何未知字段，或者存在任何重复字段，这将使请求失败并出现 BadRequest 错误。服务器返回的错误将包含遇到的所有未知和重复字段。

表 15. 请求体参数
参数	类型	描述
`body`	`Image` 模式

表 16. HTTP 响应
HTTP 代码	响应体
200 - OK	`Image` 模式
201 - 已创建	`Image` 模式
401 - 未授权	空

/apis/image.openshift.io/v1/watch/images/{name}

表 17. 全局路径参数
参数	类型	描述
`name`	`字符串`	Image 的名称

HTTP 方法: GET
描述: 监视 Image 类型对象的更改。已弃用：改用列表操作中的“watch”参数，并使用“fieldSelector”参数将其过滤为单个项目。

表 18. HTTP 响应
HTTP 代码	响应体
200 - OK	`WatchEvent` 模式
401 - 未授权	空