Docker-Image der Google Cloud CLI installieren

Mit dem Google Cloud CLI-Docker-Image können Sie eine bestimmte Version der gcloud CLI als Docker-Image aus der Artifact Registry abrufen und Google Cloud CLI-Befehle schnell in einem isolierten, korrekt konfigurierten Container ausführen.

Das Docker-Image der Google Cloud CLI ist die gcloud CLI, die auf einem Debian- oder Alpine-Image installiert ist. Mit den Docker-Images der Google Cloud CLI können Sie gcloud und die zugehörigen Komponenten verwenden, ohne gcloud manuell auf Ihrem lokalen Computer installieren zu müssen.

Docker-Image-Optionen

Es gibt sechs Docker-Images für die Google Cloud CLI. Mit allen werden die Befehlszeilentools gcloud, gsutil und bq installiert. Wir empfehlen, das :stable-Image für eine minimale Umgebung zu installieren. Sie können das stabile Image auch als Basis-Image für Ihre eigenen Bereitstellungen verwenden. So haben Sie die Flexibilität, nur die Komponenten und Pakete in Ihrem Image zu installieren, die Sie benötigen:

• :stable, :VERSION-stable: Bietet eine gcloud-Installation mit gsutil- und bq-Komponenten. Das Image basiert auf dem neuesten von Google bereitgestellten Debian 12-Basis-Image. Dieses Bild wird sowohl auf linux/amd- als auch auf linux/arm-Plattformen unterstützt. Verwenden Sie das :VERSION-stable-Tag, um bestimmte gcloud-Versionen zu installieren.

Wenn Sie ein Alpine-basiertes Image verwenden möchten, können Sie das folgende Image installieren:

• :alpine, :VERSION-alpine: Ähnlich wie „stable“, aber auf dem neuesten Basis-Image Alpine 3.19 basiert. Dieses Bild wird sowohl auf linux/amd- als auch auf linux/arm-Plattformen unterstützt. Wenn Sie bestimmte gcloud-Versionen installieren möchten, verwenden Sie das :VERSION-alpine-Tag.

Wichtig :Das Alpine-Basis-Image wird in der kommenden Google Cloud CLI-Release-Version 503.0.0 auf Version 3.20 aktualisiert, um Sicherheitslücken mit hoher Schwere im Alpine-Basis-Image 3.19 zu beheben: CVE-2024-26130 und CVE-2023-50782. Wenn Sie die Änderung deaktivieren möchten, können Sie Ihren Workflow an die Google Cloud CLI-Version 502.0.0 oder eine ältere Version anpinnen.

Wenn Sie Images mit zusätzlichen Komponenten oder vorinstallierten Paketen benötigen, können Sie eine der folgenden Optionen installieren:

• :emulators, :VERSION-emulators: Ähnlich wie „stable“, aber mit allen Emulatorkomponenten. Das Image basiert auf dem neuesten von Google bereitgestellten Debian 12-Basis-Image und verwendet den Komponentenmanager, um die Komponenten zu installieren. Dieses Bild wird sowohl auf linux/amd- als auch auf linux/arm-Plattformen unterstützt. Verwenden Sie das Tag :VERSION-emulators, um bestimmte gcloud-Versionen zu installieren.

• :latest, :VERSION: Ähnlich wie „stable“, mit vorinstallierten zusätzlichen Komponenten (Liste der im Image installierten Komponenten unten). Das Image basiert auf dem neuesten von Google bereitgestellten Debian 12-Basis-Image und verwendet Deb-Pakete, um die Komponenten zu installieren. Verwenden Sie das Tag :VERSION, um bestimmte gcloud-Versionen zu installieren.

• :slim, :VERSION-slim: Ähnlich wie „stable“, enthält aber zusätzliche Drittanbieterpakete wie curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make und gnupg. Dieses Image basiert auf dem neuesten von Google bereitgestellten Debian 12-Basis-Image. Dieses Bild wird sowohl auf linux/amd- als auch auf linux/arm-Plattformen unterstützt. Verwenden Sie das :VERSION-slim-Tag, um bestimmte gcloud-Versionen zu installieren.

• :debian_component_based, :VERSION-debian_component_based: Ähnlich wie „stable“, mit vorinstallierten zusätzlichen Komponenten (Liste der im Image installierten Komponenten unten). Das Image basiert auf dem neuesten von Google bereitgestellten Debian 12-Basis-Image und verwendet den Komponentenmanager, um die Komponenten zu installieren. Dieses Bild wird sowohl auf linux/amd- als auch auf linux/arm-Plattformen unterstützt. Verwenden Sie das Tag :VERSION-debian_component_based, um bestimmte gcloud-Versionen zu installieren.

Bestimmte Version in der Produktion verwenden

Wenn Sie ein Tag verwenden, das nicht an eine bestimmte gcloud-Version gebunden ist, kann es in Ihrer Umgebung zu den folgenden möglicherweise bahnbrechenden Änderungen kommen:

• Aktualisierungen der Google Cloud SDK-Version, die das Verhalten des Tools ändern können.
• Aktualisierungen der Liste der installierten Komponenten.

Um mögliche Unterbrechungen zu vermeiden, wird empfohlen, in Ihrer Produktionsumgebung eine der folgenden Versionen zu verwenden:

• Ein Versions-Tag wie :496.0.0-stable
• Ein bestimmter Bild-Hash, z. B.: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
• Image in Ihrem eigenen Repository hosten

Außerdem sollten Sie die Images regelmäßig aktualisieren, um die neueste gcloud-Version zu erhalten.

Informationen zur aktuellen Version der Google Cloud CLI und zu allen vorherigen Versionen der Google Cloud CLI

In den einzelnen Tags installierte Komponenten

Komponente	:stable	:alpine	:emulators	:latest	:slim	:debian_component_based
App Engine Go-Erweiterungen				x		x
Appctl						x
BigQuery-Befehlszeilentool	x	x	x	x	x	x
Im Lieferumfang enthaltenes Python 3.9	x	x	x	x	x	x
Bigtable-Befehlszeilentool				x		x
Bigtable Emulator			x	x		x
Cloud Datastore-Emulator			x	x		x
Cloud Firestore-Emulator			x	x
Cloud Pub/Sub-Emulator			x	x		x
Spanner Emulator			x	x
Cloud Storage-Befehlszeilentool	x	x	x	x	x	x
Google Cloud CLI-Kernbibliotheken	x	x	x	x	x	x
Google Cloud CRC32C-Hash-Tool	x	x	x	x	x	x
Kustomize						x
Minikube						x
Nomos-Befehlszeile						x
On-Demand Scanning API-Extraktionshilfe				x		x
Skaffold						x
anthos-auth						x
gcloud-Alphabefehle	x			x	x	x
gcloud-Betabefehle			x	x	x	x
gcloud app Java-Erweiterungen						x
Python-Erweiterungen für gcloud app						x
gcloud app Python-Erweiterungen (zusätzliche Bibliotheken)				x		x
gke-gcloud-auth-plugin				x		x
KPT				x		x
kubectl				x		x

Docker-Image installieren

Das Docker-Image wird in Artifact Registry mit dem folgenden Repository-Namen gehostet: gcr.io/google.com/cloudsdktool/google-cloud-cli. Die Bilder sind auch über die Repositories us.gcr.io, eu.gcr.io und asia.gcr.io verfügbar.

1. Wenn Sie das Image der stabilen Google Cloud CLI-Version gcr.io/google.com/cloudsdktool/google-cloud-cli:stable verwenden möchten, rufen Sie es mit dem folgenden Befehl aus der Artifact Registry ab:

   docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable
   

   Sie können auch den Image-Hash verwenden, um ein bestimmtes Docker-Image aus dem Repository abzurufen. Wenn Sie dasselbe Bild aus dem vorherigen Beispiel (:489.0.0-stable) mit dem Bild-Hash abrufen möchten, führen Sie den folgenden Befehl aus:

   docker pull gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:589a0db8919614ef919dfd6ed89127211b4b6bf5ee6a2e2ce92abf33cbfe49d8
   

2. Überprüfen Sie die Installation mit folgendem Befehl:

   docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable gcloud version
   

   Wenn Sie das frei bewegliche :stable-Tag verwendet haben, das immer auf die neueste Version verweist, prüfen Sie die Installation mit dem folgenden Befehl:

   docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version
   

Authentifizierung mit dem Docker-Image der Google Cloud CLI

Authentifizieren Sie sich mit dem Docker-Image der Google Cloud CLI. Führen Sie dazu einen der folgenden Befehle aus:

• Authentifizieren Sie gcloud mit Ihren Nutzeranmeldedaten. Führen Sie dazu gcloud auth login aus:

  docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth login
  

• Wenn Sie Anwendungen authentifizieren müssen, die die Google Cloud -APIs verwenden, übergeben Sie die Option --update-adc:

  docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud auth login --update-adc
  

• Führen Sie den folgenden Befehl aus, um ein Standardprojekt festzulegen, das jedes Mal ausgewählt wird, wenn Sie den Container öffnen:

  docker run -ti --name gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable /bin/bash -c 'gcloud auth login && gcloud config set project your-project'
  

  Nach der erfolgreichen Authentifizierung werden die Anmeldedaten im Volume von gcloud-config container aufbewahrt.

  Hinweis: gcloud-config container enthält jetzt ein Volume mit IhrenGoogle Cloud -Anmeldedaten. Verwenden Sie das Volume gcloud-config nicht in anderen Containern.

  Führen Sie den Container mit --volumes-from aus, um die Compute-Instanz mit den Anmeldedaten aufzulisten:

  docker run --rm --volumes-from gcloud-config gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud compute instances list --project your-project
  

• Wenn Sie sich mit einem Dienstkonto authentifizieren möchten, legen Sie mit der Property auth/credential_file_override einen Pfad zu einem bereitgestellten Dienstkonto fest. Aktualisieren Sie dann die Konfiguration, damit das bereitgestellte Dienstkonto mithilfe der Umgebungsvariablen CLOUDSDK_CONFIG gelesen wird.

  Im folgenden Beispiel ist die auth/credential_file_override bereits in der mycloud-Konfiguration festgelegt. Die Konfiguration verweist auf eine Zertifikatdatei, die sich im Container als separate Volume-Bindung befindet.

  $ docker run -ti -e CLOUDSDK_CONFIG=/config/mygcloud \
                -v `pwd`/mygcloud:/config/mygcloud \
                -v `pwd`:/certs  gcr.io/google.com/cloudsdktool/google-cloud-cli:stable /bin/bash
  
  bash-4.4# gcloud config list
  [auth]
  credential_file_override = /certs/svc_account.json
  
  bash-4.4# head -10  /certs/svc_account.json
  {
     "type": "service_account",
     "project_id": "project_id1",
  ....
  
  bash-4.4# gcloud projects list
  PROJECT_ID           NAME         PROJECT_NUMBER
  project_id1          GCPAppID     1071284184432
  

  Weitere Informationen zum Festlegen von Umgebungsvariablen finden Sie unter den folgenden Links:

  • Attribute mithilfe von Umgebungsvariablen festlegen
  • gcloud config

Zusätzliche Komponenten installieren

Sie können zusätzliche Komponenten im Docker-Image der Google Cloud CLI installieren. Die Installation zusätzlicher Komponenten hängt vom zugrunde liegenden Basis-Image-Typ ab.

Debian-basierte Images

Standardmäßig sind in den stabilen Images (:stable und :VERSION-stable) nur bq und gsutil installiert. Führen Sie einen der folgenden Schritte aus, um zusätzliche Komponenten für das stabile Image zu installieren:

• Eigenes Image mit dem Dockerfile des :stable-Images erstellen: Pakete installieren, die nicht direkt über apt-get (d.h. die Docker-Engine) verfügbar sind.
• Zusätzliche Pakete oder Komponenten zur Laufzeit installieren: Sie können das Image anpassen, ohne es zu hosten.

Eigenes Image mit dem Dockerfile für das :stable-Image erstellen

Wenn Sie ein eigenes Image mit zusätzlichen Komponenten aus :stable erstellen möchten, können Sie das GitHub-Verzeichnis cloud-sdk-docker klonen und mit dem Befehl docker build das :stable-Docker-Image aus dem Dockerfile mit dem Argument INSTALL_COMPONENTS erstellen. So fügen Sie beispielsweise datastore-emulator-Komponenten hinzu:

# clone the GitHub docker directory 
$ git clone https://github.com/GoogleCloudPlatform/cloud-sdk-docker.git
$ docker build --build-arg CLOUD_SDK_VERSION=<release_version> \
   --build-arg INSTALL_COMPONENTS="google-cloud-cli-datastore-emulator=<release_version>-0" \
   -t my-cloud-sdk-docker:stable .

Zusätzliche Pakete oder Komponenten zur Laufzeit installieren

Wenn Sie das stable-Docker-Image abgerufen haben, können Sie während der Laufzeit die folgenden zusätzlichen Komponenten installieren:

• gcloud-Komponenten mithilfe der Umgebungsvariablen COMPONENTS.
• apt-Pakete mithilfe der Umgebungsvariablen APT_PACKAGES.

Wenn Sie beispielsweise die Komponenten cbt und kpt zur Laufzeit installieren möchten, können Sie den folgenden Befehl ausführen:

docker run -e COMPONENTS='google-cloud-cli-cbt google-cloud-cli-kpt' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

Wenn Sie die Apt-Pakete curl und gcc installieren möchten, während das Docker-Image ausgeführt wird, führen Sie den folgenden Befehl aus:

docker run -e APT_PACKAGES='curl gcc' \
gcr.io/google.com/cloudsdktool/google-cloud-cli:stable gcloud version

Alpine-basierte Images

Um zusätzliche Komponenten für Alpine-basierte Images zu installieren, erstellen Sie ein Dockerfile, das das cloud-sdk-Image als Basis-Image verwendet.

So fügen Sie beispielsweise kubectl- und app-engine-java-Komponenten hinzu:

1. Erstellen Sie das Dockerfile so:

FROM gcr.io/google.com/cloudsdktool/google-cloud-cli:alpine
RUN apk --update add gcompat openjdk8-jre
RUN gcloud components install app-engine-java kubectl

1. Erstellen Sie das Image mit dem folgenden Befehl:

docker build -t my-cloud-sdk-docker:alpine .

Bei Alpine-basierten Images müssen Sie die Abhängigkeiten zusätzlicher Komponenten manuell installieren.

Migration zum :stable-Image

Wenn Sie die Docker-Images :latest, :slim, :emulators, :alpine und :debian_component_based verwenden, empfehlen wir Ihnen, zum Debian-basierten :stable-Image zu migrieren. Dieses hat eine kleinere Größe und bietet verbesserte Sicherheitsfixes. Eine Anleitung zur Migration zum :stable-Image finden Sie unter Zum :stable-Image migrieren.

Support für Bilder

Die in der Artifact Registry gehosteten Images bieten eine vollständige Installation der Google Cloud CLI. Wenn Sie Fehler oder Probleme im Zusammenhang mit den Docker-Images finden, können Sie ein Supportticket erstellen.

Wenn Sie ein Image mit zusätzlichen Komponenten, Paketen oder Tools benötigen, können Sie eine eigene Image-Ebene über dem Docker-Image der Google Cloud CLI erstellen.

Fehlerbehebung

Was sollten Sie tun, wenn beim Abrufen des Docker-Images ein failed to fetch <image-tag>-Fehler angezeigt wird?

Wenn Sie beim Pullen eines Docker-Images der Google Cloud CLI den Fehler failed to fetch <image-tag> erhalten, versuchen Sie höchstwahrscheinlich, ein Image-Tag abzurufen, das eingestellt und entfernt wurde. Sehen Sie unter Docker-Image-Optionen nach, welche Docker-Image-Optionen verfügbar sind, und migrieren Sie zu einem der unterstützten Tags.

In welchen Anwendungsfällen können Sie das :stable-Docker-Image nicht direkt erweitern, um Ihren aktuellen Workflow zu unterstützen?

In der folgenden Tabelle sind die Anwendungsfälle aufgeführt, in denen Sie das :stable-Docker-Image nicht direkt an Ihren Workflow anpassen können. Außerdem werden die Optionen zur Behebung des Problems aufgeführt:

Anwendungsfälle	Optionen zur Behebung
Drittanbieterpakete wie docker oder docker-buildx sind nicht im :stable-Image enthalten.	Wenn Sie diese Drittanbieterpakete benötigen, erstellen Sie ein eigenes Image oder installieren Sie diese Pakete manuell im :stable-Docker-Image.

Was sollten Sie tun, wenn Ihr Scanner Sicherheitslücken in den Docker-Images gefunden hat?

Docker-Images der Google Cloud CLI werden in Artifact Registry gehostet. Images werden täglich gescannt und gängige Sicherheitslücken (Common Vulnerabilities and Exposures, CVEs) werden vor jeder neuen gcloud-Version behoben. Wenn Ihr Scanner jedoch Sicherheitslücken in den Docker-Images der Google Cloud CLI gefunden hat, die nicht behoben wurden, können Sie einen Fehler melden. Geben Sie dabei die folgenden Informationen an:

• Die Art der Sicherheitslücke.
• Die genaue Position im Bild.

Sicherheitslücken in Basisbetriebssystem-Images werden nur behoben, um sicherzustellen, dass in den Docker-Images der Google Cloud CLI aktuelle, stabile Releases von Debian oder Alpine Linux verwendet werden.

Warum gibt es im Artifact Registry-Repository Bilder ohne Tags?

Google Cloud CLI-Docker-Images mit den Tags :stable, :alpine, :emulators und :debian_component_based unterstützen sowohl arm64- als auch amd64-Plattformen. Die Images werden mit einem Build-Prozess für mehrere Architekturen erstellt, bei dem architekturspezifische Images in einem einzigen manifest kombiniert werden. Das Manifest enthält außerdem plattformspezifische Attestierungsbilder. Beim Buildprozess für mehrere Architekturen wird nur dem endgültigen Manifest-Image ein Tag hinzugefügt, nicht aber den einzelnen Architektur-spezifischen Images oder Attestations-Images. Daher sehen Sie möglicherweise im Artifact Registry-Repository Images ohne Tags. Diese Bilder sind nicht zur Verwendung vorgesehen und können ignoriert werden.