Installazione dell'immagine Docker di Google Cloud CLI

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

L'immagine Docker di Google Cloud CLI è la gcloud CLI installata su un'immagine Debian o Alpine. Le immagini Docker dell'interfaccia a riga di comando Google Cloud consentono di utilizzare gcloud e i relativi componenti in bundle senza dover installare manualmente gcloud sulla tua macchina locale.

Opzioni di immagini Docker

Esistono sei immagini Docker di Google Cloud CLI e tutte installano gli strumenti a riga di comando gcloud, gsutil e bq. Per un ambiente minimo, ti consigliamo di installare l'immagine :stable. Puoi anche utilizzare l'immagine stabile come immagine di base per i tuoi 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 gcloud con i componenti gsutil e bq. L'immagine è basata sull'immagine di base Debian 12 fornita da Google più recente. 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 alla versione stabile, ma basata sull'immagine di base Alpine 3.19 più recente. 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'immagine di base di Debian 12 fornita da Google e utilizza il gestore dei componenti 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 preinstallati (di seguito è riportato l'elenco dei componenti installati nell'immagine). L'immagine è basata sull'immagine di base Debian 12 fornita da Google più recente e utilizza i pacchetti deb per installare i componenti. Per installare versioni gcloud specifiche, utilizza il tag :VERSION.

  • :slim, :VERSION-slim: simile a 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'immagine di base di Debian 12 fornita da Google più recente. 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 viene compilata sulla base dell'immagine di base di Debian 12 fornita da Google più recente e utilizza il gestore dei componenti per installare i componenti. Questa immagine supporta sia le piattaforme linux/amd che linux/arm. Per installare versioni gcloud specifiche, 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, nel tuo ambiente potrebbero verificarsi le seguenti possibili modifiche incompatibili:

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

Per evitare possibili modifiche che causano interruzioni, è consigliabile che l'ambiente di produzione utilizzi una delle seguenti opzioni:

  • 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

Inoltre, devi aggiornare periodicamente le immagini per ottenere la versione più recente di gcloud.

Controlla la versione più recente 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 3.9 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
Cloud Pub/Sub Emulator 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
Strumento per l'hash CRC32C di Google Cloud x x x x x x
Kustomize x
Minikube x
Nomos CLI x
Assistente 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
Estensioni Java gcloud app x
Estensioni Python di gcloud app 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 del 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, esegui il pull 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 eseguire il pull di un'immagine Docker specifica dal repository. Per estrarre la stessa immagine dall'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:

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

    Se hai utilizzato il tag :stable mobile (che rimanda sempre alla release più recente), verifica l'installazione eseguendo il seguente 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:

  • Esegui l'autenticazione di gcloud con le tue credenziali utente 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, trasmetti 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 che venga selezionato ogni volta che apri il contenitore, esegui il seguente 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 completata l'autenticazione, le credenziali vengono conservate nel volume del gcloud-config container.

    Per verificare, 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 autenticarti utilizzando un account di servizio, utilizza la proprietà auth/credential_file_override per impostare un percorso a un account di servizio montato. Aggiorna quindi la configurazione in modo da leggere l'account servizio montato utilizzando la variabile di ambiente CLOUDSDK_CONFIG.

    Nell'esempio seguente, la configurazione mycloud ha già impostato auth/credential_file_override. La configurazione fa riferimento a un file del certificato presente all'interno del contenitore come montaggio del volume distinto.

    $ 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 per installare 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 file 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 in fase di runtime

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

  • gcloud 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 esecuzione, 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 il seguente 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 il seguente 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 dimensioni inferiori e correzioni di sicurezza migliorate. Per la procedura di migrazione all'immagine :stable, consulta Eseguire la migrazione all'immagine :stable.

Ricevere assistenza per le immagini

Le immagini ospitate in 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 immagine sull'immagine Docker di Google Cloud CLI.

Risoluzione dei problemi

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

Se ricevi un errore failed to fetch <image-tag> durante il tentativo di estrarre un'immagine Docker della CLI di Google Cloud, è molto probabile che tu stia tentando di recuperare un tag immagine ritirato e rimosso. Controlla le opzioni di immagine Docker per le opzioni di immagine Docker disponibili e 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 in base al tuo flusso di lavoro e le opzioni per la correzione:

Casi d'uso Opzioni di correzione
I componenti app-engine (utilizzati nell'immagine Docker :latest o :debian_component_based) non sono compatibili con Debian 12. Crea la tua immagine da un'immagine Debian (Debian 11) compatibile per installare i componenti app-engine.
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 installali 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 sottoposte a scansione quotidiana 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 di Google Cloud CLI 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 affrontate solo per garantire che le immagini Docker di Google Cloud CLI utilizzino release stabili e recenti di Debian o Alpine Linux.