Implantar um app do App Engine no ambiente flexível 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 flexível para o Cloud Run.

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 ambiente flexível do App Engine e o Cloud Run são plataformas de aplicativos totalmente gerenciadas e nativas de contêiner, mas são estruturalmente diferentes. 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, use a configuração local do arquivo app.yaml. Isso cria uma imagem de contêiner com base no código-fonte local. Assim, todas as mudanças recentes no código ou na configuração são incluídas na nova implantação.

Antes de começar

  1. Verifique se o aplicativo do App Engine é executado sem erros. Você precisa acessar o código-fonte do App Engine.

  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 flexível. 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 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.

  3. No card Migração do ambiente flexível para o Cloud Run, selecione o Serviço e a Versão que você quer migrar e clique em Verificar compatibilidade.

  4. Na seção Verificar compatibilidade, confira os resultados. 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. Copie o comando na seção Implantar usando a 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.

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

    Solução: substitua a seção basic_scaling no arquivo app.yaml por automatic_scaling ou manual_scaling. A verificação de compatibilidade no hub de migração bloqueia versões que usam o escalonamento básico.

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

  • Portas encaminhadas com mapeamentos de porta do host, protocolos ou várias portas:

    network:
      forwarded_ports:
      - 8080:8000
      - 2222/udp
    

    Solução: atualize network.forwarded_ports no arquivo app.yaml para especificar apenas uma porta de contêiner numérica, como 8080, ou exclua forwarded_ports e configure a porta do contêiner no Cloud Run. O Cloud Run aceita apenas tráfego TCP de entrada em uma única porta de contêiner e não é compatível com mapeamentos de porta de host para contêiner ou tráfego UDP. A ferramenta de migração aceita apenas números de porta simples. Portanto, mapeamentos de porta de host e sufixos de protocolo /tcp ou /udp, como 8080/tcp, causam falha na migração. Se você especificar várias portas numéricas, a ferramenta de migração vai registrar um aviso e configurar apenas a primeira porta.

  • Tamanho do disco:

    resources:
      disk_size_gb: 20
    

    Solução: exclua disk_size_gb da seção resources do arquivo app.yaml. A ferramenta de migração exibe um aviso e ignora essa configuração porque o Cloud Run usa como padrão um sistema de arquivos na memória, em que a gravação de arquivos consome memória da instância. Se o aplicativo precisar gravar arquivos sem consumir memória, configure uma montagem de volume de disco temporário ou uma montagem de volume do Cloud Storage no Cloud Run para evitar erros de falta de memória (OOM, na sigla em inglês).

A seguir