Fehlerbehebung

In diesem Abschnitt wird beschrieben, wie Sie häufig auftretende Probleme mit Google Container Registry und Docker beheben können.

Auf Domains beschränkte Projekte

Wenn Sie den Fehler invalid reference format erhalten, besteht das Problem möglicherweise darin, dass Ihr Projekt auf eine Domain beschränkt ist.

Sollte dies bei Ihrem Projekt der Fall sein, enthält die Projekt-ID die Domain und einen Doppelpunkt, z. B. example.com:my-project. Informationen zur Verwendung von Projekt-IDs, die eine Domain enthalten, finden Sie unter Auf Domains beschränkte Projekte.

Hinweis: Die Beschränkung von Projekten auf Domains ist ein Legacy-Feature. Auf Domains beschränkte Projekte können nicht mehr erstellt werden.

Fehlerstatus 405: v1 Registry API is disabled.

Wenn Sie immer wieder einen Fehler wie "v1 Registry-API ist deaktiviert" erhalten, wenn Sie Bilder herunter- oder hochladen, müssen Sie prüfen, ob die Schreibweisen Ihres Hostnamens, Ihrer Projekt-ID, Ihres Image-Namens, Ihres Tags und Ihrer Benachrichtigung korrekt sind.

Führen Sie den folgenden Befehl aus, um die Tags und Digests Ihres Images anzuzeigen:

gcloud container images list-tags [HOSTNAME]/[PROJECT-ID]/[IMAGE]

Beispiel:

gcloud container images list-tags gcr.io/my-project/my-image

Weitere Informationen zum Auflisten von Image-Tags und Digests finden Sie unter Images verwalten.

Berechtigungsprobleme

In den folgenden Abschnitten werden Lösungen für Probleme mit Berechtigungen beschrieben. Prüfen Sie immer, ob Sie die erforderlichen Berechtigungen zum Hoch- oder Herunterladen haben. Weitere Informationen enthalten Sie unter Berechtigungen und Rollen.

Berechtigungsprobleme im Zusammenhang mit dem einheitlichen Zugriff auf Bucket-Ebene

Wenn Sie den einheitlichen Zugriff auf Bucket-Ebene für einen von Container Registry verwendeten Storage-Bucket aktiviert haben, treten möglicherweise Probleme beim Hoch-und Herunterladen in Container Registry auf.

Zum Beheben der Probleme müssen Sie die erforderlichen Berechtigungen zum Hoch- oder Herunterladen haben. Diese Berechtigungen sind unter Berechtigungen und Rollen aufgeführt.

Berechtigungsprobleme im Zusammenhang mit der Einrichtung von Docker auf meinem lokalen Computer

Bei einem permission denied-Fehler wie im folgenden Beispiel:

FATA[0000] Post http://var/run/docker.sock/v1.17/images/gcr.io/container-engine-docs/example/push?tag=: dial unix /var/run/docker.sock: permission denied
ERROR: (gcloud.docker) A Docker command did not run successfully.
Tried to run: 'docker push gcr.io/container-engine-docs/example'
Exit code: 1

müssen Sie sich möglicherweise selbst der Nutzergruppe docker hinzufügen.

Führen Sie den folgenden Befehl in der Shell oder dem Terminalfenster aus:

  sudo usermod -a -G docker ${USER}

Achtung: Die Gruppe docker entspricht dem Nutzer root. In der Docker-Dokumentation finden Sie Einzelheiten zu den damit verbundenen Auswirkungen auf die Sicherheit Ihres Systems.

Starten Sie Ihr System neu, nachdem Sie sich selbst der Nutzergruppe docker hinzugefügt haben.

Berechtigungsprobleme bei der Kommunikation mit Container Registry

Beim Auftreten eines Berechtigungsfehlers wie diesem:

Permission denied: Unable to create the repository, please check that you have access to do so

1. Überprüfen Sie, ob für Ihr Projekt die Abrechnung aktiviert ist.

2. Überprüfen Sie den Zugriff:

   1. Prüfen Sie, ob Sie für gcloud authentifiziert sind. Führen Sie dazu folgenden Befehl aus:

      gcloud init
      

   2. Sorgen Sie dafür, dass Docker für die Verwendung von gcloud als Credential Helper für Container Registry konfiguriert ist. Führen Sie dazu folgenden Befehl aus:

      gcloud auth configure-docker
      

   3. Prüfen Sie, ob docker-credential-gcloud ausgeführt werden kann:

      docker-credential-gcloud list
      

      Sie sollten ein JSON-Objekt mit Ihrer Ziel-Registry als einer seiner Schlüssel sehen. Beispiel:

      {
        "https://asia.gcr.io": "oauth2accesstoken",
        "https://eu.gcr.io": "oauth2accesstoken",
        "https://gcr.io": "oauth2accesstoken",
        "https://us.gcr.io": "oauth2accesstoken"
      }
      

   4. Prüfen Sie dann, ob Sie in Cloud Storage für das Projekt, in das Sie hochladen, die Berechtigung zum Schreiben haben. Ist dies nicht der Fall, muss ein Administrator Ihrem Benutzerkonto den entsprechenden Zugriff gewähren, bevor Sie es noch einmal versuchen können.

   5. Bleibt das Problem weiterhin bestehen, nachdem Sie die entsprechende Berechtigung erhalten haben, fehlen in Ihrem Zugriffstoken möglicherweise folgende Bereiche:

      • https://www.googleapis.com/auth/devstorage.read_write
      • https://www.googleapis.com/auth/devstorage.full_control

      Das können Sie überprüfen, wenn Sie zuerst selbst das Zugriffstoken einholen. Dies ist von Anwendung zu Anwendung unterschiedlich. Wenn Sie beispielsweise ein Zugriffstoken aus einem Compute Engine-Standarddienstkonto verwenden, können Sie es mit den hier beschriebenen Schritten abrufen.

      Wenn Sie selbst das Zugriffstoken erhalten haben, können Sie folgenden Befehl verwenden, um die Bereiche einzusehen, die zum Abrufen des Zugriffstokens verwendet werden:

      curl -H "Authorization: Bearer <your access token>" https://www.googleapis.com/oauth2/v1/tokeninfo
      

      Sind die genannten Bereiche nicht enthalten, müssen Sie zur Behebung des Problems sicherstellen, dass diese Bereiche beim Erhalt des Zugriffstokens in Ihrem Code vorhanden sind. Werden beispielsweise Tokens speziell für das Standarddienstkonto Ihrer virtuellen Maschine in Compute Engine erzeugt, müssen Sie die Bereichseinstellung für diese virtuelle Maschine anpassen und die Tokens neu erstellen.

Berechtigungsprobleme beim Übertragen und Abrufen von Images

Um auf den Container Registry-Storage-Bucket zugreifen zu können, muss die VM-Instanz, die Images überträgt oder abruft, ordnungsgemäß mit den erforderlichen IAM-Berechtigungen und Zugriffsbereichen konfiguriert sein. Informationen zu den erforderlichen Einstellungen finden Sie unter Container Registry mit Google Cloud verwenden.

ImagePullBackoff-Fehler von Google Kubernetes Engine

GKE gibt den Fehler ImagePullBackoff zurück, wenn kein Image aus einer Registry abgerufen werden kann. Der Fehler kann auftreten, weil das Image nicht gefunden werden kann oder weil Ihre Knoten keine Berechtigungen zum Abrufen aus der Registry haben. Standardmäßig haben GKE-Knoten Berechtigungen zum Abrufen von Images aus Container Registry, wenn sich die Registry im selben Google Cloud-Projekt wie Ihre Knoten befindet.

Die GKE-Dokumentation enthält Schritte zum Ermitteln der Ursache und zum Beheben des Problems.

Durchsetzung von Organisationsrichtlinien

Einschränkungen für Organisationsrichtlinien können sich auf die Verwendung von Container Registry auswirken, wenn sie für Dienste gelten, die von Container Registry verwendet werden. Dazu gehören auch Einschränkungen, die die Verwendung von vom Kunden verwalteten Verschlüsselungsschlüsseln (CMEK) erfordern.

Ungültiger Anfragefehler beim Hochladen eines Images

Wenn sich die Cloud Storage API in der Richtlinienliste Deny für die Einschränkung constraints/gcp.restrictNonCmekServices befindet, können Sie keine Images an Container Registry übertragen, wenn die zugrunde liegenden Storage-Buckets nicht mit CMEK verschlüsselt sind. Die folgende Meldung wird zurückgegeben:

unknown: Bad Request

Wenn constraints/gcp.restrictCmekCryptoKeyProjects konfiguriert ist, müssen Storage-Buckets mit einem CryptoKey aus einem zulässigen Projekt, Ordner oder einer zulässigen Organisation verschlüsselt werden. Vorhandene Buckets, die nicht konform sind, müssen so konfiguriert werden, dass sie standardmäßig den erforderlichen Schlüssel verwenden.

Informationen zum Verschlüsseln von Storage-Buckets finden Sie in der Cloud Storage-Anleitung. Der Bucket-Name für einen Registry-Host hat eines der folgenden Formate:

• artifacts.PROJECT-ID.appspot.com für Images, die auf dem Host gcr.io gespeichert sind
• STORAGE-REGION.artifacts.PROJECT-ID.appspot.com für Images, die in asia.gcr.io, eu.gcr.io oder us.gcr.io gespeichert sind.

Das gcr-Pub/Sub-Thema wurde nicht automatisch erstellt

Wenn Sie die Container Registry API in einem Google Cloud-Projekt aktivieren, versucht Container Registry, mithilfe von von Google verwalteten Verschlüsselungsschlüsseln automatisch ein Pub/Sub-Thema mit der Themen-ID gcr zu erstellen.

Wenn sich die Pub/Sub API in der Richtlinienliste Deny für die Einschränkung constraints/gcp.restrictNonCmekServices befindet, müssen Themen mit CMEK verschlüsselt werden. Anfragen zum Erstellen eines Themas ohne CMEK-Verschlüsselung schlagen fehl.

Informationen zum Erstellen des Themas gcr mit CMEK-Verschlüsselung finden Sie in der Pub/Sub-Anleitung zum Verschlüsseln von Themen.

Kontingentlimits

Wenn Sie das Kontingentlimit von Container Registry erreichen, erhalten Sie möglicherweise eine solche Fehlermeldung:

Error: Status 429 trying to pull repository [...] "Quota Exceeded."

Um das Überschreiten des festen Kontingentlimits zu verhindern, haben Sie folgende Möglichkeiten:

• Erhöhen Sie die Anzahl der IP-Adressen, die mit Container Registry kommunizieren. Das Kontingent wird nach deren Anzahl berechnet.
• Fügen Sie Wiederholungen hinzu, um eine Verzögerung zu bewirken. Hierzu können Sie zum Beispiel den exponentiellen Backoff verwenden.

Ungültiger Registry-Endpunkt mit boot2docker

Wenn Sie die Container Registry aus einer boot2docker-Umgebung nicht erreichen können:

docker push gcr.io/example/sample

Error response from daemon: invalid registry endpoint https://gcr.io/v0/:
  unable to ping registry endpoint https://gcr.io/v0/
v2 ping attempt failed with error: Get https://gcr.io/v2/:
  x509: certificate has expired or is not yet valid
v1 ping attempt failed with error: Get https://gcr.io/v1/_ping:
  x509: certificate has expired or is not yet valid.
If this private registry supports only HTTP or HTTPS with an unknown CA
certificate, please add `--insecure-registry gcr.io` to the daemon's
arguments. In the case of HTTPS, if you have access to the registry's CA
certificate, no need for the flag; simply place the CA certificate at
/etc/docker/certs.d/gcr.io/ca.crt

Müssen Sie gegebenenfalls boot2docker neu starten:

boot2docker stop
boot2docker start

Fehler beim Hochladen eines Images auf Stammebene

Wenn Sie versuchen, ein Container-Image per Push zu übertragen, schlägt der Push fehl und Sie erhalten eine Meldung, die Folgendes enthält:

Pushing to root-level images is disabled

Diese Meldung gibt an, dass Sie das Image mit dem Hostnamen und dem Image getaggt haben, aber nicht die Projekt-ID.

Taggen Sie das Bild mit dem richtigen Bildpfadformat:

HOSTNAME/PROJECT-ID/IMAGE:TAG

Beispiel: gcr.io/web-project/web-app:1.0.

Docker auf Mac

Treten Probleme mit Docker in einer Mac-Umgebung auf, kann eine Behelfslösung erforderlich sein. Zu den möglichen Fehlern gehören nicht reagierende Schreib-/Abrufvorgänge unter Docker sowie der folgende, bzw. ein ähnlicher Netzwerkfehler:

Post https://us.gcr.io/v2/[repo name]/blobs/uploads/: dial tcp xx.xxx.xx.xx:xxx: i/o timeout

Versuchen Sie es mit folgenden Schritten, wenn einer dieser Fehler auftritt:

• Führen Sie den Befehl docker-machine restart default im Mac-Terminal aus, um den Docker-Daemon neu zu starten.

• Achten Sie darauf, dass "Docker-Logins sicher in MacOS-Keychain speichern" im Menü "Einstellungen" nicht aktiviert ist.

• Prüfen Sie, ob Sie die aktuelle Docker-Version verwenden.