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

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. Recomendamos que você use ferramentas padrão do Python, como virtualenv para criar ambientes isolados e pytest para executar testes de unidade e testes de integração, em vez de depender de dev_appserver, o servidor de desenvolvimento local fornecido com o SDK Google Cloud.

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, execute o servidor de interface de gateway do servidor da Web (WSGI, na sigla em inglês) completo localmente. Use o mesmo comando especificado como ponto de entrada no arquivo app.yaml, por exemplo:

gunicorn -b :$PORT main:app

Antes de implantar o aplicativo

Antes de implantar o 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.

implantar o aplicativo

Implante o aplicativo no App Engine usando o comando gcloud app deploy. Durante a implantação, o serviço Cloud Build cria uma imagem de contêiner do seu aplicativo para ser executada no ambiente padrão. Cada build é executado na mesma região do projeto do Google Cloud. Para saber mais, consulte Gerenciar imagens de build.

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

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 uma versão do serviço do seu aplicativo, execute o comando a seguir no diretório em que o arquivo app.yaml do serviço está localizado:

gcloud app deploy

Se você não especificar um arquivo com o comando, somente o arquivo app.yaml será implantado no diretório atual. Por padrão, o comando deploy gera um ID exclusivo para a versão a ser implantada, implanta a versão no projetoGoogle Cloud que você configurou para usar a CLI do Google Cloud e encaminha todo o tráfego para a nova versão.

É possível alterar o comportamento padrão do comando. Basta apontar arquivos específicos ou incluir outros parâmetros:

• Para implantar os outros arquivos de configuração do serviço, é necessário direcionar e implantar cada um deles separadamente. 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 Google Cloud específico, use a flag --project.

Por exemplo, para implantar o serviço definido pelo arquivo app.yaml em um projeto Google Cloud específico, atribua a ele 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 sobre esse comando, consulte a referência do gcloud app deploy.

Observação: defina propriedades para a Google Cloud CLI, crie e gerencie configurações do SDK para não ter que especificar sinalizações como --project toda vez que você fizer uma 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 serviços posteriores.
• O ID de cada serviço precisa ser especificado nos arquivos de configuração app.yaml correspondentes. Para fazer isso, 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 default.

Para implantar vários serviços, implante o arquivo app.yaml de cada serviço separadamente. É possível especificar vários arquivos com um único comando gcloud app deploy:

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

Veja os registros das versões

Os streams do Cloud Build criam e implantam registros visíveis na seção de histórico do Build do Console do Google Cloud. Para ver os builds na região do app, use o menu Região para filtrar por região.

Gerenciar imagens de build

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 Descontinuação do Container Registry.

Cada vez que você implanta uma nova versão:

1. O App Engine cria uma imagem de contêiner usando o serviço Cloud Build.

2. O Cloud Build cria a imagem do contêiner na região do aplicativo e é executada no ambiente padrão do App Engine.

3. O App Engine armazena as imagens de contêiner criadas no Artifact Registry. É possível fazer o download dessas imagens para guardá-las ou executá-las em outro lugar.

Depois da conclusão da implantação, o App Engine não precisa mais das imagens de contêiner. As imagens do contêiner não são excluídas automaticamente. Para evitar atingir sua cota de armazenamento, é possível excluir com segurança todas as imagens desnecessárias. No entanto, se você precisar das imagens no futuro ou quiser manter uma cópia delas, precisará exportar uma cópia antes da exclusão. Para mais informações sobre como gerenciar imagens no Artifact Registry, consulte Gerenciar imagens.

Ignorar arquivos

É possível usar um arquivo .gcloudignore para especificar arquivos e diretórios que não serão enviados ao App Engine quando você implantar os 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.

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 transferir tráfego

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 serviço default, siga estas etapas:

1. Implante a nova versão, mas impeça que o tráfego seja roteado automaticamente para ela:

   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: encontre o ID da versão no console do Google Cloud ou especifique um ao implantar com o --version flag. A Google Cloud CLI também exibe o ID da versão durante a implantação.

   Agora você pode testar sua nova versão no ambiente de execução do App Engine. Além disso, é possível depurar o aplicativo visualizando os registros. Para obter mais informações, consulte Como gravar registros de aplicativos.

   O App Engine encaminha as solicitações enviadas a https://PROJECT_ID.REGION_ID.r.appspot.com 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 servidor de desenvolvimento local

A Google Cloud CLI inclui um servidor de desenvolvimento local chamado dev_appserver que você pode executar localmente para simular o aplicativo em execução no App Engine de produção. Esse servidor de desenvolvimento simula parcialmente o ambiente em que seu aplicativo é executado, permitindo testar apps escritos para qualquer um dos ambientes de execução padrão.

Executar o servidor de desenvolvimento local

Importante:

• Antes de executar o servidor de desenvolvimento local, siga as instruções de configuração.
• A ferramenta dev_appserver não é compatível com o desenvolvimento de aplicativos Python 3 no Windows.

Depois de criar o arquivo de configuração app.yaml para seu aplicativo, inicie o servidor de desenvolvimento local com o comando dev_appserver.py para executá-lo localmente.

1. Para receber as credenciais de acesso da sua conta de usuário, execute:

   gcloud auth login
   

2. Permita que seu aplicativo local use temporariamente suas credenciais de usuário para acesso à API:

   gcloud auth application-default login
   

3. Para iniciar o servidor de desenvolvimento local:

   No diretório que contém o arquivo de configuração app.yaml, execute o comando dev_appserver.py e especifique o ID do projeto e o caminho para o arquivo app.yaml:

   python3 CLOUD_SDK_ROOT/bin/dev_appserver.py --application=PROJECT_ID app.yaml

   Para alterar a porta, inclua a opção --port:

   python3 CLOUD_SDK_ROOT/bin/dev_appserver.py --application=PROJECT_ID app.yaml --port=9999

   Para testar um aplicativo Python 3, execute dev_appserver.py com um interpretador do Python 3. É necessário especificar o binário do Python 3 na sinalização --runtime_python_path, por exemplo:

   python3 CLOUD_SDK_ROOT/bin/dev_appserver.py --runtime_python_path=/usr/bin/python3 --application=PROJECT_ID app.yaml --port=9999

   Saiba mais sobre as opções do comando dev_appserver.py em Opções do servidor de desenvolvimento local.

4. Depois que o servidor de desenvolvimento local for iniciado, ele configurará um ambiente de desenvolvimento que pré-instala as dependências encontradas no seu arquivo requirements.txt.

5. O servidor de desenvolvimento local já está sendo executado e detectando solicitações. Visite http://localhost:8080/ no navegador da Web para ver o aplicativo em ação.

   Caso tenha especificado uma porta personalizada com a opção --port, lembre-se de abrir essa porta no navegador.

6. Para parar o servidor local a partir da linha de comando, pressione Control-C no teclado.

Detectar o ambiente de execução do aplicativo

Para determinar se o código está sendo executado no servidor de desenvolvimento de produção ou local, verifique a variável de ambiente GAE_ENV:

if os.getenv('GAE_ENV', '').startswith('standard'):
  # Production in the standard environment
else:
  # Local execution.

Usar o servidor de desenvolvimento local com serviços Google Cloud

É possível integrar dev_appserver a outros componentes Google Cloud .

Bibliotecas de cliente do Cloud

Muitas bibliotecas de cliente do Google Cloud dependem da presença da variável de ambiente GOOGLE_CLOUD_PROJECT, que precisa ser o ID do projeto do Google Cloud. Encontre o valor dele executando o comando gcloud config list project ou olhando a página do projeto no console do Google Cloud.

Para garantir que essa variável de ambiente seja definida corretamente durante o desenvolvimento local, inicialize dev_appserver usando o parâmetro --application=PROJECT_ID, conforme mostrado no exemplo acima.

Emuladores do Cloud

É possível testar o aplicativo com emuladores para Cloud Datastore, Cloud Bigtable e Cloud Pub/Sub.

Atualizar automaticamente as alterações em requirements.txt e app.yaml

O servidor de desenvolvimento local instala automaticamente as dependências encontradas no seu arquivo requirements.txt. O dev_appserver também permite que você teste a funcionalidade configurada por app.yaml. Por exemplo, é possível testar a capacidade do aplicativo de exibir arquivos estáticos. Quando o dev_appserver está em execução, qualquer alteração em requirements.txt e app.yaml reinicia o aplicativo automaticamente para refletir essas alterações. Isso pode resultar em um atraso temporário à medida que são feitos o download e a instalação das dependências.

Gerenciamento e roteamento de instâncias no servidor de desenvolvimento

Descubra endereços de instâncias

O servidor de desenvolvimento local cria todas as instâncias de escalonamento manuais na inicialização. As instâncias para serviços de escalonamento automáticos e básicos são gerenciadas dinamicamente. O servidor atribui uma porta a cada serviço, e os clientes podem depender do servidor para balancear a carga e selecionar automaticamente uma instância. As atribuições de porta para endereçar cada serviço são exibidas no streaming de mensagens de registro do servidor.

Aqui estão as portas de um app que define três serviços:

INFO Starting module "default" running at: http://localhost:8084
INFO Starting module "service1" running at: http://localhost:8082
INFO Starting module "service2" running at: http://localhost:8083

Quando você usa o endereço de um serviço, como http://localhost:8082/, o servidor cria ou seleciona uma instância do serviço e envia a solicitação para essa instância.

O servidor atribui portas exclusivas a cada instância de um serviço. Você pode usar o servidor admin para descobrir essas portas. Há uma porta exclusiva para o servidor de administrador, exibida no registro da mensagem:

INFO Starting admin server at: http://localhost:8000

Esse endereço leva você ao console do servidor de administrador. Clique em Instâncias para ver o estado dinâmico das instâncias do aplicativo.

Uma entrada separada aparece para cada instância manual e básica. Os números da instância são links com endereços de porta exclusivos para cada instância. Clique no link para enviar uma solicitação diretamente para essa instância.

Arquivos de expedição

Se o aplicativo incluir um arquivo dispatch.yaml, o stream de mensagens de registro incluirá uma porta do agente:

INFO Starting dispatcher running at: http://localhost:8080

As solicitações para essa porta são encaminhadas de acordo com as regras no arquivo de expedição. O servidor não oferece suporte a regras de arquivo dispatch.yaml, que incluem nomes de host, por exemplo, url: "customer1.myapp.com/*". Regras com padrões de caminho relativos (url: "*/fun") funcionam, então é possível usar URLs como http://localhost/fun/mobile para alcançar instâncias. O servidor relata um erro no stream de registros se você tentar iniciar um aplicativo com um arquivo dispatch.yaml que contenha regras baseadas no host.

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.

Para ver detalhes de trace no Cloud Trace, siga Encontrar e explorar traces. No explorer do Trace, você pode usar os filtros para filtrar por serviço e versão específicos do App Engine.