使用 Azure 容器注册表推送和拉取 OCI 项目Push and pull an OCI artifact using an Azure container registry

可以使用 Azure 容器注册表来存储和管理开放容器计划 (OCI) 项目、Docker 以及与 Docker 兼容的容器映像。You can use an Azure container registry to store and manage Open Container Initiative (OCI) artifacts as well as Docker and Docker-compatible container images.

为了演示此功能,本文介绍了如何使用 OCI 注册表即存储 (ORAS) 工具将示例项目(一个文本文件)推送到 Azure 容器注册表,To demonstrate this capability, this article shows how to use the OCI Registry as Storage (ORAS) tool to push a sample artifact - a text file - to an Azure container registry. 然后从注册表拉取项目。Then, pull the artifact from the registry. 可以使用适用于每个 OCI 项目的不同命令行工具,在 Azure 容器注册表中管理各种 OCI 项目。You can manage a variety of OCI artifacts in an Azure container registry using different command-line tools appropriate to each artifact.

先决条件Prerequisites

  • Azure 容器注册表 - 在 Azure 订阅中创建容器注册表。Azure container registry - Create a container registry in your Azure subscription. 例如,使用 Azure 门户Azure CLIFor example, use the Azure portal or the Azure CLI.
  • ORAS 工具 - 从 GitHub 存储库下载并安装适合操作系统的最新 ORAS 版本。ORAS tool - Download and install a current ORAS release for your operating system from the GitHub repo. 此工具以压缩 tarball(.tar.gz 文件)形式发布。The tool is released as a compressed tarball (.tar.gz file). 使用适合操作系统的标准过程提取并安装该文件。Extract and install the file using standard procedures for your operating system.
  • Azure Active Directory 服务主体(可选) - 若要使用 ORAS 直接进行身份验证,请创建一个用于访问注册表的服务主体Azure Active Directory service principal (optional) - To authenticate directly with ORAS, create a service principal to access your registry. 请确保为服务主体分配一个角色(例如 AcrPush),使之有权推送和拉取项目。Ensure that the service principal is assigned a role such as AcrPush so that it has permissions to push and pull artifacts.
  • Azure CLI(可选) - 若要使用单个标识,需在本地安装 Azure CLI。Azure CLI (optional) - To use an individual identity, you need a local installation of the Azure CLI. 建议使用 2.0.71 或更高版本。Version 2.0.71 or later is recommended. 运行 az --version 即可查找版本。Run az --version to find the version. 如果需要进行安装或升级,请参阅安装 Azure CLIIf you need to install or upgrade, see Install Azure CLI.
  • Docker(可选) - 若要使用单个标识,还必须在本地安装 Docker,以便通过注册表进行身份验证。Docker (optional) - To use an individual identity, you must also have Docker installed locally, to authenticate with the registry. Docker 提供的包可在任何 macOSWindowsLinux 系统上轻松配置 Docker。Docker provides packages that easily configure Docker on any macOS, Windows, or Linux system.

登录到注册表Sign in to a registry

此部分介绍两个建议用于登录注册表的工作流,具体取决于所用标识。This section shows two suggested workflows to sign into the registry, depending on the identity used. 选择适合环境的方法。Choose the method appropriate for your environment.

使用 ORAS 登录Sign in with ORAS

使用带推送权限的服务主体时,请运行 oras login 命令,以便使用服务主体应用程序 ID 和密码登录到注册表。Using a service principal with push rights, run the oras login command to sign in to the registry using the service principal application ID and password. 请指定完全限定的注册表名称(全部小写),在此示例中为 myregistry.azurecr.cnSpecify the fully qualified registry name (all lowercase), in this case myregistry.azurecr.cn. 服务主体应用程序 ID 将传入到环境变量 $SP_APP_ID 中,密码将传入到变量 $SP_PASSWD 中。The service principal application ID is passed in the environment variable $SP_APP_ID, and the password in the variable $SP_PASSWD.

oras login myregistry.azurecr.cn --username $SP_APP_ID --password $SP_PASSWD

若要从 Stdin 读取密码,请使用 --password-stdinTo read the password from Stdin, use --password-stdin.

使用 Azure CLI 登录Sign in with Azure CLI

使用标识登录到 Azure CLI,以便通过容器注册表推送和拉取项目。Sign in to the Azure CLI with your identity to push and pull artifacts from the container registry.

然后,使用 Azure CLI 命令 az acr login 访问注册表。Then, use the Azure CLI command az acr login to access the registry. 例如,若要向名为 myregistry 的注册表进行身份验证,请执行以下命令:For example, to authenticate to a registry named myregistry:

az login
az acr login --name myregistry

备注

az acr login 使用 Docker 客户端在 docker.config 文件中设置 Azure Active Directory 令牌。az acr login uses the Docker client to set an Azure Active Directory token in the docker.config file. Docker 客户端必须已安装并处于运行状态,否则不能完成单个身份验证流。The Docker client must be installed and running to complete the individual authentication flow.

推送项目Push an artifact

请使用一些示例文本在本地工作目录中创建一个文本文件。Create a text file in a local working working directory with some sample text. 例如,在 Bash shell 中执行以下代码:For example, in a bash shell:

echo "Here is an artifact!" > artifact.txt

使用 oras push 命令将该文本文件推送到注册表。Use the oras push command to push this text file to your registry. 以下示例将示例文本文件推送到 samples/artifact 存储库。The following example pushes the sample text file to the samples/artifact repo. 注册表通过完全限定的注册表名称 myregistry.azurecr.cn(全小写)进行标识。The registry is identified with the fully qualified registry name myregistry.azurecr.cn (all lowercase). 此项目标记为 1.0The artifact is tagged 1.0. 默认情况下,此项目有一个未定义的类型,该类型通过文件名 artifact.txt 后的媒体类型 字符串进行标识。The artifact has an undefined type, by default, identified by the media type string following the filename artifact.txt. 有关其他类型,请参阅 OCI Artifacts(OCI 项目)。See OCI Artifacts for additional types.

LinuxLinux

oras push myregistry.azurecr.cn/samples/artifact:1.0 \
    --manifest-config /dev/null:application/vnd.unknown.config.v1+json \
    ./artifact.txt:application/vnd.unknown.layer.v1+txt

WindowsWindows

.\oras.exe push myregistry.azurecr.cn/samples/artifact:1.0 ^
    --manifest-config NUL:application/vnd.unknown.config.v1+json ^
    .\artifact.txt:application/vnd.unknown.layer.v1+txt

成功推送后,输出将如下所示:Output for a successful push is similar to the following:

Uploading 33998889555f artifact.txt
Pushed myregistry.azurecr.cn/samples/artifact:1.0
Digest: sha256:xxxxxxbc912ef63e69136f05f1078dbf8d00960a79ee73c210eb2a5f65xxxxxx

如果使用 Azure CLI,则若要管理注册表中的项目,请运行标准的用于管理映像的 az acr 命令。To manage artifacts in your registry, if you are using the Azure CLI, run standard az acr commands for managing images. 例如,使用 az acr repository show 命令获取项目的属性:For example, get the attributes of the artifact using the az acr repository show command:

az acr repository show \
    --name myregistry \
    --image samples/artifact:1.0

输出与下面类似:Output is similar to the following:

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2019-08-28T20:43:31.0001687Z",
  "digest": "sha256:xxxxxxbc912ef63e69136f05f1078dbf8d00960a79ee73c210eb2a5f65xxxxxx",
  "lastUpdateTime": "2019-08-28T20:43:31.0001687Z",
  "name": "1.0",
  "signed": false
}

拉取项目Pull an artifact

请运行 oras pull 命令从注册表拉取项目。Run the oras pull command to pull the artifact from your registry.

首先,从本地工作目录中删除以下文本文件:First remove the text file from your local working directory:

rm artifact.txt

运行 oras pull 来拉取项目,并指定用于推送项目的媒体类型:Run oras pull to pull the artifact, and specify the media type used to push the artifact:

oras pull myregistry.azurecr.cn/samples/artifact:1.0 \
    --media-type application/vnd.unknown.layer.v1+txt

验证拉取是否成功:Verify that the pull was successful:

$ cat artifact.txt
Here is an artifact!

删除项目(可选)Remove the artifact (optional)

若要从 Azure 容器注册表中删除项目,请使用 az acr repository delete 命令。To remove the artifact from your Azure container registry, use the az acr repository delete command. 以下示例删除存储在该处的项目:The following example removes the artifact you stored there:

az acr repository delete \
    --name myregistry \
    --image samples/artifact:1.0

后续步骤Next steps

  • 详细了解 ORAS 库,包括如何为项目配置清单。Learn more about the ORAS Library, including how to configure a manifest for an artifact
  • 有关新项目类型的参考信息,请访问 OCI 项目存储库Visit the OCI Artifacts repo for reference information about new artifact types