Instala la imagen de Docker de Google Cloud CLI

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

La imagen de Docker de Google Cloud CLI es la gcloud CLI instalada sobre una imagen de Debian o Alpine. Las imágenes de Docker de la CLI de Google Cloud permiten el uso de gcloud y sus componentes empaquetados sin tener que instalar gcloud de forma manual en tu máquina local.

Opciones de imagen de Docker

Hay seis imágenes de Docker de Google Cloud CLI, y todas instalarán las herramientas de línea de comandos gcloud, gsutil y bq. Te recomendamos que instales la imagen :stable para obtener un entorno mínimo. También puedes usar la imagen estable como imagen base para tus propias implementaciones, lo que te brinda la flexibilidad de instalar solo los componentes y paquetes que necesitas en tu imagen:

  • :stable, :VERSION-stable: Proporciona una instalación de gcloud con los componentes gsutil y bq. La imagen se compila en la imagen base de Debian 12 más reciente que proporciona Google. Esta imagen admite plataformas linux/amd y linux/arm. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION-stable.

Si quieres usar una imagen basada en Alpine, puedes instalar la siguiente imagen:

  • :alpine, :VERSION-alpine: Son similares a las estables, pero se compilan en la imagen base más reciente de Alpine 3.19. Esta imagen admite plataformas linux/amd y linux/arm. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION-alpine.

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

  • :emulators, :VERSION-emulators: Similar a la versión estable, con la adición de todos los componentes del emulador. La imagen se compila en la imagen base de Debian 12 más reciente que proporciona Google y usa 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, usa 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 indica más abajo). La imagen se compila en la imagen base de Debian 12 más reciente que proporciona Google y usa paquetes deb para instalar los componentes. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION.

  • :slim y :VERSION-slim: Son similares a la versión estable, pero incluyen paquetes adicionales de terceros, como curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make y gnupg. Esta imagen se compila en la imagen base de Debian 12 más reciente que proporciona Google. Esta imagen admite plataformas linux/amd y linux/arm. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION-slim.

  • :debian_component_based, :VERSION-debian_component_based: Son similares a las imágenes estables, con componentes adicionales (la lista de componentes instalados en la imagen se indica más abajo) preinstalados. La imagen se compila en la imagen base de Debian 12 más reciente que proporciona Google y usa 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, usa la etiqueta :VERSION-debian_component_based.

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

Si usas una etiqueta que no está vinculada a una versión específica de gcloud, es posible que tu entorno experimente los siguientes cambios drásticos:

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

Para evitar posibles cambios drásticos, se recomienda que tu entorno de producción use cualquiera de las siguientes opciones:

  • Una etiqueta con versión, como :496.0.0-stable
  • Un hash de imagen específico, como gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
  • Aloja la imagen en tu propio repositorio

También debes actualizar las imágenes periódicamente para obtener la versión más reciente de gcloud.

Consulta la versión más reciente de Google Cloud CLI y todas las versiones anteriores de Google Cloud CLI.

Componentes instalados en cada etiqueta

Componente :stable :alpine :emulators :latest :slim :debian_component_based
Extensiones de Go de App Engine x x
Appctl x
Herramienta de línea de comandos de BigQuery x x x x x x
Python 3.9 incluido x x x x x x
Herramienta de línea de comandos de Bigtable x x
Emulador de Bigtable x x x
Emulador de Cloud Datastore x x x
Emulador de Cloud Firestore x x
Emulador de Cloud Pub/Sub x x x
Spanner Emulator x x
Herramienta de línea de comandos de Cloud Storage x x x x x x
Bibliotecas principales de Google Cloud CLI x x x x x x
Herramienta de hash CRC32C de Google Cloud x x x x x x
Kustomize x
Minikube x
CLI de Nomos x
Ayudante de extracción de la API de On-Demand Scanning x x
Skaffold x
anthos-auth x
Comandos Alfa de gcloud x x x x
Comandos Beta de gcloud x x x x
Extensiones de Java de la app de gcloud x
Extensiones de Python de la app de gcloud x
Extensiones de Python de gcloud app (bibliotecas adicionales) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

Instala una imagen de Docker

La imagen de Docker se aloja 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 con 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áela de Artifact Registry con el siguiente comando:

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

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

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

  2. Ejecute el siguiente comando para verificar la instalación:

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

    Si usaste la etiqueta :stable flotante (que siempre apunta a la versión más reciente), ejecuta el siguiente comando para verificar la instalación:

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

Autenticación con la imagen de Docker de Google Cloud CLI

Ejecuta uno de los siguientes comandos para autenticar con la imagen de Docker de Google Cloud CLI:

  • Ejecuta gcloud auth login para autenticar gcloud con tus credenciales de usuario:

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

  • Si necesitas autenticar aplicaciones que usan las APIs de Google Cloud, pasa 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 abras el contenedor, ejecuta 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'

    Después de haber autenticado correctamente, las credenciales se conservan en el volumen de gcloud-config container.

    Para verificar, enumera la instancia de procesamiento que usa 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 deseas autenticarte con una cuenta de servicio, usa la propiedad auth/credential_file_override para establecer una ruta de acceso a una cuenta de servicio activada. Luego, actualiza la configuración para leer la cuenta de servicio activada con la variable de entorno CLOUDSDK_CONFIG.

    En el siguiente ejemplo, la configuración de mycloud ya tiene configurado auth/credential_file_override. La configuración apunta a un archivo de certificado que está presente dentro del contenedor como un activador 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, consulta los siguientes recursos:

Instala componentes adicionales

Puedes instalar componentes adicionales en la imagen de Docker de Google Cloud CLI. El enfoque 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 componentes instalados distintos de bq y gsutil. Para instalar componentes adicionales para la imagen estable, haz una de las siguientes acciones:

Cómo compilar tu propia imagen con el Dockerfile de la imagen :stable

Para compilar tu propia imagen con un componente adicional de :stable, puedes clonar el directorio cloud-sdk-docker de GitHub y usar el comando docker build para compilar la imagen de Docker de :stable desde el Dockerfile con el argumento INSTALL_COMPONENTS. Por ejemplo, para agregar componentes datastore-emulator, haz lo siguiente:

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

Instala paquetes o componentes adicionales durante el tiempo de ejecución.

Si extrajiste la imagen de Docker de stable, puedes instalar los siguientes componentes adicionales durante el tiempo de ejecución:

  • gcloud con la variable de entorno COMPONENTS.
  • apt-packages con la variable de entorno APT_PACKAGES.

Por ejemplo, si deseas instalar los componentes cbt y kpt durante el tiempo de ejecución, puedes 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 ejecutas la imagen de Docker, ejecuta 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 Alpine

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

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

  1. Crea el Dockerfile de la siguiente manera:
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. Ejecuta el siguiente comando para compilar la imagen:
docker build -t my-cloud-sdk-docker:alpine .

En el caso de las imágenes basadas en Alpine, debes instalar las dependencias de los componentes adicionales de forma manual.

Cómo migrar a la imagen :stable

Si usas las imágenes de Docker :latest, :slim, :emulators, :alpine y :debian_component_based, te recomendamos que migres a la imagen :stable basada en Debian para obtener un tamaño de imagen más pequeño y correcciones de seguridad mejoradas. Para conocer los pasos para migrar a la imagen :stable, consulta Migración a la imagen :stable.

Cómo obtener asistencia para las imágenes

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

Cuando necesites una imagen con componentes, paquetes o herramientas adicionales, puedes crear tu propia capa de imagen sobre la imagen de Docker de Google Cloud CLI.

Soluciona problemas

¿Qué debes hacer si ves un error failed to fetch <image-tag> mientras extraes la imagen de Docker?

Si recibes un error failed to fetch <image-tag> cuando intentas extraer una imagen de Docker de Google Cloud CLI, es probable que estés intentando recuperar una etiqueta de imagen que dejó de estar disponible y se quitó. Consulta las opciones de imagen de Docker para conocer las opciones de imagen de Docker disponibles y migra a una de las etiquetas admitidas.

¿Cuáles son los casos de uso en los que no puedes extender directamente la imagen de Docker :stable para admitir tu flujo de trabajo actual?

En la siguiente tabla, se enumeran los casos de uso en los que no puedes extender directamente la imagen de Docker :stable para que se adapte a tu flujo de trabajo y se enumeran las opciones para solucionar el problema:

Casos de uso Opciones de solución
Los componentes app-engine (que se usan en la imagen de Docker :latest o :debian_component_based) no son compatibles con Debian 12. Compila tu propia imagen a partir de una imagen de Debian (Debian 11) compatible para instalar componentes de app-engine.
Los paquetes de terceros, como docker o docker-buildx, no se incluyen en la imagen :stable. Si necesitas estos paquetes de terceros, compila tu propia imagen o instálalos en la imagen de Docker de :stable de forma manual.

¿Qué debes hacer si tu escáner encontró 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 tu escáner detectó vulnerabilidades en las imágenes de Docker de Google Cloud CLI que no se resolvieron, puedes informar un error que incluya la siguiente información:

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

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