Hello Cloud Run com Python (FastAPI)

1. Introdução

O Cloud Run é uma plataforma de computação gerenciada que permite executar contêineres sem estado que podem ser invocados usando solicitações HTTP. Ele é desenvolvido com base no projeto de código aberto Knative, o que garante a portabilidade das suas cargas de trabalho entre as plataformas. O Cloud Run não tem servidor. Ele cuida de todo o gerenciamento da infraestrutura para que você possa se concentrar no que mais importa: criar aplicativos incríveis.

O objetivo deste tutorial é criar um aplicativo da Web FastAPI simples e implantá-lo no Cloud Run.

O que você vai aprender

• Como criar um aplicativo "Hello World" do FastAPI.
• Testar o aplicativo executando o servidor FastAPI no modo dev.
• Buildpacks do Cloud e como a presença de fastapi e uvicorn em um requirements.txt permite que um Dockerfile não seja necessário.
• Como implantar o aplicativo FastAPI no Cloud Run.

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Se você ainda não tem uma conta do Gmail ou do Google Workspace, crie uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud possa ser operado remotamente em seu laptop, neste tutorial você vai usar o Cloud Shell, um ambiente de linha de comando executado no Cloud.

Ativar o Cloud Shell

1. No console do Cloud, clique em Ativar o Cloud Shell.

Se esta for a primeira vez que você inicia o Cloud Shell, uma tela intermediária vai aparecer com a descrição dele. Se essa tela aparecer, clique em Continuar.

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, quase todo o trabalho pode ser feito com um navegador.

Depois de se conectar ao Cloud Shell, você vai ver que sua conta já está autenticada e que o projeto está configurado com seu ID do projeto.

2. Execute o seguinte comando no Cloud Shell para confirmar se a conta está autenticada:

gcloud auth list

Resposta ao comando

 Credentialed Accounts
ACTIVE  ACCOUNT
*       <my_account>@<my_domain.com>

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Talvez seja necessário fazer a autenticação na primeira vez que você executar um comando. Para obter mais informações, consulte aos aspectos gerais da ferramenta de linha de comando gcloud.

3. Execute o comando a seguir no Cloud Shell para confirmar se o comando gcloud sabe sobre seu projeto:

gcloud config list project

Resposta ao comando

[core]
project = <PROJECT_ID>

Se o projeto não estiver configurado, configure-o usando este comando:

gcloud config set project <PROJECT_ID>

Resposta ao comando

Updated property [core/project].

Observação:se você estiver concluindo este tutorial fora do Cloud Shell, siga as instruções em Configurar as credenciais padrão do aplicativo.

3. Ative as APIs

No Cloud Shell, ative as APIs Artifact Registry, Cloud Build e Cloud Run:

gcloud services enable \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com

Isso gera uma mensagem de sucesso semelhante a esta:

Operation "operations/..." finished successfully.

Para implantar seu aplicativo, o Cloud Run se une ao ecossistema de contêineres:

• O Cloud Build cria automaticamente uma imagem de contêiner com base no código-fonte e a envia para o Artifact Registry.
• O Artifact Registry gerencia a imagem do contêiner.

Agora você já pode começar a trabalhar e escrever seu aplicativo.

4. Escrever o aplicativo

Nesta etapa, você vai criar um aplicativo Python "Hello World" do FastAPI que responde a solicitações HTTP.

Diretório de trabalho

Use o Cloud Shell para criar um diretório de trabalho chamado helloworld-fastapi e mude para ele:

mkdir ~/helloworld-fastapi && cd ~/helloworld-fastapi

main.py

Crie um arquivo chamado main.py:

touch main.py

Edite o arquivo com o editor de linha de comando que preferir (nano, vim ou emacs) ou clicando no botão "Editor do Cloud Shell":

Para editar o arquivo diretamente com o editor do Cloud Shell, use este comando:

cloudshell edit main.py

main.py

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def hello(name: str = "World"):
    """Return a friendly HTTP greeting."""
    return {
        "message": f"Hello {name}!"
    }

Esse código cria um serviço da Web básico que responde a solicitações HTTP GET com uma mensagem amigável.

requirements.txt

Reabra o terminal e adicione um arquivo chamado requirements.txt para definir as dependências:

touch requirements.txt

Para editar o arquivo diretamente com o editor do Cloud Shell, use este comando:

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/fastapi
fastapi[standard]==0.116.1

# https://pypi.org/project/uvicorn
uvicorn==0.35.0

Há várias outras linguagens documentadas para começar a usar o Cloud Run. Confira instruções para Go, Node.js, Java, C#, C++, PHP, Ruby, scripts de shell e outros neste link: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

O aplicativo FastAPI está pronto para ser implantado, mas primeiro é hora de testá-lo.

5. Testar o aplicativo

Para testar o aplicativo, use o uv (gerenciador de projetos e pacotes extremamente rápido do Python), que vem pré-instalado no Cloud Shell.

Para testar o aplicativo, crie um ambiente virtual:

uv venv

Instale as dependências:

uv pip install -r requirements.txt

Inicie o aplicativo no modo dev:

uv run fastapi dev main.py --port=8080

Os registros mostram que você está no modo de desenvolvimento:

FastAPI   Starting development server 🚀

          Searching for package file structure from directories with __init__.py files
          Importing from /home/user/code/helloworld-fastapi

  module  🐍 main.py

    code  Importing the FastAPI app object from the module with the following code:

          from main import app

     app  Using import string: main:app

  server   Server started at http://127.0.0.1:8080
  server   Documentation at http://127.0.0.1:8080/docs

     tip   Running in development mode, for production use: fastapi run

           Logs:

    INFO   Will watch for changes in these directories: ['/home/user/code/helloworld-fastapi']
    INFO   Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)
    INFO   Started reloader process [19627] using WatchFiles
    INFO   Started server process [19629]
    INFO   Waiting for application startup.
    INFO   Application startup complete.

Na janela do Cloud Shell, clique no ícone Web Preview e selecione Preview on port 8080:

Uma janela do navegador será aberta com a mensagem Hello World!.

Você também pode abrir outra sessão do Cloud Shell (uma nova guia do terminal) clicando no ícone + e enviando uma solicitação da Web para o aplicativo em execução localmente:

curl localhost:8080

Você vai receber a seguinte resposta:

{"message": "Hello World!"}

Quando terminar, volte para a sessão principal do Cloud Shell e pare o servidor de desenvolvimento do FastAPI com CTRL+C.

O aplicativo funciona conforme o esperado: é hora de implantá-lo...

6. Implantar no 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. Defina a região que você vai usar para a implantação, por exemplo:

REGION=europe-west1

Para conferir a lista completa de regiões compatíveis, consulte Locais do Cloud Run (totalmente gerenciado).

Verifique se você ainda está no diretório de trabalho:

ls

Isso vai listar os seguintes arquivos:

main.py  requirements.txt

Antes da implantação, crie um arquivo .gcloudignore com .venv/. Isso impede que a implantação do Cloud Run inclua o ambiente virtual criado com uv durante o teste local.

Crie o .gcloudignore com o seguinte comando:

echo ".venv/" > .gcloudignore

Implante o aplicativo no Cloud Run:

gcloud run deploy helloworld-fastapi \
  --source . \
  --region $REGION \
  --allow-unauthenticated

• A opção --allow-unauthenticated torna o serviço disponível publicamente. Para evitar solicitações não autenticadas, use --no-allow-unauthenticated.

Para conferir todas as opções, use gcloud run deploy --help.

Na primeira vez, você vai receber uma solicitação para criar um repositório do Artifact Registry. Toque em Enter para validar:

Deploying from source requires an Artifact Registry Docker repository to store
built containers. A repository named [cloud-run-source-deploy] in region [REGION]
will be created.

Do you want to continue (Y/n)?

Isso inicia o upload do código-fonte para o repositório do Artifact Registry e a criação da imagem do contêiner:

Building using Buildpacks and deploying container ...
* Building and deploying new service... Building Container.           
  OK Creating Container Repository...
  OK Uploading sources...
  * Building Container... Logs are available at ...

O Cloud Build usa Buildpacks, que detectam automaticamente a linguagem do seu código-fonte e criam uma imagem de contêiner com base na versão estável mais recente do interpretador Python (Python 3.13 no momento da redação).

Para usar buildpacks com um servidor da Web ASGI, como uvicorn, que é exigido pelo FastAPI, a presença de uvicorn precisa estar no arquivo requirements.txt. Caso contrário, os pacotes de build vão usar um servidor da Web WSGI com gunicorn, o que vai gerar erros com o FastAPI.

Para mais detalhes, consulte Como criar um aplicativo em Python.

Aguarde alguns instantes até a conclusão da implantação. Em caso de sucesso, a linha de comando vai exibir o URL de serviço:

...
OK Building and deploying new service... Done.
  OK Creating Container Repository...
  OK Uploading sources...
  OK Building Container... Logs are available at ...
  OK Creating Revision... Creating Service.
  OK Routing traffic...
  OK Setting IAM Policy...
Done.
Service [SERVICE]... has been deployed and is serving 100 percent of traffic.
Service URL: https://SERVICE-PROJECTHASH-REGIONID.a.run.app

Use este comando para acessar o URL do serviço:

SERVICE_URL=$( \
  gcloud run services describe helloworld-fastapi \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Isso vai mostrar algo como:

https://helloworld-fastapi-PROJECTHASH-REGIONID.a.run.app

Agora você pode usar o aplicativo abrindo o URL de serviço em um navegador da Web:

Também é possível chamar o aplicativo no Cloud Shell:

curl $SERVICE_URL?name=me

Isso vai gerar a saudação esperada:

{"message": "Hello me!"}

Embora este laboratório curto tenha sido feito usando a linha de comando gcloud, o Cloud Run também está disponível no console do Cloud ( console.cloud.google.com/run). O serviço helloworld-fastapi vai aparecer na lista:

Também é possível usar o console para implantar serviços do Cloud Run.

Parabéns! Você acabou de implantar um aplicativo no Cloud Run. O Cloud Run escalona de maneira automática e horizontal a imagem do contêiner para processar as solicitações recebidas, depois reduz o escalonamento quando a demanda diminui. Você paga apenas pela CPU, memória e rede consumidas durante o processamento da solicitação para esse serviço do Cloud Run.

7. Limpar

O Cloud Run não gera custos quando o serviço não está em uso, mas você ainda pode receber cobranças pelo armazenamento da imagem de contêiner no Artifact Registry. É possível excluir o repositório ou o projeto do Cloud para evitar cobranças. A exclusão do projeto do Cloud interrompe o faturamento de todos os recursos usados nele.

Para excluir o repositório de imagens de contêineres:

gcloud artifacts repositories delete cloud-run-source-deploy \
  --location $REGION

Para excluir o serviço do Cloud Run:

gcloud run services delete helloworld-fastapi \
  --region $REGION

Para excluir seu projeto do Google Cloud,

1. Recupere o ID do projeto atual:

PROJECT_ID=$(gcloud config get-value core/project)

2. Confirme se é o projeto que você quer excluir:

echo $PROJECT_ID

3. Excluir o projeto:

gcloud projects delete $PROJECT_ID

8. Parabéns!

Você criou um aplicativo da Web "Hello World" do FastAPI e o implantou no Cloud Run.

O que aprendemos

• Como criar um aplicativo "Hello World" do FastAPI.
• Testar o aplicativo executando o servidor FastAPI no modo dev.
• Buildpacks do Cloud e como a presença de fastapi e uvicorn em um requirements.txt permite que um Dockerfile não seja necessário.
• Como implantar o aplicativo FastAPI no Cloud Run.

Saiba mais

• Confira a documentação do Cloud Run
• Conclua o laboratório Dev to Prod in Three Easy Steps with Cloud Run para conhecer mais opções.
• Conclua o tutorial Django no Cloud Run para criar um banco de dados do Cloud SQL, gerenciar credenciais com o Secret Manager e implantar o Django.
• Confira mais codelabs do Cloud Run...