Réduire la latence avec le préchauffage des images

La préparation des images vous permet de déclencher explicitement le téléchargement d'images de conteneurs dans le cache Image Streaming avant qu'un client d'exécution ne les demande. Cela élimine efficacement la latence de "démarrage à froid" associée à la première extraction d'une nouvelle version d'image pour les charges de travail utilisant le streaming d'images.

Présentation

Lorsque vous transférez une image vers Artifact Registry, elle est stockée dans un système de stockage sous-jacent. Pour un accès à faible latence, Artifact Registry utilise également un cache Image Streaming , qui est généralement rempli lors de la première extraction à partir d'un client pour lequel le streaming d'images est activé. Pour les charges de travail sensibles à la latence, comme la mise à l'échelle d'un cluster Google Kubernetes Engine, l'attente du remplissage de ce cache peut entraîner des retards. La préparation permet de placer les images dans le cache Image Streaming à l'avance.

L'API Prewarm Artifact vous permet de demander manuellement la mise en cache préalable d'une version ou d'un tag d'image spécifique. Vous spécifiez également une période de conservation pour vous assurer que l'image reste dans le cache pendant une durée déterminée.

Limites

  • API uniquement : la préparation n'est disponible qu'à l'aide de l'API REST Artifact Registry. Elle n'est pas disponible à l'aide de la gcloud CLI ou Google Cloud de la console.
  • GKE uniquement : la préparation n'est efficace que pour les clusters GKE pour lesquels le streaming d'images est activé. Le streaming d'images nécessite l'exécution d'un logiciel spécifique sur le nœud client.
  • Artefact unique : vous ne pouvez préparer qu'un seul artefact (version ou tag) par requête API.
  • Images multi-architectures : non prises en charge. Utilisez la version spécifique d'une image d'architecture.

Avant de commencer

  1. Activez l'API Artifact Registry. Pour en savoir plus, consultez Activer Artifact Registry.
  2. Installez la gcloud CLI pour obtenir des jetons d'authentification pour les requêtes de l'API REST.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les images préparées, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le dépôt :

  • Préparer ou supprimer des artefacts du cache (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact) : Rédacteur Artifact Registry (roles/artifactregistry.writer)
  • Vérifier ou répertorier les artefacts préparés (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts) : Lecteur Artifact Registry (roles/artifactregistry.reader)

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Ce modèle d'autorisations garantit que seuls les utilisateurs disposant d'un accès en écriture peuvent gérer l'état du cache, ce qui empêche les utilisateurs non autorisés de le surcharger. Pendant ce temps, les utilisateurs disposant d'un accès en lecture peuvent vérifier quels artefacts sont disponibles pour le streaming.

Préparer une image

Pour préparer une image, envoyez une requête POST à la méthode :prewarmArtifact de votre dépôt.

API REST

Référence : projects.locations.repositories.prewarmArtifact

Le corps de la requête possède la structure suivante :

{
  "version": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/versions/VERSION",
  "retention_days": 3
}

Vous pouvez également utiliser un tag :

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
Champ Description
tag Facultatif. Tag d'artefact spécifique à préparer. Vous devez spécifier une version ou un tag.
version Facultatif. Version d'artefact spécifique à préparer. Vous devez spécifier une version ou un tag.
retention_days Facultatif. Nombre de jours pendant lesquels l'artefact doit être conservé dans le cache. Si vous ne spécifiez pas ce champ, la valeur par défaut est de trois jours.
force Facultatif. Si la valeur est true, le système peut supprimer des artefacts plus anciens pour faire de la place à celui-ci.

Exemple : Préparer une version spécifique

L'exemple suivant prépare la version sha256:52e... du package nginx dans le dépôt 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"

Exemple : Préparer un tag

L'exemple suivant prépare l'image taguée production du package 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"

Vérifier l'état de la préparation

Pour vérifier si un artefact est préparé, utilisez la méthode :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"

Répertorier les artefacts préparés

Pour répertorier tous les artefacts préparés dans un dépôt, utilisez la méthode GET sur la collection 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"

Supprimer du cache

Pour supprimer explicitement un artefact du cache de préparation, utilisez la méthode :removePrewarmedArtifact. Utilisez cette méthode pour libérer de l'espace ou lorsqu'une version d'image spécifique n'est plus nécessaire dans le 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"

Étape suivante