Installer l'image Docker de la Google Cloud CLI

L'image Docker de la Google Cloud CLI vous permet d'extraire une version spécifique de gcloud CLI en tant qu'image Docker depuis Artifact Registry et d'exécuter rapidement des commandes Google Cloud CLI dans un conteneur isolé et correctement configuré.

L'image Docker de la Google Cloud CLI est la gcloud CLI installée sur une image Debian ou Alpine. Les images Docker de la Google Cloud CLI permettent d'utiliser gcloud ainsi que ses composants groupés sans avoir à installer manuellement gcloud sur votre machine locale.

Options d'images Docker

Il existe six images Docker Google Cloud CLI, et toutes installent les outils de ligne de commande gcloud, gsutil et bq. Nous vous recommandons d'installer l'image :stable pour un environnement minimal. Vous pouvez également utiliser l'image stable comme image de base pour vos propres déploiements, ce qui vous permet d'installer uniquement les composants et les packages dont vous avez besoin dans votre image:

  • :stable, :VERSION-stable: fournit une installation gcloud avec les composants gsutil et bq. L'image est basée sur la dernière image de base Debian 12 fournie par Google. Cette image est compatible avec les plates-formes linux/amd et linux/arm. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION-stable.

Si vous souhaitez utiliser une image basée sur Alpine, vous pouvez installer l'image suivante:

  • :alpine, :VERSION-alpine: semblable à la version stable, mais basé sur la dernière image de base Alpine 3.19. Cette image est compatible avec les plates-formes linux/amd et linux/arm. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION-alpine.

Si vous souhaitez des images avec des composants ou des packages supplémentaires préinstallés, vous pouvez installer l'une des options suivantes:

  • :emulators, :VERSION-emulators: semblable à la version stable, avec l'ajout de tous les composants de l'émulateur. L'image est basée sur la dernière image de base Debian 12 fournie par Google et utilise le gestionnaire de composants pour installer les composants. Cette image est compatible avec les plates-formes linux/amd et linux/arm. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION-emulators.

  • :latest, :VERSION: semblable à la version stable, avec des composants supplémentaires (la liste des composants installés dans l'image est indiquée ci-dessous) préinstallés. L'image est basée sur la dernière image de base Debian 12 fournie par Google et utilise des paquets deb pour installer les composants. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION.

  • :slim, :VERSION-slim: semblable à la version stable, mais inclut les packages tiers supplémentaires tels que curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make et gnupg. Cette image est basée sur la dernière image de base Debian 12 fournie par Google. Cette image est compatible avec les plates-formes linux/amd et linux/arm. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION-slim.

  • :debian_component_based, :VERSION-debian_component_based: semblable à la version stable, avec des composants supplémentaires (la liste des composants installés dans l'image est indiquée ci-dessous) préinstallés. L'image est basée sur la dernière image de base Debian 12 fournie par Google et utilise le gestionnaire de composants pour installer les composants. Cette image est compatible avec les plates-formes linux/amd et linux/arm. Pour installer des versions gcloud spécifiques, utilisez la balise :VERSION-debian_component_based.

Utiliser une version spécifique en production

Si vous utilisez une balise qui n'est pas associée à une version gcloud spécifique, votre environnement peut subir les modifications cassantes suivantes:

  • Mises à jour de la version de Google Cloud SDK, qui peuvent modifier le comportement de l'outil.
  • Mises à jour de la liste des composants installés.

Pour éviter d'éventuelles modifications non compatibles, nous vous recommandons d'utiliser l'une des options suivantes dans votre environnement de production:

  • Un tag avec version, tel que :496.0.0-stable
  • Un hachage d'image spécifique, par exemple: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
  • Héberger l'image dans votre propre dépôt

Vous devez également mettre à jour les images régulièrement pour obtenir la dernière version de gcloud.

Consultez la dernière version de Google Cloud CLI et toutes les versions précédentes de Google Cloud CLI.

Composants installés dans chaque balise

Composant :stable :alpine :emulators :latest :slim :debian_component_based
Extensions Go App Engine x x
Appctl x
Outil de ligne de commande BigQuery x x x x x x
Python 3.9 groupé x x x x x x
Outil de ligne de commande Bigtable x x
Émulateur Bigtable x x x
Émulateur Cloud Datastore x x x
Émulateur Cloud Firestore x x
Émulateur Cloud Pub/Sub x x x
Émulateur Spanner x x
Outil de ligne de commande Cloud Storage x x x x x x
Bibliothèques principales de la Google Cloud CLI x x x x x x
Outil de hachage CRC32C Google Cloud x x x x x x
Kustomize x
Minikube x
CLI Nomos x
Assistant d'extraction de l'API On-Demand Scanning x x
Skaffold x
anthos-auth x
Commandes gcloud alpha x x x x
Commandes gcloud bêta x x x x
Extensions Java d'application gcloud x
Extensions Python d'application gcloud x
Extensions Python d'application gcloud (bibliothèques supplémentaires) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

Installer une image Docker

L'image Docker est hébergée sur Artifact Registry, avec le nom de dépôt suivant : gcr.io/google.com/cloudsdktool/google-cloud-cli. Les images sont également disponibles à l'aide des dépôts us.gcr.io, eu.gcr.io et asia.gcr.io.

  1. Pour utiliser l'image de la version stable de la Google Cloud CLI, gcr.io/google.com/cloudsdktool/google-cloud-cli:stable, extrayez-la de Artifact Registry en exécutant la commande suivante:

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

    Vous pouvez également utiliser le hachage de l'image pour extraire une image Docker spécifique du dépôt. Pour extraire la même image de l'exemple précédent (:489.0.0-stable) à l'aide du hachage d'image, exécutez la commande suivante:

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

  2. Vérifiez l'installation en exécutant la commande suivante :

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

    Si vous avez utilisé la balise :stable flottante (qui pointe toujours vers la dernière version), vérifiez l'installation en exécutant la commande suivante:

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

S'authentifier avec l'image Docker de la Google Cloud CLI

Authentifiez-vous avec l'image Docker Google Cloud CLI en exécutant l'une des commandes suivantes:

  • Authentifiez gcloud avec vos identifiants utilisateur en exécutant gcloud auth login:

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

  • Si vous devez authentifier les applications qui utilisent les API Google Cloud, transmettez l'option --update-adc:

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

  • Pour définir un projet par défaut qui est sélectionné chaque fois que vous ouvrez le conteneur, exécutez la commande suivante:

    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'

    Une fois l'authentification effectuée, les identifiants sont conservés dans le volume de gcloud-config container.

    Pour vérifier, listez l'instance Compute à l'aide des identifiants en exécutant le conteneur avec --volumes-from:

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

  • Si vous souhaitez vous authentifier à l'aide d'un compte de service, utilisez la propriété auth/credential_file_override pour définir un chemin d'accès à un compte de service installé. Mettez ensuite à jour la configuration pour lire le compte de service monté à l'aide de la variable d'environnement CLOUDSDK_CONFIG.

    Dans l'exemple suivant, la configuration mycloud a déjà défini auth/credential_file_override. La configuration pointe vers un fichier de certificat présent dans le conteneur en tant qu'installation de volume distincte.

    $ 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

    Pour en savoir plus sur la définition de variables d'environnement, consultez les ressources suivantes:

Installer des composants supplémentaires

Vous pouvez installer des composants supplémentaires dans l'image Docker de la Google Cloud CLI. L'approche d'installation de composants supplémentaires varie en fonction du type d'image de base sous-jacent.

Images basées sur Debian

Par défaut, les images stables (:stable et :VERSION-stable) ne contiennent aucun composant installé autre que bq et gsutil. Pour installer des composants supplémentaires pour l'image stable, effectuez l'une des opérations suivantes:

Créer votre propre image à l'aide du fichier Dockerfile de l'image :stable

Pour créer votre propre image avec un composant supplémentaire à partir de :stable, vous pouvez cloner le répertoire GitHub cloud-sdk-docker et utiliser la commande docker build pour créer l'image Docker :stable à partir du fichier Dockerfile avec l'argument INSTALL_COMPONENTS. Par exemple, pour ajouter des composants datastore-emulator:

# 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 .

Installer des packages ou des composants supplémentaires au moment de l'exécution

Si vous avez extrait l'image Docker stable, vous pouvez installer les composants supplémentaires suivants au moment de l'exécution:

  • composants gcloud à l'aide de la variable d'environnement COMPONENTS.
  • apt-packages à l'aide de la variable d'environnement APT_PACKAGES.

Par exemple, si vous souhaitez installer les composants cbt et kpt au moment de l'exécution, vous pouvez exécuter la commande suivante:

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

Pour installer les paquets apt curl et gcc lors de l'exécution de l'image Docker, exécutez la commande suivante:

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

Images basées sur Alpine

Pour installer des composants supplémentaires sur les images basées sur Alpine, créez un Dockerfile qui utilise l'image cloud-sdk en tant qu'image de base.

Par exemple, pour ajouter des composants kubectl et app-engine-java:

  1. Créez le fichier Dockerfile comme suit:
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. Créez l'image en exécutant la commande suivante:
docker build -t my-cloud-sdk-docker:alpine .

Pour les images basées sur Alpine, vous devez installer manuellement les dépendances des composants supplémentaires.

Migrer vers l'image :stable

Si vous utilisez les images Docker :latest, :slim, :emulators, :alpine et :debian_component_based, nous vous recommandons de migrer vers l'image :stable basée sur Debian pour réduire la taille de l'image et améliorer les correctifs de sécurité. Pour découvrir comment migrer vers l'image :stable, consultez la section Migrer vers l'image :stable.

Obtenir de l'aide pour les images

Les images hébergées sur Artifact Registry fournissent des installations entièrement fonctionnelles de la Google Cloud CLI. Si vous trouvez des bugs ou des problèmes liés aux images Docker, vous pouvez créer une demande d'assistance.

Lorsque vous avez besoin d'une image avec des composants, des paquets ou des outils supplémentaires, vous pouvez créer votre propre couche d'image au-dessus de l'image Docker de la CLI Google Cloud.

Dépannage

Que devez-vous faire si une erreur failed to fetch <image-tag> s'affiche lorsque vous extrayez l'image Docker ?

Si une erreur failed to fetch <image-tag> s'affiche lorsque vous essayez d'extraire une image Docker de la Google Cloud CLI, vous essayez probablement d'extraire une balise d'image qui a été abandonnée et supprimée. Consultez les options d'image Docker pour connaître les options d'image Docker disponibles et migrez vers l'une des balises compatibles.

Dans quels cas ne pouvez-vous pas étendre directement l'image Docker :stable pour prendre en charge votre workflow actuel ?

Le tableau suivant présente les cas d'utilisation où vous ne pouvez pas étendre directement l'image Docker :stable pour l'adapter à votre workflow, ainsi que les options à prendre en compte pour y remédier:

Cas d'utilisation Options de correction
Les composants app-engine (utilisés dans l'image Docker :latest ou :debian_component_based) ne sont pas compatibles avec Debian 12. Créez votre propre image à partir d'une image Debian (Debian 11) compatible pour installer les composants app-engine.
Les packages tiers tels que docker ou docker-buildx ne sont pas inclus dans l'image :stable. Si vous avez besoin de ces packages tiers, créez votre propre image ou installez-les manuellement dans l'image Docker :stable.

Que devez-vous faire si votre analyseur a détecté des failles dans les images Docker ?

Les images Docker de la CLI Google Cloud sont hébergées dans Artifact Registry. Les images sont analysées quotidiennement, et les failles et expositions courantes (CVE) sont atténuées avant chaque nouvelle version de gcloud. Toutefois, si votre analyseur a détecté des failles non résolues dans les images Docker de la Google Cloud CLI, vous pouvez signaler un bug en incluant les informations suivantes:

  • Type de faille.
  • Emplacement exact dans l'image.

Les failles des images de base de l'OS ne sont traitées que pour s'assurer que les images Docker de la Google Cloud CLI utilisent des versions récentes et stables de Debian ou d'Alpine Linux.