Latenz durch Vorab-Aufwärmen von Bildern reduzieren

Mit dem Vorab-Download von Images können Sie das Herunterladen von Container-Images in den Image-Streaming-Cache explizit auslösen, bevor ein Laufzeitclient sie anfordert. Dadurch wird die „Kaltstart“-Latenz, die mit dem ersten Abruf einer neuen Image-Version für Arbeitslasten mit Image-Streaming verbunden ist, effektiv eliminiert.

Übersicht

Wenn Sie ein Image in Artifact Registry hochladen, wird es in einem zugrunde liegenden Speichersystem gespeichert. Für den Zugriff mit niedriger Latenz verwendet Artifact Registry auch einen Image Streaming-Cache, der in der Regel beim ersten Pull von einem Client mit aktiviertem Image Streaming gefüllt wird. Bei latenzempfindlichen Arbeitslasten, z. B. beim Hochskalieren eines Google Kubernetes Engine-Clusters, kann das Warten auf das Aufwärmen dieses Cache zu Verzögerungen führen. Durch das Vorwärmen können Bilder vorab in den Image-Streaming-Cache geladen werden.

Mit der Prewarm Artifact API können Sie manuell anfordern, dass eine bestimmte Image-Version oder ein bestimmtes Tag vorab im Cache gespeichert wird. Sie geben auch einen Aufbewahrungszeitraum an, damit das Bild für einen bestimmten Zeitraum im Cache verbleibt.

Beschränkungen

  • Nur API: Das Vorwärmen ist nur über die Artifact Registry REST API verfügbar. Das Vorwärmen ist nicht über die gcloud CLI oder die Console verfügbar. Google Cloud
  • Nur GKE: Das Vorwärmen ist nur für GKE-Cluster mit aktiviertem Image-Streaming wirksam. Für das Image-Streaming ist spezielle Software erforderlich, die auf dem Clientknoten ausgeführt wird.
  • Einzelnes Artefakt: Sie können nur ein Artefakt (Version oder Tag) pro API-Anfrage vorab laden.
  • Images mit mehreren Architekturen: Nicht unterstützt. Verwenden Sie die spezifische Version für ein Architektur-Image.
  • Projektlimit: Für vorab geladene Bilder gilt ein Gesamtlagerlimit von 100 GB pro Verbraucherprojekt. Wenn das Limit erreicht ist, werden ältere Bilder entfernt, um Platz für neue Bilder zu schaffen.

Hinweis

  1. Aktivieren Sie die Artifact Registry API. Weitere Informationen finden Sie unter Artifact Registry aktivieren.
  2. Installieren Sie die gcloud CLI, um Authentifizierungstokens für REST API-Anfragen zu erhalten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, damit Sie die nötigen Berechtigungen zum Verwalten von vorab aufgewärmten Images haben:

  • Artefakte vorab laden oder aus dem Cache entfernen (artifactregistry.repositories.prewarmArtifact, artifactregistry.repositories.removePrewarmedArtifact): Artifact Registry-Autor (roles/artifactregistry.writer)
  • Vorab geladene Artefakte prüfen oder auflisten (artifactregistry.repositories.checkPrewarmedArtifact, artifactregistry.repositories.listPrewarmedArtifacts): Artifact Registry-Leser (roles/artifactregistry.reader)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Dieses Berechtigungsmodell sorgt dafür, dass nur Nutzer mit Schreibzugriff den Cachestatus verwalten können. So wird verhindert, dass unbefugte Nutzer den Cache überfüllen. Nutzer mit Lesezugriff können in der Zwischenzeit prüfen, welche Artefakte für das Streaming verfügbar sind.

Bild vorab laden

Um ein Bild vorzuwärmen, senden Sie eine POST-Anfrage an die :prewarmArtifact-Methode Ihres Repositorys.

REST API

Referenz: projects.locations.repositories.prewarmArtifact

Der Anfragetext hat die folgende Struktur:

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

Alternativ können Sie ein Tag verwenden:

{
  "tag": "projects/PROJECT_ID/locations/LOCATION/repositories/REPOSITORY/packages/PACKAGE/tags/TAG",
  "retention_days": 3,
  "force": true
}
Feld Beschreibung
tag Optional: Das spezifische Artefakt-Tag, das vorab geladen werden soll. Sie müssen entweder version oder tag angeben.
version Optional: Die spezifische Artefaktversion, die vorab geladen werden soll. Sie müssen entweder version oder tag angeben.
retention_days Optional: Die Anzahl der Tage, die das Artefakt im Cache aufbewahrt werden soll. Wenn Sie dieses Feld nicht angeben, beträgt der Standardwert 3 Tage.
force Optional: Wenn true, werden möglicherweise ältere Artefakte entfernt, um Platz für dieses zu schaffen.
stream_location Optional: Die spezifische Region, in der das Image vorab geladen wird. Standardmäßig entspricht dies dem Speicherort des Bildes. Multiregionale Konfigurationen werden nicht unterstützt. Wenn eine allgemeine Region angegeben wird, sind die Standardeinstellungen „us-central1“ (USA), „europe-north1“ (EU) und „asia-east1“ (Asien).

Beispiel: Bestimmte Version vorab laden

Im folgenden Beispiel wird die Version sha256:52e... des Pakets nginx im Repository my-repo in der Region „us-east1“ vorab aufgewärmt.

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"

Beispiel: Tag aufwärmen

Im folgenden Beispiel wird das Bild mit dem Tag production des Pakets my-app vorab geladen.

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"

Status der Vorbereitung prüfen

Verwenden Sie die Methode :checkPrewarmedArtifact, um zu prüfen, ob ein Artefakt vorab aufgewärmt wurde.

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"

Vorab aufgewärmte Artefakte auflisten

Wenn Sie alle vorab geladenen Artefakte in einem Repository auflisten möchten, verwenden Sie die Methode GET für die Sammlung prewarmedArtifacts. Im folgenden Beispiel werden alle vorab geladenen Images unter my-repo in us-east1 aufgelistet. Der Filter stream_location ist erforderlich.

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

Aus Cache entfernen

Wenn Sie ein Artefakt explizit aus dem Prewarm-Cache entfernen möchten, verwenden Sie die Methode :removePrewarmedArtifact. Verwenden Sie diese Methode, um Speicherplatz freizugeben oder wenn eine bestimmte Bildversion im Cache nicht mehr benötigt wird.

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"

Nächste Schritte