Images hoch- und herunterladen

Mit Artifact Registry können Sie Container-Images mit Docker oder Podman speichern, versionieren und abrufen. Sie können auch Images mit dem Tool crictl abrufen, um Probleme mit Google Kubernetes Engine-Knoten zu beheben. Informationen zum Ausführen von Arbeitslasten finden Sie unter In Google Cloudbereitstellen. Informationen zum Auflisten, Taggen und Löschen von Images finden Sie unter Images verwalten.

Hinweis

  1. Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
  2. Sie müssen auf das Repository mindestens Zugriff als Artifact Registry-Autor haben.
  3. Wenn Sie Images mit Docker übertragen möchten, installieren Sie Docker, falls es noch nicht installiert ist.
  4. Wenn Sie Images mit Podman übertragen möchten, installieren Sie Podman.
  5. Installieren Sie die Google Cloud CLI, falls sie noch nicht installiert ist.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, damit Sie die nötigen Berechtigungen zum Pushen und Pullen von Images haben:

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.

Bei einem Repository authentifizieren

Sie müssen sich bei Repositories authentifizieren, wenn Sie Docker oder einen anderen Drittanbieterclient mit einem Docker-Repository verwenden. In diesem Abschnitt finden Sie eine kurze Zusammenfassung der Voraussetzungen für eine erfolgreiche Authentifizierung. Eine ausführliche Anleitung finden Sie unter Authentifizierung für Docker einrichten.

Credential Helper verwenden

Für den gcloud CLI Credential Helper oder den Standalone Credential Helper müssen die von Ihnen verwendeten Artifact Registry-Hosts in Ihrer Docker-Konfigurationsdatei enthalten sein.

In Artifact Registry werden nicht automatisch alle Registry-Hosts der Docker-Konfigurationsdatei hinzugefügt. Die Docker-Reaktionszeit ist deutlich langsamer, wenn eine große Anzahl von Registries konfiguriert ist. Um die Anzahl der Registrierungen in der Konfigurationsdatei zu minimieren, fügen Sie die benötigten Hosts in die Datei ein.

Führen Sie den folgenden Befehl aus, um den Inhalt der Konfigurationsdatei aufzurufen und zu prüfen, welche Hosts konfiguriert sind:

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

Im Abschnitt credHelpers werden die konfigurierten Artifact Registry-Docker-Hosts aufgeführt. Hostnamen enden mit -docker.pkg.dev. Im folgenden Beispiel sind einige Hosts zu sehen, die für den Anmeldedaten-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 den Credential Helper noch einmal aus, um den Host hinzuzufügen. Mit dem folgenden Befehl wird beispielsweise us-west1-docker.pkg.dev hinzugefügt.

  • gcloud CLI-Anmeldedaten-Helfer:

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

  • Eigenständiger Credential Helper

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

Zugriffstoken verwenden

Bei der Authentifizierung mit Zugriffstoken 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, Pushing oder Pulling von Images authentifizieren.

Im folgenden Beispiel wird ein Zugriffstoken mithilfe der Dienstkonto-Identitätsübernahme generiert und dann die Authentifizierung bei Artifact Registry durchgeführt. 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 Authentifizierung mit Zugriffstoken.

Dienstkontoschlüssel verwenden

Bei einem Dienstkontoschlüssel verwenden Sie den Schlüssel als Passwort mit dem Befehl docker login.

Mit dem folgenden Befehl wird beispielsweise der base64-codierte Dienstkontoschlüssel in der Datei key.json verwendet, um sich bei us-west1-docker.pkg.dev zu authentifizieren.

Linux

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

Windows

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

Weitere Informationen finden Sie in der Anleitung zum Einrichten der Authentifizierung mit einem Dienstkontoschlüssel.

Image mit Docker übertragen

Repository-Modi:Standard

Wenn Sie ein lokales Image in ein Standard-Docker-Repository hochladen möchten, taggen Sie es mit dem Repository-Namen und laden es dann hoch.

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

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

Upload-Zeitpunkt
Wenn Sie sich mit einem Zugriffstoken bei Artifact Registry authentifizieren, ist das Token nur 60 Minuten lang gültig. Wenn Sie davon ausgehen, dass der Upload länger als 60 Minuten dauert, verwenden Sie eine andere Authentifizierungsmethode.
Bildgröße
Die maximale Größe eines Artefakts beträgt 5 TB.
Artifact Registry unterstützt keine chunked uploads von Docker. Einige Tools unterstützen das Hochladen großer Bilder entweder mit Chunked Uploads oder mit einem einzelnen monolithischen Upload. Sie müssen monolithische Uploads verwenden, um Images per Push an Artifact Registry zu übertragen.

Lokales Image taggen

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

  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 Speicherort des Repositorys, in dem das Image gespeichert ist.
    • PROJECT-ID ist die Projekt-ID Ihrer Google Cloud -Konsole. Wenn Ihre Projekt-ID einen Doppelpunkt (:) enthält, lesen Sie den Abschnitt Projekte mit Domainbereich.
    • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
    • IMAGE ist der Image-Name. Er kann sich vom lokalen Namen des Bildes unterscheiden.

    Angenommen, Sie haben ein Image mit folgenden Merkmalen:

    • Speicherort des Repositorys: us-west1
    • 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-west1-docker.pkg.dev/my-project/my-repo/test-image

    Weitere Informationen zum Format von Image-Namen, einschließlich der Verarbeitung von Projekten mit Domainbereich, 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 lokalen Image-Namen oder die Image-ID und TAG durch das Tag. Wenn Sie kein Tag angeben, wendet Docker das Standard-Tag latest 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 latest-Tags. Sie können kein Image an das Repository senden, wenn das Tag bereits von einer anderen Version desselben Images im Repository verwendet wird. Führen Sie den folgenden Befehl aus, um zu prüfen, 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-west1-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-west1-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 authentifiziert sind.

    Wenn Sie gcloud auth configure-docker oder docker-credential-gcr configure-docker zum Konfigurieren Ihres Docker-Clients verwendet haben, prüfen Sie, ob sich der Zielhostname in Ihrer 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 Bild 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-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
  us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46

Image mit Podman übertragen

Sie können ein Container-Image von Podman in Artifact Registry übertragen.

  1. Erstellen Sie Ihr Image mit Podman mit dem folgenden Befehl: 

     podman build -t IMAGE:latest .

  2. Taggen Sie Ihr lokales Podman-Image für Artifact Registry.

    Verwenden Sie den vollständigen Artifact Registry-Pfad für das Tag. Das Format ist dasselbe wie für Docker: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE:TAG

    Führen Sie dazu diesen Befehl aus:

     podman tag IMAGE-NAME LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY_NAME/PODMAN-IMAGE:TAG

  3. Authentifizieren Sie Podman bei Artifact Registry. Wenn Sie es mit dem Credential Helper verwenden möchten, führen Sie den folgenden Befehl aus:

     gcloud auth configure-docker LOCATION-docker.pkg.dev

    Wenn Podman Anmeldedaten nicht automatisch abrufen kann, können Sie sich auch mit einem Zugriffstoken authentifizieren. Führen Sie dazu diesen Befehl aus:

     gcloud auth print-access-token | podman login -u oauth2accesstoken --password-stdin LOCATION-docker.pkg.dev

  4. Übertragen Sie das getaggte Image per Push an Artifact Registry:

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

    Das Tag muss genau mit dem Tag übereinstimmen, das Sie zum Taggen des lokalen Podman-Images verwendet haben.

Images mit Docker abrufen

Repository modes (Repository-Modi): standard, remote, virtual

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

    Wenn Sie gcloud auth configure-docker oder docker-credential-gcr configure-docker zum Konfigurieren Ihres Docker-Clients verwendet haben, prüfen Sie, ob sich der Zielhostname in Ihrer Docker-Konfigurationsdatei befindet.

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

    ghcr.io

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

    oder

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

    Ersetzen Sie die folgenden Werte:

    • LOCATION ist der regionale oder multiregionale Speicherort des Repositorys, in dem das Image gespeichert ist.
    • PROJECT ist die Projekt-ID Ihrer Google Cloud -Konsole. Wenn Ihre Projekt-ID einen Doppelpunkt (:) enthält, lesen Sie den Abschnitt Projekte mit Domainbereich.
    • PROJECT ist die Projekt-ID Ihrer Google Cloud -Konsole.
    • REPOSITORY ist der Name des Repositorys, in dem das Image gespeichert ist.
    • OWNER ist das GitHub-Nutzerkonto oder der Organisationsname des Repository-Inhabers.
    • 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-Hashwert des Bildinhalts. Jede Version eines Bildes hat einen eindeutigen Bild-Digest. Klicken Sie in der Google Cloud Console auf das jeweilige Bild, 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-west1
    • Repository-Name: my-repo
    • Projekt-ID: my-project
    • Repository-Inhaber: owner-name
    • Image-Name: test-image
    • Tag: staging

    Der Befehl zum Herunterladen dieses Images lautet dann:

    docker pull us-west1-docker.pkg.dev/my-project/my-repo/owner-name/test-image:staging

    Andere Repositories

    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 Speicherort des Repositorys, in dem das Image gespeichert ist.
    • PROJECT ist die Projekt-ID Ihrer Google Cloud -Konsole. Wenn Ihre Projekt-ID einen Doppelpunkt (:) enthält, lesen Sie den Abschnitt Projekte mit Domainbereich.
    • PROJECT ist die Projekt-ID Ihrer Google Cloud -Konsole.
    • 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-Hashwert des Bildinhalts. Jede Version eines Bildes hat einen eindeutigen Bild-Digest. Klicken Sie in der Google Cloud Console auf das jeweilige Bild, 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-west1
    • 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-west1-docker.pkg.dev/my-project/my-repo/test-image:staging

Docker lädt das angegebene Image herunter.

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

Wenn Sie ein Image aus einem virtuellen Repository anfordern, sucht Artifact Registry in Upstream-Repositories nach dem angeforderten Image. Wenn Sie eine Version anfordern, die in mehreren Upstream-Repositories verfügbar ist, wählt Artifact Registry ein Upstream-Repository basierend auf den für das virtuelle Repository konfigurierten Prioritätseinstellungen aus.

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

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

main-repo hat den höchsten Prioritätswert, daher wird immer zuerst darin gesucht.

Sowohl für secondary-repo1 als auch für secondary-repo2 ist die Priorität auf 80 festgelegt. Wenn ein angefordertes Image nicht in main-repo verfügbar ist, durchsucht Artifact Registry als Nächstes diese Repositories. Da beide denselben Prioritätswert haben, kann Artifact Registry ein Image aus einem der beiden Repositorys 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 vorhanden ist.

Bilder werden mit crictl abgerufen

crictl ist ein nützliches Befehlszeilentool für CRI-Laufzeitentwickler, um ihre Laufzeit zu debuggen, ohne Kubernetes-Komponenten einrichten zu müssen. Wenn Ihre Google Kubernetes Engine-Knoten die 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 Pushen oder Taggen von Bildern nicht verfügbar.

So laden Sie ein Image aus Artifact Registry herunter:

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

    Zu Seite „VM-Instanzen“

  2. Stellen Sie eine SSH-Verbindung zum Knoten her, bei dem Sie die Fehlerbehebung durchführen.

  3. Rufen Sie ein Zugriffstoken für die Authentifizierung beim Repository ab.

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

  4. Rufen Sie das Image mit crictl pull --creds und dem Wert access_token ab.

    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 etwa so aus:

    Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Nächste Schritte