Hello Cloud Run com Python (Streamlit)

1. Introdução

O Cloud Run é uma plataforma de computação gerenciada onde você executa 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 diversas 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.
• Como testar o aplicativo executando o app do Streamlit antes da implantação.
• Os buildpacks do Cloud e como a presença de streamlit em um requirements.txt dispensa a necessidade de um Dockerfile.
• Como implantar um aplicativo do Streamlit no Cloud Run.

2. Configuração e requisitos

Configuração de ambiente personalizada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver 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, você precisará ativar 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.

Iniciar Cloud Shell

Embora o Google Cloud possa ser operado remotamente em seu laptop, neste tutorial vamos usar o Cloud Shell, um ambiente de linha de comando executado no Google 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 será exibida descrevendo o que ele é. Se você recebeu uma tela intermediária, 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 simplesmente com um navegador.

Depois de se conectar ao Cloud Shell, você vai ver que sua conta está autenticada e que o projeto está configurado com o ID do seu 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 autenticar na primeira vez que você executar um comando. Para obter mais informações, consulte a visão geral 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, faça a configuraçã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 o aplicativo, o Cloud Run é pareado com o 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ê está pronto para começar a trabalhar e criar seu aplicativo.

4. Criar o aplicativo

Nesta etapa, você vai criar um aplicativo Python "Hello World" 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 mudar 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 de sua preferência (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 outras linguagens neste link: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

O aplicativo do Streamlit está pronto para ser implantado, mas vamos testá-lo primeiro.

5. Testar o aplicativo

Para testar o aplicativo, use 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 (desativando --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 do 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:

Uma janela do navegador será aberta 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 do 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-west4

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/ nele. Isso impede que a implantação do Cloud Run inclua o ambiente virtual criado no 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ê 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 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 streamlit esteja presente no arquivo requirements.txt. Caso contrário, os buildpacks vão usar o gunicorn como padrão para veicular o app, o que vai gerar erros com o Streamlit.

Para mais detalhes, consulte Como criar um aplicativo Python.

Em seguida, aguarde um momento até que a implantação seja concluída. 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

É possível acessar o URL do serviço com este comando:

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

Isso vai mostrar algo como o seguinte:

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 usando o console do Cloud ( console.cloud.google.com/run). O serviço helloworld-streamlit será listado:

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

Ainda que o Cloud Run não gere custos quando o serviço não estiver em uso, é possível que receba cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. É possível excluir seu repositório ou seu projeto na nuvem para evitar cobranças. A exclusão do projeto na nuvem interrompe o faturamento de todos os recursos usados nesse projeto.

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. Verifique se este é 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.
• Como testar o aplicativo executando o app do Streamlit antes da implantação.
• Os buildpacks do Cloud e como a presença de streamlit em um requirements.txt dispensa a necessidade de um Dockerfile.
• Como implantar o aplicativo do Streamlit no Cloud Run.

Saiba mais

• Consulte a documentação do Cloud Run.
• Conclua o tutorial Desenvolvimento para produção em três etapas simples com o Cloud Run para conferir 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.