Auf dieser Seite wird beschrieben, wie Sie Container-Images mit Docker hoch- und herunterladen. Außerdem finden Sie Informationen zum Abrufen von Images mit dem Tool crictl
, wenn Sie Probleme in der Google Kubernetes Engine beheben.
Informationen zum Bereitstellen in Google Cloud -Laufzeitumgebungen finden Sie unter In Google Cloudbereitstellen.
Unter Images verwalten finden Sie Anleitungen zum Auflisten, Taggen und Löschen von Images.
Hinweis
- Wenn das Ziel-Repository nicht vorhanden ist, erstellen Sie ein neues Repository.
- Sie müssen auf das Repository mindestens Zugriff als Artifact Registry-Autor haben.
- Installieren Sie Docker, falls es noch nicht installiert ist.
Erforderliche Rollen
Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Repository zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Pushen und Pullen von Images benötigen:
-
Images abrufen:
Artifact Registry-Leser (
roles/artifactregistry.reader
) -
Images taggen und per Push übertragen:
Artifact Registry Writer (
roles/artifactregistry.writer
)
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 Anforderungen 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.
Artifact Registry fügt der Docker-Konfigurationsdatei nicht automatisch alle Registry-Hosts hinzu. Die Docker-Antwortzeit ist bei einer großen Anzahl konfigurierter Registries deutlich langsamer. Um die Anzahl der Registrierungen in der Konfigurationsdatei zu minimieren, fügen Sie der Datei die erforderlichen Hosts hinzu.
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
sind die konfigurierten Docker-Hosts für Artifact Registry aufgeführt.
Hostnamen enden auf -docker.pkg.dev
. Im folgenden Beispiel sind einige Hosts zu sehen, die für den Anmeldedaten-Helfer 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 Anmeldedaten-Helper noch einmal aus, um den Host hinzuzufügen. Mit dem folgenden Befehl wird beispielsweise us-west1-docker.pkg.dev
hinzugefügt.
gcloud Credential Helper:
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 Zugriffstoken-Authentifizierung generieren Sie ein Token und verwenden es mit dem Befehl docker login
als Passwort. Tokens sind 60 Minuten lang gültig. Sie sollten sich also kurz vor dem Tagging, Pushen oder Pullen von Bildern authentifizieren.
Im folgenden Beispiel wird ein Zugriffstoken mithilfe der Identitätsübernahme eines Dienstkontos generiert und dann bei der Artifact Registry authentifiziert. Sie benötigen Berechtigungen für die Rolle „Ersteller von Dienstkonto-Tokens“ (roles/iam.serviceAccountTokenCreator
), um auf diese Weise ein Token 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
Bei einem 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
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 per Dienstkontoschlüssel.
Image hochladen
Repository-Modi:standard
Wenn Sie ein lokales Image in ein standardmäßiges Docker-Repository per Push übertragen möchten, taggen Sie es mit dem Repository-Namen und laden es dann hoch.
Wenn die Unveränderlichkeit von Tags in Ihrem Artifact Registry-Docker-Repository 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 Bildes verwenden, das Sie an das Repository pushen. 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 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 einen Upload von mehr als 60 Minuten erwarten, verwenden Sie eine andere Authentifizierungsmethode.
- Bildgröße
- Die maximale Größe eines Artefakts beträgt 5 TB.
- Artifact Registry unterstützt keine von Docker aufgeteilten Uploads. Einige Tools unterstützen das Hochladen großer Images mit aufgeteilten Uploads oder mit einem einzelnen monolithischen Upload. Sie müssen monolithische Uploads verwenden, um Images in Artifact Registry zu übertragen.
Lokales Image taggen
Sie müssen im Repository authentifiziert sein.
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 Ihre Projekt-ID in 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 sich vom lokalen Image-Namen 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 Zielbilds:
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 des Image-Namens sowie zur Handhabung von auf Domains beschränkten Projekten finden Sie unter Repository- und Image-Namen.
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-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 in das Repository pushen, wenn das Tag bereits von einer anderen Version desselben Images im Repository verwendet wird. Um zu prüfen, ob die Einstellung für das Repository aktiviert ist, führen Sie den Befehl aus: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
Sie müssen im Repository authentifiziert sein.
Wenn Sie
gcloud auth configure-docker
oderdocker-credential-gcr configure-docker
zum Konfigurieren Ihres Docker-Clients verwendet haben, prüfen Sie, ob sich der Ziel-Hostname in Ihrer Docker-Konfigurationsdatei befindet.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 sich das Image anzeigen zu lassen.
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
Images mit Docker abrufen
Repository-Modi: standard, remote, virtualSie müssen im Repository authentifiziert sein.
Wenn Sie
gcloud auth configure-docker
oderdocker-credential-gcr configure-docker
zum Konfigurieren Ihres Docker-Clients verwendet haben, prüfen Sie, ob sich der Ziel-Hostname in Ihrer Docker-Konfigurationsdatei befindet.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 Speicherort des Repositorys, in dem das Image gespeichert ist.PROJECT
ist Ihre Projekt-ID in der Google Cloud Console. Wenn die Projekt-ID einen Doppelpunkt (:
) enthält, finden Sie weitere Informationen unter Auf Domains beschränkte Projekte.PROJECT
ist Ihre Projekt-ID in der Google Cloud Console.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 Bildes hat einen eindeutigen Bild-Digest. Klicken Sie in der Google Cloud Console auf das jeweilige Image, um dessen 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, wird das Image von diesem Repository heruntergeladen und im Cache gespeichert, wenn 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 mehr als einem Upstream-Repository verfügbar ist, wählt Artifact Registry basierend auf den für das virtuelle Repository konfigurierten Prioritätseinstellungen ein Upstream-Repository aus.
Angenommen, Sie haben ein virtuelles Repository mit den folgenden Prioritätseinstellungen für Upstream-Repositories:
main-repo
: Priorität auf100
festgelegtsecondary-repo1
: Priorität auf80
festgelegt.secondary-repo2
: Priorität auf80
festgelegt.test-repo
: Priorität auf20
festgelegt.
main-repo
hat den höchsten Prioritätswert, daher wird im virtuellen Repository immer zuerst danach gesucht.
Sowohl für secondary-repo1
als auch für secondary-repo2
ist die Priorität auf 80
festgelegt. Wenn ein angefordertes Image in main-repo
nicht verfügbar ist, sucht Artifact Registry als Nächstes in diesen Repositories. Da beide denselben Prioritätswert haben, kann Artifact Registry ein Image aus einem der beiden Repositories bereitstellen, wenn die Version in beiden verfügbar ist.
test-repo
hat den niedrigsten Prioritätswert und ein gespeichertes Artefakt wird bereitgestellt, wenn es in keinem der anderen Upstream-Repositories vorhanden ist.
Bilder mit crictl
herunterladen
crictl
ist ein nützliches Befehlszeilentool für CRI-Laufzeitentwickler, mit dem sie ihre Laufzeit debuggen können, ohne Kubernetes-Komponenten einrichten zu müssen. Wenn Ihre Google Kubernetes Engine-Knoten eine containerd-Laufzeit verwenden, können Sie mit crictl
Images aus Artifact Registry abrufen.
Da crictl
in erster Linie ein Tool zur Fehlerbehebung ist, sind einige Docker-Befehle wie das Pushen oder Tagging von Images nicht verfügbar.
So laden Sie ein Image aus Artifact Registry herunter:
Rufen Sie in der Google Cloud Console die Seite VM-Instanzen auf.
Stellen Sie eine SSH-Verbindung zum Knoten her, für den Sie die Fehlerbehebung durchführen.
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"
Bild mit
crictl pull --creds
und dem Wertaccess_token
abrufencrictl 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 so aus:
Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5
Nächste Schritte
- Mehr über das Verwalten von Tags und das Löschen von Images erfahren
- Mehr über Container in Compute Engine erfahren, wenn Sie Container in Compute Engine ausführen möchten
crictl
zum Debuggen von Kubernetes-Knoten verwenden- Mit
crictl
Images aus privaten Artifact Registry-Repositories abrufen crictl
Weitere Informationen zum Konfigurieren von Image-Registries