Hello Cloud Run com Python (Streamlit)

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 "Hello World" Streamlit e implantá-lo no Cloud Run.

O que você vai aprender

• Como criar um aplicativo "Hello World" do Streamlit.
• Testar o aplicativo executando o app Streamlit antes da implantação.
• Buildpacks do Cloud e como a presença de streamlit em um requirements.txt elimina a necessidade de um Dockerfile.
• Como implantar um aplicativo Streamlit 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 "Hello World" em Python do Streamlit que responde a solicitações HTTP.

Diretório de trabalho

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

mkdir ~/helloworld-streamlit && cd ~/helloworld-streamlit

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

import streamlit as st

st.title("Hello World! 👋🌎")
st.markdown(
    """
    This is a demo Streamlit app.

    Enter your name in the text box below and press a button to see some fun features in Streamlit.
    """
)

name = st.text_input("Enter your name:")

# Use columns to create buttons side by side
col1, col2 = st.columns(2)

with col1:
    if st.button("Send balloons! 🎈"):
        st.balloons()
        st.write(f"Time to celebrate {name}! 🥳")
        st.write("You deployed a Streamlit app! 👏")

with col2:
    if st.button("Send snow! ❄️"):
        st.snow()
        st.write(f"Let it snow {name}! 🌨️")
        st.write("You deployed a Streamlit app! 👏")

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/streamlit
streamlit==1.47.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 Streamlit está pronto para ser implantado, mas vamos testá-lo primeiro...

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 usando streamlit run (desative --server.enableCORS para testes, já que ele interfere no Cloud Shell):

uv run streamlit run main.py --server.port=8080 --server.enableCORS=false

Os registros vão mostrar que o app Streamlit está em execução:

You can now view your Streamlit app in your browser.

  Local URL: http://localhost:8080
  Network URL: http://10.1.0.1:8080
  External URL: http://34.37.7.94:8080

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

Isso vai abrir uma janela do navegador mostrando o título Hello World! 👋🌎.

Tente preencher seu nome e testar os dois botões na tela.

Quando terminar, volte para a sessão principal do Cloud Shell e interrompa o app Streamlit 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-streamlit \
  --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). Se necessário, é possível fixar o build em uma versão específica incluindo um arquivo .python-version no diretório de origem. Para usar buildpacks com o Streamlit, é necessário que o streamlit esteja presente no arquivo requirements.txt. Caso contrário, os buildpacks vão usar o gunicorn para veicular o app, o que vai gerar erros com o Streamlit.

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-streamlit \
  --region $REGION \
  --format "value(status.address.url)" \
)
echo $SERVICE_URL

Isso vai mostrar algo como:

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

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

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-streamlit 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-streamlit \
  --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 Streamlit e o implantou no Cloud Run.

O que aprendemos

• Como criar um aplicativo "Hello World" do Streamlit.
• Testar o aplicativo executando o app Streamlit antes da implantação.
• Buildpacks do Cloud e como a presença de streamlit em um requirements.txt elimina a necessidade de um Dockerfile.
• Implantação do aplicativo Streamlit 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...