GCP - gcloud CLI

gcloud é a CLI oficial do GCP, parte do Cloud SDK. Permite interagir com praticamente todos os serviços da GCP direto do terminal: criar recursos, gerenciar projetos, autenticar, submeter jobs e muito mais.

O Cloud SDK inclui também o gsutil (operações no Cloud Storage) e o bq (operações no BigQuery), embora ambos estejam sendo gradualmente unificados no próprio gcloud.

Instalação

# Linux / macOS (via script)
curl https://sdk.cloud.google.com | bash
exec -l $SHELL
 
# macOS (via Homebrew)
brew install --cask google-cloud-sdk
 
# Verificar versão instalada
gcloud version

No Windows, o instalador está disponível em cloud.google.com/sdk.

Autenticação

# Login com conta pessoal (abre o navegador)
gcloud auth login
 
# Credenciais para bibliotecas e SDKs (Application Default Credentials)
gcloud auth application-default login
 
# Autenticar via Service Account (CI/CD, automações)
gcloud auth activate-service-account \
  --key-file=/path/to/service-account.json
 
# Ver conta ativa
gcloud auth list

A diferença entre os dois primeiros:

auth login autentica o CLI para comandos gcloud
auth application-default login configura as credenciais que as bibliotecas Python/Java/Go usam automaticamente via GOOGLE_APPLICATION_CREDENTIALS

Configurações (configs)

O gcloud usa configurações para salvar projeto, região e zona padrão. Útil para alternar entre ambientes:

# Ver configuração ativa
gcloud config list
 
# Definir projeto padrão
gcloud config set project meu-projeto-id
 
# Definir região e zona padrão
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a
 
# Criar uma configuração nomeada (ex: para ambiente de prod)
gcloud config configurations create prod
gcloud config set project meu-projeto-prod
gcloud config set account [email protected]
 
# Listar todas as configurações
gcloud config configurations list
 
# Ativar uma configuração
gcloud config configurations activate prod

Projetos

# Listar projetos disponíveis
gcloud projects list
 
# Definir projeto ativo
gcloud config set project MEU_PROJECT_ID
 
# Criar projeto
gcloud projects create meu-novo-projeto --name="Meu Projeto"
 
# Descrever um projeto
gcloud projects describe meu-projeto-id

Habilitar APIs

Serviços GCP precisam ter a API habilitada no projeto antes de serem usados:

# Habilitar APIs individualmente
gcloud services enable bigquery.googleapis.com
gcloud services enable storage.googleapis.com
gcloud services enable composer.googleapis.com
gcloud services enable dataflow.googleapis.com
gcloud services enable pubsub.googleapis.com
 
# Listar APIs habilitadas
gcloud services list --enabled
 
# Verificar se uma API específica está habilitada
gcloud services list --enabled --filter="name:bigquery.googleapis.com"

IAM

# Listar bindings de IAM de um projeto
gcloud projects get-iam-policy meu-projeto
 
# Conceder role a um usuário
gcloud projects add-iam-policy-binding meu-projeto \
  --member="user:[email protected]" \
  --role="roles/bigquery.dataViewer"
 
# Conceder role a uma Service Account
gcloud projects add-iam-policy-binding meu-projeto \
  --member="serviceAccount:[email protected]" \
  --role="roles/storage.objectAdmin"
 
# Criar Service Account
gcloud iam service-accounts create minha-sa \
  --display-name="SA do pipeline de dados"
 
# Gerar chave JSON para uma SA (usar apenas em dev/CI)
gcloud iam service-accounts keys create chave.json \
  [email protected]

Compute Engine

# Listar instâncias
gcloud compute instances list
 
# Criar instância
gcloud compute instances create minha-vm \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud
 
# SSH em uma instância
gcloud compute ssh minha-vm --zone=us-central1-a
 
# Copiar arquivo para a instância
gcloud compute scp arquivo.txt minha-vm:~/ --zone=us-central1-a

Cloud Storage (gsutil / gcloud storage)

# gcloud storage é o substituto moderno do gsutil
gcloud storage buckets create gs://meu-bucket --location=us-central1
gcloud storage cp arquivo.csv gs://meu-bucket/raw/
gcloud storage ls gs://meu-bucket/
gcloud storage rm gs://meu-bucket/raw/arquivo.csv

Ver também gcp-cloud-storage para operações mais completas com gsutil.

BigQuery (bq)

# Executar query
bq query --use_legacy_sql=false \
  'SELECT COUNT(*) FROM `meu-projeto.dataset.tabela`'
 
# Listar datasets
bq ls --project_id=meu-projeto
 
# Descrever tabela
bq show meu-projeto:dataset.tabela
 
# Carregar arquivo para tabela
bq load --source_format=PARQUET \
  meu-projeto:dataset.tabela \
  gs://meu-bucket/dados/*.parquet
 
# Exportar tabela para GCS
bq extract \
  --destination_format=PARQUET \
  meu-projeto:dataset.tabela \
  gs://meu-bucket/export/*.parquet

Formatação de saída

O gcloud suporta diferentes formatos de saída, úteis para scripts e automações:

# Saída em JSON
gcloud projects list --format=json
 
# Saída em YAML
gcloud compute instances list --format=yaml
 
# Saída filtrada com apenas campos específicos
gcloud compute instances list \
  --format="table(name, zone, status, machineType)"
 
# Filtrar por propriedade
gcloud compute instances list --filter="status=RUNNING"
gcloud projects list --filter="projectId:prod-*"

Variáveis de ambiente úteis

Variável	Efeito
`GOOGLE_CLOUD_PROJECT`	Projeto padrão para SDKs e bibliotecas
`GOOGLE_APPLICATION_CREDENTIALS`	Caminho para chave JSON de SA
`CLOUDSDK_CORE_PROJECT`	Equivale a `gcloud config set project`
`CLOUDSDK_COMPUTE_REGION`	Região padrão para recursos de compute

Dicas gerais

Autocompletion: executar gcloud components install alpha beta e adicionar o script de completion ao .bashrc / .zshrc via gcloud completion.

--dry-run e --verbosity: usar --verbosity=debug para ver as chamadas de API que o gcloud faz por baixo, útil ao depurar integrações com Terraform ou scripts.

gcloud alpha e gcloud beta: comandos em preview disponíveis antes de chegar ao GA. Úteis, mas sujeitos a mudanças.

Ver também: gcp | gcp-cloud-storage | gcp-bigquery | gcp-boas-praticas | terraform-cloud-gcp

Second Brain

Explorer