Hello Cloud Run com Python

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 foi 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 simples e implantá-lo 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. 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, 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 um laptop, neste tutorial você 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 você estiver iniciando o Cloud Shell pela primeira vez, verá uma tela intermediária com a descrição dele. Se aparecer uma tela intermediária, clique em Continuar.

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

Essa máquina virtual tem 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. Grande parte do trabalho neste codelab, se não todo, pode ser feito em um navegador.

Depois de se conectar ao Cloud Shell, você verá sua autenticação e o projeto estará 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 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 seguinte comando no Cloud Shell para confirmar que 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 o Application Default Credentials.

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

Será exibida uma mensagem de sucesso semelhante a esta:

Operation "operations/..." finished successfully.

Nos bastidores, para implantar seu aplicativo, o Cloud Run é combinado 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 está tudo pronto para você começar a trabalhar e criar o aplicativo...

4. Programar o aplicativo

Nesta etapa, você vai criar um aplicativo simples em Python baseado em Flask que responde a solicitações HTTP.

Diretório de trabalho

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

mkdir ~/helloworld-python
cd ~/helloworld-python

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 clique no botão do editor do Cloud Shell:

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

cloudshell edit main.py

main.py

from flask import Flask, request

app = Flask(__name__)


@app.get("/")
def hello():
    """Return a friendly HTTP greeting."""
    who = request.args.get("who", default="World")
    return f"Hello {who}!\n"


if __name__ == "__main__":
    # Development only: run "python main.py" and open http://localhost:8080
    # When deploying to Cloud Run, a production-grade WSGI HTTP server,
    # such as Gunicorn, will serve the app.
    app.run(host="localhost", port=8080, debug=True)

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

requirements.txt

Adicione um arquivo chamado requirements.txt para definir as dependências:

touch requirements.txt

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

cloudshell edit requirements.txt

requirements.txt

# https://pypi.org/project/flask
Flask==3.0.2

# https://pypi.org/project/gunicorn
gunicorn==21.2.0

Procfile (em inglês)

Por fim, adicione um arquivo chamado Procfile para especificar como o aplicativo será exibido:

touch Procfile

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

cloudshell edit Procfile

Procfile

web: gunicorn --bind :$PORT --workers 1 --threads 8 --timeout 0 main:app

Verifique se todos os arquivos estão presentes no diretório de trabalho:

ls

Os seguintes arquivos serão listados:

main.py  Procfile  requirements.txt

Muitas outras linguagens estão documentadas para começar com o Cloud Run. Veja instruções para Go, Node.js, Java, C#, C++, PHP, Ruby, scripts de shell, entre outros: https://cloud.google.com/run/docs/quickstarts/build-and-deploy

Seu aplicativo está pronto para ser implantado, mas vamos testá-lo primeiro...

5. Testar o aplicativo

Para testar o aplicativo, crie um ambiente virtual:

virtualenv venv

Ative o ambiente virtual:

source venv/bin/activate

Instale as dependências:

pip install -r requirements.txt

Você vai receber uma mensagem de confirmação como esta:

...
Successfully installed Flask ... gunicorn ...

Inicie o aplicativo:

python main.py

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

 * Serving Flask app 'main'
 * Debug mode: on
   WARNING: This is a development server.
   Do not use it in a production deployment.
   Use a production WSGI server instead.
 * Running on http://localhost:8080
   Press CTRL+C to quit
...

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!.

Também é possível 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 local:

curl localhost:8080

Você vai receber a seguinte resposta:

Hello World!

Quando terminar, volte para a sessão principal do Cloud Shell e interrompa o comando python main.py com CTRL+C.

Saia do ambiente virtual:

deactivate

Por fim, remova o diretório do ambiente virtual:

rm -r venv/

Seu aplicativo funciona como esperado: vamos implantá-lo...

6. Implantar no Cloud Run

O Cloud Run é regional, ou seja, a infraestrutura que executa os 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 dessa região. Defina a região que você usará para sua implantação, por exemplo:

REGION="europe-west9"

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

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

ls

Os seguintes arquivos serão listados:

main.py  Procfile  requirements.txt

Implante o aplicativo no Cloud Run:

gcloud run deploy helloworld-python \
  --source . \
  --platform managed \
  --region $REGION \
  --allow-unauthenticated

• Defina uma região padrão com este comando: gcloud config set run/region $REGION
• Também é possível tornar o Cloud Run gerenciado por padrão com este comando: gcloud config set run/platform managed
• A opção --allow-unauthenticated torna o serviço disponível publicamente. Para evitar solicitações não autenticadas, use --no-allow-unauthenticated.

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

Na primeira vez, você vai receber um comando 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 seu código-fonte para o repositório do Artifact Registry e o build da imagem de 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 detecta automaticamente a linguagem do código-fonte e cria uma imagem de contêiner com base na versão estável mais recente do interpretador de Python (Python 3.12 no momento da gravação). Se necessário, você pode fixar o build em uma versão específica incluindo um arquivo .python-version no diretório de origem. Para mais detalhes, consulte Como criar um aplicativo Python.

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

Para conseguir o URL do serviço, use este comando:

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

O resultado será semelhante a este:

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

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

Você também pode chamar o aplicativo do Cloud Shell:

curl $SERVICE_URL?who=me

A saudação esperada será esta:

Hello me!

Embora este breve laboratório tenha sido feito com a linha de comando gcloud, o Cloud Run está disponível no console do Cloud ( console.cloud.google.com/run). Você verá o serviço helloworld listado:

Também é possível usar o console para implantar os 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.

7. Limpar

O Cloud Run não gera cobranças quando o serviço não está em uso, mas você ainda pode receber cobranças pelo armazenamento da imagem do contêiner no Artifact Registry. Você pode excluir seu repositório ou 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êiner:

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

Para excluir o serviço do Cloud Run:

gcloud run services delete helloworld-python \
  --platform managed \
  --region $REGION

Para excluir seu projeto do Google Cloud, faça o seguinte:

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 simples e o implantou no Cloud Run.

Saiba mais

• Confira a documentação do Cloud Run
• Conclua Dev to Prod em três etapas fáceis com o Cloud Run para conferir mais opções
• Concluir 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...

Licença

Este conteúdo está sob a licença Atribuição 2.0 Genérica da Creative Commons.