通过映像预热缩短延迟时间

通过预热映像，您可以在运行时客户端请求容器映像之前，显式触发将容器映像下载到映像流式传输缓存中。这样一来，对于使用映像流式传输的工作负载，可以有效消除与首次拉取新映像版本相关的“冷启动”延迟。

概览

当您将映像推送到 Artifact Registry 时，该映像会存储在底层存储系统中。为了实现低延迟访问，Artifact Registry 还使用映像流式传输缓存，该缓存通常会在首次从启用映像流式传输的客户端拉取映像时填充。对于延迟敏感型工作负载（例如伸缩 Google Kubernetes Engine 集群），等待此缓存预热可能会导致延迟。预热有助于提前将映像放入映像流式传输缓存中。

借助 Prewarm Artifact API，您可以手动请求预缓存特定映像版本或标记。您还可以指定保留期限，以确保映像在指定期限内保留在缓存中。

限制

  • 仅限 API：预热只能使用 Artifact Registry REST API 进行。 无法使用 gcloud CLI 或 Google Cloud 控制台进行预热。
  • 仅限 GKE：预热仅对启用了映像流式传输的 GKE 集群有效。映像流式传输需要在客户端节点上运行特定软件。
  • 单个制品：您只能为每个 API 请求预热一个制品（版本或标记）。
  • 多架构映像：不支持。请使用特定版本的架构映像。
  • 项目限额：每个使用方项目的预热映像总限额为 100 GB。达到限制后，系统会逐出旧图片，以便为新图片腾出空间。

准备工作

  1. 启用 Artifact Registry API。如需了解详情，请参阅启用 Artifact Registry。
  2. 安装 gcloud CLI 以获取 REST API 请求的身份验证令牌。

所需的角色

如需获得管理预热映像所需的权限，请让您的管理员为您授予代码库的以下 IAM 角色：

  • 预热或移除缓存中的制品（artifactregistry.repositories.prewarmArtifact、artifactregistry.repositories.removePrewarmedArtifact）：Artifact Registry Writer (roles/artifactregistry.writer)
  • 检查或列出预热的制品（artifactregistry.repositories.checkPrewarmedArtifact、artifactregistry.repositories.listPrewarmedArtifacts）： Artifact Registry Reader (roles/artifactregistry.reader)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

此权限模型可确保只有具有写入权限的用户才能管理缓存状态，从而防止未经授权的用户过度填充缓存。同时，具有读取权限的用户可以验证哪些制品可用于流式传输。

预热映像

如需预热映像，请向代码库的 :prewarmArtifact 方法发出 POST 请求。

REST API

参考：projects.locations.repositories.prewarmArtifact

请求正文的结构如下：

{
  "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
  "retention_days": 3
}

或者，使用代码：

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
字段 说明
tag 可选。要预热的特定制品标记。您必须指定 version 或 tag。
version 可选。要预热的特定制品版本。您必须指定 version 或 tag。
retention_days 可选。制品在缓存中保留的天数。如果您未指定此字段，则默认值为 3 天。
force 可选。如果值为 true，系统可能会逐出较旧的制品，以便为该制品腾出空间。
stream_location 可选。将预热映像的特定区域。默认情况下，此值与图片位置一致。请注意，不支持多区域配置。如果指定的是广义区域，则默认值为 us-central1（美国）、europe-north1（欧盟）和 asia-east1（亚洲）。

示例：预热特定版本

以下示例预热了“us-east1”区域中 my-repo 代码库内 nginx 软件包的版本 sha256:52e...。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "retention_days": 7,
    "stream_location": "us-east1",
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

示例：预热代码

以下示例预热了 my-app 软件包中标记为 production 的映像。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "projects/my-project/locations/us-central1/repositories/my-repo/packages/my-app/tags/production",
    "force": true
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:prewarmArtifact"

检查预热状态

如需检查制品是否已预热，请使用 :checkPrewarmedArtifact 方法。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

列出预热的制品

如需列出代码库中的所有预热制品，请对 prewarmedArtifacts 集合使用 GET 方法。以下示例列出了 us-east1 中 my-repo 下的所有预热映像。必须指定 stream_location 过滤条件。

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo/prewarmedArtifacts?filter=stream_location=us-east1"/

从缓存中移除

如需从预热缓存中明确移除制品，请使用 :removePrewarmedArtifact 方法。使用此方法可释放空间，或者在缓存中不再需要特定映像版本时使用此方法。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "projects/my-project/locations/us-central1/repositories/my-repo/packages/nginx/versions/sha256:52e85304675567b5e656f5e997576a9d20c57176"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:removePrewarmedArtifact"

后续步骤