Instalar a imagem do Docker da CLI Google Cloud

A imagem Docker da CLI do Google Cloud permite-lhe obter uma versão específica da CLI do Google Cloud como uma imagem Docker do Artifact Registry e executar rapidamente comandos da CLI do Google Cloud num contentor isolado e configurado corretamente.

A imagem Docker da CLI Google Cloud é a CLI gcloud instalada sobre uma imagem Debian ou Alpine. As imagens do Docker da CLI Google Cloud permitem a utilização do gcloud, bem como dos respetivos componentes incluídos, sem ter de instalar manualmente o gcloud na sua máquina local.

Opções de imagem de Docker

Existem seis imagens Docker da CLI do Google Cloud, e todas instalam as ferramentas de linha de comandos gcloud, gsutil e bq. Recomendamos que instale a imagem :stable para um ambiente mínimo. Também pode usar a imagem estável como imagem base para as suas próprias implementações, o que lhe dá a flexibilidade de instalar apenas os componentes e os pacotes de que precisa na sua imagem:

• :stable, :VERSION-stable: fornece uma instalação do gcloud com os componentes gsutil e bq. A imagem é criada com base na imagem base do Debian 12 mais recente fornecida pela Google. Esta imagem é compatível com as plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a etiqueta :VERSION-stable.

Se quiser usar uma imagem baseada no Alpine, pode instalar a seguinte imagem:

• :alpine, :VERSION-alpine: semelhante à versão estável, mas criada com base na imagem base mais recente do Alpine 3.20. Esta imagem é compatível com as plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a etiqueta :VERSION-alpine.

Se quiser imagens com componentes ou pacotes adicionais pré-instalados, 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 é criada com base na imagem de base do Debian 12 mais recente fornecida pela Google e usa o gestor de componentes para instalar os componentes. Esta imagem é compatível com as plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a etiqueta :VERSION-emulators.

• :latest, :VERSION: semelhante à versão estável, com componentes adicionais (a lista de componentes instalados na imagem é apresentada abaixo) pré-instalados. A imagem é criada com base na imagem de base do Debian 12 mais recente fornecida pela Google e usa pacotes DEB para instalar os componentes. Esta imagem é compatível com as plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a etiqueta :VERSION.

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

• :debian_component_based, :VERSION-debian_component_based: semelhante à versão estável, com componentes adicionais (a lista de componentes instalados na imagem é apresentada abaixo). A imagem é criada com base na imagem base do Debian 12 mais recente fornecida pela Google e usa o gestor de componentes para instalar os componentes. Esta imagem é compatível com as plataformas linux/amd e linux/arm. Para instalar versões específicas do gcloud, use a etiqueta :VERSION-debian_component_based.

Use uma versão específica em produção

Se usar uma etiqueta que não esteja associada a uma versão específica do gcloud, o seu ambiente pode sofrer as seguintes possíveis alterações significativas:

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

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

• Uma etiqueta 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
• Aloje a imagem no seu próprio repositório

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

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

Componentes instalados em cada etiqueta

Instalar uma imagem do Docker

A imagem de Docker está alojada no Artifact Registry com o seguinte nome do repositório: gcr.io/google.com/cloudsdktool/google-cloud-cli. As imagens também estão disponíveis através dos 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
   

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

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

2. Valide a instalação executando o seguinte comando:

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

   Se usou a etiqueta :stable flutuante (que aponta sempre para a versão mais recente), valide 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 da CLI do Google Cloud

Autentique-se com a imagem do Docker da CLI do Google Cloud executando um dos seguintes comandos:

• Autentique o gcloud com as suas credenciais de utilizador executando o seguinte comando: gcloud auth login

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

• Se precisar de autenticar aplicações que usam as Trusted Cloud by S3NS APIs, 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 predefinido que é selecionado sempre que abre o contentor, 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 se autenticar com êxito, as credenciais são preservadas no volume do gcloud-config container.

  Para validar, liste a instância de computação com as credenciais executando o contentor 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 fazer a autenticação através de 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 através da variável de ambiente CLOUDSDK_CONFIG.

  No exemplo seguinte, a configuração mycloud já tem o auth/credential_file_override definido. A configuração aponta para um ficheiro de certificado presente no contentor 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 a definição de variáveis de ambiente, consulte o seguinte:

  • Definir propriedades através de variáveis de ambiente
  • gcloud config

A instalar componentes adicionais

Pode instalar componentes adicionais na imagem Docker da CLI Google Cloud. A abordagem para instalar componentes adicionais varia consoante o tipo de imagem base subjacente.

Imagens baseadas em Debian

Por predefiniçã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, faça uma das seguintes ações:

• Criar a sua própria imagem com o :stable Dockerfile da imagem: Instalar pacotes que não estão diretamente disponíveis através do apt-get, ou seja, o motor do Docker.
• Instalar pacotes ou componentes adicionais no tempo de execução: Personalize a sua imagem sem a alojar.

Criar a sua própria imagem com o Dockerfile de imagem :stable

Para criar a sua própria imagem com um componente adicional de :stable, pode clonar o diretório do GitHub cloud-sdk-docker 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 .

Instalar pacotes ou componentes adicionais no tempo de execução

Se tiver extraído a imagem do stable Docker, pode instalar os seguintes componentes adicionais durante a execução:

• gcloud components através da variável de ambiente COMPONENTS.
• apt-packages usando a variável de ambiente APT_PACKAGES.

Por exemplo, se quiser instalar os componentes cbt e kpt no tempo de execução, 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 apt-packages 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 no Alpine

Para instalar componentes adicionais para imagens baseadas no Alpine, crie um Dockerfile que use a imagem cloud-sdk como imagem base.

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

1. Crie o ficheiro Dockerfile da seguinte forma:

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, tem de instalar manualmente as dependências de componentes adicionais.

Migrar para a imagem :stable

Se estiver a usar as imagens do Docker :latest, :slim, :emulators, :alpine e :debian_component_based, recomendamos que migre para a imagem :stable baseada no Debian para ter um tamanho de imagem mais pequeno e correções de segurança melhoradas. Para ver os passos para migrar para a imagem :stable, consulte o artigo Migrar para a imagem :stable.

Receber apoio técnico para imagens

As imagens alojadas no Artifact Registry oferecem instalações totalmente funcionais da CLI gcloud. Se encontrar erros ou problemas relacionados com as imagens do Docker, pode criar um pedido de apoio técnico.

Quando precisa de uma imagem com componentes, pacotes ou ferramentas adicionais, pode criar a sua própria camada de imagem sobre a imagem Docker da CLI Google Cloud.

Resolução de problemas

O que deve fazer se vir um erro failed to fetch <image-tag> ao extrair a imagem do Docker?

Se receber um erro failed to fetch <image-tag> ao tentar obter uma imagem do Docker da CLI Google Cloud, é provável que esteja a tentar obter uma etiqueta de imagem descontinuada e removida. Verifique as opções de imagem de Docker para ver as opções de imagem de Docker disponíveis e migre para uma das etiquetas suportadas.

Quais são os exemplos de utilização em que não pode estender diretamente a imagem do :stable Docker para suportar o seu fluxo de trabalho atual?

A tabela seguinte lista os exemplos de utilização em que não pode estender diretamente a imagem do Docker para se adequar ao seu fluxo de trabalho, bem como as opções de correção::stable

O que deve fazer se o seu scanner encontrar vulnerabilidades nas imagens do Docker?

As imagens Docker da CLI do Google Cloud estão alojadas no Artifact Registry. As imagens são analisadas diariamente e as vulnerabilidades e exposições comuns (CVEs) são mitigadas antes de cada novo lançamento do gcloud. No entanto, se o seu scanner tiver detetado vulnerabilidades nas imagens Docker da CLI Google Cloud que não foram resolvidas, pode apresentar um erro que inclua as seguintes informações:

• O tipo de vulnerabilidade.
• A localização exata na imagem.

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

Por que existem imagens sem etiqueta no repositório do Artifact Registry?

As imagens Docker da CLI do Google Cloud com as etiquetas :stable, :alpine, :emulators e :debian_component_based suportam as plataformas arm64 e amd64. As imagens são criadas com um processo de criação multi-arquitetura, que combina imagens específicas da arquitetura num único manifesto. O manifesto também inclui imagens de atestação específicas da plataforma. O processo de compilação de várias arquiteturas apenas adiciona a etiqueta à imagem do manifesto final, mas não etiqueta as imagens específicas da arquitetura individual nem as imagens de atestação. Como resultado, pode ver imagens sem etiquetas no repositório do Artifact Registry. Estas imagens não se destinam a utilização e pode ignorá-las em segurança.

Onde posso obter as informações sobre os pacotes de terceiros removidos das imagens do Docker do gcloud?

As informações sobre todos os pacotes de terceiros removidos estão disponíveis através dos anúncios no GitHub.