Instalación de la imagen Docker de Google Cloud CLI

La imagen Docker de Google Cloud CLI le permite extraer una versión específica de gcloud CLI como una imagen Docker desde Artifact Registry y ejecutar rápidamente comandos de Google Cloud CLI en un contenedor aislado y configurado correctamente.

La imagen Docker de la CLI de Google Cloud es la CLI de gcloud instalada sobre una imagen de Debian o Alpine. Las imágenes Docker de la CLI de Google Cloud permiten usar gcloud y sus componentes sin tener que instalarlo manualmente en el equipo local.

Novedades / Actualizaciones importantes

4 de junio de 2025

Paquete docker eliminado de las imágenes Docker de gcloud

28 de mayo de 2025

El soporte para los emuladores gcloud Firestore y Datastore con Java 17 o versiones anteriores finalizará el 24 de junio de 2025

Actualizar la cronología

Opciones de imagen de Docker

Hay seis imágenes Docker de Google Cloud CLI, y todas instalarán las herramientas de línea de comandos gcloud , gsutil y bq . Recomendamos instalar la imagen :stable para un entorno mínimo. También puede usar la imagen estable como base para sus propias implementaciones, lo que le brinda la flexibilidad de instalar solo los componentes y paquetes que necesita en su imagen.

• :stable , :VERSION-stable : Proporciona una instalación de gcloud con componentes gsutil y bq . La imagen se basa en la última imagen base de Debian 12 proporcionada por Google . Esta imagen es compatible con las plataformas linux/amd y linux/arm . Para instalar versiones específicas de gcloud, use la etiqueta :VERSION-stable .

Si desea utilizar una imagen basada en Alpine, puede instalar la siguiente imagen:

• :alpine , :VERSION-alpine : Similar a la versión estable, pero basada en la imagen base de Alpine 3.20 . Esta imagen es compatible con las plataformas linux/amd y linux/arm . Para instalar versiones específicas de gcloud, use la etiqueta :VERSION-alpine .

Si desea imágenes con componentes o paquetes adicionales preinstalados, puede instalar una de las siguientes opciones:

• :emulators , :VERSION-emulators : Similar a la versión estable, con todos los componentes del emulador incluidos. La imagen se basa en la última imagen base de Debian 12 proporcionada por Google y utiliza el administrador de componentes para instalar los componentes. Esta imagen es compatible con las plataformas linux/amd y linux/arm . Para instalar versiones específicas de gcloud, use la etiqueta :VERSION-emulators .

• :latest , :VERSION : Similar a la versión estable, con componentes adicionales preinstalados (la lista de componentes instalados en la imagen se muestra a continuación ). La imagen se basa en la última imagen base de Debian 12 proporcionada por Google y utiliza paquetes deb para instalar los componentes. Para instalar versiones específicas de gcloud, use la etiqueta :VERSION .

• :slim , :VERSION-slim : Similar a la versión estable, pero incluye paquetes de terceros adicionales como curl , python3-crcmod , apt-transport-https , lsb-release , openssh-client , git , make y gnupg . Esta imagen se basa en la última imagen base de Debian 12 proporcionada por Google . Es compatible con las plataformas linux/amd y linux/arm . Para instalar versiones específicas de gcloud, use la etiqueta :VERSION-slim .

• :debian_component_based , :VERSION-debian_component_based : Similar a la versión estable, con componentes adicionales preinstalados (la lista de componentes instalados en la imagen se muestra a continuación ). La imagen se basa en la última imagen base de Debian 12 proporcionada por Google y utiliza el administrador de componentes para instalarlos. Esta imagen es compatible con las plataformas linux/amd y linux/arm . Para instalar versiones específicas de gcloud, utilice la etiqueta :VERSION-debian_component_based .

Utilice una versión específica en producción

Si usa una etiqueta que no está vinculada a una versión específica de gcloud, su entorno podría experimentar los siguientes posibles cambios importantes:

• Actualizaciones de versión del SDK de Google Cloud, que pueden cambiar el comportamiento de la herramienta.
• Actualizaciones a la lista de componentes instalados.

Para evitar posibles cambios importantes, se recomienda que su entorno de producción utilice uno de los siguientes:

• Una etiqueta versionada, como :496.0.0-stable
• Un hash de imagen específico como: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
• Aloje la imagen en su propio repositorio

También debes actualizar las imágenes periódicamente para obtener la última versión de gcloud.

Consulte la última versión de Google Cloud CLI y todas las versiones anteriores de Google Cloud CLI .

Componentes instalados en cada etiqueta

Instalación de una imagen de Docker

La imagen de Docker está alojada en Artifact Registry con el siguiente nombre de repositorio: gcr.io/google.com/cloudsdktool/google-cloud-cli . Las imágenes también están disponibles en los repositorios us.gcr.io , eu.gcr.io y asia.gcr.io

1. Para usar la imagen de la versión estable de Google Cloud CLI, gcr.io/google.com/cloudsdktool/google-cloud-cli:stable , extráigala de Artifact Registry ejecutando el siguiente comando:

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

   También puedes usar el hash de la imagen para extraer una imagen de Docker específica del repositorio. Para extraer la misma imagen del ejemplo anterior ( :489.0.0-stable ) usando el hash de la imagen, ejecuta el siguiente comando:

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

2. Verifique la instalación ejecutando:

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

   Si ha utilizado la etiqueta flotante :stable (que siempre apunta a la última versión), verifique la instalación ejecutando el siguiente comando:

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

Autenticación con la imagen Docker de Google Cloud CLI

Autentíquese con la imagen Docker de Google Cloud CLI ejecutando uno de los siguientes comandos:

• Autentique gcloud con sus credenciales de usuario ejecutando gcloud auth login :

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

• Si necesita autenticar aplicaciones que utilizan el Google Cloud API, pase la opción --update-adc :

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

• Para establecer un proyecto predeterminado que se seleccione cada vez que abra el contenedor, ejecute el siguiente 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 vez que se haya autenticado correctamente, las credenciales se conservan en el volumen del gcloud-config container .

  Para verificar, enumere la instancia de cómputo usando las credenciales ejecutando el contenedor 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
  

• Si desea autenticarse con una cuenta de servicio, utilice la propiedad auth/credential_file_override para establecer la ruta a una cuenta de servicio montada. A continuación, actualice la configuración para leer la cuenta de servicio montada mediante la variable de entorno CLOUDSDK_CONFIG .

  En el siguiente ejemplo, la configuración mycloud ya tiene configurado el auth/credential_file_override . Esta configuración apunta a un archivo de certificado presente en el contenedor como un montaje de volumen independiente.

  $ 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
  

  Para obtener más información sobre cómo configurar variables de entorno, consulte lo siguiente:

  • Configuración de propiedades mediante variables de entorno
  • configuración de gcloud

Instalación de componentes adicionales

Puedes instalar componentes adicionales en la imagen de Docker de Google Cloud CLI. El método para instalar componentes adicionales varía según el tipo de imagen base subyacente.

Imágenes basadas en Debian

De forma predeterminada, las imágenes estables ( :stable y :VERSION-stable ) no tienen instalados componentes aparte de bq y gsutil . Para instalar componentes adicionales para la imagen estable, realice una de las siguientes acciones:

• Construya su propia imagen usando el Dockerfile de imagen :stable : instale paquetes que no estén disponibles directamente a través de apt-get , es decir, el motor Docker.
• Instalar paquetes o componentes adicionales en tiempo de ejecución : personalice su imagen sin alojarla.

Construyendo su propia imagen usando el Dockerfile de imagen :stable

Para crear tu propia imagen con componentes adicionales de :stable , puedes clonar el directorio de GitHub cloud-sdk-docker y usar el comando docker build para crear la imagen Docker :stable desde el Dockerfile con el argumento INSTALL_COMPONENTS . Por ejemplo, para añadir componentes 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 .

Instalar paquetes o componentes adicionales en tiempo de ejecución

Si ha extraído la imagen stable de Docker, puede instalar los siguientes componentes adicionales durante el tiempo de ejecución:

• Componentes de gcloud mediante el uso de la variable de entorno COMPONENTS .
• apt-packages mediante el uso de la variable de entorno APT_PACKAGES .

Por ejemplo, si desea instalar los componentes cbt y kpt en tiempo de ejecución, puede ejecutar el siguiente comando:

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

Para instalar los paquetes apt curl y gcc mientras se ejecuta la imagen de Docker, ejecute el siguiente comando:

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

Imágenes basadas en los Alpes

Para instalar componentes adicionales para imágenes basadas en Alpine, cree un Dockerfile que use la imagen cloud-sdk como imagen base.

Por ejemplo, para agregar componentes kubectl y app-engine-java :

1. Crea el Dockerfile como:

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. Construya la imagen ejecutando el siguiente comando:

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

Para las imágenes basadas en Alpine, debe instalar las dependencias de componentes adicionales manualmente.

Migración a la imagen :stable

Si utiliza las imágenes de Docker :latest , :slim , :emulators , :alpine y :debian_component_based , le recomendamos migrar a la imagen :stable basada en Debian para obtener un tamaño de imagen más pequeño y mejoras de seguridad. Para conocer los pasos para migrar a la imagen :stable , consulte Migración a la imagen :stable .

Obtener soporte para imágenes

Las imágenes alojadas en Artifact Registry proporcionan instalaciones completamente funcionales de Google Cloud CLI. Si encuentra errores o problemas relacionados con las imágenes de Docker, puede crear un ticket de soporte .

Cuando necesite una imagen con componentes, paquetes o herramientas adicionales, puede crear su propia capa de imagen sobre la imagen de Docker de Google Cloud CLI.

Solución de problemas

¿Qué debe hacer si ve un error failed to fetch <image-tag> al extraer la imagen de Docker?

Si failed to fetch <image-tag> un error al intentar obtener una imagen Docker de Google Cloud CLI, es probable que estés intentando obtener una etiqueta de imagen obsoleta y eliminada. Consulta las opciones de imagen Docker disponibles y migra a una de las etiquetas compatibles.

¿Cuáles son los casos de uso en los que no puede ampliar directamente la imagen Docker :stable para respaldar su flujo de trabajo actual?

La siguiente tabla enumera los casos de uso en los que no puede extender directamente la imagen de Docker :stable para que se ajuste a su flujo de trabajo y enumera las opciones para solucionarlo:

¿Qué debe hacer si su escáner encuentra vulnerabilidades en las imágenes de Docker?

Las imágenes de Docker de la CLI de Google Cloud se alojan en Artifact Registry . Las imágenes se analizan a diario y las vulnerabilidades y exposiciones comunes (CVE) se mitigan antes de cada nueva versión de gcloud. Sin embargo, si el analizador ha detectado vulnerabilidades en las imágenes de Docker de la CLI de Google Cloud que no se han resuelto, puede informar de un error con la siguiente información:

• El tipo de vulnerabilidad.
• La ubicación exacta en la imagen.

Las vulnerabilidades dentro de las imágenes del sistema operativo base solo se abordan para garantizar que las imágenes de Docker de Google Cloud CLI utilicen versiones recientes y estables de Debian o Alpine Linux.

¿Por qué hay imágenes sin etiquetas en el repositorio de Artifact Registry ?

Las imágenes Docker de Google Cloud CLI con las etiquetas :stable , :alpine , :emulators y :debian_component_based son compatibles con las plataformas arm64 y amd64. Las imágenes se compilan mediante un proceso de compilación multiarquitectura, que combina imágenes específicas de cada arquitectura en un único manifiesto . El manifiesto también incluye imágenes de atestación específicas de la plataforma. El proceso de compilación multiarquitectura solo añade la etiqueta a la imagen final del manifiesto, pero no etiqueta las imágenes individuales específicas de la arquitectura ni las imágenes de atestación. Por lo tanto, es posible que vea imágenes sin etiquetas en el repositorio de Artifact Registry . Estas imágenes no están diseñadas para su uso y puede ignorarlas sin problema.