Testar e implantar seu aplicativo

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.

OK

Go Java Node.js PHP Python Ruby .NET Custom

Saiba como executar o aplicativo localmente, implantá-lo e testá-lo no App Engine.

Executar no local

Para testar o aplicativo antes da implantação, execute-o no ambiente local com as ferramentas de desenvolvimento que você costuma usar. Por exemplo, normalmente é possível executar um aplicativo Flask com o servidor de desenvolvimento Flask usando:

python main.py

Inicie aplicativos Django usando:

python manage.py runserver

Para simular um ambiente de produção do App Engine, é possível executar o servidor de interface de gateway do servidor da Web (WSGI, na sigla em inglês) completo localmente. Use o mesmo comando especificado como entrypoint no arquivo app.yaml, por exemplo:

gunicorn -b :$PORT main:app

implantar o aplicativo

Implante o aplicativo no App Engine usando o comando gcloud app deploy.

O serviço Cloud Build cria automaticamente a implantação em uma imagem de contêiner e a implanta no ambiente flexível do App Engine. O contêiner inclui todas as modificações locais realizadas na imagem do ambiente de execução.

Para implantar os aplicativos de maneira programática, use a API Admin.

Antes de começar

Antes de implantar seu aplicativo:

• O proprietário do projeto do Google Cloud precisa configurar o projeto Google Cloud para o App Engine.

• Verifique se a conta de usuário inclui os privilégios exigidos.

Garantir uma implantação bem-sucedida

Ao ativar as verificações de integridade atualizadas, as implantações são revertidas se o aplicativo não tiver o status "íntegro". Quando você implanta seu primeiro aplicativo no ambiente flexível, pode ocorrer um atraso conforme a máquina virtual (VM) e outras infraestruturas são configuradas. Após a configuração inicial, as verificações de integridade garantem que a instância esteja íntegra e pronta para receber tráfego. Se o aplicativo não atingir o status pronto em um período especificado, indicado pelo campo initial_delay_sec na seção liveness_check do arquivo app.yaml, a implantação falhará e será revertida.

Talvez o aplicativo demore um pouco mais para ficar pronto. Por exemplo, você pode inicializar o aplicativo fazendo o download de arquivos grandes ou carregando caches com antecedência. Com o uso de verificações de integridade atualizadas, é possível aumentar o tempo modificando a configuração app_start_timeout_sec na seção readiness_check do arquivo app.yaml.

Se a implantação falhar, verifique se a API Cloud Build está ativada no projeto. O App Engine ativa essa API automaticamente na primeira vez que você implanta um aplicativo, mas se alguém tiver desativado a API, as implantações falham.

Implantar um serviço

Implante o aplicativo no App Engine implantando as versões dos serviços dele e os respectivos arquivos de configuração.

Para implantar o serviço do aplicativo, execute o seguinte comando no diretório em que o arquivo app.yaml do serviço está localizado:

gcloud app deploy

Por padrão, o comando gcloud app deploy implanta apenas o arquivo app.yaml no diretório atual. Sempre que você executa esse comando, o App Engine gera um ID exclusivo para a versão implantada, implanta a versão no projeto do Google Cloud em que você configurou o uso da CLI gcloud e roteia todo o tráfego para a nova versão. A nova versão se torna a padrão.

Observação: é recomendável verificar a página Versões do App Engine no console do Google Cloud ou executar gcloud app versions list depois de executar o comando gcloud app deploy para verificar a versão que está recebendo tráfego.

É possível alterar o comportamento padrão do comando implantar segmentando arquivos específicos, especificando versões ou incluindo outros parâmetros:

• Para implantar os outros arquivos de configuração do serviço, segmente e implante cada arquivo separadamente. Por exemplo:

  gcloud app deploy cron.yaml
  gcloud app deploy dispatch.yaml
  gcloud app deploy index.yaml
  

• Para especificar um ID de versão personalizado, use a sinalização --version.

• Para impedir que o tráfego seja roteado automaticamente para a nova versão, use a sinalização --no-promote.

• Para implantar em um projeto específico do Google Cloud, use a sinalização --project.

Por exemplo, para implantar o serviço definido pelo arquivo app.yaml em um projeto específico do Google Cloud, atribua o serviço a um ID de versão personalizado e impeça que o tráfego seja roteado para a nova versão:

gcloud app deploy --project PROJECT_ID --version VERSION_ID --no-promote

Para mais informações, consulte a referência gcloud app deploy.

É possível definir propriedades para a CLI gcloud, assim como criar e gerenciar configurações do SDK. Dessa forma, não será preciso especificar sinalizações como --project a cada implantação.

Implantar vários serviços

Use o mesmo comando para implantar ou atualizar os diversos serviços que compõem seu aplicativo.

Antes de começar:

• Primeiro é preciso implantar uma versão do seu aplicativo no serviço default para depois criar e implantar os serviços posteriores.

• É necessário especificar o ID de cada serviço nos arquivos de configuração app.yaml correspondentes. Para especificar o ID do serviço, inclua a definição do elemento service em cada arquivo de configuração. Por padrão, a exclusão dessa definição de elemento do arquivo de configuração faz com que a versão seja implantada no serviço defaultdefault.

Para implantar vários serviços, é necessário implantar o arquivo app.yaml de cada serviço separadamente. Por exemplo:

gcloud app deploy service1/app.yaml
gcloud app deploy service2/app.yaml

Especifique vários arquivos com um único comando de implantação:

gcloud app deploy service1/app.yaml service2/app.yaml

Ignorar arquivos

É possível usar um arquivo .gcloudignore para especificar os arquivos e diretórios que não serão enviados ao Google Cloud ao implantar seus serviços. Isso é útil para ignorar artefatos de versão e outros arquivos que não precisam ser enviados com a implantação.

Observação: não será possível especificar o campo skip_files no arquivo app.yaml, caso você tenha um arquivo .gcloudignore.

Saiba mais sobre a sintaxe do arquivo .gcloudignore na referência do gcloud (em inglês).

Criar manualmente um contêiner para implantação

Atenção: o Container Registry foi descontinuado e está programado para ser desativado. As organizações que não usaram o Container Registry antes de 8 de janeiro de 2024 terão novos repositórios gcr.io hospedados no Artifact Registry por padrão. A partir de 15 de maio de 2024, os projetos Google Cloud sem uso anterior do Container Registry só vão ser compatíveis com a hospedagem e o gerenciamento de imagens para o domínio gcr.io no Artifact Registry.

A desativação do Container Registry está programada para 18 de março de 2025. Para detalhes sobre a descontinuação, consulte Suspensão de uso do Container Registry.

Para criar as imagens de contêiner fora do Google Cloud:

1. Faça upload das imagens para um repositório do Artifact Registry. Para mais informações, consulte Enviar e extrair imagens.
2. Implante no App Engine com o comando gcloud app deploy.

Por exemplo, ao criar localmente imagens de contêiner com o Docker, envie-as para o Artifact Registry e especifique o URL correspondente na sinalização --image-url do comando:

gcloud app deploy --image-url LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE

Substitua:

• LOCATION pelo local do repositório em que a imagem está armazenada.

• PROJECT-ID com o Google Cloud ID do projeto.

• REPOSITORY pelo nome do repositório em que a imagem está armazenada.

• IMAGE pelo nome da imagem do contêiner.

Use pipelines de implantação contínua automatizados

Use o Cloud Build para automatizar implantações em pipelines de implantação contínua. Para mais informações, consulte Como implantar no App Engine e Criar e gerenciar gatilhos de build na documentação do Cloud Build.

Imagens de base do Docker

Se quiser criar um aplicativo de ambiente de execução personalizado, consulte Criar um arquivo do Docker.

mostrar o aplicativo

Depois de implantar o aplicativo no App Engine, execute o comando a seguir para iniciar o navegador e visualizá-lo em https://PROJECT_ID.REGION_ID.r.appspot.com:

gcloud app browse

Testar no App Engine

Antes de configurar uma nova versão para receber tráfego, teste-a no App Engine. Por exemplo, para testar uma nova versão do seu serviço default, siga estas etapas:

1. Implante sua nova versão e inclua a sinalização --no-promote:

   gcloud app deploy --no-promote

2. Acesse a nova versão no URL a seguir:

   https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

   Observação: você encontra o ID da versão no console do Google Cloud ou especifica um ao implantar com o parâmetro version.

   Agora você pode testar sua nova versão no ambiente de execução do App Engine. Depure o aplicativo visualizando os registros no Visualizador de registros do console do Google Cloud. Para saber mais informações, consulte Como gravar registros de aplicativos.

   As solicitações enviadas para https://PROJECT_ID.REGION_ID.r.appspot.com ainda serão encaminhadas para a versão configurada anteriormente para receber tráfego.

3. Quando você quiser enviar tráfego para a nova versão, use o console do Google Cloud para migrá-lo:

   Gerenciar versões

   Selecione a versão que você acabou de implantar e clique em Migrar tráfego.

Use o mesmo processo para testar novas versões de outros serviços substituindo default no URL pelo nome do serviço:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

Para mais informações sobre como segmentar serviços e versões específicos, consulte Como as solicitações são encaminhadas.

Usar variáveis de ambiente de build

Também é possível definir variáveis de ambiente de build para ambientes de execução compatíveis com buildpacks.

As variáveis de ambiente de build são pares de chave-valor que você pode especificar para configurar o buildpack usado para implantar o app. Por exemplo, é possível especificar opções de compilador.

Antes de começar:

• As chaves precisam começar com uma letra ASCII maiúscula e podem incluir letras ASCII maiúsculas, dígitos e sublinhados.
• Evite criar variáveis com um prefixo de chave GOOGLE_*.
• As seguintes chaves são reservadas para uso do Google:
  • GOOGLE_RUNTIME
  • GOOGLE_RUNTIME_VERSION
  • GOOGLE_ENTRYPOINT
  • GOOGLE_DEVMODE
• Você pode usar qualquer chave aceita pelos buildpacks.

Para usar variáveis de ambiente com buildpacks, especifique o campo build_env_variables no seu arquivo app.yaml.

Saiba mais sobre buildpacks.

Usar o Cloud Trace

O Cloud Trace é útil para entender como as solicitações se propagam pelo aplicativo. É possível analisar informações detalhadas sobre a latência de uma única solicitação ou ver a latência agregada do aplicativo como um todo.

É possível visualizar detalhes do trace. No explorador de traces, é possível filtrar por serviço e versão específicos do App Engine.

Resolver problemas

Veja mensagens de erro comuns que você talvez encontre ao implantar aplicativos:

PERMISSION_DENIED: Operation not allowed

The "appengine.applications.create" permission is required.

Se o projeto do Google Cloud não incluir o aplicativo necessário do App Engine, o comando gcloud app deploy pode falhar ao tentar executar o comando gcloud app create. Somente contas com o papel Proprietário têm as permissões necessárias para criar aplicativos do App Engine.

502 Bad Gateway

O projeto do Google Cloud poderá falhar ao iniciar se o app.yaml estiver configurado incorretamente. Verifique os registros do aplicativo para ver mensagens de erro mais detalhadas.

[13] An internal error occurred while creating a Cloud Storage bucket.

O App Engine cria um bucket multirregional padrão do Cloud Storage em seu nome na mesma região em que cria o aplicativo. Ele exige que esse bucket armazene o conteúdo do aplicativo. O erro é retornado quando não é possível criar o bucket, como nos cenários a seguir:

• O agente de serviço do ambiente flexível do App Engine não está presente no projeto ou não tem o papel App Engine flexible environment Service Agent. É possível adicionar a conta de serviço do agente novamente ao projeto ao conceder a ela as permissões corretas do IAM. Consulte Restaurar um agente de serviço excluído.

• A conta de serviço padrão do App Engine não está presente no projeto. Se a conta de serviço do App Engine foi removida antes de 30 dias desde a exclusão, é possível restaurá-la.

• O projeto está em uma organização que aplica a política constraints/gcp.resourceLocations e a organização não permite a criação de recursos na mesma região em que o App Engine foi criado. É preciso substituir a política constraints/gcp.resourceLocations aplicada ao projeto e permitir os locais multirregionais na mesma região em que o aplicativo do App Engine é criado.

Por exemplo, se o aplicativo do App Engine for criado na região europe-west, mesmo que a região seja mapeada para locais europe-west1 , você precisará modificar a restrição para permitir recursos em in:eu-locations, que inclui todas as regiões EU.. Isso é necessário porque os buckets criados do App Engine são multirregionais. Se o aplicativo do App Engine for criado na região US, você precisará permitir in:us-locations, e se o aplicativo for criado nas regiões ASIA, será necessário permitir in:asia-locations.

[13] An internal error occurred.

Esse erro poderá ocorrer se você implantar o serviço com uma configuração de rede que usa uma configuração de VPC compartilhada. Tente o seguinte:

1. Verifique se a configuração app.yaml é válida.
2. Verifique se o ambiente flexível do App Engine atende a todos os requisitos de uma configuração de VPC compartilhada. Consulte Como usar o ambiente flexível do App Engine em uma rede VPC compartilhada.
3. Verifique se você configurou as contas de serviço no projeto. Caso contrário, você precisará restaurar as contas. A região da sub-rede no projeto host da VPC compartilhada precisa corresponder ao local em que o ambiente do App Engine foi criado.

Se o problema persistir, reimplante o serviço usando o SDK do Google Cloud. Adicione a sinalização --verbosity=debug. Entre em contato com o suporte doGoogle Cloud e forneça a saída do comando.

IP space of {USER_SUBNETWORK_NAME} is exhausted and needs to be expanded.

Se a implantação falhar com essa mensagem de erro, a rede configurada para o serviço do App Engine não tem endereços para alocar para as novas instâncias do serviço. Para resolver o problema, expanda os intervalos da VPC na sub-rede configurada para o serviço de ambiente flexível do App Engine.