O guia definitivo do Cloud Run, do zero ao tutorial de demonstração de produção

1. Introdução

Este codelab mostra os princípios básicos para começar a usar o Cloud Run. Você vai aprender a usar outros recursos, incluindo acesso à VPC, Secret Manager e ADK para agentes de IA hospedados no Cloud Run.

O que você vai aprender

Implantar uma imagem do nginx
Implantar do código-fonte
Reverter uma implantação
Visualizar uma implantação
Usar a ferramenta do servidor MCP de conhecimento do desenvolvedor
Usar o Secret Manager com o Cloud Run
Conectar-se a um serviço interno do Cloud Run em uma VPC
Implantar um agente do ADK no Cloud Run

O que é necessário

Um navegador da web, como o Chrome
Tenha um projeto do Google Cloud com o faturamento ativado.

Criar um projeto do Google Cloud

No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias.

Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
Depois de se conectar ao Cloud Shell, verifique sua autenticação:
```
gcloud auth list
```
Confirme se o projeto está configurado:
```
gcloud config get project
```

Se o projeto não estiver definido como esperado, faça o seguinte:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Definir variáveis de ambiente

Este codelab usa a seguinte variável de ambiente.

Primeiro, defina sua região.

export REGION=<YOUR_REGION>

Em seguida, confirme seu PROJECT_ID e REGION.

echo "PROJECT_ID: $PROJECT_ID | REGION: $REGION"

2. Implantar da imagem

Nesta seção, você vai implantar uma imagem padrão do nginx diretamente do Docker Hub. Você vai configurar o acesso público e definir a porta do contêiner como 80.

Implante o serviço nginx:

   gcloud run deploy nginx-service \
     --image=nginx \
     --allow-unauthenticated \
     --port=80 \
     --region=$REGION

Quando a implantação estiver concluída, a resposta ao comando vai fornecer um URL de serviço. Abra esse URL no navegador para ver a página "Welcome to nginx!".

3. Implantar a partir da origem

mkdir color-app && cd $_

Crie um arquivo chamado requirements.txt com o conteúdo a seguir.

Flask>=2.0.0
gunicorn>=20.0.0

Crie um arquivo chamado main.py com o conteúdo a seguir.

import os
from flask import Flask, render_template_string

app = Flask(__name__)

TEMPLATE = """
<!doctype html>
<html lang="en">
<head>
    <title>Cloud Run Traffic Revisions</title>
    <style>
        body {
            display: flex;
            justify-content: center;
            align-items: center;
            min-height: 50vh;
            background-color: darkseagreen;
            font-family: sans-serif;
        }
        .content {
            background-color: rgba(255, 255, 255, 0.8); /* Semi-transparent white background */
            padding: 2em;
            border-radius: 8px;
            text-align: center;
            box-shadow: 0 4px 8px rgba(0,0,0,0.1);
        }
    </style>
</head>
<body>
    <div class="content">
	  <!-- ROLLBACK DEMO: change this text to "gray" -->
        <p>background color: <strong>darkseagreen</strong></p>
    </div>
</body>
</html>
"""

@app.route('/')
def main():
    
    return render_template_string(TEMPLATE)

if __name__ == '__main__':
    port = int(os.environ.get('PORT', 8080))
    app.run(debug=True, host='0.0.0.0', port=port)

Agora, execute o comando a seguir.

gcloud run deploy \
 --allow-unauthenticated
 --region $REGION

4. Rollbacks e links de visualização

Nesta seção, você vai introduzir um bug e aprender a reverter para uma revisão anterior enquanto investiga a correção.

Primeiro, registre o nome da revisão que está veiculando tráfego no momento, já que ela não contém o bug.

GOOD_REVISION=$(gcloud run revisions list --service color-app \
  --region $REGION --format 'value(REVISION)')

No arquivo main.py do app de cores, pesquise "ROLLBACK DEMO" e atualize a linha para o seguinte:

<p>background color: <strong>gray</strong></p>

Agora execute gcloud run deploy novamente. Observe como suas configurações anteriores foram usadas.

Agora que você implantou um bug, pode voltar à origem, fazer uma mudança ou um git revert e depois criar, acionar uma nova build etc. No entanto, é possível que você introduza um erro ao longo do caminho.

Uma maneira mais segura é reverter.

Para reverter para a revisão anterior, execute o seguinte:

gcloud run services update-traffic color-app \
  --to-revisions=$GOOD_REVISION=100 \
  --region=$REGION

Agora você pode implantar uma nova revisão que não vai receber tráfego.

Agora corrija o bug mudando o texto de volta para darkseagreen

<p>background color: <strong>darkseagreen</strong></p>

e implante para verificar a correção. Ela não vai receber tráfego porque 100% dele está fixado na GOOD_REVISION.

gcloud run deploy color-app --no-traffic --tag bugfix --region $REGION

Verificar a implantação

O URL vai ser um pouco diferente. Ao acessar, você vai ver a correção de bug nessa implantação.

Envie o tráfego de volta para a revisão mais recente.

Agora, você vai definir o tráfego de volta para a revisão mais recente.

gcloud run services update-traffic color-app \
  --to-latest \
  --region=$REGION

e exclua a tag de revisão.

gcloud run services update-traffic color-app \
  --remove-tags=bugfix \
  --region=$REGION

Saiba mais sobre reversões na documentação.

5. Servidor MCP de conhecimento do desenvolvedor

O servidor MCP do Developer Knowledge permite que ferramentas de desenvolvimento com tecnologia de IA pesquisem a documentação oficial para desenvolvedores do Google e recuperem informações sobre produtos do Google, como Firebase, Google Cloud, Android, Maps e muito mais. Ao conectar seu aplicativo de IA diretamente à nossa biblioteca oficial de documentação, você garante que o código e as orientações recebidas estejam atualizados e baseados em um contexto confiável.

Siga as orientações de instalação para dar ao seu agente de IA acesso ao servidor MCP do Developer Knowledge.

Depois de instalado, você pode fazer perguntas ao seu agente de IA sobre os recursos mais recentes na documentação que podem ter ficado disponíveis após a data limite de treinamento do modelo.

Por exemplo, se você consultar as notas da versão do Cloud Run, verá em 24 de fevereiro de 2026 uma entrada sobre "Implante um serviço do Cloud Run multirregional de alta disponibilidade com failover e failback automatizados para tráfego externo usando a integridade do serviço do Cloud Run (prévia)".

Agora você pode perguntar ao seu agente de IA: "Conte mais sobre esse novo recurso do Cloud Run para failover automático multirregional".

6. Como usar o Gerenciador de secrets

Há três maneiras de expor secrets no Cloud Run:

Como uma variável de ambiente (bloqueada para a versão extraída no momento da implantação).
Montado como um volume de arquivo (atualizado continuamente para a versão mais recente).
Usando as bibliotecas de cliente do Secret Manager no seu código.

Nesta seção, você vai expor um secret como uma variável de ambiente usando uma conta de serviço dedicada.

Crie um secret chamado "my-secret":

gcloud secrets create my-secret --replication-policy="automatic"

Adicione o valor do secret como uma nova versão:

echo -n "my precious" | gcloud secrets versions add my-secret --data-file=-

Crie uma conta de serviço dedicada para o app de cores:

gcloud iam service-accounts create color-app-sa \
     --display-name="Color App Service Account"

Conceda à conta de serviço dedicada acesso ao secret.

   gcloud secrets add-iam-policy-binding my-secret \
     --member="serviceAccount:color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/secretmanager.secretAccessor"

Implante novamente. Agora o serviço terá acesso à variável de ambiente MY_SECRET:

gcloud run deploy color-app \
     --source . \
     --update-secrets=MY_SECRET=my-secret:latest \
     --service-account=color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --region=$REGION

7. Conectar-se a uma VPC

Nesta seção, você vai configurar a seguinte arquitetura:

backend particular que não pode ser acessado pela Internet pública
um front-end público que se comunica com o back-end usando a saída direta de VPC

Este exemplo usa a rede e a sub-rede padrão.

Pré-requisito:verifique se o Acesso privado do Google está ativado na sua sub-rede para que a VPC possa rotear solicitações internas para os serviços do Cloud Run.

   gcloud compute networks subnets update default \
     --region=$REGION \
     --enable-private-ip-google-access

Criar pasta para esta seção

mkdir ../vpc-demo
cd ../vpc-demo

criar o serviço de back-end particular

mkdir backend
touch backend/app.js
touch backend/package.json

No arquivo backend/app.js, adicione o seguinte:

const http = require('http');

const server = http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World from the Private Backend!');
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Private backend listening on port ${port}`);
});

No arquivo backend/package.json, adicione o seguinte:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

Implante o back-end particular com entrada somente interna:

   gcloud run deploy private-backend \
     --source ./backend \
     --region $REGION \
     --ingress internal \
     --no-allow-unauthenticated

Grave o URL de back-end. Você vai fornecer esse URL ao app de front-end mais tarde.

export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projec
tNumber)')

export BACKEND_URL="https://private-backend-${PROJECT_NUMBER}.${REGION}.run.app"

Criar o app de front-end

mkdir frontend
touch frontend/app.js
touch frontend/package.json

No arquivo frontend/app.js, adicione o seguinte:

const http = require('http');

const server = http.createServer(async (req, res) => {
  const backendUrl = process.env.BACKEND_URL;
  
  if (!backendUrl) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    return res.end('Error: BACKEND_URL environment variable is missing.');
  }

  try {
    // Fetch the OIDC token from the Metadata server
    const tokenResponse = await fetch(`http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=${backendUrl}`, {
      headers: { 'Metadata-Flavor': 'Google' }
    });

    if (!tokenResponse.ok) {
      throw new Error(`Failed to fetch identity token: ${tokenResponse.statusText}`);
    }
    const token = await tokenResponse.text();

    // Ping the backend with the token
    const response = await fetch(backendUrl, {
      headers: { 'Authorization': `Bearer ${token}` }
    });
    const text = await response.text();

    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end(`Frontend successfully routed through VPC. Backend says: "${text}"`);
  } catch (error) {
    res.writeHead(500, { 'Content-Type': 'text/plain' });
    res.end(`Frontend failed to reach the backend. Error: ${error.message}`);
  }
});

const port = process.env.PORT || 8080;
server.listen(port, () => {
  console.log(`Public frontend listening on port ${port}`);
});

No arquivo frontend/package.json, adicione o seguinte:

{
    "name": "backend",
    "scripts": {
        "start": "node app.js"
    }
}

Crie uma conta de serviço dedicada para o serviço de front-end:

  gcloud iam service-accounts create frontend-sa \
     --display-name="Frontend Service Account"

Conceda a ela o papel de invocador do Cloud Run.

PROJECT_ID=$(gcloud config get project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/run.invoker"

Agora implante o front-end público usando a saída direta de VPC. Definimos "–vpc-egress=all-traffic" para forçar a solicitação de saída na VPC:

   gcloud run deploy public-frontend \
     --source ./frontend \
     --region $REGION \
     --allow-unauthenticated \
     --network default \
     --subnet default \
     --vpc-egress all-traffic \
    --service-account=frontend-sa@${PROJECT_ID}.iam.gserviceaccount.com \
     --set-env-vars BACKEND_URL=$BACKEND_URL

Verificar os serviços

Teste o front-end:use curl no URL público do front-end. Ele precisa se comunicar com o back-end e retornar uma resposta.

     FRONTEND_URL=$(gcloud run services describe public-frontend --region $REGION --format='value(status.url)')
     curl $FRONTEND_URL

Teste o back-end (direto): tente usar curl no URL do back-end diretamente da sua máquina local (Internet pública). Ele vai falhar com um erro 404 porque o ingresso é restrito a "interno" e a autenticação é obrigatória.

  curl $BACKEND_URL

8. Implantar um agente do ADK

Nesta seção, você vai aprender como o buildpack do Python oferece suporte à detecção de ponto de entrada padrão para o Kit de Desenvolvimento de Agente (ADK).

Você vai criar a seguinte estrutura de pastas:

adk-demo
 - my_agent
   - __init.py__
   - agent.py
 - requirements.txt

Criar a estrutura de pastas

mkdir ../adk-demo
cd ../adk-demo
mkdir my_agent
touch my_agent/__init.py__
touch my_agent/agent.py
touch requirements.txt

Adicione o seguinte conteúdo ao arquivo my_agent/__init.py__:

from . import agent

Adicione o seguinte conteúdo ao arquivo my_agent/agent.py:

from google.adk import Agent

root_agent = Agent(
    name="demo_agent",
    model="gemini-3-flash-preview",
    instruction="You are a helpful assistant for a Cloud Run demo."
)

Adicione o seguinte conteúdo ao arquivo requirements.txt:

google-adk

Crie uma conta de serviço dedicada para o agente:

  gcloud iam service-accounts create agent-sa \
     --display-name="Agent Service Account"

Conceda à conta de serviço o papel de usuário da Vertex AI:

PROJECT_ID=$(gcloud config get-value project)
  
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:agent-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
     --role="roles/aiplatform.user"

Implantar o agente do ADK

Você precisa fazer a implantação em uma região onde a API Gemini esteja acessível. Neste exemplo, é us-west1.

gcloud run deploy my-adk-agent-demo \
   --source . \
   --region us-west1 \
   --allow-unauthenticated \
   --service-account=agent-sa@${PROJECT_ID}.iam.gserviceaccount.com \
   --set-env-vars="GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"

Fazer curl do endpoint

Você pode ver como o agente fica disponível instantaneamente como uma API pronta para produção.

Registre o URL do serviço do Cloud Run em uma variável de ambiente.

AGENT_URL=$(gcloud run services describe my-adk-agent-demo \
  --region us-west1 \
  --format 'value(status.url)')

Criar uma sessão com o agente

curl -X POST $AGENT_URL/apps/my_agent/users/u_123/sessions/s_123 -H "Content-Type: application/json" -d '{"key1": "value1", "key2": 42}'

Pergunte o que é o Cloud Run e filtre a resposta para mostrar apenas o que o agente diz

curl -X POST $AGENT_URL/run \
-H "Content-Type: application/json" \
-d "{
   \"appName\": \"my_agent\",
   \"userId\": \"u_123\",
   \"sessionId\": \"s_123\",
   \"newMessage\": { 
        \"role\": \"user\", 
        \"parts\": [{ \"text\": \"What is Cloud Run?\" 
    }]}
}" | python3 -c "import sys, json; print(json.load(sys.stdin)[-1]['content']['parts'][0]['text'])"

e você vai ver algo parecido com isto:

Hello! I am **demo_agent**, and I'm here to help you with your Cloud Run demo. **Cloud Run** is a fully managed compute platform by Google Cloud that allows you to run **containerized applications** in a serverless environment...

9. Limpar

Para evitar cobranças recorrentes na sua conta do Google Cloud, exclua todo o projeto (mostrado abaixo) ou os recursos individuais criados durante este codelab.

Exclua os serviços nginx, color-app, private-backend e public-frontend.

gcloud run services delete nginx-service --region $REGION --quiet
gcloud run services delete color-app --region $REGION --quiet
gcloud run services delete private-backend --region $REGION --quiet
gcloud run services delete public-frontend --region $REGION --quiet

Exclua o agente do ADK (observação: implantado em us-west1 para este exemplo)

gcloud run services delete my-adk-agent-demo --region us-west1 --quiet

Remova o secret armazenado no Secret Manager:

gcloud secrets delete my-secret --quiet

Excluir a conta de serviço do app Color

gcloud iam service-accounts delete color-app-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Excluir a conta de serviço do agente do ADK

gcloud iam service-accounts delete agent-sa@${PROJECT_ID}.iam.gserviceaccount.com --quiet

(Opcional) Excluir o projeto

Se você criou um projeto especificamente para este codelab, exclua todo o projeto para garantir que todos os recursos sejam removidos de uma só vez:

# run only if you want to delete the entire project
gcloud projects delete $PROJECT_ID

10. Parabéns!

Você concluiu o codelab. Você aprendeu os conceitos básicos para começar a usar o Cloud Run.

O que você aprendeu

Implantar uma imagem do nginx
Implantar do código-fonte
Reverter uma implantação
Visualizar uma implantação
Usar a ferramenta do servidor MCP de conhecimento do desenvolvedor
Usar o Secret Manager com o Cloud Run
Conectar-se a um serviço interno do Cloud Run em uma VPC
Implantar um agente do ADK no Cloud Run