Il pre-riscaldamento delle immagini consente di attivare esplicitamente il download delle immagini container nella cache di Image Streaming prima che un client di runtime le richieda. In questo modo, si elimina efficacemente la latenza di "avvio a freddo" associata al primo pull di una nuova versione dell'immagine per i carichi di lavoro che utilizzano Image Streaming.
Panoramica
Quando esegui il push di un'immagine in Artifact Registry, questa viene archiviata in un sistema di archiviazione sottostante. Per un accesso a bassa latenza, Artifact Registry utilizza anche una cache di Image Streaming , che in genere viene compilata al primo pull da un client con Image Streaming abilitato. Per i carichi di lavoro sensibili alla latenza, come lo scale up di un cluster Google Kubernetes Engine, l'attesa del riscaldamento di questa cache può causare ritardi. Il pre-riscaldamento consente di inserire le immagini nella cache di Image Streaming in anticipo.
L'API Prewarm Artifact consente di richiedere manualmente la pre-memorizzazione nella cache di una versione immagine o un tag specifici. Puoi anche specificare un periodo di conservazione per assicurarti che l'immagine rimanga nella cache per una durata specificata.
Limitazioni
- Solo API: il pre-riscaldamento è disponibile solo tramite l'API REST di Artifact Registry. Il pre-riscaldamento non è disponibile tramite gcloud CLI o Cloud de Confiance console.
- Solo GKE: il pre-riscaldamento è efficace solo per i cluster GKE con Image Streaming abilitato. Image Streaming richiede l'esecuzione di software specifici sul nodo client.
- Singolo artefatto: puoi pre-riscaldare un solo artefatto (versione o tag) per richiesta API.
- Immagini multi-architettura: non supportate. Utilizza la versione specifica per un'immagine di architettura.
- Limite del progetto: esiste un limite complessivo di 100 GB per progetto consumer per le immagini pre-riscaldate. Quando viene raggiunto il limite, le immagini meno recenti vengono eliminate per fare spazio a quelle nuove.
Prima di iniziare
- Abilita l'API Artifact Registry. Per saperne di più, consulta Abilitare Artifact Registry.
- Installa gcloud CLI per ottenere i token di autenticazione per le richieste API REST.
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per gestire le immagini pre-riscaldate, chiedi all'amministratore di concederti i seguenti ruoli IAM sul repository:
-
Pre-riscalda o rimuovi gli artefatti dalla cache (
artifactregistry.repositories.prewarmArtifact,artifactregistry.repositories.removePrewarmedArtifact): Writer di Artifact Registry (roles/artifactregistry.writer) -
Controlla o elenca gli artefatti pre-riscaldati (
artifactregistry.repositories.checkPrewarmedArtifact,artifactregistry.repositories.listPrewarmedArtifacts): Reader di Artifact Registry (roles/artifactregistry.reader)
Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.
Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.
Questo modello di autorizzazioni garantisce che solo gli utenti con accesso in scrittura possano gestire lo stato della cache, impedendo agli utenti non autorizzati di riempire eccessivamente la cache. Nel frattempo, gli utenti con accesso in lettura possono verificare quali artefatti sono disponibili per lo streaming.
Pre-riscalda un'immagine
Per pre-riscaldare un'immagine, invia una richiesta POST al metodo :prewarmArtifact del repository.
API REST
Riferimento: projects.locations.repositories.prewarmArtifact
Il corpo della richiesta ha la seguente struttura:
{
"version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
"retention_days": 3
}
In alternativa, utilizza un tag:
{
"tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
"retention_days": 3,
"force": true
}
| Campo | Descrizione |
|---|---|
tag |
Facoltativo. Il tag dell'artefatto specifico da pre-riscaldare. Devi specificare un version o un tag. |
version |
Facoltativo. La versione specifica dell'artefatto da pre-riscaldare. Devi specificare un version o un tag. |
retention_days |
Facoltativo. Il numero di giorni per mantenere l'artefatto nella cache. Se non specifichi questo campo, il valore predefinito è 3 giorni. |
force |
Facoltativo. Se true, il sistema potrebbe eliminare gli artefatti meno recenti per fare spazio a questo. |
stream_location |
Facoltativo. La regione specifica in cui verrà pre-riscaldata l'immagine. Per impostazione predefinita, corrisponde alla località dell'immagine. Tieni presente che le configurazioni multiregionali non sono supportate. Se viene specificata una regione ampia, i valori predefiniti sono us-central1 (Stati Uniti), europe-north1 (UE) e asia-east1 (Asia). |
Esempio: pre-riscalda una versione specifica
L'esempio seguente pre-riscalda la versione sha256:52e... del pacchetto nginx nel repository my-repo nella regione "us-east1".
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"
Esempio: pre-riscalda un tag
L'esempio seguente pre-riscalda l'immagine con tag production del pacchetto my-app.
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"
Controlla lo stato del pre-riscaldamento
Per verificare se un artefatto è pre-riscaldato, utilizza il metodo :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"
Elenca gli artefatti pre-riscaldati
Per elencare tutti gli artefatti pre-riscaldati in un repository, utilizza il metodo GET nella raccolta prewarmedArtifacts.
L'esempio seguente elenca tutte le immagini pre-riscaldate in my-repo in us-east1. Il filtro stream_location è obbligatorio.
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"/
Rimuovi dalla cache
Per rimuovere esplicitamente un artefatto dalla cache di pre-riscaldamento, utilizza il metodo :removePrewarmedArtifact. Utilizza questo metodo per liberare spazio o quando una versione specifica dell'immagine non è più necessaria nella cache.
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"