A imagem do Docker do Google Cloud CLI permite que você extraia uma versão específica do gcloud CLI como uma imagem do Docker do Artifact Registry e execute rapidamente comandos do Google Cloud CLI em um contêiner isolado e configurado corretamente.
A imagem Docker da Google Cloud CLI é a CLI do gcloud instalada sobre uma imagem Debian ou Alpine. As imagens Docker da Google Cloud CLI permitem o uso do gcloud e de seus componentes sem a necessidade de instalar manualmente o gcloud na sua máquina local.
Novidades / Atualizações importantes
04 de junho de 2025
pacote docker
removido das imagens do docker do gcloud
28 de maio de 2025
O suporte para emuladores gcloud Firestore e Datastore com Java 17 ou anterior será encerrado em 24 de junho de 2025.
Cronograma de atualização
Data | Pacote | Removido em versão do gcloud | Pin-to versão do gcloud (para continuar usando o pacote) | Pacote removido das imagens |
---|---|---|---|---|
22 de abril de 2025 | docker-buildx | 519.0.0 | 518.0.0 | :alpine e :debian_component_based |
20 de maio de 2025 | docker-buildx | 523.0.0 | 522.0.0 | :slim e :latest |
01 de julho de 2025 | docker | 529.0.0 | 528.0.0 | :alpine e :debian_component_based |
22 de julho de 2025 | docker | 531.0.0 | 530.0.0 | :slim e :latest |
Opções de imagem do Docker
Existem seis imagens do Docker do Google Cloud CLI, e todas instalarão as ferramentas de linha de comando gcloud
, gsutil
e bq
. Recomendamos que você instale a imagem :stable
para um ambiente minimalista. Você também pode usar a imagem estável como imagem base para suas próprias implantações, o que lhe dá a flexibilidade de instalar apenas os componentes e pacotes necessários na sua imagem:
-
:stable
,:VERSION-stable
: Fornece uma instalação do gcloud com os componentesgsutil
ebq
. A imagem é construída sobre a imagem base Debian 12 mais recente fornecida pelo Google . Esta imagem suporta as plataformaslinux/amd
elinux/arm
. Para instalar versões específicas do gcloud, use a tag:VERSION-stable
.
Se você quiser usar uma imagem baseada em Alpine, você pode instalar a seguinte imagem:
-
:alpine
,:VERSION-alpine
: Semelhante à versão estável, mas construída sobre a imagem base mais recente , Alpine 3.20 . Esta imagem suporta as plataformaslinux/amd
elinux/arm
. Para instalar versões específicas do gcloud, use a tag:VERSION-alpine
.
Se quiser imagens com componentes ou pacotes adicionais pré-instalados, você pode instalar uma das seguintes opções:
:emulators
,:VERSION-emulators
: Semelhante à versão estável, com a adição de todos os componentes do emulador. A imagem é construída sobre a imagem base mais recente do Debian 12 fornecida pelo Google e usa o gerenciador de componentes para instalar os componentes. Esta imagem suporta as plataformaslinux/amd
elinux/arm
. Para instalar versões específicas do gcloud, use a tag:VERSION-emulators
.:latest
,:VERSION
: Semelhante à versão estável, com componentes adicionais (a lista de componentes instalados na imagem está listada abaixo ) pré-instalados. A imagem é construída sobre a imagem base Debian 12 mais recente fornecida pelo Google e usa pacotes deb para instalar os componentes. Para instalar versões específicas do gcloud, use a tag:VERSION
.:slim
,:VERSION-slim
: Semelhante ao stable, mas inclui pacotes adicionais de terceiros, comocurl
,python3-crcmod
,apt-transport-https
,lsb-release
,openssh-client
,git
,make
egnupg
. Esta imagem foi criada com base na imagem base Debian 12 mais recente fornecida pelo Google . Esta imagem suporta as plataformaslinux/amd
elinux/arm
. Para instalar versões específicas do gcloud, use a tag:VERSION-slim
.:debian_component_based
,:VERSION-debian_component_based
: Semelhante à versão estável, com componentes adicionais (a lista de componentes instalados na imagem está listada abaixo ) pré-instalados. A imagem é construída sobre a imagem base Debian 12 mais recente fornecida pelo Google e usa o gerenciador de componentes para instalar os componentes. Esta imagem suporta plataformaslinux/amd
elinux/arm
. Para instalar versões específicas do gcloud, use a tag:VERSION-debian_component_based
.
Use uma versão específica em 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 possíveis alterações significativas:
- Atualizações de versão do Google Cloud SDK, que podem alterar o comportamento da ferramenta.
- Atualizações na lista de componentes instalados.
Para evitar possíveis alterações drásticas, é recomendável que seu ambiente de produção use um dos seguintes:
- Uma tag versionada, como
:496.0.0-stable
- Um hash de imagem específico, como:
gcr.io/google.com/cloudsdktool/google-cloud-cli@sha256:9c0efc06918d5405b13bfe4bb5ce1d98ea4695cc703446e9e0aa0ee8800622df
- Hospede a imagem em seu próprio repositório
Você também deve atualizar as imagens periodicamente para obter a versão mais recente do gcloud.
Verifique a versão mais recente do Google Cloud CLI e todas as versões anteriores do Google Cloud CLI .
Componentes instalados em cada tag
Componente | :estável | :alpino | :emuladores | :mais recente | :magro | :debian_component_based |
---|---|---|---|---|---|---|
Extensões do App Engine Go | x | x | ||||
Appctl | x | |||||
Ferramenta de linha de comando do BigQuery | x | x | x | x | x | x |
Python empacotado | x | x | x | x | x | x |
Ferramenta de linha de comando Bigtable | x | x | ||||
Emulador Bigtable | x | x | x | |||
Emulador de armazenamento de dados em nuvem | x | x | x | |||
Emulador Cloud Firestore | x | x | ||||
Emulador Cloud Pub/Sub | x | x | x | |||
Emulador de chave inglesa | x | x | ||||
Ferramenta de linha de comando de armazenamento em nuvem | x | x | x | x | x | x |
Bibliotecas principais do Google Cloud CLI | x | x | x | x | x | x |
Google Cloud Ferramenta de Hash CRC32C | x | x | x | x | x | x |
Personalizar | x | |||||
Minikubo | x | |||||
Nomos CLI | x | |||||
Auxiliar de extração de API de varredura sob demanda | x | x | ||||
Andaime | x | |||||
anthos-auth | x | |||||
Comandos Alpha do gcloud | x | x | x | x | ||
Comandos Beta do gcloud | x | x | x | x | ||
Extensões Java do aplicativo gcloud | x | |||||
Extensões Python do aplicativo gcloud | x | |||||
Extensões Python do aplicativo gcloud (bibliotecas extras) | x | x | ||||
plugin gke-gcloud-auth | x | x | ||||
kpt | x | x | ||||
kubectl | x | x |
Instalando 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 nos repositórios us.gcr.io
, eu.gcr.io
e asia.gcr.io
Para usar a imagem da versão estável do 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
Você também pode 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
Verifique a instalação executando:
docker run --rm gcr.io/google.com/cloudsdktool/google-cloud-cli:489.0.0-stable gcloud version
Se você usou a tag flutuante
:stable
(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
Autenticação com a imagem do Docker do Google Cloud CLI
Autentique com a imagem do Docker do Google Cloud CLI executando um dos seguintes comandos:
Autentique o 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 o Google Cloud APIs, passe 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'
Após a autenticação bem-sucedida, as credenciais são preservadas no volume do
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 quiser autenticar 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 ambienteCLOUDSDK_CONFIG
.No exemplo a seguir, a configuração
mycloud
já possui aauth/credential_file_override
definida. 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 obter mais informações sobre como definir variáveis de ambiente, consulte o seguinte:
Instalando componentes adicionais
Você pode instalar componentes adicionais na imagem do Docker da Google Cloud CLI. A abordagem para instalar componentes adicionais varia dependendo do tipo de imagem base subjacente.
Imagens baseadas em 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 componentes adicionais para a imagem estável, siga um destes procedimentos:
- Crie sua própria imagem usando o Dockerfile de imagem
:stable
: instale pacotes que não estão diretamente disponíveis através doapt-get
, ou seja, docker engine. - Instalando pacotes ou componentes adicionais em tempo de execução : personalize sua imagem sem hospedá-la.
Construindo sua própria imagem usando o Dockerfile de imagem :stable
Para criar sua própria imagem com componentes adicionais de :stable
, você pode clonar o diretório cloud-sdk-docker do GitHub e usar o comando docker build
para criar a imagem do Docker :stable
a partir 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 .
Instalando pacotes ou componentes adicionais em tempo de execução
Se você tiver obtido a imagem stable
do Docker, poderá instalar os seguintes 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
em tempo de execução, você pode executar 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 curl
e gcc
enquanto executa a imagem do Docker, 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 Alpes
Para instalar componentes adicionais para imagens baseadas em Alpine, crie um Dockerfile que use a imagem cloud-sdk
como imagem base.
Por exemplo, para adicionar componentes kubectl
e app-engine-java
:
- 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
- Crie a imagem executando o seguinte comando:
docker build -t my-cloud-sdk-docker:alpine .
Para imagens baseadas em Alpine, você deve instalar dependências de componentes adicionais manualmente.
Migrando para a imagem :stable
Se você estiver usando as imagens Docker :latest
, :slim
, :emulators
, :alpine
e :debian_component_based
, recomendamos migrar para a imagem :stable
baseada em Debian para obter um tamanho de imagem menor e correções de segurança aprimoradas. Para ver as etapas de migração para a imagem :stable
, consulte Migrando para a imagem :stable
.
Obtendo suporte para imagens
As imagens hospedadas no Artifact Registry fornecem instalações totalmente funcionais do Google Cloud CLI. Se você encontrar bugs ou problemas relacionados às imagens do Docker, pode criar um tíquete de suporte .
Quando precisar de uma imagem com componentes, pacotes ou ferramentas adicionais, você pode criar sua própria camada de imagem sobre a imagem do Docker do Google Cloud CLI.
Solução de problemas
O que você deve fazer se vir um erro failed to fetch <image-tag>
ao extrair a imagem do Docker?
Se você receber o erro failed to fetch <image-tag>
ao tentar extrair uma imagem do Docker da Google Cloud CLI, provavelmente está tentando buscar uma tag de imagem que foi descontinuada e removida. Verifique as Opções de Imagem do Docker para ver 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 você não pode estender diretamente a imagem Docker :stable
para dar suporte ao seu fluxo de trabalho atual?
A tabela a seguir lista os casos de uso em que você não pode estender diretamente a imagem do docker :stable
para se ajustar ao seu fluxo de trabalho e lista as opções para corrigir:
Casos de uso | Opções de remediação |
---|---|
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 você deve fazer se o seu scanner encontrar vulnerabilidades nas imagens do Docker?
As imagens do Docker da Google Cloud CLI são hospedadas no Artifact Registry . As imagens são verificadas diariamente e vulnerabilidades e exposições comuns (CVEs) são mitigadas antes de cada novo lançamento do gcloud. No entanto, se o seu scanner detectar vulnerabilidades nas imagens do Docker da Google Cloud CLI que não foram resolvidas, você pode registrar um bug que inclua as seguintes informações:
- O tipo de vulnerabilidade.
- A localização exata na imagem.
Vulnerabilidades em imagens do sistema operacional base são abordadas apenas para garantir que as imagens do Docker do Google Cloud CLI estejam usando versões recentes e estáveis do Debian ou Alpine Linux.
Por que há imagens sem tags no repositório do Artifact Registry ?
As imagens do Docker do Google Cloud CLI 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 compilação multiarquitetura, que combina imagens específicas da arquitetura em um único manifesto . O manifesto também inclui imagens de atestado específicas da plataforma. O processo de compilação multiarquitetura apenas adiciona a tag à imagem do manifesto final, mas não marca as imagens específicas da arquitetura ou as imagens de atestado individuais. Como resultado, você pode ver imagens sem tags no repositório do Artifact Registry . Essas imagens não são destinadas ao uso e você pode ignorá-las com segurança.