Instalar la imagen de Docker de Google Cloud CLI

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

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

Opciones de imagen 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 crear un entorno mínimo. También puedes usar la imagen estable como imagen base para tus propias implementaciones, lo que te ofrece la flexibilidad de instalar solo los componentes y paquetes que necesites en tu imagen:

  • :stable, :VERSION-stable: proporciona una instalación de gcloud con los componentes gsutil y bq. La imagen se basa en la imagen base de Debian 12 más reciente proporcionada por Google. Esta imagen es compatible con las 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 y :VERSION-alpine: son similares a la versión estable, pero se basan en la imagen base más reciente de Alpine 3.20. Esta imagen es compatible con las plataformas linux/amd y linux/arm. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION-alpine.

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

  • :emulators y :VERSION-emulators: similar a la versión estable, pero con todos los componentes del emulador. La imagen se basa en la imagen base de Debian 12 más reciente proporcionada por Google y usa el gestor 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, pero con componentes adicionales preinstalados. (La lista de componentes instalados en la imagen se muestra más abajo). La imagen se basa en la imagen base de Debian 12 proporcionada por Google más reciente y usa paquetes deb 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.

  • :slim y :VERSION-slim: son similares a la versión estable, pero incluyen paquetes de terceros adicionales, como curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make y gnupg. Esta imagen se ha creado a partir de la imagen base de Debian 12 más reciente proporcionada por Google. Esta imagen es compatible con las plataformas linux/amd y linux/arm. Para instalar versiones específicas de gcloud, usa la etiqueta :VERSION-slim.

  • :debian_component_based y :VERSION-debian_component_based: similar a la versión estable, pero con componentes adicionales preinstalados (la lista de componentes instalados en la imagen se muestra más abajo). La imagen se basa en la imagen base de Debian 12 más reciente proporcionada por Google y usa el gestor 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.

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

Si usas una etiqueta que no está vinculada a una versión específica de gcloud, tu entorno puede experimentar los siguientes posibles cambios incompatibles:

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

Para evitar posibles cambios que provoquen errores, te recomendamos que tu entorno de producción utilice una 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 última versión 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 para App Engine x x
Appctl x
Herramienta de línea de comandos de BigQuery x x x x x x
Python 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
Emulador de Spanner x x
Herramienta de línea de comandos de Cloud Storage x x x x x x
Bibliotecas principales de la CLI de Google Cloud x x x x x x
Google Cloud Herramienta de hash CRC32C x x x x x x
Kustomize x
Minikube x
CLI de Nomos x
Asistente de extracción de la API 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 gcloud app x
Extensiones de Python de gcloud app x
Extensiones de Python de gcloud app (bibliotecas adicionales) x x
gke-gcloud-auth-plugin x x
KPT x x
kubectl x x

Instalar una imagen de Docker

La imagen 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, descárgala 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 Docker específica del repositorio. Para descargar la misma imagen del ejemplo anterior (:489.0.0-stable) con el hash de la imagen, ejecuta el siguiente comando:

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

  2. Para verificar la instalación, ejecuta el siguiente comando:

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

    Si has usado la etiqueta :stable flotante (que siempre apunta a la última versión), verifica la instalación ejecutando el siguiente comando:

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

Autenticarse con la imagen de Docker de Google Cloud CLI

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

  • Autentica gcloud con tus 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 necesitas autenticar aplicaciones que usen 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 definir 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'

    Una vez que te hayas autenticado correctamente, las credenciales se conservarán en el volumen de gcloud-config container.

    Para verificarlo, enumera la instancia de proceso con 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 quieres autenticarte con una cuenta de servicio, usa la propiedad auth/credential_file_override para definir una ruta a una cuenta de servicio montada. A continuación, actualiza la configuración para leer la cuenta de servicio montada mediante la variable de entorno CLOUDSDK_CONFIG.

    En el siguiente ejemplo, la configuración de mycloud ya tiene el valor auth/credential_file_override. La configuración apunta a un archivo de certificado que se encuentra 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 definir variables de entorno, consulta los siguientes artículos:

Instalando componentes adicionales

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

Imágenes basadas en Debian

De forma predeterminada, las imágenes estables (:stable y :VERSION-stable) no tienen ningún componente instalado, excepto bq y gsutil. Para instalar componentes adicionales de la imagen estable, haz una de las siguientes acciones:

Crear tu propia imagen con el Dockerfile de la imagen :stable

Para crear 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 crear la imagen Docker de :stable a partir del Dockerfile con el argumento INSTALL_COMPONENTS. Por ejemplo, para añadir componentes datastore-emulator, sigue estos pasos:

# 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 durante el tiempo de ejecución

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

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

Por ejemplo, si quieres instalar los componentes cbt y kpt en 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 se ejecuta 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 en imágenes basadas en Alpine, crea un Dockerfile que utilice la imagen cloud-sdk como imagen base.

Por ejemplo, para añadir los componentes kubectl y app-engine-java, sigue estos pasos:

  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. Compila la imagen ejecutando el siguiente comando:
docker build -t my-cloud-sdk-docker:alpine .

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

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 reducir el tamaño de la imagen y mejorar los parches de seguridad. Para ver los pasos que debes seguir para migrar a la imagen de :stable, consulta el artículo Migrar a la imagen de :stable.

Obtener asistencia con imágenes

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

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

Solución de problemas

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

Si recibes un error failed to fetch <image-tag> al intentar extraer una imagen de Docker de la CLI de Google Cloud, es muy probable que estés intentando obtener una etiqueta de imagen que se ha retirado. Consulta las opciones de imagen Docker para ver las opciones de imagen Docker disponibles y migra a una de las etiquetas admitidas.

¿En qué casos no puedes ampliar directamente la imagen de :stable Docker para que sea compatible con tu flujo de trabajo actual?

En la siguiente tabla se indican los casos prácticos en los que no puedes ampliar directamente la imagen de Docker :stable para adaptarla a tu flujo de trabajo, así como las opciones para solucionar el problema:

Casos prácticos Opciones de corrección
Los paquetes de terceros, como docker o docker-buildx, no se incluyen en la imagen :stable. Si necesitas estos paquetes de terceros, crea tu propia imagen o instala estos paquetes manualmente en la imagen Docker :stable.

¿Qué debes hacer si tu escáner ha encontrado vulnerabilidades en las imágenes de Docker?

Las imágenes de Docker de Google Cloud CLI se alojan en Artifact Registry. Las imágenes se analizan a diario y las vulnerabilidades y exposiciones comunes (CVEs) se mitigan antes de cada nuevo lanzamiento de gcloud. Sin embargo, si tu escáner ha detectado vulnerabilidades en las imágenes de Docker de la CLI de Google Cloud que no se han resuelto, puedes registrar un error que incluya la siguiente información:

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

Las vulnerabilidades de las imágenes del SO base solo se abordan para asegurar que las imágenes Docker de la CLI de Google Cloud usen 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 de Docker de Google Cloud CLI con las etiquetas :stable, :alpine, :emulators y :debian_component_based admiten las plataformas arm64 y amd64. Las imágenes se compilan con un proceso de compilación de varias arquitecturas, que combina imágenes específicas de la arquitectura en un solo manifiesto. El manifiesto también incluye imágenes de atestación específicas de la plataforma. El proceso de compilación de varias arquitecturas solo añade etiquetas a la imagen de manifiesto final, pero no etiqueta las imágenes específicas de cada arquitectura ni las imágenes de certificación. Como resultado, es posible que veas imágenes sin etiquetas en el repositorio de Artifact Registry. Estas imágenes no están pensadas para usarse y puedes ignorarlas sin problemas.

¿Dónde puedo obtener información sobre los paquetes de terceros retirados de las imágenes de Docker de gcloud?

Puedes consultar información sobre todos los paquetes de terceros retirados en los anuncios de GitHub.