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.
  • Un seul artefact : 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 pour une image d'architecture.
  • Limite par projet : il existe une limite globale de 100 Go par projet consommateur pour les images préparées. Lorsque la limite est atteinte, les images plus anciennes sont supprimées pour faire de la place aux nouvelles images.

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.
stream_location Facultatif. Région spécifique dans laquelle l'image sera préparée. Par défaut, elle correspond à l'emplacement de l'image. Notez que les configurations multirégionales ne sont pas prises en charge. Si une région étendue est spécifiée, les valeurs par défaut sont us-central1 (États-Unis), europe-north1 (Europe) et asia-east1 (Asie).

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 de la région "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"

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. L'exemple suivant répertorie toutes les images préparées sous my-repo dans us-east1. Le filtre stream_location est obligatoire.

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"/

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