使用圖片預先載入功能縮短延遲時間

預先暖機映像檔可讓您在執行階段用戶端要求容器映像檔之前，明確觸發將容器映像檔下載至映像檔串流快取。這項功能可有效消除與工作負載首次提取新版映像檔相關的「冷啟動」延遲，這些工作負載使用映像檔串流。

總覽

將映像檔推送至 Artifact Registry 時，系統會將其儲存在基礎儲存系統中。為提供低延遲存取服務，Artifact Registry 也會使用映像檔串流快取，通常會在首次從啟用映像檔串流的用戶端提取時填入。對於延遲時間敏感的工作負載 (例如擴充 Google Kubernetes Engine 叢集)，等待這個快取暖機可能會導致延遲。預先暖機有助於事先將映像檔載入映像檔串流快取。

預先暖機 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 寫入者 (roles/artifactregistry.writer)
  • 檢查或列出預先暖機的構件 (artifactregistry.repositories.checkPrewarmedArtifact、artifactregistry.repositories.listPrewarmedArtifacts)： Artifact Registry 讀取者 (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"

後續步驟