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 arquivoapp.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
Verifique se o aplicativo do App Engine é executado sem erros. Você precisa acessar o código-fonte do App Engine.
Ative as API Cloud Run Admin e Artifact Registry:
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 updateSubstitua:
- PROJECT_ID: o ID do projeto Google Cloud .
- REGION: a região em que você quer implantar o serviço do Cloud Run.
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.yamlestá localizado:gcloud beta app migrate-to-run --dry-runRevise os resultados da verificação de compatibilidade e faça as mudanças recomendadas, se necessário.
Analise as seguintes diferenças do Cloud Run:
O Cloud Run usa o termo
Revisionem vez deVersionpara 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.appno 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:
- Desenvolvedor de origem do Cloud Run (
roles/run.sourceDeveloper) no projeto - Consumidor do Service Usage (
roles/serviceusage.serviceUsageConsumer) no seu projeto - Usuário da conta de serviço (
roles/iam.serviceAccountUser) na identidade de serviço do Cloud Run
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
No console do Google Cloud , acesse a página do App Engine.
No menu de navegação, clique em Hub de migração para implantar o aplicativo do App Engine no Cloud Run.
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.
Na seção Verificar compatibilidade, confira os resultados. O hub de migração executa um verificador de compatibilidade para identificar recursos incompatíveis.
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.
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.yamle execute o comando no diretório de origem do aplicativo.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:
No terminal, mude para o diretório de origem em que o arquivo
app.yamlestá.Execute o comando a seguir para implantar o serviço no Cloud Run:
gcloud beta app migrate-to-runEsse comando gera a configuração do arquivo
service.yamlpara o Cloud Run e a salva localmente no mesmo diretório do arquivoapp.yaml. Para mais informações, consultegcloud beta app migrate-to-run.- Quando solicitado
Proceed with the deployment?, digiteYpara criar uma imagem do contêiner com base no código-fonte e implantar o serviço no Cloud Run.
- Quando solicitado
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 proxye 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.yamlestiver em um diretório diferente, especifique o caminho dele usando a flag--appyaml:gcloud beta app migrate-to-run --appyaml=PATHSubstitua PATH pelo caminho do seu arquivo
app.yaml.Para gerar e exportar a configuração
service.yamldo Cloud Run sem implantar o serviço, use a flag--export-only:gcloud beta app migrate-to-run --export-only=EXPORT_PATHSubstitua EXPORT_PATH pelo diretório ou caminho em que você quer salvar o arquivo
service.yaml.
- Para testar o serviço de forma particular (recomendado), execute o comando
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: - warmupSolução: exclua a seção
inbound_servicesdo arquivoapp.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.htmlSolução: exclua a seção
error_handlersdo arquivoapp.yamle 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
404ou500, 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.
- Implemente o tratamento de erros diretamente no código do aplicativo. Capture
códigos de erro HTTP padrão, como
Gerenciadores de URL e arquivos estáticos:
handlers: - url: /stylesheets static_dir: stylesheetsSolução: exclua a seção
handlersdo arquivoapp.yaml. O Cloud Run não é compatível com o roteamento de solicitaçõesapp.yamlou 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-runnã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_variablesdo arquivoapp.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: 10mSolução: substitua a seção
basic_scalingno arquivoapp.yamlporautomatic_scalingoumanual_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: 1500A 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.yamlpara 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/udpSolução: atualize
network.forwarded_portsno arquivoapp.yamlpara especificar apenas uma porta de contêiner numérica, como8080, ou excluaforwarded_portse 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/tcpou/udp, como8080/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: 20Solução: exclua
disk_size_gbda seçãoresourcesdo arquivoapp.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
- Saiba como gerenciar os serviços do Cloud Run.
- Consulte o contrato de ambiente de execução de contêineres do Cloud Run para entender os requisitos e comportamentos dos contêineres no Cloud Run.
- Saiba como armazenar dependências para seus requisitos para serviços que exigem chaves de API, senhas ou outras informações sensíveis usando um Secret Manager.