Implantar um app do App Engine no ambiente padrão para o Cloud Run

ID da região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

Neste guia, descrevemos como implantar seus apps atuais no ambiente padrão no Cloud Run. As instruções são aplicáveis a ambientes de execução de segunda geração que não usam os serviços integrados legados do App Engine.

As etapas descritas neste guia não afetam a funcionalidade ou o fluxo de tráfego do seu app do App Engine. O serviço do Cloud Run recém-criado é uma réplica do serviço do App Engine que pode ser testada de forma independente.

O Cloud Run usa grande parte da mesma infraestrutura do ambiente padrão do App Engine, o que resulta em muitas semelhanças entre as plataformas. Para entender as semelhanças e diferenças entre o App Engine e o Cloud Run, incluindo os benefícios da migração para o Cloud Run, consulte o resumo de comparação.

Para implantar no Cloud Run, escolha uma das seguintes estratégias:

  • Usar a configuração local de um arquivo app.yaml (recomendado): escolha essa opção para criar uma imagem de contêiner diretamente do código-fonte local e implantá-la no Cloud Run. Isso garante que todas as modificações locais recentes no código ou na configuração sejam incluídas na nova implantação.

  • Usar uma imagem criada anteriormente: essa opção é útil se você não tiver acesso ao código-fonte. Escolha essa opção para implantar uma cópia exata de uma versão que já está em execução no App Engine, sem recriar a imagem do contêiner. Isso é útil se você quiser verificar o comportamento da implantação ativa sem mudanças no código.

Antes de começar

  1. Verifique se o aplicativo do App Engine é executado sem erros. Você precisará de acesso ao código-fonte do App Engine se optar por implantar usando sua configuração local.

  2. Ative a API Cloud Run Admin e a API Artifact Registry:

    Ativar APIs

  3. Configure o projeto e a região usando o seguinte comando:

    gcloud auth login
gcloud config set project PROJECT_ID
gcloud config set run/region REGION
gcloud components update

    Substitua:

    • PROJECT_ID: o ID do projeto Google Cloud .
    • REGION: a região em que você quer implantar o serviço do Cloud Run.

  4. Verifique se há recursos incompatíveis no aplicativo e remova-os antes de migrar para o Cloud Run. Para verificar se há incompatibilidade no aplicativo sem realizar uma migração ou implantação, execute o seguinte comando:

    gcloud beta app migrate-to-run --dry-run

    Revise os resultados da verificação de compatibilidade e faça as mudanças recomendadas, se necessário.

  5. Analise as seguintes diferenças do Cloud Run:

    • O Cloud Run usa o termo Revision em vez de Version para representar cada vez que você implanta alterações em um serviço específico. Implantar o app em um serviço no Cloud Run pela primeira vez cria a primeira revisão. Cada implantação subsequente de um serviço cria outra revisão. Saiba mais sobre como implantar no Cloud Run.

    • É possível implantar o código-fonte no Cloud Run usando a CLI gcloud ou o console do Google Cloud para definir e gerenciar as configurações do app. O Cloud Run não requer configuração baseada em arquivo. No entanto, Configuração do YAML tem suporte.

    • Cada serviço implantado no Cloud Run usa o domínio run.app no URL para acessar o serviço publicamente.

    • Ao contrário dos serviços do App Engine que são públicos por padrão, os serviços do Cloud Run são particulares por padrão e exigem que você os configure para acesso público (não autenticado).

Funções exigidas

É possível criar uma nova conta de serviço ou usar a mesma conta de serviço gerenciado pelo usuário no Cloud Run que você está usando para o ambiente padrão. Você ou seu administrador precisa conceder à conta de implantador e à conta de serviço do Cloud Build os seguintes papéis do IAM.

Clique para conferir os papéis necessários para a conta de implantador

Para receber as permissões necessárias para criar e implantar a partir da origem, peça ao administrador para conceder a você os seguintes papéis do IAM:

Clique para conferir os papéis necessários para a conta de serviço do Cloud Build

O Cloud Build usa automaticamente a conta de serviço padrão do Compute Engine como a conta de serviço padrão do Cloud Build para criar o código-fonte e o recurso do Cloud Run, a menos que você substitua esse comportamento. Para que o Cloud Build crie suas origens, peça ao administrador para conceder o papel de Criador do Cloud Run (roles/run.builder) à conta de serviço padrão do Compute Engine no projeto:

  gcloud projects add-iam-policy-binding PROJECT_ID \
      --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
      --role=roles/run.builder

Substitua PROJECT_NUMBER pelo número do projeto do Google Cloude PROJECT_ID pelo ID do projeto do Google Cloud. Para instruções detalhadas sobre como encontrar o ID do projeto e o número do projeto, consulte Criar e gerenciar projetos.

A concessão do papel de criador do Cloud Run à conta de serviço padrão do Compute Engine leva alguns minutos para se propagar.

Para uma lista de papéis e permissões do IAM associados ao Cloud Run, consulte Papéis do IAM do Cloud Run e Permissões do IAM do Cloud Run. Se o serviço do Cloud Run interage com as APIs doGoogle Cloud , como as bibliotecas de cliente do Cloud, consulte o guia de configuração de identidade de serviço. Para mais informações sobre como conceder papéis, consulte permissões de implantação e gerenciar acesso.

Usar a configuração local de um arquivo app.yaml

Implante a configuração local do App Engine no Cloud Run usando o console do Google Cloud ou a CLI gcloud.

Console

  1. No console do Google Cloud , acesse a página do App Engine.

    Acessar o App Engine

  2. No menu de navegação, clique em Hub de migração para implantar o app do App Engine no Cloud Run. O Hub de migração também permite verificar a economia estimada no Cloud Run para estimativa de custos e recomendações.

  3. Selecione o serviço que você quer migrar e clique em Verificar compatibilidade.

  4. Selecione o Serviço e a Versão para conferir os resultados de compatibilidade. O hub de migração executa um verificador de compatibilidade para identificar recursos incompatíveis.

  5. Revise os resultados para verificar se o app é totalmente compatível com o Cloud Run e clique em Continuar para prosseguir para a seção Revisar e implantar.

  6. Copie o comando na seção Implantar usando a gcloud e execute-o no diretório do projeto.

  7. Clique em Ver versões implantadas para conferir os serviços do App Engine implantados no Cloud Run.

gcloud

Para implantar o serviço do Cloud Run usando o arquivo app.yaml local de uma configuração do App Engine, siga estas etapas:

  1. No terminal, mude para o diretório de origem em que o arquivo app.yaml está.

  2. Execute o comando a seguir para implantar o serviço no Cloud Run:

    gcloud beta app migrate-to-run

    Esse comando gera a configuração do arquivo service.yaml para o Cloud Run e a salva localmente no mesmo diretório do arquivo app.yaml. Para mais informações, consulte gcloud beta app migrate-to-run.

    • Quando solicitado Proceed with the deployment?, digite Y para criar uma imagem do contêiner com base no código-fonte e implantar o serviço no Cloud Run.

  3. Acesse o serviço do Cloud Run implantado abrindo o URL dele em um navegador da Web.

    Opcional:

    • Se o arquivo app.yaml estiver em um diretório diferente, especifique o caminho dele usando a flag --appyaml:

      gcloud beta app migrate-to-run --appyaml=PATH

      Substitua PATH pelo caminho do seu arquivo app.yaml.

    • Para gerar e exportar a configuração do Cloud Run service.yaml sem implantar o serviço, use a flag --export-only:

      gcloud beta app migrate-to-run --export-only=EXPORT_PATH

      Substitua EXPORT_PATH pelo diretório ou caminho em que você quer salvar o arquivo service.yaml.

Usar uma imagem criada anteriormente

Para implantar usando uma imagem de contêiner criada anteriormente de uma versão implantada do App Engine, em vez de recriar a imagem de contêiner de um arquivo app.yaml local, siga estas etapas:

Não é necessário ter o código-fonte do aplicativo para essa implantação.

  1. Execute o comando a seguir para implantar o serviço no Cloud Run. Esse comando usa a imagem de contêiner de uma implantação ativa do App Engine e não captura as mudanças recentes do arquivo app.yaml local, o que pode resultar em uma implantação desatualizada:

    gcloud beta app migrate-to-run --service=SERVICE --version=VERSION --from-image

    Substitua:

    • SERVICE: o nome do serviço do App Engine.
    • VERSION: o ID da versão do serviço.

    Esse comando busca a configuração do serviço e da versão especificados para gerar o arquivo service.yaml para o Cloud Run. Para mais informações, consulte gcloud beta app migrate-to-run.

    • Quando solicitado com Proceed with the deployment?, digite Y para exportar a imagem do contêiner do App Engine e implantar o serviço no Cloud Run.

  2. Acesse o serviço do Cloud Run implantado abrindo o URL dele em um navegador da Web.

    Opcional:

    • Para gerar a configuração service.yaml do Cloud Run sem implantar o serviço, execute o seguinte comando:

      gcloud beta app migrate-to-run --service=SERVICE \
    --version=VERSION \
    --from-image \
    --export-only=EXPORT_PATH

      Substitua EXPORT_PATH pelo diretório ou caminho em que você quer salvar o arquivo service.yaml.

Recursos incompatíveis

O comando de migração falhará se o arquivo app.yaml contiver alguma das seguintes configurações não compatíveis:

  • Serviços de entrada:

    inbound_services:
- warmup

    Solução: exclua a seção inbound_services do arquivo app.yaml. O Cloud Run aquece as instâncias usando o ponto de entrada do contêiner, então não é necessário configurar solicitações de aquecimento. Se você precisar executar o código de inicialização antes de exibir o tráfego, configure o serviço para executá-lo na inicialização, antes de detectar solicitações ou use sondagens de inicialização. Também é possível configurar instâncias mínimas para manter as instâncias ativas.

  • Páginas de erro personalizadas:

    error_handlers:
 - file: default_error.html
 - error_code: over_quota
 file: over_quota.html

    Solução: exclua a seção error_handlers do arquivo app.yaml e siga uma ou ambas as estratégias:

    • Implementar o tratamento de erros diretamente no código do aplicativo. Capture códigos de erro HTTP padrão, como 404 ou 500, e exiba suas páginas de erro HTML personalizadas na lógica do aplicativo.
    • Se você estiver usando o Cloud Load Balancing com o Cloud Run, configure respostas de erro personalizadas no nível do balanceador de carga. Isso permite que você disponibilize páginas de erro personalizadas do Cloud Storage com base no código de resposta do serviço do Cloud Run.

  • Serviços integrados para ambientes de execução de segunda geração:

    app_engine_apis: true

    Solução: exclua a configuração app_engine_apis do arquivo app.yaml e migre para as APIs do Google Cloud ou alternativas de terceiros. Para mais informações, consulte Como migrar de serviços integrados.

  • Ambientes de execução de primeira geração:

    runtime: python27

    Solução: faça upgrade do aplicativo para um ambiente de execução de segunda geração compatível. Para mais informações, consulte a Visão geral da migração para ambientes de execução de segunda geração.

A seguir