Using OCI v1.1.0 Specification to Manage and Associate Container Images and Their Derivative Artifacts - Container Registry

Starting from April 2024, newly created Container Registry Enterprise Edition instances support Open Container Initiative (OCI) Image and Distribution Specification V1.1.0, which includes support for Reference Types. This means that you can store and distribute container images and manage and distribute their associated OCI artifacts, such as image signatures and Software Bills of Materials (SBOMs). This allows you to manage and distribute these OCI artifacts in the same way that you manage container images. This topic describes how to use the features of OCI V1.1.0 in Container Registry.

Prerequisites

An OCI Registry As Storage (ORAS) client is installed on your on-premises machine. For more information, see Installation.
Docker is installed on your on-premises machine. For more information, see Install and use Docker on a Linux instance.
A virtual private cloud (VPC) access control list (ACL) is configured or Internet access is enabled for the Container Registry Enterprise Edition instance. In this topic, Internet access is enabled. For more information, see Configure access over the Internet.
The password that is used to log on to the Container Registry Enterprise Edition instance is obtained. If you forget your password, you can reset the password by configuring access credentials. For more information, see Configure access credentials for a Container Registry Enterprise Edition instance.

Step 1: Use the Referrers API to associate a container image with its derivative artifacts

The Referrers API is a capability proposed in OCI V1.1.0 and aims to associate container images with their derivative artifacts such as SBOMs, signatures, and vulnerability scan results. The Referrers API helps you effectively track the sources of specific software artifacts, thus improving the efficiency of image security and compliance management and reviewing. The following example shows how to use the Referrers API to generate the SBOM of a container image and associate the container image with the SBOM.

If you cannot run the docker sbom command in your environment, you must install and configure the sbom-cli-plugin component.

Install and configure the sbom-cli-plugin component

If you cannot run the docker sbom command in your environment, perform the following steps to install and configure the sbom-cli-plugin component:

Install the sbom-cli-plugin component.

wget "https://github.com/docker/sbom-cli-plugin/releases/download/v0.6.1/sbom-cli-plugin_0.6.1_linux_amd64.tar.gz"

Create a component directory.
```
mkdir -p /root/.docker/cli-plugins
```

Decompress the TAR package to the created directory.

tar -zxvf sbom-cli-plugin_0.6.1_linux_amd64.tar.gz -C  /root/.docker/cli-plugins

The following example shows how to use the Referrers API to associate a container image hosted at <Name of the Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20 with the SBOM of the container image:

Specify the domain name of the Container Registry Enterprise Edition instance and enter your username and logon password.
After you log on to the Container Registry Enterprise Edition instance, Login Succeeded is displayed.
```
docker login <Name of the Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com
Username: ****@test.com
Password:
Login Succeeded
```

Run the following command to generate the SBOM of the container image:

docker sbom <Name of the Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20 --format spdx-json -o sbom.jsom

Expected output:

Run the following command to associate the container image with the SBOM:

 oras attach  --distribution-spec v1.1-referrers-api <Name of the Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20 sbom.jsom --artifact-type example/sbom

Expected output:

Run the following command to view the association relationship between the container image and the SBOM:

oras discover  --distribution-spec v1.1-referrers-api <Name of the Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20

Expected output:

Step 2: Distribute a container image and its associated derivative artifacts across Container Registry Enterprise Edition instances

Container Registry Enterprise Edition allows you to use tools such as the ORAS client to distribute container images and their associated derivative artifacts across Container Registry Enterprise Edition instances. In this example, a container image and its associated SBOM are copied across Container Registry Enterprise Edition instances.

To distribute a container image hosted at <Name of the source Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20 and its associated SBOM to an image repository in the <Name of the destination Container Registry Enterprise Edition instance>-registry.cn-beijing.cr.aliyuncs.com domain, you must log on to the image repository of the destination Container Registry Enterprise Edition instance.

Specify the domain name of the destination Container Registry Enterprise Edition instance and enter your username and logon password.
After you log on to the destination Container Registry Enterprise Edition instance, Login Succeeded is displayed.
```
docker login <Name of the destination Container Registry Enterprise Edition instance>-registry.cn-beijing.cr.aliyuncs.com
Username: ****@test.com
Password:
Login Succeeded
```

Run the following command to distribute the container image and its associated SBOM to the image repository of the destination Container Registry Enterprise Edition instance:

$ oras cp -r --from-distribution-spec v1.1-referrers-api --to-distribution-spec v1.1-referrers-api <Name of the source Container Registry Enterprise Edition instance>-registry.cn-hangzhou.cr.aliyuncs.com/library/golang:1.20 <Name of the destination Container Registry Enterprise Edition instance>-registry.cn-beijing.cr.aliyuncs.com/library/golang:1.20

Expected output:

Run the following command to verify that the SBOM is distributed to the image repository of the destination Container Registry Enterprise Edition instance:

oras discover  --distribution-spec v1.1-referrers-api <Name of the destination Container Registry Enterprise Edition instance>-registry.cn-beijing.cr.aliyuncs.com/library/golang:1.20

Expected output: