Images hoch- und herunterladen

Auf dieser Seite wird beschrieben, wie Sie Container-Images mit Docker hoch- und herunterladen können. Außerdem erhalten Sie Informationen zum Abrufen von Images mit dem crictl-Tool, wenn Sie Probleme in Google Kubernetes Engine beheben möchten.

Informationen zum Bereitstellen in Google Cloud-Laufzeitumgebungen finden Sie unter In Google Cloud bereitstellen.

Unter Images verwalten finden Sie Anleitungen zum Auflisten, Taggen und Löschen von Images.

Hinweise

  1. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
  2. Sie müssen auf das Repository mindestens access als Artifact Registry-Autor haben.
  3. Installieren Sie Docker, falls noch nicht geschehen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zu gewähren, damit Sie die Berechtigungen erhalten, die Sie zum Hoch- und Herunterladen von Images benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff verwalten.

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

Bei einem Repository authentifizieren

Sie müssen sich bei Repositories authentifizieren, wenn Sie Docker oder den Client eines Drittanbieters mit einem Docker-Repository verwenden. Dieser Abschnitt enthält eine kurze Zusammenfassung dessen, was du für eine erfolgreiche Authentifizierung benötigst. Eine ausführliche Anleitung finden Sie unter Authentifizierung für Docker einrichten.

Credential Helper verwenden

Für gcloud CLI Credential Helper oder eigenständiges Credential Helper müssen sich die verwendeten Artifact Registry-Hosts in Ihrer Docker-Konfigurationsdatei befinden.

Artifact Registry fügt der Docker-Konfigurationsdatei nicht automatisch alle Registry-Hosts hinzu. Die Docker-Antwortzeit ist bei einer großen Anzahl konfigurierter Registries erheblich länger. Um die Anzahl der Registrys in der Konfigurationsdatei zu minimieren, fügen Sie der Datei die benötigten Hosts hinzu.

Wenn Sie prüfen möchten, welche Hosts konfiguriert sind, führen Sie den folgenden Befehl aus, um den Inhalt der Konfigurationsdatei anzuzeigen:

  • Linux: cat ~/.docker/config.json
  • Windows: cat %USERPROFILE%\.docker\config.json

Im Abschnitt credHelpers werden die konfigurierten Artifact Registry-Docker-Hosts aufgeführt. Hostnamen enden auf -docker.pkg.dev. Das folgende Beispiel zeigt einige Hosts, die für den Credential Helper der gcloud CLI konfiguriert sind.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Wenn ein Host, den Sie verwenden möchten, nicht in der Liste enthalten ist, führen Sie Credential Helper noch einmal aus, um den Host hinzuzufügen. Mit dem folgenden Befehl wird beispielsweise us-east1-docker.pkg.dev hinzugefügt.

  • Credential Helper für die gcloud CLI:

    gcloud auth configure-docker us-east1-docker.pkg.dev

  • Eigenständiger Credential Helper

    docker-credential-gcr configure-docker us-east1-docker.pkg.dev

Zugriffstoken

Für die Zugriffstoken-Authentifizierung generieren Sie ein Token und verwenden es als Passwort mit dem Befehl docker login. Tokens sind 60 Minuten lang gültig. Sie sollten sich also kurz vor dem Taggen, Übertragen oder Abrufen von Images authentifizieren.

Im folgenden Beispiel wird mithilfe des Identitätswechsels eines Dienstkontos ein Zugriffstoken generiert und dann bei Artifact Registry authentifiziert. Sie benötigen Berechtigungen in der Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator), um ein Token auf diese Weise zu generieren.

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Wenn Sie nicht berechtigt sind, die Identität eines Dienstkontos zu übernehmen, können Sie das Dienstkonto in Ihrer gcloud CLI-Sitzung aktivieren und dann ein Token abrufen. Weitere Informationen finden Sie in der Anleitung zum Einrichten der Zugriffstoken-Authentifizierung.

Dienstkontoschlüssel verwenden

Für einen Dienstkontoschlüssel verwenden Sie den Schlüssel als Passwort mit dem Befehl docker login.

Im folgenden Befehl wird beispielsweise der base64-codierte Dienstkontoschlüssel in der Datei key.json zur Authentifizierung bei us-east1-docker.pkg.dev verwendet.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-east1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-east1-docker.pkg.dev < key.json

Weitere Informationen finden Sie in der Anleitung zum Einrichten der Authentifizierung für den Dienstkontoschlüssel.

Image hochladen

Repository-Modi: Standard

Um ein lokales Image in ein standardmäßiges Docker-Repository zu übertragen, taggen Sie es mit dem Repository-Namen und übertragen es dann per Push.

Wenn in Ihrem Artifact Registry-Docker-Repository die Tag-Unveränderlichkeit aktiviert ist, muss ein Tag im Repository immer auf denselben Image-Digest verweisen. Sie können das Tag nicht für eine andere Version desselben Images verwenden, das Sie in das Repository übertragen. Weitere Informationen zu Image-Digests, Tags und der Unveränderlichkeit von Tags finden Sie unter Container-Image-Versionen.

Für große Bilder gelten die folgenden Beschränkungen:

Upload-Zeitpunkt
Wenn Sie sich mit einem Zugriffstoken bei Artifact Registry authentifizieren, ist dieses nur 60 Minuten lang gültig. Wenn Sie davon ausgehen, dass die Uploadzeit 60 Minuten überschreitet, verwenden Sie eine andere Authentifizierungsmethode.
Bildgröße
Die maximale Artefaktgröße beträgt 5 TB.
Artifact Registry unterstützt keine aufgeteilten Docker-Uploads. Einige Tools unterstützen das Hochladen großer Bilder entweder mit aufgeteilten Uploads oder einem einzelnen monolithischen Upload. Sie müssen monolithische Uploads verwenden, um Images per Push in Artifact Registry zu übertragen.

Lokales Image taggen

  1. Achten Sie darauf, dass Sie für das Repository authentifizieren.

  2. Legen Sie den Namen des Images fest. Der vollständige Image-Name hat folgendes Format:

    LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

    Ersetzen Sie die folgenden Werte:

    • LOCATION ist der regionale oder multiregionale Standort des Repositorys, an dem das Image gespeichert ist, z. B. us-east1 oder us.

    • PROJECT-ID ist die Projekt-ID der Google Cloud Console. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.

    • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.

    • IMAGE ist der Image-Name. Dieser kann vom lokalen Image-Namen abweichen.

    Angenommen, Sie haben ein Image mit folgenden Merkmalen:

    • Speicherort des Repositorys: us-east1
    • Repository-Name: my-repo
    • Projekt-ID: my-project
    • Name des lokalen Images: my-image
    • Name des Ziel-Images: test-image

    Der Image-Name in diesem Beispiel lautet dann:

    us-east1-docker.pkg.dev/my-project/my-repo/test-image

    Weitere Informationen zum Format des Image-Namens sowie zur Handhabung von auf Domains beschränkten Projekten finden Sie unter Repository- und Image-Namen.

  3. Taggen Sie das lokale Image mit dem Repository-Namen.

    docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    Ersetzen Sie SOURCE-IMAGE durch den Namen des lokalen Images oder die Image-ID und TAG durch das Tag. Wenn Sie kein Tag angeben, wendet Docker das Standard-latest-Tag an.

    Wenn die Einstellung für unveränderliche Image-Tags aktiviert ist, müssen Tags für jede Image-Version eindeutig sein, einschließlich des Tags latest. Sie können ein Image nicht in das Repository hochladen, wenn das Tag bereits von einer anderen Version desselben Images im Repository verwendet wird. Prüfen Sie mit dem folgenden Befehl, ob die Einstellung für das Repository aktiviert ist:

    gcloud artifacts repositories describe REPOSITORY \
    --project=PROJECT-ID \
    --location=LOCATION

    Für das Beispiel-Image aus dem vorherigen Schritt verwenden Sie den folgenden Befehl, wenn sich das lokale Image my-image im aktuellen Verzeichnis befindet:

    docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image

    Wenn Sie ein bestimmtes Tag anwenden möchten, geben Sie folgenden Befehl ein:

    docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    Um das Tag staging für das Beispiel-Image zu verwenden, fügen Sie zum Befehl :staging hinzu:

    docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging

Getaggtes Image in Artifact Registry hochladen

  1. Achten Sie darauf, dass Sie für das Repository authentifizieren.

    Wenn Sie Ihren Docker-Client mit gcloud auth configure-docker oder docker-credential-gcr configure-docker konfiguriert haben, prüfen Sie, ob sich der Zielhostname in der Docker-Konfigurationsdatei befindet.

  2. Laden Sie das getaggte Image mit dem folgenden Befehl hoch:

    docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

    Mit diesem Befehl wird das Image mit dem Tag latest hochgeladen. Wenn Sie ein Image mit einem anderen Tag hochladen möchten, verwenden Sie folgenden Befehl:

    docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

Wenn Sie ein Image hochladen, wird es in dem angegebenen Repository gespeichert.

Nach dem Hochladen des Images haben Sie folgende Möglichkeiten:

  • Rufen Sie die Google Cloud Console auf, um das Image anzusehen.

  • Führen Sie den Befehl gcloud aus, um die Tags und den automatisch generierten Digest des Images anzeigen zu lassen:

    gcloud artifacts docker images list \
LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]

    Die folgende Beispielausgabe enthält abgeschnittene Image-Digests. Der Befehl gibt aber immer den vollständigen Image-Digest zurück.

     IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
  us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46

Images mit Docker abrufen

Repository-Modi: Standard, Remote, virtuell

  1. Achten Sie darauf, dass Sie für das Repository authentifizieren.

    Wenn Sie Ihren Docker-Client mit gcloud auth configure-docker oder docker-credential-gcr configure-docker konfiguriert haben, prüfen Sie, ob sich der Zielhostname in der Docker-Konfigurationsdatei befindet.

  2. Zum Herunterladen von Daten aus einem Repository verwenden Sie folgenden Befehl:

    docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    oder

    docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

    Ersetzen Sie die folgenden Werte:

    • LOCATION ist der regionale oder multiregionale Standort des Repositorys, an dem das Image gespeichert ist, z. B. us-east1 oder us.
    • PROJECT ist die Projekt-ID der Google Cloud Console. Wenn die Projekt-ID einen Doppelpunkt (:) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.
    • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
    • IMAGE ist der Name des Images im Repository.
    • TAG ist das Tag für die Image-Version, die Sie herunterladen möchten.
    • IMAGE-DIGEST ist der sha256-Hash-Wert des Image-Inhalts. Jede Version eines Images hat einen eigenen Image-Digest. Klicken Sie in der Google Cloud Console auf das jeweilige Image, um die zugehörigen Metadaten aufzurufen. Der Digest wird unter Image-Digest aufgeführt.

    Angenommen, Sie haben ein Image mit folgenden Merkmalen:

    • Speicherort des Repositorys: us-east1
    • Repository-Name: my-repo
    • Projekt-ID: my-project
    • Image-Name: test-image
    • Tag: staging

    Der Befehl zum Herunterladen dieses Images lautet dann:

    docker pull us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging

Docker lädt das angegebene Image herunter.

Wenn Sie ein Image von einem Remote-Repository anfordern, lädt das Remote-Repository das Image von der Upstream-Quelle herunter und speichert es im Cache, wenn keine im Cache gespeicherte Kopie vorhanden ist.

Wenn Sie ein Image von einem virtuellen Repository anfordern, durchsucht Artifact Registry die Upstream-Repositories nach dem angeforderten Image. Wenn Sie eine Version anfordern, die in mehr als einem Upstream-Repository verfügbar ist, wählt Artifact Registry anhand der für das virtuelle Repository konfigurierten Prioritätseinstellungen ein Upstream-Repository aus, das verwendet werden soll.

Angenommen, Sie haben ein virtuelles Repository mit den folgenden Prioritätseinstellungen für Upstream-Repositories:

  • main-repo: Priorität auf 100 festgelegt
  • secondary-repo1: Priorität auf 80 festgelegt.
  • secondary-repo2: Priorität auf 80 festgelegt.
  • test-repo: Priorität auf 20 festgelegt.

main-repo hat den höchsten Prioritätswert, sodass das virtuelle Repository immer zuerst danach sucht.

Die Priorität von secondary-repo1 und secondary-repo2 ist auf 80 festgelegt. Wenn ein angefordertes Image in main-repo nicht verfügbar ist, durchsucht Artifact Registry als Nächstes diese Repositories. Da beide denselben Prioritätswert haben, kann Artifact Registry ein Image aus beiden Repositories bereitstellen, wenn die Version in beiden verfügbar ist.

test-repo hat den niedrigsten Prioritätswert und stellt ein gespeichertes Artefakt bereit, wenn es in keinem der anderen Upstream-Repositories verfügbar ist.

Bilder mit crictl abrufen

crictl ist ein nützliches Befehlszeilentool für CRI-Laufzeitentwickler, um Fehler in ihrer Laufzeit zu beheben, ohne Kubernetes-Komponenten einrichten zu müssen. Wenn Ihre Google Kubernetes Engine-Knoten eine containerd-Laufzeit verwenden, können Sie Images mit crictl aus Artifact Registry abrufen.

Da crictl in erster Linie ein Tool zur Fehlerbehebung ist, sind einige Docker-Befehle wie das Hochladen oder Taggen von Images nicht verfügbar.

So rufen Sie ein Image aus Artifact Registry ab:

  1. Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.

    Zu Seite „VM-Instanzen“

  2. Stellen Sie eine SSH-Verbindung zu dem Knoten her, für den Sie eine Fehlerbehebung durchführen.

  3. Rufen Sie ein Zugriffstoken zur Authentifizierung beim Repository ab.

    curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

  4. Image mit crictl pull --creds und dem Wert access_token abrufen

    crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

    oder

    crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

    Die Ausgabe sieht in etwa so aus:

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Nächste Schritte