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, ou verifique o comportamento da implantação ativa sem alterações de código.

Antes de começar

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

  2. Ative as API Cloud Run Admin e 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 no diretório em que o arquivo app.yaml está localizado:

    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 o console doGoogle Cloud ou a Google Cloud CLI para definir e gerenciar as configurações dos apps. 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 Cloud e 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 implantar uma imagem criada anteriormente, peça ao administrador para conceder a você os seguintes papéis do IAM:

Opcional: para ver a economia de custos estimada no Hub de migração, você precisa da permissão recommender.appengineVersionCostRecommendations.list. Os papéis de implantador do App Engine e de leitor do App Engine (roles/appengine.appViewer) contêm essa permissão.

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 Google Cloud CLI.

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 aplicativo do App Engine no Cloud Run. O hub de migração também permite verificar as economias estimadas no Cloud Run para recomendações de custo.

  3. No card Migração do Standard para o Cloud Run, selecione o Serviço que você quer migrar e clique em Verificar compatibilidade.

  4. Na seção Verificar compatibilidade, confirme ou selecione sua Versão para conferir os resultados de compatibilidade. O hub de migração executa um verificador de compatibilidade para identificar recursos incompatíveis.

  5. Analise os resultados para verificar se o app não tem incompatibilidades de bloqueio e clique em Continuar para prosseguir para a seção Revisar e implantar.

  6. Na guia Implantação baseada na origem, copie o comando na seção Implantar pelo gcloud, substitua o marcador de posição PATH_TO_APP_YAML pelo caminho para o arquivo app.yaml e execute o comando no diretório de origem do aplicativo.

  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 atual 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. Teste o serviço do Cloud Run implantado. Como o serviço do Cloud Run é privado por padrão, abrir o URL do serviço diretamente em um navegador da Web retorna um erro 403 Forbidden. Para ver seu serviço, siga um destes procedimentos:

    • Para testar o serviço de forma particular (recomendado), execute o comando gcloud run services proxy e abra o URL do proxy local em um navegador da Web.
    • Se você quiser que o serviço esteja disponível publicamente, ative o acesso público e abra o URL do serviço 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 service.yaml do Cloud Run 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

Implante uma imagem de contêiner criada anteriormente de uma versão do App Engine implantada no Cloud Run usando o console do Google Cloud ou a Google Cloud CLI. Isso não recria a imagem do contêiner de um arquivo app.yaml local, e você não precisa do código-fonte do aplicativo.

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.

  3. No card Migração do Standard para o Cloud Run, selecione o Serviço que você quer migrar e clique em Verificar compatibilidade.

  4. Na seção Verificar compatibilidade, confirme ou selecione a Versão que você quer implantar. O hub de migração executa um verificador de compatibilidade para identificar recursos incompatíveis.

  5. Analise os resultados para verificar se o app não tem incompatibilidades de bloqueio e clique em Continuar para prosseguir para a seção Revisar e implantar.

  6. Clique na guia Implantação baseada em imagem.

  7. Analise as configurações do Cloud Run que o hub de migração deriva da sua versão do App Engine, como CPU, memória, escalonamento, simultaneidade, conta de serviço e variáveis de ambiente. É possível mudar essas configurações após a implantação. Para implantar uma versão diferente, clique em Alterar versão.

  8. Se você não tiver ativado as APIs necessárias, clique em Ativar APIs do Cloud Run e em Ativar todas para ativar a API Cloud Run Admin e a API Cloud Build.

  9. Clique em Corresponder permissões e em Conceder tudo para conceder os seguintes papéis do IAM à sua conta de usuário:

    • Desenvolvedor do Cloud Run (roles/run.developer)
    • Usuário da conta de serviço (roles/iam.serviceAccountUser)
    • Leitor do Artifact Registry (roles/artifactregistry.reader)

    Se você não tiver permissão para ativar APIs ou conceder papéis, peça ao administrador para fazer isso.

  10. Clique em Implantar. O hub de migração exporta a imagem de contêiner da versão do App Engine e a implanta em um serviço do Cloud Run com o mesmo nome do serviço do App Engine. O serviço é criado na região do Cloud Run que corresponde à região do aplicativo do App Engine.

    Se já houver um serviço do Cloud Run com o mesmo nome nessa região, clique em Substituir e implantar na caixa de diálogo de confirmação. A implantação cria uma nova revisão que atende a 100% do tráfego e mantém as configurações atuais de autenticação e entrada do serviço.

    Após a conclusão da implantação, a página Serviços do Cloud Run é aberta, filtrada para mostrar os serviços migrados do App Engine.

  11. Teste o serviço do Cloud Run implantado. Como o serviço do Cloud Run é privado por padrão, abrir o URL do serviço diretamente em um navegador da Web retorna um erro 403 Forbidden. Para ver seu serviço, siga um destes procedimentos:

    • Para testar o serviço de forma particular (recomendado), execute o comando gcloud run services proxy e abra o URL do proxy local em um navegador da Web.
    • Se você quiser que o serviço esteja disponível publicamente, ative o acesso público e abra o URL do serviço em um navegador da Web.

gcloud

  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. Teste o serviço do Cloud Run implantado. Como o serviço do Cloud Run é privado por padrão, abrir o URL do serviço diretamente em um navegador da Web retorna um erro 403 Forbidden. Para ver o serviço, siga um destes procedimentos:

    • Para testar o serviço de forma particular (recomendado), execute o comando gcloud run services proxy e abra o URL do proxy local em um navegador da Web.
    • Se você quiser que o serviço esteja disponível publicamente, ative o acesso público e abra o URL do serviço 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á ou exibirá um aviso 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:

    • Implemente 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ê veicule páginas de erro personalizadas do Cloud Storage com base no código de resposta do serviço do Cloud Run.
  • Gerenciadores de URL e arquivos estáticos:

    handlers:
    - url: /stylesheets
      static_dir: stylesheets
    

    Solução: exclua a seção handlers do arquivo app.yaml ou mantenha apenas um gerenciador catch-all que encaminhe todo o tráfego para o aplicativo (url: /.* ou url: .* com script: auto). O Cloud Run não é compatível com o roteamento de solicitações app.yaml ou gerenciadores de arquivos estáticos. Em vez disso, exiba arquivos estáticos diretamente do serviço do Cloud Run ou do Cloud Storage e processe o roteamento de URL no código do aplicativo ou usando o Cloud Load Balancing.

  • Variáveis de ambiente de build:

    build_env_variables:
      BUILD_MODE: "production"
    

    A verificação de compatibilidade no hub de migração informa essa configuração como uma incompatibilidade de bloqueio. O comando gcloud beta app migrate-to-run não as informa e aplica as variáveis ao build quando você implanta a partir da origem.

    Solução: exclua a seção build_env_variables do arquivo app.yaml. Se o build ainda exigir esses valores, defina variáveis de ambiente de build ao implantar o serviço do Cloud Run usando a origem. Se o app precisar desses valores no ambiente de execução, defina-os como variáveis de ambiente no serviço.

  • Escalonamento básico:

    basic_scaling:
      max_instances: 10
      idle_timeout: 10m
    

    O Cloud Run não tem uma configuração de escalonamento básico. O comando de migração exibe um aviso e usa o valor max_instances como o número máximo de instâncias do serviço do Cloud Run.

    Solução: verifique se o escalonamento automático do Cloud Run atende às suas necessidades.

  • Valores de recursos e escalonamento fora dos limites do Cloud Run:

    manual_scaling:
      instances: 1500
    

    A migração vai mostrar um aviso se a configuração estiver fora de qualquer um dos seguintes limites do Cloud Run:

    • CPU: 8 vCPUs
    • Memória: 512 MiB a 32 GiB
    • Instâncias de escalonamento mínimo, máximo ou manual: 1.000
    • Solicitações simultâneas por instância: 1.000

    Solução: atualize o arquivo app.yaml para usar valores dentro desses limites. Para mais informações, consulte limites de CPU, limites de memória e simultaneidade. Se você precisar de mais de 1.000 instâncias, solicite um aumento de cota.

A seguir