Installazione dell'immagine Docker di Google Cloud CLI

L'immagine Docker di Google Cloud CLI ti consente di eseguire il pull di una versione specifica di gcloud CLI come immagine Docker da Artifact Registry ed eseguire rapidamente i comandi Google Cloud CLI in un container isolato e configurato correttamente.

L'immagine Docker di Google Cloud CLI è gcloud CLI installato sopra un'immagine Debian o Alpine. Le immagini Docker di Google Cloud CLI consentono l'utilizzo di gcloud e dei relativi componenti in bundle senza dover installare manualmente gcloud nella tua macchina locale.

Novità / Aggiornamenti importanti

4 giugno 2025

Pacchetti docker e make da rimuovere dalle immagini Docker di gcloud

14 luglio 2025

Il supporto per gli emulatori gcloud Firestore e Datastore con Java 17 o versioni precedenti è terminato il 1° luglio 2025

Aggiorna la cronologia

Data Pacchetto Rimossa nella versione
di gcloud		 Pin-to gcloud version (per continuare a utilizzare il pacchetto) Pacchetto rimosso dalle immagini
1° luglio 2025 docker 529.0.0 528.0.0 :alpine e :debian_component_based
22 luglio 2025 docker 531.0.0 530.0.0 :slim e :latest
5 agosto 2025 make 533.0.0 532.0.0 :latest e :debian_component_based

Opzioni dell'immagine Docker

Esistono sei immagini Docker di Google Cloud CLI e tutte installeranno gli strumenti a riga di comando gcloud, gsutil e bq. Ti consigliamo di installare l'immagine :stable per un ambiente minimale. Puoi anche utilizzare l'immagine stabile come immagine di base per le tue implementazioni, il che ti offre la flessibilità di installare solo i componenti e i pacchetti di cui hai bisogno nella tua immagine:

  • :stable, :VERSION-stable: fornisce un'installazione di gcloud con i componenti gsutil e bq. L'immagine è basata sull'ultima immagine di base Debian 12 fornita da Google. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION-stable.

Se vuoi utilizzare un'immagine basata su Alpine, puoi installare la seguente immagine:

  • :alpine, :VERSION-alpine: simile a Stable, ma basata sull'ultima immagine di base Alpine 3.20. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION-alpine.

Se vuoi immagini con componenti o pacchetti aggiuntivi preinstallati, puoi installare una delle seguenti opzioni:

  • :emulators, :VERSION-emulators: simile alla versione stabile, con l'aggiunta di tutti i componenti dell'emulatore. L'immagine è basata sull'ultima immagine di base Debian 12 fornita da Google e utilizza Component Manager per installare i componenti. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION-emulators.

  • :latest, :VERSION: simile alla versione stabile, con componenti aggiuntivi (l'elenco dei componenti installati nell'immagine è riportato di seguito) preinstallati. L'immagine è basata sull'ultima immagine di base fornita da Google Debian 12 e utilizza pacchetti deb per installare i componenti. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION.

  • :slim, :VERSION-slim: simile alla versione stabile, ma include i pacchetti di terze parti aggiuntivi come curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make e gnupg. Questa immagine è basata sull'ultima immagine di base Debian 12 fornita da Google. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION-slim.

  • :debian_component_based, :VERSION-debian_component_based: simile a stable, con componenti aggiuntivi (l'elenco dei componenti installati nell'immagine è riportato di seguito) preinstallati. L'immagine è basata sull'ultima immagine di base Debian 12 fornita da Google e utilizza Component Manager per installare i componenti. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni specifiche di gcloud, utilizza il tag :VERSION-debian_component_based.

Utilizzare una versione specifica in produzione

Se utilizzi un tag non associato a una versione specifica di gcloud, il tuo ambiente potrebbe subire le seguenti possibili modifiche che causano interruzioni:

  • Aggiornamenti della versione di Google Cloud SDK, che potrebbero modificare il comportamento dello strumento.
  • Aggiornamenti all'elenco dei componenti installati.

Per evitare possibili modifiche che causano interruzioni, ti consigliamo di utilizzare uno dei seguenti elementi nel tuo ambiente di produzione:

  • Un tag con versione, ad esempio :496.0.0-stable
  • Un hash immagine specifico, ad esempio: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
  • Ospita l'immagine nel tuo repository

Devi anche aggiornare periodicamente le immagini per ottenere l'ultima versione di gcloud.

Controlla l'ultima versione di Google Cloud CLI e tutte le versioni precedenti di Google Cloud CLI.

Componenti installati in ogni tag

Componente :stable :alpine :emulators :latest :slim :debian_component_based
Estensioni Go di App Engine x x
Appctl x
Strumento a riga di comando BigQuery x x x x x x
Python in bundle x x x x x x
Strumento a riga di comando Bigtable x x
Emulatore Bigtable x x x
Emulatore di Cloud Datastore x x x
Emulatore di Cloud Firestore x x
Emulatore Cloud Pub/Sub x x x
Emulatore di Spanner x x
Strumento a riga di comando Cloud Storage x x x x x x
Librerie di base di Google Cloud CLI x x x x x x
Google Cloud Strumento hash CRC32C x x x x x x
Kustomize x
Minikube x
Interfaccia a riga di comando Nomos x
Helper per l'estrazione dell'API On-Demand Scanning x x
Skaffold x
anthos-auth x
Comandi gcloud alpha x x x x
Comandi gcloud beta x x x x
gcloud app Java Extensions x
gcloud app Python Extensions x
Estensioni Python di gcloud app (librerie aggiuntive) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

Installazione di un'immagine Docker

L'immagine Docker è ospitata su Artifact Registry con il seguente nome repository: gcr.io/google.com/cloudsdktool/google-cloud-cli. Le immagini sono disponibili anche utilizzando i repository us.gcr.io, eu.gcr.io e asia.gcr.io.

  1. Per utilizzare l'immagine della release stabile di Google Cloud CLI, gcr.io/google.com/cloudsdktool/google-cloud-cli:stable, recuperala da Artifact Registry eseguendo il seguente comando:

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

    Puoi anche utilizzare l'hash dell'immagine per estrarre un'immagine Docker specifica dal repository. Per estrarre la stessa immagine dell'esempio precedente (:489.0.0-stable) utilizzando l'hash dell'immagine, esegui il seguente comando:

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

  2. Verifica l'installazione eseguendo il comando:

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

    Se hai utilizzato il tag mobile :stable (che punta sempre all'ultima release), verifica l'installazione eseguendo questo comando:

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

Autenticazione con l'immagine Docker di Google Cloud CLI

Esegui l'autenticazione con l'immagine Docker di Google Cloud CLI eseguendo uno dei seguenti comandi:

  • Autentica gcloud con le tue credenziali utente eseguendo gcloud auth login:

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

  • Se devi autenticare le applicazioni che utilizzano le API Google Cloud , passa l'opzione --update-adc:

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

  • Per impostare un progetto predefinito selezionato ogni volta che apri il contenitore, esegui questo comando:

    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'

    Una volta autenticato correttamente, le credenziali vengono conservate nel volume di gcloud-config container.

    Per la verifica, elenca l'istanza di calcolo utilizzando le credenziali eseguendo il container con --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

  • Se vuoi eseguire l'autenticazione utilizzando un account di servizio, utilizza la proprietà auth/credential_file_override per impostare un percorso a unaccount di serviziont montato. Quindi, aggiorna la configurazione per leggere l'account di servizio montato utilizzando la variabile di ambiente CLOUDSDK_CONFIG.

    Nell'esempio seguente, la configurazione mycloud ha già impostato auth/credential_file_override. La configurazione punta a un file di certificato presente nel container come montaggio del volume separato.

    $ 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

    Per ulteriori informazioni sull'impostazione delle variabili di ambiente, consulta quanto segue:

Installazione di componenti aggiuntivi

Puoi installare componenti aggiuntivi nell'immagine Docker di Google Cloud CLI. L'approccio all'installazione di componenti aggiuntivi varia a seconda del tipo di immagine di base sottostante.

Immagini basate su Debian

Per impostazione predefinita, le immagini stabili (:stable e :VERSION-stable) non hanno componenti installati diversi da bq e gsutil. Per installare componenti aggiuntivi per l'immagine stabile, esegui una delle seguenti operazioni:

Creare la tua immagine utilizzando il Dockerfile dell'immagine :stable

Per creare la tua immagine con un componente aggiuntivo da :stable, puoi clonare la directory GitHub cloud-sdk-docker e utilizzare il comando docker build per creare l'immagine Docker :stable dal Dockerfile con l'argomento INSTALL_COMPONENTS. Ad esempio, per aggiungere componenti 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 .

Installazione di pacchetti o componenti aggiuntivi al runtime

Se hai eseguito il pull dell'immagine Docker stable, puoi installare i seguenti componenti aggiuntivi durante il runtime:

  • gcloud components utilizzando la variabile di ambiente COMPONENTS.
  • apt-packages utilizzando la variabile di ambiente APT_PACKAGES.

Ad esempio, se vuoi installare i componenti cbt e kpt in fase di runtime, puoi eseguire il seguente comando:

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

Per installare i pacchetti apt curl e gcc durante l'esecuzione dell'immagine Docker, esegui questo comando:

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

Immagini basate su Alpine

Per installare componenti aggiuntivi per le immagini basate su Alpine, crea un Dockerfile che utilizzi l'immagine cloud-sdk come immagine di base.

Ad esempio, per aggiungere i componenti kubectl e app-engine-java:

  1. Crea il Dockerfile come segue:
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. Crea l'immagine eseguendo questo comando:
docker build -t my-cloud-sdk-docker:alpine .

Per le immagini basate su Alpine, devi installare manualmente le dipendenze di componenti aggiuntivi.

Migrazione all'immagine :stable

Se utilizzi le immagini Docker :latest, :slim, :emulators, :alpine e :debian_component_based, ti consigliamo di eseguire la migrazione all'immagine :stable basata su Debian per una dimensione dell'immagine più piccola e correzioni di sicurezza migliorate. Per i passaggi per eseguire la migrazione all'immagine :stable, vedi Eseguire la migrazione all'immagine :stable.

Ricevere assistenza per le immagini

Le immagini ospitate su Artifact Registry forniscono installazioni completamente funzionali di Google Cloud CLI. Se riscontri bug o problemi relativi alle immagini Docker, puoi creare un ticket di assistenza.

Quando hai bisogno di un'immagine con componenti, pacchetti o strumenti aggiuntivi, puoi creare il tuo livello di immagine sopra l'immagine Docker di Google Cloud CLI.

Risoluzione dei problemi

Cosa devi fare se viene visualizzato un errore failed to fetch <image-tag> durante il pull dell'immagine Docker?

Se ricevi un errore failed to fetch <image-tag> mentre tenti di eseguire il pull di un'immagine Docker di Google Cloud CLI, molto probabilmente stai tentando di recuperare un tag immagine che è stato ritirato e rimosso. Controlla le Opzioni immagine Docker per le opzioni immagine Docker disponibili ed esegui la migrazione a uno dei tag supportati.

Quali sono i casi d'uso in cui non puoi estendere direttamente l'immagine Docker :stable per supportare il tuo flusso di lavoro attuale?

La tabella seguente elenca i casi d'uso in cui non puoi estendere direttamente l'immagine Docker :stable per adattarla al tuo flusso di lavoro ed elenca le opzioni di correzione:

Casi d'uso Opzioni di correzione
I pacchetti di terze parti come docker o docker-buildx non sono inclusi nell'immagine :stable Se hai bisogno di questi pacchetti di terze parti, crea la tua immagine o installa questi pacchetti manualmente nell'immagine Docker :stable.

Cosa devi fare se lo scanner ha rilevato vulnerabilità nelle immagini Docker?

Le immagini Docker di Google Cloud CLI sono ospitate in Artifact Registry. Le immagini vengono analizzate quotidianamente e le vulnerabilità ed esposizioni comuni (CVE) vengono mitigate prima di ogni nuova release di gcloud. Tuttavia, se lo scanner ha rilevato vulnerabilità nelle immagini Docker della CLI Google Cloud che non sono state risolte, puoi segnalare un bug che includa le seguenti informazioni:

  • Il tipo di vulnerabilità.
  • La posizione esatta nell'immagine.

Le vulnerabilità all'interno delle immagini del sistema operativo di base vengono risolte solo per garantire che le immagini Docker di Google Cloud CLI utilizzino versioni recenti e stabili di Debian o Alpine Linux.

Perché ci sono immagini senza tag nel repository Artifact Registry?

Le immagini Docker di Google Cloud CLI con i tag :stable, :alpine, :emulators e :debian_component_based supportano le piattaforme arm64 e amd64. Le immagini vengono create con un processo di compilazione multi-architettura, che combina immagini specifiche dell'architettura in un unico manifest. Il manifest include anche immagini di attestazione specifiche della piattaforma. Il processo di compilazione multi-arch aggiunge il tag solo all'immagine del manifest finale, ma non tagga le singole immagini specifiche dell'architettura o le immagini di attestazione. Di conseguenza, potresti visualizzare immagini senza tag nel repository Artifact Registry. Queste immagini non sono destinate all'uso e puoi ignorarle in sicurezza.