預先暖機映像檔可讓您在執行階段用戶端要求容器映像檔之前,明確觸發將容器映像檔下載到映像檔串流快取。這可有效消除工作負載使用映像檔串流時,首次提取新映像檔版本所產生的「冷啟動」延遲。
總覽
將映像檔推送至 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時,系統會移除最近最少預熱的映像檔,為映像檔騰出空間。如要預估用量,請參閱「查看快取用量」。
事前準備
- 啟用 Artifact Registry API。詳情請參閱「啟用 Artifact Registry」。
- 安裝 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 狀態的構件不會計入限制。
每項清單要求都會傳回一個串流位置中一個存放區的預熱構件。如要估算專案在串流位置使用的限制量,請按照下列步驟操作:
- 無論存放區位置為何,請使用
filter=stream_location=LOCATION查詢參數,列出專案中每個存放區的所有預熱構件頁面。將LOCATION替換為串流位置。 - 將處於
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"