Como instalar a imagem do Docker da Google Cloud CLI

A imagem Docker da Google Cloud CLI permite extrair uma versão específica do CLI gcloud como uma imagem Docker Artifact Registry e execute com rapidez Comandos da Google Cloud CLI em um contêiner isolado e configurado corretamente.

A imagem do Docker da Google Cloud CLI é a CLI gcloud instalada sobre uma imagem Debian ou Alpine. As imagens Docker da CLI do Google Cloud permitem o uso da gcloud e dos componentes agrupados sem precisar instalar manualmente a gcloud na máquina local.

Opções de imagem do Docker

Há seis imagens Docker da CLI do Google Cloud. Recomendamos que você instale esta imagem estável:

  • :stable, :VERSION-stable: imagem padrão, a menor (baseada em Debian) com uma a instalação padrão da gcloud.

Se você quiser usar uma imagem baseada em Alpine, instale a imagem a seguir:

  • :alpine, :VERSION-alpine: imagem menor baseada no Alpine sem componentes complementares instalados. Esta imagem é compatível com linux/arm.

Se você quiser imagens com pacotes adicionais ou componentes do gcloud pré-instalados, instale uma das seguintes opções:

  • :emulators, :VERSION-emulators: imagem menor (baseada no Debian) com componentes do emulador pré-instalados.
  • :latest, :VERSION: imagem grande (baseada em Debian) com componentes adicionais que já vem pré-instalado.
  • :slim, :VERSION-slim: imagem menor (baseada em Debian) sem componentes que já vem pré-instalado.
  • :debian_component_based, :VERSION-debian_component_based: grande (baseado em Debian) com componentes adicionais pré-instalados. Ao contrário do :latest, que usava pacotes deb, essa imagem usa o gerenciador de componentes para instalar componentes. Essa imagem oferece suporte a linux/arm.

Componentes instalados em cada tag

Componente :stable :alpine :emulators :latest :slim :debian_component_based
Extensões do App Engine para Go x x
Appctl x
Ferramenta de linha de comando do BigQuery x x x x x x
Python 3.9 agrupado x x x x x x
Ferramenta de linha de comando do Bigtable x x
Emulador do Bigtable x x x
Emulador do Cloud Datastore x x x
Emulador do Cloud Firestore x x
Emulador do Cloud Pub/Sub x x x
Emulador do Spanner x x
Ferramenta de linha de comando do Cloud Storage x x x x x x
Bibliotecas principais da CLI do Google Cloud x x x x x x
Ferramenta de hash CRC32C do Google Cloud x x x x x x
Kustomize x
Minikube x
CLI do Nomos x
Auxiliar de extração da API On-Demand Scanning x x
Skaffold x
anthos-auth x
Comandos gcloud alpha x x x x
Comandos beta do gcloud x x x x
Extensões Java do app gcloud x
Extensões Python do app gcloud x
Extensões Python do app gcloud (bibliotecas extras) x x
gke-gcloud-auth-plugin x x
kpt x x
kubectl x x

Usar uma versão específica na produção

As tags :<tag> e :<VERSION-tag> da imagem Docker da Google Cloud CLI são refeitas diariamente para incorporar imediatamente as correções de vulnerabilidade da imagem de base. Se você usar uma tag que não esteja vinculada a uma versão específica, seu ambiente poderá apresentar as seguintes mudanças:

  • Atualizações de versão do SDK Google Cloud, que podem alterar o comportamento da ferramenta.
  • Atualizações na lista de componentes instalados.

Para evitar possíveis alterações interruptivas, é recomendável que sua produção use um destes métodos:

  • Uma tag com controle de versão datado, como :496.0.0-stable-20241015
  • Um hash de imagem específico, como: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df

Atualize as imagens periodicamente para receber as versões mais recentes versão da gcloud.

Confira a versão mais recente da CLI do Google Cloud e todas as versões anteriores.

Como instalar uma imagem do Docker

A imagem do Docker está hospedada no Artifact Registry com o seguinte nome de repositório: gcr.io/google.com/cloudsdktool/google-cloud-cli. As imagens também estão disponíveis usando os repositórios us.gcr.io, eu.gcr.io e asia.gcr.io.

  1. Para usar a imagem da versão estável da CLI do Google Cloud, gcr.io/google.com/cloudsdktool/google-cloud-cli:stable, extraia-a do Artifact Registry executando o seguinte comando:

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

  2. Execute o seguinte comando para confirmar a instalação:

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

    Se você usou a tag :stable flutuante, que sempre aponta para a tag mais recente versão), verifique a instalação executando o seguinte comando:

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

Como fazer a autenticação com a imagem do Docker da Google Cloud CLI

Faça a autenticação com a imagem do Docker da CLI do Google Cloud executando um dos seguintes comandos:

  • Faça a autenticação do gcloud com suas credenciais de usuário executando gcloud auth login:

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

  • Se você precisar autenticar aplicativos que usam as APIs do Google Cloud, transmita a opção --update-adc:

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

  • Para definir um projeto padrão que é selecionado sempre que você abre o contêiner, execute o seguinte 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'

    Depois de autenticadas com sucesso, as credenciais são preservadas no volume de gcloud-config container.

    Para verificar, liste a instância de computação usando as credenciais. Para isso, execute o contêiner com --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 quiser autenticar usando uma conta de serviço, use o auth/credential_file_override para definir um caminho conta de serviço montada. Em seguida, atualize a configuração para ler a conta de serviço montada usando a variável de ambiente CLOUDSDK_CONFIG.

    No exemplo abaixo, a configuração mycloud tem o auth/credential_file_override já definido. A configuração aponta para um arquivo de certificado que está presente no contêiner como um arquivo montagem de volume.

    $ 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 mais informações sobre como definir variáveis de ambiente, consulte:

Como instalar componentes complementares

É possível instalar outros componentes na imagem Docker da Google Cloud CLI. A abordagem para instalar outros componentes varia de acordo com o tipo de imagem de base.

Imagens baseadas no Debian

Por padrão, as imagens estáveis (:stable e :VERSION-stable) não têm componentes instalados que não sejam bq e gsutil. Para instalar outros componentes na imagem estável, siga um destes procedimentos:

Como criar sua própria imagem usando o Dockerfile da imagem :stable

Para criar sua própria imagem com um componente adicional do :stable, clone o diretório cloud-sdk-docker do GitHub e use o comando docker build para criar a imagem do Docker :stable do Dockerfile com o argumento INSTALL_COMPONENTS. Por exemplo, para adicionar 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 .

Como instalar outros pacotes ou componentes no ambiente de execução

Se você extraiu a imagem do Docker stable, é possível instalar o seguinte componentes adicionais durante o tempo de execução:

  • componentes do gcloud usando a variável de ambiente COMPONENTS.
  • apt-packages usando a variável de ambiente APT_PACKAGES.

Por exemplo, se você quiser instalar os componentes cbt e kpt no momento da execução, execute o seguinte 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 os pacotes apt-packages curl e gcc enquanto a imagem do Docker está sendo executada, execute o seguinte comando:

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

Imagens baseadas em Alpine

Para instalar outros componentes para imagens baseadas em Alpine, crie um Dockerfile que usa a imagem cloud-sdk como a imagem base.

Por exemplo, para adicionar os componentes kubectl e app-engine-java:

  1. Crie o 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. Crie a imagem executando o seguinte comando:
docker build -t my-cloud-sdk-docker:alpine .

Para imagens baseadas em Alpine, você precisa instalar dependências de outros os componentes manualmente.

Migração para a imagem :stable

Se você estiver usando as imagens :latest, :slim, :emulators, :alpine e :debian_component_based do Docker, recomendamos migrar para a imagem :stable baseada no Debian para um tamanho de imagem menor e correções de segurança melhores. Para acessar as etapas de migração para a imagem :stable, consulte Migrando para a imagem :stable.

Como receber suporte para imagens

As imagens hospedadas no Artifact Registry fornecem instalações totalmente funcionais da CLI do Google Cloud. Se você encontrar bugs ou problemas relacionados às imagens Docker, crie um tíquete de suporte.

Quando você precisar de uma imagem com componentes, pacotes ou ferramentas adicionais, poderá crie sua própria camada de imagem sobre a Imagem do Docker da Google Cloud CLI.

Solução de problemas

O que fazer se você encontrar um erro failed to fetch <image-tag> durante a extração da imagem Docker?

Se você receber um erro failed to fetch <image-tag> ao tentar extrair uma imagem do Docker da CLI do Google Cloud, provavelmente está tentando buscar uma tag de imagem que foi descontinuada e removida. Verifique as opções de imagem do Docker para conferir as opções de imagem do Docker disponíveis e migre para uma das tags compatíveis.

Quais são os casos de uso em que não é possível estender diretamente o Docker :stable imagem para ajudar no seu fluxo de trabalho atual?

A tabela a seguir lista os casos de uso em que não é possível estender diretamente os :stable para se adequar ao seu fluxo de trabalho e lista as opções de correção:

Casos de uso Opções de correção
Os componentes app-engine (usados na imagem do Docker :latest ou :debian_component_based) não são compatíveis com o Debian 12. Crie sua própria imagem a partir de uma imagem compatível do Debian (Debian 11) para instalar os componentes app-engine.
Pacotes de terceiros, como docker ou docker-buildx, não estão incluídos na imagem :stable Se você precisar desses pacotes de terceiros, crie sua própria imagem ou instale-os manualmente na imagem do Docker :stable.

O que fazer se o verificador encontrar vulnerabilidades nas imagens do Docker?

As imagens Docker da CLI do Google Cloud são hospedadas no Artifact Registry. As imagens são verificadas diariamente, e as vulnerabilidades e exposições comuns (CVEs) são mitigadas antes de cada nova versão do gcloud. No entanto, se o scanner detectar vulnerabilidades nas imagens do Docker da CLI do Google Cloud que não forem resolvidas, você poderá enviar um bug que inclua as seguintes informações:

  • O tipo de vulnerabilidade.
  • O local exato na imagem.

As vulnerabilidades nas imagens de base do SO são tratadas apenas para garantir que o As imagens Docker do Google Cloud CLI usam versões recentes e estáveis do Debian ou Alpine Linux