此页面由 Cloud Translation API 翻译。

深入了解 Artifact Registry

1. 概览

Artifact Registry 是一款全代管式软件包管理器，提供统一的工具来管理 OCI 容器映像和语言软件包（如 Maven 和 npm）。

Artifact Registry 与 Google Cloud 的众多其他 Google Cloud 服务完全集成，如下例所示：

Cloud Build 可以直接将映像工件上传到 Artifact Registry。
Cloud Deploy 可以直接将 Artifact Registry 映像部署到各种运行时环境。
它可向 Cloud Run 和 GKE 等容器运行时提供映像，并支持映像流式传输等高级性能优化功能。
Artifact Registry 可以用作 Artifact Analysis 的检测点，以持续监控是否存在已知漏洞。
Cloud IAM 可对工件访问权限进行一致且精细的控制。

本实验将以实操教程的形式向您介绍其中的许多功能。

学习内容

本实验的学习目标是什么？

为容器和语言软件包创建不同的代码库
使用 Artifact Registry 创建和使用容器映像
使用 Artifact Registry 分析工件的安全状况和内容
为 Java Maven 依赖项配置和使用 Artifact Registry

2. 设置和要求

自定进度的环境设置

项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。

接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

设置 gcloud

在 Cloud Shell 中，设置您的项目 ID 和项目编号。将它们保存为 PROJECT_ID 和 PROJECT_NUMBER 变量。

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

启用 Google 服务

gcloud services enable \
  cloudresourcemanager.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  containerregistry.googleapis.com \
  containerscanning.googleapis.com \
  binaryauthorization.googleapis.com \
  cloudbuild.googleapis.com

获取源代码

本实验的源代码位于 GitHub 上的 GoogleCloudPlatform 组织中。使用以下命令克隆该仓库。

git clone https://github.com/GoogleCloudPlatform/java-docs-samples

3. 推送容器映像

在 Artifact Registry 上创建 Docker 代码库

如前所述，Artifact Registry 支持不同的代码库格式，可让您管理容器映像和语言软件包。与不同类型的工件仓库的互动在规范中定义，并且是广泛采用的标准。例如，Maven 依赖项的请求与 Node 依赖项的请求不同。

为了支持特定的工件 API 规范，Artifact Registry 需要在相应的代码库类型中管理您的工件。创建新代码库时，您需要传入 --repository-format 标志来指明代码库的类型。

如需为 Docker 映像创建第一个代码库，请在 Cloud Shell 中运行以下命令：

gcloud artifacts repositories create container-example --repository-format=docker \
--location=us-central1 --description="Example Docker repository"

如果系统显示 Cloud Shell 授权提示，请点击“授权”

前往 Google Cloud 控制台 - Artifact Registry - Repositories，然后找到您新创建的名为 container-example 的 Docker 代码库，如果您点击该代码库，会发现它目前是空的

配置向 Artifact Registry 的 Docker 身份验证

连接到 Artifact Registry 时，必须提供凭据才能获得访问权限。您可以将 Docker 配置为无缝使用您的 gcloud 凭据，而无需设置单独的凭据。

在 Cloud Shell 中，运行以下命令将 Docker 配置为使用 Google Cloud CLI 对 us-central1 区域中的 Artifact Registry 发出的请求进行身份验证，

gcloud auth configure-docker us-central1-docker.pkg.dev

如果该命令提示您确认是否要更改 Cloud Shell Docker 配置，请按 Enter 键。

探索示例应用

您在上一步中克隆的 Git 代码库中提供了一个示例应用。切换到 java 目录并查看应用代码。

cd java-docs-samples/run/helloworld/
ls

该文件夹包含一个用于呈现简单网页的 Java 示例应用：除了与本实验无关的各种文件之外，它还包含 src 文件夹下的源代码，以及我们将用于构建容器映像的 Dockerfile。

构建容器映像

您需要先创建一个仓库，然后才能在 Artifact Registry 中存储容器映像。

运行以下命令以构建容器映像，并使用完整的 Artifact Registry 路径为其添加标记：

docker build -t us-central1-docker.pkg.dev/$PROJECT_ID/container-example/java-hello-world:tag1 .

将容器映像推送到 Artifact Registry

运行以下命令，将容器映像推送到之前创建的代码库：

docker push us-central1-docker.pkg.dev/$PROJECT_ID/container-example/java-hello-world:tag1

在 Artifact Registry 中查看映像

前往 Google Cloud 控制台 - Artifact Registry - 代码库. 打开 container-example 代码库，并确认其中包含 java-hello-world 映像。

点击该图片，并记下标记为 tag1 的图片。由于我们已通过 containerscanning.googleapis.com 服务启用自动扫描映像功能，因此您会看到漏洞扫描正在运行或已完成。扫描完成后，您可以查看系统为此映像修订版本检测到的漏洞数量。我们将在下一部分中探索漏洞和其他工件分析。

4. 检查容器映像

现在，您已将第一个映像推送到 container-example 代码库，接下来我们可以更详细地了解一下该映像。在“版本”标签页中，点击我们刚刚创建的版本。如需更详细地显示图片，请执行以下操作：

顶部的“复制”按钮特别有用，因为它提供了一种简单的方式来访问包含 SHA 哈希的映像版本的完全限定映像 URI。然后，此 URI 可用于拉取特定映像版本，或在 Kubernetes 部署或 Cloud Run 服务中用作映像引用。如需测试图片 URI，您可以在 Cloud Shell 中运行以下命令：

docker pull $IMAGE_URI

了解依赖项

前往顶部的“依赖项”标签页，您可以查看在映像中检测到的所有依赖项。请注意，它会同时列出语言依赖项级别和操作系统级别的依赖项。您还可以查看与每个依赖项关联的软件许可。

仔细观察后，您会发现 SBOM 信息尚未填充。如需为工件填充 SOM，您可以在 Cloud Shell 中使用可从顶部的面包屑导航栏中复制的完全限定图片 URI 运行以下命令。

gcloud artifacts sbom export --uri $IMAGE_URI

刷新页面后，您会看到页面中包含指向存储在 Cloud Storage 中的自动生成的 SBOM 的链接。如果您依赖于映像的 SBOM，则可能需要为工件自动生成 SBOM，并将生成过程纳入 CI/CD 流水线。

探索映像漏洞

点击视图顶部的“漏洞”标签页后，您可以查看在映像中检测到的所有漏洞。除了顶部的漏洞摘要之外，您还可以在底部的表格中查看漏洞的完整列表。每行都链接到 CVE 公告，其中会指明严重程度和来源软件包。对于有修复程序的漏洞，还会说明如何更新依赖项以修复漏洞。

5. 虚拟仓库和远程仓库

在上一部分中，我们使用单个图片仓库来推送和拉取图片。这对于小规模用例非常有用，但对于需要对代码库拥有自主权的不同团队的大型组织来说，这会带来挑战。团队或业务部门通常都有自己的映像仓库，具有自己的权限和配置。为了简化在这些代码库中使用映像的操作，并使使用方不受底层组织结构的影响，Artifact Registry 提供了虚拟代码库，可汇总来自多个底层代码库的资源。可能的架构如下所示：

Docker Hub 的远程仓库

Docker Hub 是一个热门的公共映像注册库，托管着许多开源容器映像。虽然直接使用公共代码库非常简单，但在生产环境中，它会带来诸多挑战，而我们可以通过 Artifact Registry 中的远程代码库来克服这些挑战。

借助远程代码库，您可以将请求代理到上游注册表，并在此过程中缓存映像。这不仅缩短了图片的下载时间，还消除了对外部服务正常运行时间的依赖，并让您能够应用与您对自己的图片应用的相同安全和访问权限政策。

如需为 Docker Hub 创建远程仓库，您可以在 Cloud Shell 中运行以下命令：

gcloud artifacts repositories create dockerhub \
  --repository-format=docker \
  --mode=remote-repository \
  --remote-docker-repo=docker-hub \
  --location=us-central1 \
  --description="Example Remote Repo for Docker Hub"

现在，您应该会在 Artifact Registry 代码库列表中看到一个额外的代码库：

如需测试远程代码库是否能够将请求代理到远程代码库，请在 Cloud Shell 中运行以下命令以拉取 nginx 映像：

docker pull us-central1-docker.pkg.dev/$PROJECT_ID/dockerhub/nginx:stable-alpine

拉取成功后，您还可以在 Cloud 控制台中查看代码库，您会发现缓存的 nginx 映像现在提供与您自行构建的映像相同的依赖项和漏洞报告。

创建虚拟代码库

按照我们到目前为止所用的过程，您可以为每个团队或企业创建多个代码库，并明确定义每个代码库的所有权和 IAM 权限。我们还可以为远程代码库创建代理，以便更轻松、更安全地使用第三方映像。如果您将视角转向这些图片的使用方，就会发现如此众多的代码库的缺点。开发者应如何了解自己在部署时应使用哪个映像仓库？

如需简化使用并将底层代码库隐藏在抽象层后面，您可以在 Cloud Shell 中使用以下命令在 Artifact Registry 中创建虚拟代码库：

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:service-$PROJECT_NUMBER@gcp-sa-artifactregistry.iam.gserviceaccount.com \
    --role roles/artifactregistry.reader

cat <<EOF > /tmp/upstream.json
[{
"id" : "hello-repo",
"repository" : "projects/$PROJECT_ID/locations/us-central1/repositories/container-example",
"priority" : 100
},{
"id" : "dockerhub",
"repository" : "projects/$PROJECT_ID/locations/us-central1/repositories/dockerhub",
"priority" : 101
}]
EOF

gcloud artifacts repositories create all-images \
    --repository-format=docker \
    --mode=virtual-repository \
    --location=us-central1 \
    --upstream-policy-file=/tmp/upstream.json \
    --description="Example Virtual Repo"

现在，我们可以从虚拟仓库中拉取映像，而无需公开底层结构。如需验证一切是否按预期运行，您可以在 Cloud Shell 中运行以下命令：

docker pull us-central1-docker.pkg.dev/$PROJECT_ID/all-images/java-hello-world:tag1

docker pull us-central1-docker.pkg.dev/$PROJECT_ID/all-images/nginx:stable-alpine

6. 部署到 Cloud Run

相应的代码库和映像已就绪，现在我们可以开始在部署中使用它们了。为了演示示例用例并避免部署额外的基础架构，我们将容器部署到 Cloud Run。最简单的部署方式是在 Cloud Shell 中运行以下命令：

gcloud run deploy hello-world \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/all-images/java-hello-world:tag1 \
  --region us-central1 \
  --allow-unauthenticated

部署完成后，系统会显示自动生成的网址，您可以通过该网址访问您的服务。

Deploying container to Cloud Run service [hello-world] in project [my-project] region [us-central1]
OK Deploying... Done.                                                                      
  OK Creating Revision...                                                                  
  OK Routing traffic...
  OK Setting IAM Policy...                                                                    
Done.                                                                                      
Service [hello-world] revision [hello-world-00001-wtc] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-world-13746229022.us-central1.run.app

如果您在新的浏览器标签页中打开该网址，应该会看到成功的“Hello World!”消息。

7. 加强供应链安全

现在，您的容器映像已成功部署到生产环境，不妨考虑如何加强端到端供应链。在上一部分中，我们了解了 Artifact Registry 的容器分析功能如何深入了解映像中使用的库和许可。不过，恶意行为者仍有可能在供应链中向您的图片中引入有害内容。在本部分中，我们将探讨如何使用 SLSA 框架为 build 工件引入认证，甚至利用工件本身的加密签名，以确保只有可信工件才能部署到 Cloud Run 运行时。

使用 Cloud Build 进行 SLSA 认证

SLSA 框架为供应链工件提供了不同级别的证据。规范和实现乍一看可能令人生畏，但借助 Cloud Build，创建 SLSA 认证只需添加一个 cloudbuild.yaml 规范（将 requestedVerifyOption 设置为 VERIFIED）即可。

对于我们的应用，我们可以在 Cloud Shell 中运行以下命令，在 helloworld 文件夹中创建 cloudbuild.yaml 文件。

cat <<EOF > cloudbuild.yaml
steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', '\$_IMAGE_URI', '.']
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', '\$_IMAGE_URI']
images:
- '\$_IMAGE_URI'
options:
  requestedVerifyOption: VERIFIED
substitutions:
  _IMAGE_URI: us-central1-docker.pkg.dev/$PROJECT_ID/container-example/java-hello-world:latest
EOF

现在，我们在 Cloud Shell 中运行以下命令，创建一个新的 Cloud Build 作业，以构建新版本的 Java Hello World 映像。

gcloud builds submit --substitutions=_IMAGE_URI=us-central1-docker.pkg.dev/$PROJECT_ID/container-example/java-hello-world:cloud-build

构建完成后，我们可以前往 Google Cloud 控制台中的 Cloud Build 界面，打开 build 并查看“Build Summary”（Build 摘要）下的“Build Artifacts”（Build 工件），以查看我们达到的 SLSA 级别。该图片上有一个按钮，用于查看“安全分析”。点击该图标后，您会看到 SLSA 认证以及我们之前在 Artifact Registry 界面中推送本地 build 时看到的熟悉的漏洞报告。

您还可以在 Cloud Shell 中运行以下命令，检索映像的 SLSA 来源：

gcloud artifacts docker images describe \
"us-central1-docker.pkg.dev/$PROJECT_ID/container-example/java-hello-world:cloud-build" \
 --show-provenance

使用 Binary Authorization 要求 Cloud Build 提供来源

有了 Cloud Build 流水线，如果能确保我们部署到生产环境的所有映像都是使用可编程且可重现的构建环境构建的，那不是很棒吗？

这时，Binary Authorization 就可以派上用场了。借助它，您可以在容器运行时之前放置一个守门器，用于检查容器映像并验证是否存在可信证明。如果未找到任何认证，系统会根据配置创建审核日志条目或完全阻止部署。

如需将项目的默认二进制授权配置更改为要求 Cloud Run 签发的内置认证，我们需要在 Cloud Shell 中运行以下命令：

cat << EOF > /tmp/policy.yaml
defaultAdmissionRule:
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  evaluationMode: REQUIRE_ATTESTATION
  requireAttestationsBy:
  - projects/$PROJECT_ID/attestors/built-by-cloud-build
name: projects/$PROJECT_ID/policy
EOF

gcloud container binauthz policy import /tmp/policy.yaml

当然，您还可以在此处添加自己的自定义 Attestor，但这超出了本 Codelab 的范围，因此将作为一项可选的课外作业留待您完成。

如需对 Cloud Run 服务强制执行二进制授权，我们需要在 Cloud Shell 中运行以下命令：

gcloud run services update hello-world \
  --region us-central1 \
  --binary-authorization=default

我们先重新部署本地构建的映像，以测试是否正确应用了二进制授权

gcloud run deploy hello-world \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/all-images/java-hello-world:tag1 \
  --region us-central1

正如预期，您应该会收到一条错误消息，说明无法部署映像的原因，该消息应如下所示：

Image us-central1-docker.pkg.dev/my-project/all-images/java-hello-world@sha256:71eebbf04bf7d1d023e5de5e18f786ea3b8b6411bf64c8def3301c71baca0518 denied by attestor projects/my-project/attestors/built-by-cloud-build: No attestations found that were valid and signed by a key trusted by the attestor

因此，若要将新版本部署到 Cloud Run 服务，我们需要提供使用 Cloud Build 构建的映像。

gcloud run deploy hello-world \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/all-images/java-hello-world:cloud-build \
  --region us-central1

这次部署应该会成功，并显示类似于以下内容的部署成功消息：

Deploying container to Cloud Run service [hello-world] in project [my-project] region [us-central1]
OK Deploying... Done.                                                                      
  OK Creating Revision...                                                                  
  OK Routing traffic...                                                                    
Done.                                                                                      
Service [hello-world] revision [hello-world-00005-mq4] has been deployed and is serving 100 percent of traffic.
Service URL: https://hello-world-13746229022.us-central1.run.app

8. 管理 Java Maven 语言软件包

在本部分，您将了解如何设置 Artifact Registry Java 代码库并向其上传软件包，以便在不同的应用中使用这些软件包。

创建 Maven 软件包代码库

在 Cloud Shell 中，运行以下命令以创建 Java 工件仓库：

gcloud artifacts repositories create java-repo \
    --repository-format=maven \
    --location=us-central1 \
    --description="Example Java Maven Repo"

如果系统显示 Cloud Shell 授权提示，请点击“授权”

前往 Google Cloud 控制台 - Artifact Registry - 代码库，然后找到您新创建的名为 java-repo 的 Maven 代码库。如果您点击该代码库，会发现它目前是空的。

设置对工件代码库的身份验证

使用以下命令将应用默认凭据 (ADC) 的众所周知位置更新为您的用户账号凭据，以便 Artifact Registry 凭据帮助程序在与代码库连接时使用这些凭据进行身份验证：

gcloud auth login --update-adc

为 Artifact Registry 配置 Maven

运行以下命令来输出要添加到 Java 项目的代码库配置：

gcloud artifacts print-settings mvn \
    --repository=java-repo \
    --location=us-central1 | tee config.xml

在 Cloud Shell 中，从 helloworld 目录中运行以下命令，即可在 Cloud Shell Editor 中打开 pom.xml：

cloudshell edit pom.xml

并将返回的设置添加到文件中的相应部分，

更新 distributionManagement 部分

<distributionManagement>
   <snapshotRepository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
   </snapshotRepository>
   <repository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
   </repository>
</distributionManagement>

更新 repositories 部分

 <repositories>
   <repository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
     <releases>
       <enabled>true</enabled>
     </releases>
     <snapshots>
       <enabled>true</enabled>
     </snapshots>
   </repository>
 </repositories>

更新 build 下的 extensions 部分

   <extensions>
     <extension>
       <groupId>com.google.cloud.artifactregistry</groupId>
       <artifactId>artifactregistry-maven-wagon</artifactId>
       <version>2.1.0</version>
     </extension>
   </extensions>

以下是完整文件示例，供您参考。请务必将 <PROJECT> 替换为您的项目 ID。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
 <modelVersion>4.0.0</modelVersion>
 <groupId>com.example.run</groupId>
 <artifactId>helloworld</artifactId>
 <version>0.0.1-SNAPSHOT</version>
 <packaging>jar</packaging>

 <parent>
   <groupId>com.google.cloud.samples</groupId>
   <artifactId>shared-configuration</artifactId>
   <version>1.2.0</version>
 </parent>
 <dependencyManagement>
   <dependencies>
     <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-dependencies</artifactId>
       <version>${spring-boot.version}</version>
       <type>pom</type>
       <scope>import</scope>
     </dependency>
   </dependencies>
 </dependencyManagement>
 <properties>
   <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
   <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
   <maven.compiler.target>17</maven.compiler.target>
   <maven.compiler.source>17</maven.compiler.source>
   <spring-boot.version>3.2.2</spring-boot.version>
 </properties>
 <dependencies>
   <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-web</artifactId>
   </dependency>
   <dependency>
     <groupId>org.springframework.boot</groupId>
     <artifactId>spring-boot-starter-test</artifactId>
     <scope>test</scope>
   </dependency>
   <dependency>
     <groupId>org.junit.vintage</groupId>
     <artifactId>junit-vintage-engine</artifactId>
     <scope>test</scope>
   </dependency>
   <dependency>
     <groupId>junit</groupId>
     <artifactId>junit</artifactId>
     <scope>test</scope>
   </dependency>
 </dependencies>
 <!-- [START Artifact Registry Config] -->
 <distributionManagement>
   <snapshotRepository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
   </snapshotRepository>
   <repository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
   </repository>
 </distributionManagement>

 <repositories>
   <repository>
     <id>artifact-registry</id>
     <url>artifactregistry://us-central1-maven.pkg.dev/<PROJECT>/java-repo</url>
     <releases>
       <enabled>true</enabled>
     </releases>
     <snapshots>
       <enabled>true</enabled>
     </snapshots>
   </repository>
 </repositories>
  <build>
   <extensions>
     <extension>
       <groupId>com.google.cloud.artifactregistry</groupId>
       <artifactId>artifactregistry-maven-wagon</artifactId>
       <version>2.2.0</version>
     </extension>
   </extensions>
 <!-- [END Artifact Registry Config] -->

   <plugins>
     <plugin>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-maven-plugin</artifactId>
       <version>${spring-boot.version}</version>
       <executions>
         <execution>
           <goals>
             <goal>repackage</goal>
           </goals>
         </execution>
       </executions>
     </plugin>
     <plugin>
       <groupId>com.google.cloud.tools</groupId>
       <artifactId>jib-maven-plugin</artifactId>
       <version>3.4.0</version>
       <configuration>
         <to>
           <image>gcr.io/PROJECT_ID/helloworld</image>
         </to>
       </configuration>
     </plugin>
   </plugins>
 </build>
 </project>

将 Java 软件包上传到 Artifact Registry

在 Maven 中配置 Artifact Registry 后，您现在可以使用 Artifact Registry 存储 Java Jar，以供贵组织中的其他项目使用。

运行以下命令将 Java 软件包上传到 Artifact Registry：

mvn deploy

在 Artifact Registry 中查看 Java 软件包

依次前往 Cloud 控制台 - Artifact Registry - 代码库。点击 java-repo，检查是否存在 helloworld 二进制工件：

9. 恭喜！

恭喜，您已完成此 Codelab！

您学习了以下内容

为容器和语言软件包创建了代码库
使用 Artifact Registry 管理容器映像
将 Artifact Registry 与 Cloud Code 集成
配置 Maven 以使用 Artifact Registry 存储 Java 依赖项

清理

在 Cloud Shell 中运行以下命令以删除整个项目

gcloud projects delete $PROJECT_ID