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 la CLI de gcloud como una imagen de Docker desde Artifact Registry y ejecutar rápidamente comandos de la CLI de Google Cloud 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. El Las imágenes de Docker de Google Cloud CLI habilitan el uso de gcloud así como los paquetes de componentes, sin tener que instalar gcloud en tu máquina local.

Opciones de imagen de Docker

Hay seis imágenes de Docker de Google Cloud CLI. Te recomendamos que instales la siguiente imagen estable:

  • :stable, :VERSION-stable: Imagen predeterminada, más pequeña (basada en Debian) con una instalación estándar de gcloud.

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

  • :alpine, :VERSION-alpine: Imagen más pequeña (basada en Alpine) sin elementos adicionales componentes instalados. Esta imagen admite Linux/ARM.

Si quieres imágenes con paquetes adicionales o gcloud components preinstalados, puedes instalar una de las siguientes opciones:

  • :emulators, :VERSION-emulators: Imagen más pequeña (basada en Debian) con emulador preinstalados.
  • :latest, :VERSION: Imagen grande (basada en Debian) con componentes adicionales preinstalados
  • :slim, :VERSION-slim: Imagen más pequeña (basada en Debian) sin componentes preinstalados
  • :debian_component_based, :VERSION-debian_component_based: Imagen grande (basada en Debian) con componentes adicionales preinstalados A diferencia de :latest, que usaba paquetes deb, esta imagen usa el administrador de componentes para instalar componentes. Esta imagen es compatible con Linux/ARM.

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
Paquete de Python 3.9 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 app Java de gcloud x
Extensiones de Python de la app de gcloud x
Extensiones de Python para gcloud app (bibliotecas adicionales) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

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

Las etiquetas :<tag> y :<VERSION-tag> de la imagen de Docker de Google Cloud CLI son reconstruir a diario para incorporar de inmediato cualquier corrección de vulnerabilidades de las imágenes base. Si usas una etiqueta que no está vinculada a una versión específica, es posible que tu entorno experimente los siguientes cambios drásticos:

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

Para evitar posibles cambios rotundos, se recomienda que tus imágenes entorno, usa una de las siguientes opciones:

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

También deberías actualizar las imágenes periódicamente para obtener las últimas de gcloud.

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

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

  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

Autentica con la imagen de Docker de Google Cloud CLI. Para ello, ejecuta uno de los siguientes comandos:

  • 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 autenticar 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 que no sean bq y gsutil. Para instalar más componentes para la imagen estable, realiza una de las siguientes acciones:

Compila tu propia imagen con el Dockerfile de imágenes de :stable

Para compilar tu propia imagen con el componente adicional de :stable, puedes clonar. la clase cloud-sdk-docker Directorio de GitHub y usa el comando docker build para compilar la imagen de Docker :stable del Dockerfile con el INSTALL_COMPONENTS argumento. 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 quieres instalar los componentes cbt y kpt en el entorno 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 los 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 necesitas una imagen con componentes, paquetes o herramientas adicionales, puedes crea tu propia capa de imágenes sobre 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 correcció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 los 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 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 tu escáner haya detectado vulnerabilidades en el las imágenes de Docker de Google Cloud CLI que no están resueltas, puedes informar un error incluye 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.