Ridurre la latenza con il pre-riscaldamento delle immagini

Il precaricamento 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, viene eliminata la latenza di "avvio a freddo" associata al primo pull di una nuova versione dell'immagine per i workload che utilizzano lo streaming delle immagini.

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 Image Streaming, che in genere viene compilata al primo pull da un client con lo streaming di immagini 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 dello streaming di immagini in anticipo.

L'API Prewarm Artifact consente di richiedere manualmente che una versione immagine o un tag specifico venga prememorizzato nella cache. Specifichi anche un periodo di conservazione per assicurarti che l'immagine rimanga nella cache per un periodo di tempo specificato.

Limitazioni

  • Solo API: il pre-riscaldamento è disponibile solo utilizzando l'API REST di Artifact Registry. Il pre-riscaldamento non è disponibile utilizzando gcloud CLI o Google Cloud la console.
  • Solo GKE: il pre-riscaldamento è efficace solo per i cluster GKE con lo streaming delle immagini attivato. Lo streaming di immagini richiede un software specifico in esecuzione sul nodo client.
  • Singolo artefatto: puoi precaricare un solo artefatto (versione o tag) per richiesta API.
  • Immagini multi-architettura: non supportate. Utilizza la versione specifica per un'immagine dell'architettura.

Prima di iniziare

  1. Abilita l'API Artifact Registry. Per ulteriori informazioni, consulta Attivare Artifact Registry.
  2. 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 precaricate, chiedi all'amministratore di concederti i seguenti ruoli IAM sul repository:

  • Precarica o rimuovi gli artefatti dalla cache (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact): Artifact Registry Writer (roles/artifactregistry.writer)
  • Controlla o elenca gli artefatti precaricati (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts): Lettore 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 riempirla eccessivamente. Nel frattempo, gli utenti con accesso in lettura possono verificare quali artefatti sono disponibili per lo streaming.

Precaricare un'immagine

Per precaricare 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 precaricare. Devi specificare un version o un tag.
version (Facoltativo) La versione specifica dell'artefatto da preriscaldare. Devi specificare un version o un tag.
retention_days (Facoltativo) Il numero di giorni per cui l'artefatto deve essere conservato 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.

Esempio: precaricamento di una versione specifica

L'esempio seguente precarica la versione sha256:52e... del pacchetto nginx nel repository my-repo.

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

Esempio: precaricare un tag

Il seguente esempio precarica l'immagine taggata 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"

Controllare lo stato del prewarm

Per verificare se un artefatto è preriscaldato, 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 precaricati in un repository, utilizza il metodo GET nella raccolta prewarmedArtifacts.

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"

Rimuovi dalla cache

Per rimuovere esplicitamente un artefatto dalla cache di prewarm, 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"

Passaggi successivi