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

預先暖機映像檔可讓您在執行階段用戶端要求容器映像檔之前,明確觸發將容器映像檔下載到映像檔串流快取。這可有效消除工作負載使用映像檔串流時,首次提取新映像檔版本所產生的「冷啟動」延遲。

總覽

將映像檔推送至 Artifact Registry 時,映像檔會儲存在基礎儲存系統中。為提供低延遲存取,Artifact Registry 也會使用映像檔串流快取,通常會在用戶端啟用映像檔串流後,首次提取時填入。對於延遲敏感的工作負載 (例如擴充 Google Kubernetes Engine 叢集),等待快取預熱可能會導致延遲。預熱功能可預先將映像檔放入映像檔串流快取。

Prewarm Artifact API 可讓您手動要求預先快取特定映像檔版本或標記。您也可以指定保留期限,確保圖片在快取中保留指定時間。

限制

  • 僅限 API:只能使用 Artifact Registry REST API 預熱。無法使用 Google Cloud 控制台預熱。
  • 僅限 GKE:預先暖機僅適用於已啟用映像檔串流的 GKE 叢集。圖片串流需要用戶端節點上執行的特定軟體。
  • 單一構件:每次 API 要求只能預熱一個構件 (版本或標記)。
  • 多架構映像檔:不支援。使用架構映像檔的特定版本。
  • 專案限制:預設情況下,每項專案的預熱儲存空間上限為 100 GB。如果空間不足,無法容納映像檔,除非您在要求中將 force 設為 true,否則預熱作業會失敗。當 force 為 true 時,系統會移除最近最少預熱的映像檔,為映像檔騰出空間。如要預估用量,請參閱「查看快取用量」。

事前準備

  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 (亞洲)。

:prewarmArtifact 方法會傳回長時間執行的作業。作業成功完成後,其 response 欄位會包含 prewarmedArtifact 物件。如要進一步瞭解這個物件中的欄位,請參閱「檢查預熱狀態」。

範例:預熱特定版本

下列範例會預熱「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 方法。如果您在存放區位置以外的串流位置預熱構件,請在 stream_location 欄位中指定該位置。以下 範例會檢查先前範例在 us-east1 中預熱的 nginx 版本:

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",
    "stream_location": "us-east1"
  }' \
  "https://artifactregistry.googleapis.com/v1/projects/my-project/locations/us-central1/repositories/my-repo:checkPrewarmedArtifact"

如果構件位於快取中,輸出內容會大致如下:

{
  "prewarmedArtifact": {
    "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
    "location": "us-east1",
    "expirationTime": "2026-03-21T17:04:05.123456Z",
    "state": "ACTIVE",
    "sizeBytes": "734003200",
    "createTime": "2026-03-14T17:04:05.123456Z"
  }
}

如果構件不在快取中 (例如已過期),回應會是空白的 JSON 物件。

prewarmedArtifact 物件包含下列欄位:

欄位 說明
uri 映像檔的 URI,可透過摘要識別映像檔。
location 快取圖片的串流位置。
state 構件的快取狀態:CACHING、ACTIVE 或 FAILED。
sizeBytes 構件壓縮後的大小 (以位元組為單位)。這個大小會計入預熱儲存空間限制。
createTime 首次預熱構件的時間。
expirationTime 構件從快取中到期的時間,除非您在到期前再次預熱。
errorMessage 快取失敗的原因。只有在 state 為 FAILED 時,系統才會設定這個欄位。

使用 state 欄位判斷構件是否可供串流:

  • CACHING:構件正在快取,尚未準備好串流。
  • ACTIVE:構件已快取,可供串流。
  • FAILED:無法快取構件。errorMessage 欄位會說明失敗原因。

列出預熱構件

如要列出存放區中所有預熱的構件,請對 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"

輸出結果會與下列內容相似:

{
  "prewarmedArtifacts": [
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/nginx@sha256:52e85304675567b5e656f5e997576a9d20c57176",
      "location": "us-east1",
      "expirationTime": "2026-03-21T17:04:05.123456Z",
      "state": "ACTIVE",
      "sizeBytes": "734003200",
      "createTime": "2026-03-14T17:04:05.123456Z"
    },
    {
      "uri": "us-central1-docker.pkg.dev/my-project/my-repo/redis@sha256:4d3c2b1a0f9e8d7c6b5a49382716051f4e3d2c1b",
      "location": "us-east1",
      "expirationTime": "2026-03-17T18:30:12.654321Z",
      "state": "CACHING",
      "sizeBytes": "52428800",
      "createTime": "2026-03-14T18:30:12.654321Z"
    }
  ]
}

回應會包含所有狀態的構件,因此請查看 state 欄位,瞭解哪些構件已可串流。不含過期的構件。

根據預設,每頁結果最多包含 100 個構件。如要每頁最多取得 1,000 個構件,請設定 pageSize 查詢參數。如果回應包含 nextPageToken 值,表示還有更多構件。如要取得下一頁,請重複要求,並將 pageToken 查詢參數設為 nextPageToken 值。

查看快取用量

預熱儲存空間限制適用於專案中處於 CACHING 或 ACTIVE 狀態的預熱構件總sizeBytes。過期的構件和處於 FAILED 狀態的構件不會計入限制。

每項清單要求都會傳回一個串流位置中一個存放區的預熱構件。如要估算專案在串流位置使用的限制量,請按照下列步驟操作:

  1. 無論存放區位置為何,請使用 filter=stream_location=LOCATION 查詢參數,列出專案中每個存放區的所有預熱構件頁面。將 LOCATION 替換為串流位置。
  2. 將處於 CACHING 或 ACTIVE 狀態構件的 sizeBytes 值相加。

如要在構件到期前釋出空間,請移除不再需要的構件。

從快取中移除

如要明確從預熱快取中移除構件,請使用 :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"

後續步驟