Como instalar a imagem do Docker da Google Cloud CLI

A imagem do Docker da Google Cloud CLI permite extrair uma versão específica da CLI gcloud como uma imagem do Docker do Artifact Registry e executar rapidamente 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, e todas instalam as ferramentas de linha de comando gcloud, gsutil e bq. Recomendamos que você instale a imagem :stable para um ambiente mínimo. Você também pode usar a imagem estável como a imagem de base para suas implantações, o que oferece a flexibilidade de instalar apenas os componentes e pacotes necessários na imagem:

  • :stable, :VERSION-stable: fornece uma instalação do gcloud com componentes gsutil e bq. A imagem é criada com base na imagem base do Debian 12 fornecida pelo Google mais recente. Essa imagem oferece suporte às plataformas linux/amd e linux/arm. Para instalar versões específicas da gcloud, use a tag :VERSION-stable.

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

  • :alpine, :VERSION-alpine: semelhante à versão estável, mas criada com base na imagem de base Alpine 3.19 mais recente. Essa imagem oferece suporte às plataformas linux/amd e linux/arm. Para instalar versões específicas da gcloud, use a tag :VERSION-alpine.

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

  • :emulators, :VERSION-emulators: semelhante à estável, com a adição de todos os componentes do emulador. A imagem é baseada na imagem de base do Debian 12 fornecida pelo Google mais recente e usa o gerenciador de componentes para instalar os componentes. Essa imagem oferece suporte às plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a tag :VERSION-emulators.

  • :latest, :VERSION: semelhante à estável, com componentes adicionais (a lista de componentes instalados na imagem está abaixo) pré-instalados. A imagem é baseada na imagem de base fornecida pelo Google do Debian 12 mais recente e usa pacotes deb para instalar os componentes. Para instalar versões específicas da gcloud, use a tag :VERSION.

  • :slim, :VERSION-slim: semelhante à estável, mas inclui os pacotes de terceiros adicionais, como curl, python3-crcmod, apt-transport-https, lsb-release, openssh-client, git, make e gnupg. Essa imagem é criada com base na imagem de base do Debian 12 fornecida pelo Google mais recente. Essa imagem oferece suporte às plataformas linux/amd e linux/arm. Para instalar versões específicas da gcloud, use a tag :VERSION-slim.

  • :debian_component_based, :VERSION-debian_component_based: semelhante à estável, com componentes adicionais (a lista de componentes instalados na imagem está listada abaixo) pré-instalados. A imagem é criada com base na imagem de base do Debian 12 fornecida pelo Google mais recente e usa o gerenciador de componentes para instalar os componentes. Essa imagem oferece suporte às plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a tag :VERSION-debian_component_based.

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

Se você usar uma tag que não esteja vinculada a uma versão específica do gcloud, seu ambiente poderá apresentar as seguintes mudanças importantes:

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

Para evitar possíveis mudanças importantes, recomendamos que seu ambiente de produção use uma das seguintes opções:

  • Uma tag com versão, como :496.0.0-stable
  • Um hash de imagem específico, como: gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
  • Hospedar a imagem no seu próprio repositório

Também é preciso atualizar as imagens periodicamente para receber a versão mais recente do gcloud.

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

Componentes instalados em cada tag

Componente :stable :alpine :emulators :latest :slim :debian_component_based
Extensões do Go no App Engine 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
Google Cloud Ferramenta de hash CRC32C x x x x x x
Kustomize x
Minikube x
CLI do Nomos x
Assistente 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 gcloud app 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

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 Google Cloud CLI, 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

    Também é possível usar o hash da imagem para extrair uma imagem específica do Docker do repositório. Para extrair a mesma imagem do exemplo anterior (:489.0.0-stable) usando o hash da imagem, execute o seguinte comando:

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

  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 versão mais recente, 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 Google Cloud CLI 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 será selecionado sempre que você abrir 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 executando 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 você quiser fazer a autenticação usando uma conta de serviço, use a propriedade auth/credential_file_override para definir um caminho para uma 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 já tem o auth/credential_file_override definido. A configuração aponta para um arquivo de certificado presente no contêiner como uma montagem de volume separada.

    $ 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 do 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 além de bq e gsutil. Para instalar outros componentes para a imagem estável, siga um destes procedimentos:

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 .

Instalar pacotes ou componentes adicionais no momento da execução

Se você extraiu a imagem do Docker stable, poderá instalar os seguintes componentes adicionais durante a 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 componentes adicionais para imagens baseadas em Alpine, crie um Dockerfile que use a imagem cloud-sdk como a imagem de 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 no Alpine, é necessário instalar manualmente as dependências de outros componentes.

Migrar 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 saber as etapas de migração para a imagem :stable, consulte Como migrar para a imagem :stable.

Como receber suporte para imagens

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

Quando você precisar de uma imagem com outros componentes, pacotes ou ferramentas, 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ê receber um erro failed to fetch <image-tag> ao extrair a imagem do 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 a imagem do Docker :stable para oferecer suporte ao seu fluxo de trabalho atual?

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

Casos de uso Opções de correção
Os 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 esses pacotes na imagem do Docker :stable manualmente.

O que você precisa 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 detectou vulnerabilidades nas imagens do Docker da CLI do Google Cloud que não foram resolvidas, você pode registrar um bug que inclua as seguintes informações:

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

As vulnerabilidades nas imagens do SO de base são resolvidas apenas para garantir que as imagens do Docker da CLI do Google Cloud estejam usando versões estáveis e recentes do Debian ou Alpine Linux.

Por que há imagens sem tags no repositório do Artifact Registry?

As imagens do Docker da CLI do Google Cloud com as tags :stable, :alpine, :emulators e :debian_component_based são compatíveis com as plataformas arm64 e amd64. As imagens são criadas com um processo de build de várias arquiteturas, que combina imagens específicas da arquitetura em um único manifest. O manifesto também inclui imagens de atestado específicas da plataforma. O processo de build de várias arquiteturas só adiciona a tag à imagem final do manifesto, mas não marca as imagens específicas da arquitetura ou de atestado individual. Como resultado, é possível que imagens sem tags apareçam no repositório do Artifact Registry. Essas imagens não são destinadas ao uso e podem ser ignoradas com segurança.