Linha de comando gcloud em um tutorial de serviço do Cloud Run

---

Neste tutorial, você cria um inventário dos serviços do Cloud Run usando as ferramentas de linha de comando gcloud e gsutil dentro de um serviço do Cloud Run. Você pode aplicar o que aprendeu neste tutorial nos scripts de operações do Cloud ou criar uma prova de conceito antes de usar bibliotecas de cliente para criar um serviço mais robusto.

Use as ferramentas gcloud e gsutil como qualquer script de shell dentro de um serviço da Web. Por exemplo, como mostrado no guia de início rápido do Shell. No Cloud Run, as duas ferramentas trabalham com os serviços do Google Cloud fazendo a autenticação automática com a identidade do serviço do Cloud Run. Todas as permissões concedidas à identidade do serviço estão disponíveis para a CLI gcloud.

A CLI gcloud tem capacidades muito abrangentes de coleta de informações e gerenciamento de recursos no Google Cloud. Portanto, usá-la em um serviço da Web minimiza o risco de um autor de chamada fazer mau uso dessas capacidades. Sem controles de segurança, é possível haver riscos para outros serviços ou recursos em execução no mesmo projeto, possibilitando atividades prejudiciais acidentais ou intencionais. Veja alguns exemplos desses riscos:

• Ativar a descoberta de endereços IP de máquinas virtuais particulares
• Ativar acesso a dados particulares de um banco de dados no mesmo projeto
• Ativar a exclusão de outros serviços em execução

Várias etapas neste tutorial mostram como impor controles para minimizar riscos, como, por exemplo, especificar o comando gcloud a ser executado no código, em vez de deixá-lo aberto como uma entrada do usuário.

O processo de script com a ferramenta de linha de comando em um serviço do Cloud Run é semelhante ao uso local. A principal diferença são as restrições extras que precisam ser adicionadas em torno da lógica principal do script.

Objetivos

• Gravar e criar um contêiner personalizado com um Dockerfile (links em inglês)
• Gravar, criar e implantar um serviço do Cloud Run
• Usar as ferramentas gcloud e gsutil com segurança em um serviço da Web
• Gerar um relatório dos serviços do Cloud Run e salvá-lo no Cloud Storage

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Antes de começar

1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.

2. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

3. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

4. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   Acessar o seletor de projetos

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Ative as APIs Artifact Registry, Cloud Build, Cloud Run, and Cloud Storage.

   Ative as APIs

7. Instale e inicialize a CLI gcloud.

Funções exigidas

Para conseguir as permissões necessárias para concluir o tutorial, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

• Editor do Cloud Build (roles/cloudbuild.builds.editor)
• Administrador do Cloud Run (roles/run.admin)
• Criar contas de serviço (roles/iam.serviceAccountCreator)
• Administrador de projetos do IAM (roles/resourcemanager.projectIamAdmin)
• Usuário da conta de serviço (roles/iam.serviceAccountUser)
• Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer)
• Administrador de armazenamento (roles/storage.admin)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Observação: os papéis básicos do IAM também podem conter permissões para concluir o tutorial. Não conceda papéis básicos em um ambiente de produção, mas é possível fazer isso em um ambiente de desenvolvimento ou teste.

Configurar os padrões da gcloud

Para configurar a gcloud com os padrões do serviço do Cloud Run, realize as etapas a seguir:

1. Defina seu projeto padrão:

   gcloud config set project PROJECT_ID

   Substitua PROJECT_ID pelo nome do projeto que você criou para este tutorial.

2. Configure a gcloud para a região escolhida:

   gcloud config set run/region REGION

   Substitua REGION pela região compatível do Cloud Run.

Locais do Cloud Run

O Cloud Run é regional, o que significa que a infraestrutura que executa seus serviços do Cloud Run está localizada em uma região específica e é gerenciada pelo Google para estar disponível de maneira redundante em todas as zonas da região.

Atender aos seus requisitos de latência, disponibilidade ou durabilidade são os principais fatores para selecionar a região em que seus serviços do Cloud Run são executados. Geralmente, é possível selecionar a região mais próxima de seus usuários, mas considere a localização dos outros produtos do Google Cloud usados pelo serviço do Cloud Run. O uso de produtos do Google Cloud em vários locais pode afetar a latência e o custo do serviço.

O Cloud Run está disponível nas regiões a seguir:

Sujeitas aos preços do nível 1

• asia-east1 (Taiwan)
• asia-northeast1 (Tóquio)
• asia-northeast2 (Osaka)
• europe-north1 (Finlândia) Baixo CO₂
• europe-southwest1 (Madrid)
• europe-west1 (Bélgica) Baixo CO_₂
• europe-west4 (Países Baixos)
• europe-west8 (Milão)
• europe-west9 (Paris) Baixo CO₂
• me-west1 (Tel Aviv)
• us-central1 (Iowa) Baixo CO₂
• us-east1 (Carolina do Sul)
• us-east4 (Norte da Virgínia)
• us-east5 (Columbus)
• us-south1 (Dallas)
• us-west1 (Oregon) Baixo CO₂

Sujeitas aos preços do nível 2

• africa-south1 (Johannesburgo)
• asia-east2 (Hong Kong)
• asia-northeast3 (Seul, Coreia do Sul)
• asia-southeast1 (Singapura)
• asia-southeast2 (Jacarta)
• asia-south1 (Mumbai, Índia)
• asia-south2 (Déli, Índia)
• australia-southeast1 (Sydney)
• australia-southeast2 (Melbourne)
• europe-central2 (Varsóvia, Polônia)
• europe-west10 (Berlim)
• europe-west12 (Turim)
• europe-west2 (Londres, Reino Unido) Baixo CO₂
• europe-west3 (Frankfurt, Alemanha) Baixo CO₂
• europe-west6 (Zurique, Suíça) Baixo CO₂
• me-central1 (Doha)
• me-central2 (Damã)
• northamerica-northeast1 (Montreal) Baixo CO₂
• northamerica-northeast2 (Toronto) Baixo CO₂
• southamerica-east1 (São Paulo, Brasil) Baixo CO₂
• southamerica-west1 (Santiago, Chile) Baixo CO₂
• us-west2 (Los Angeles)
• us-west3 (Salt Lake City)
• us-west4 (Las Vegas)

Se você já criou um serviço do Cloud Run, é possível visualizar a região no painel do Cloud Run no console do Google Cloud.

OK

Como recuperar o exemplo de código

Para recuperar o exemplo de código para uso, siga estas etapas:

1. Clone o repositório do aplicativo de amostra na máquina local:

   git clone https://github.com/GoogleCloudPlatform/cloud-run-samples.git

   Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.

2. Mude para o diretório que contém o código de amostra do Cloud Run:

   cd cloud-run-samples/gcloud-report/

Revisar o código

Esta seção inclui informações sobre o exemplo de código que você recuperou.

Gerar um relatório e fazer upload dele no Cloud Storage

Esse script de shell gera um relatório dos serviços do Cloud Run no projeto e na região atuais e faz upload do resultado para o Cloud Storage. Ele lista os serviços cujo nome contém o argumento search de string fornecido.

O script usa o comando gcloud run services list, opções de formato avançado da gcloud e o modo de cópia da transferência por streaming da gsutil.

set -eo pipefail

# Check for required environment variables.
requireEnv() {
  test "${!1}" || (echo "gcloud-report: '$1' not found" >&2 && exit 1)
}
requireEnv GCLOUD_REPORT_BUCKET

# Prepare formatting: Default search term to include all services.
search=${1:-'.'}
limits='spec.template.spec.containers.resources.limits.flatten("", "", " ")'
format='table[box, title="Cloud Run Services"](name,status.url,metadata.annotations.[serving.knative.dev/creator],'${limits}')'

# Create a specific object name that will not be overridden in the future.
obj="gs://${GCLOUD_REPORT_BUCKET}/report-${search}-$(date +%s).txt"

# Write a report containing the service name, service URL, service account or user that
# deployed it, and any explicitly configured service "limits" such as CPU or Memory.
gcloud run services list \
  --format "${format}" \
  --filter "metadata.name~${search}" | gsutil -q cp -J - "${obj}"

# /dev/stderr is sent to Cloud Logging.
echo "gcloud-report: wrote to ${obj}" >&2
echo "Wrote report to ${obj}"

Esse script é seguro para ser executado como um serviço, porque invocações repetidas dele atualizam o relatório sem que haja mais desligamentos de usuários. Outros scripts que usam a CLI gcloud podem ser mais caros quando invocados repetidamente, como criar novos recursos do Cloud ou realizar tarefas caras. Scripts idempotentes, que geram o mesmo resultado em invocações repetidas, são mais seguros para executar como um serviço.

Invocar o script na solicitação HTTP

Este código em Go configura um serviço da Web que executa um script de shell para gerar um relatório. Como a consulta de pesquisa é uma entrada do usuário, o código a valida para garantir que ela contenha apenas letras, números ou hífens para impedir comandos maliciosos como entrada. Esse conjunto de caracteres é restrito o suficiente para evitar ataques de injeção de comandos.

O serviço da Web passa o parâmetro de pesquisa como um argumento para o script de shell.

// Service gcloud-report is a Cloud Run shell-script-as-a-service.
package main

import (
	"log"
	"net/http"
	"os"
	"os/exec"
	"regexp"
)

func main() {
	http.HandleFunc("/", scriptHandler)

	// Determine port for HTTP service.
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
		log.Printf("defaulting to port %s", port)
	}

	// Start HTTP server.
	log.Printf("listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

func scriptHandler(w http.ResponseWriter, r *http.Request) {
	search := r.URL.Query().Get("search")
	re := regexp.MustCompile(`^[a-z]+[a-z0-9\-]*$`)
	if !re.MatchString(search) {
		log.Printf("invalid search criteria %q, using default", search)
		search = "."
	}

	cmd := exec.CommandContext(r.Context(), "/bin/bash", "script.sh", search)
	cmd.Stderr = os.Stderr
	out, err := cmd.Output()
	if err != nil {
		log.Printf("Command.Output: %v", err)
		http.Error(w, http.StatusText(http.StatusInternalServerError), http.StatusInternalServerError)
		return
	}
	w.Write(out)
}

Observação: para saber como invocar um comando em outras linguagens, consulte o tutorial de pacotes do sistema. O código mostrado neste tutorial é implementado em Go para proporcionar um desempenho rápido e inicializações curtas: a lógica de negócios está no script de shell.

Um arquivo go.mod declara as dependências do aplicativo em um módulo go:

module github.com/GoogleCloudPlatform/cloud-run-samples/gcloud-report

go 1.19

Definir o ambiente do contêiner

O Dockerfile define como o ambiente é agrupado para o serviço. Ele é semelhante ao Dockerfile do guia de início rápido "helloworld-shell", exceto que a imagem do contêiner final é baseada na imagem da CLI do Google Cloud gcloud. Isso permite que nosso serviço use gcloud e gsutil sem etapas personalizadas de instalação e configuração para a CLI do Google Cloud.

# Use the official golang image to create a binary.
# This is based on Debian and sets the GOPATH to /go.
# https://hub.docker.com/_/golang
FROM golang:1.20-buster as builder

# Create and change to the app directory.
WORKDIR /app

# Retrieve application dependencies.
# This allows the container build to reuse cached dependencies.
# Expecting to copy go.mod and if present go.sum.
COPY go.* ./
RUN go mod download

# Copy local code to the container image.
COPY invoke.go ./

# Build the binary.
RUN go build -mod=readonly -v -o server

# Use a gcloud image based on debian:buster-slim for a lean production container.
# https://docs.docker.com/develop/develop-images/multistage-build/#use-multi-stage-builds
FROM gcr.io/google.com/cloudsdktool/cloud-sdk:slim

WORKDIR /app

# Copy the binary to the production image from the builder stage.
COPY --from=builder /app/server /app/server
COPY *.sh /app/
RUN chmod +x /app/*.sh

# Run the web service on container startup.
CMD ["/app/server"]

Criar um repositório padrão do Artifact Registry

Crie um repositório padrão do Artifact Registry para armazenar a imagem do contêiner:

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=REGION

Substitua:

• REPOSITORY por um nome exclusivo para o repositório.
• REGION pela região do Google Cloud do Artifact Registry.

Configurar o bucket do Cloud Storage

Crie um bucket do Cloud Storage para fazer upload de relatórios:

gsutil mb gs://REPORT_ARCHIVE_BUCKET

Substitua REPORT_ARCHIVE_BUCKET por um nome de bucket globalmente exclusivo.

Configurar a identidade do serviço

Para limitar os privilégios que o serviço tem a outra infraestrutura, crie uma identidade de serviço e personalize as permissões específicas do IAM necessárias para fazer o trabalho.

Nesse caso, os privilégios necessários são permissão para ler serviços do Cloud Run e permissão para ler e gravar no bucket do Cloud Storage.

1. Crie uma conta de serviço:

   gcloud iam service-accounts create gcloud-report-identity

2. Conceder permissão à conta de serviço para ler os serviços do Cloud Run:

   gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com \
     --role roles/run.viewer

3. Conceder permissão à conta de serviço para ler e gravar no bucket do Cloud Storage:

   gsutil iam ch \
     serviceAccount:gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com:objectViewer,objectCreator \
     gs://REPORT_ARCHIVE_BUCKET

O acesso limitado dessa identidade de serviço personalizada impede que o serviço acesse outros recursos do Google Cloud.

Enviar o serviço

O código de envio é composto de três etapas:

• Criar uma imagem de contêiner com o Cloud Build
• Enviar a imagem do contêiner para o Artifact Registry
• Implantar a imagem de contêiner no Cloud Run.

Para enviar o código, siga estas etapas:

1. Compile seu contêiner e publique no Artifact Registry:

   gcloud builds submit --tag REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report

   Substitua:

   • PROJECT_ID pelo ID do projeto do Google Cloud
   • REPOSITORY pelo nome do repositório do Artifact Registry.
   • REGION pela região do Google Cloud do Artifact Registry.

   gcloud-report é o nome do serviço.

   Após a conclusão, uma mensagem de sucesso exibe o ID, a hora da criação e o nome da imagem. A imagem é armazenada no Artifact Registry e poderá ser reutilizada se necessário.

2. Execute o comando a seguir para implantar o serviço:

   gcloud run deploy gcloud-report \
      --image REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/gcloud-report \
      --update-env-vars GCLOUD_REPORT_BUCKET=REPORT_ARCHIVE_BUCKET \
      --service-account gcloud-report-identity \
      --no-allow-unauthenticated

   Substitua:

   • PROJECT_ID pelo ID de projeto do Google Cloud;
   • REPOSITORY pelo nome do repositório do Artifact Registry.
   • REGION pela região do Google Cloud do serviço.

   gcloud-report faz parte do nome do contêiner e do serviço. A imagem de contêiner é implantada no serviço e na região (Cloud Run) que você configurou anteriormente em Como configurar a gcloud.

   A sinalização --no-allow-unauthenticated restringe o acesso não autenticado ao serviço. Mantendo o serviço particular, a autenticação integrada do Cloud Run bloqueia solicitações não autorizadas. Para mais detalhes sobre autenticação baseada no Identity and Access Management (IAM), consulte Como gerenciar o acesso usando o IAM.

   Aguarde a conclusão da implantação. Isso pode levar cerca de meio minuto. Em caso de sucesso, a linha de comando exibe o URL de serviço.

3. Se você quer implantar uma atualização de código no serviço, repita as etapas anteriores. Cada implantação em um serviço cria uma nova revisão e inicia automaticamente o tráfego de serviço quando estiver pronto.

Consulte Como gerenciar o acesso usando o IAM para saber como conceder acesso aos usuários do Google Cloud para invocar esse serviço. Os editores e proprietários do projeto têm esse acesso automaticamente.

Gerar um relatório

Para gerar um relatório dos serviços do Cloud Run:

1. Use curl para enviar uma solicitação autenticada:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL

   Substitua SERVICE_URL pelo URL fornecido pelo Cloud Run após concluir a implantação.

   Se você criou um novo projeto e seguiu este tutorial, a saída será semelhante a:

   Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-.-DATE.txt

   O . no nome do arquivo é o argumento de pesquisa padrão, conforme mencionado no código-fonte.

   Para usar o recurso de pesquisa, adicione um argumento search à solicitação:

   curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" SERVICE_URL?search=gcloud

   Esta consulta retornará uma resposta como esta:

   Wrote report to gs://REPORT_ARCHIVE_BUCKET/report-gcloud-DATE.txt

2. Recuperar o arquivo usando a ferramenta gsutil localmente:

   gsutil cp gs://REPORT_FILE_NAME .

   O . no comando significa o diretório de trabalho atual.

   Substitua REPORT_FILE_NAME pela saída do nome do objeto do Cloud Storage na etapa anterior.

Abra o arquivo para ver o relatório. Você verá o seguinte:

As quatro colunas são extraídas da descrição do serviço. Elas incluem o Nome do serviço, o URL atribuído na primeira implantação, o Criador inicial do serviço e os Limites de CPU e memória máximas do serviço.

Melhorar a robustez para o futuro

Se você pretende desenvolver mais esse serviço, considere reescrever em uma linguagem de programação mais robusta, usando a API Cloud Run e a biblioteca de cliente do Cloud Storage.

É possível examinar as chamadas de API que estão sendo feitas (e ver alguns detalhes da autenticação) adicionando --log-http aos comandos da gcloud e -D aos comandos da gsutil.

Automatizar esta operação

Agora que o relatório de serviços do Cloud Run pode ser acionado por uma solicitação HTTP, use automação para gerar relatórios quando você precisar deles:

• Execute este serviço em uma programação com o Cloud Scheduler
• Crie o relatório como uma tarefa na fila ou programação no futuro com o Google Tarefas.

Limpar

Se você criou um novo projeto para este tutorial, exclua o projeto. Se você usou um projeto atual e quer mantê-lo sem as alterações incluídas neste tutorial, exclua os recursos criados para o tutorial.

Como excluir o projeto

O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.

Para excluir o projeto:

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

1. No Console do Google Cloud, acesse a página Gerenciar recursos.

   Acessar "Gerenciar recursos"

2. Na lista de projetos, selecione o projeto que você quer excluir e clique em Excluir .
3. Na caixa de diálogo, digite o ID do projeto e clique em Encerrar para excluí-lo.

Como excluir recursos do tutorial

1. Exclua o serviço do Cloud Run que você implantou neste tutorial:

   gcloud run services delete SERVICE-NAME

   SERVICE-NAME é o nome escolhido do serviço.

   Também é possível excluir os serviços do Cloud Run no Console do Google Cloud.

2. Remova a configuração da região padrão da gcloud que você adicionou durante a configuração do tutorial:

    gcloud config unset run/region
   

3. Remova a configuração do projeto:

    gcloud config unset project
   

4. Exclua outros recursos do Google Cloud criados neste tutorial:

   • Exclua o bucket do Cloud Storage REPORT_ARCHIVE_BUCKET
   • Exclua a imagem do contêiner.
   • Exclua a conta de serviço do invocador gcloud-report-identity@PROJECT_ID.iam.gserviceaccount.com.

A seguir

• Reduza as dependências do serviço substituindo as ferramentas gcloud e gsutil por chamadas de API: Como fazer upload de objetos e referência da API Cloud Run
• Aumente ainda mais a segurança usando controles de entrada de rede para limitar o acesso ao serviço.
• Confira arquiteturas de referência, diagramas e práticas recomendadas do Google Cloud. Confira o Centro de arquitetura do Cloud.