Resolver problemas de implantação no App Engine

Vários fatores podem causar erros de implantação no App Engine, incluindo permissões ausentes, mudanças nas políticas da organização e problemas na configuração do app.

Esta página descreve os seguintes erros de implantação comuns no App Engine e métodos para resolvê-los:

Erros de permissão

Esta seção descreve os erros que podem ocorrer ao implantar seu app devido a permissões de conta ausentes ou alterações nas políticas da organização.

Para identificar a conta ativa que você usa para acessar a Google Cloud CLI e outras ferramentas na Google Cloud plataforma, faça o seguinte:

  • Se você usou a Google Cloud CLI para implantar, execute o comando gcloud auth list.

  • Se você implantou em um ambiente de desenvolvimento integrado, veja as configurações do plug-in do Cloud Tools.

Para saber por que apenas atribuir o papel de Implantador do App Engine (roles/appengine.deployer) pode não ser suficiente em alguns casos, consulte os Papéis do App Engine.

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Falha na implantação de novos projetos

Você pode ver o seguinte erro ao implantar seu aplicativo pela primeira vez em um novo projeto:

ERROR: (gcloud.app.deploy) Error Response: [13] Failed to create cloud build: com.google.net.rpc3.client.RpcClientException:..........invalid bucket "staging.PROJECT_ID.appspot.com"; service account PROJECT_ID@appspot.gserviceaccount.com does not have access to the bucket

Para resolver esse problema, conceda o papel Administrador do Storage (roles/storage.admin) à conta de serviço padrão. Para mais informações, consulte Armazenar registros de build em um bucket criado pelo usuário.

Se você já concedeu o papel de administrador do Storage, com as outras funções necessárias com base em diferentes erros de permissão encontrados durante a implantação, e ainda não consegue implantar seu app, isso pode ser devido às seguintes alterações nas políticas da organização:

  • Desde maio de 2024, Google Cloud aplica políticas da organização com segurança por padrão a todos os recursos da organização. Essa política impede que o App Engine conceda o papel Editor às contas de serviço padrão do App Engine.

  • Em junho de 2024, o Cloud Build mudou o comportamento padrão de como o Cloud Build usa contas de serviço em novos projetos. Confira mais detalhes em Mudança na conta de serviço do Cloud Build. Como resultado dessa mudança, novos projetos que implantam versões pela primeira vez podem usar a conta de serviço padrão do App Engine com permissões insuficientes para implantar versões.

Para resolver esse problema, faça o seguinte:

O autor da chamada não tem permissão para acessar o projeto

O erro a seguir ocorre se a conta de serviço não tiver permissão para implantar apps no projeto atual:

User EMAIL_ADDRESS does not have permission to access project PROJECT_ID (or it may not exist).

Para resolver esse problema, conceda o papel Implantador do App Engine (roles/appengine.deployer) à conta de serviço.

Falha ao buscar metadados pelo registro

O erro a seguir ocorre se você usar o comando gcloud app deploy de uma conta de serviço que não tem o papel Administrador do Storage (roles/storage.admin):

Failed to fetch metadata from the registry, with reason: generic::permission_denied

Para resolver esse problema, conceda o papel de administrador do Storage à conta de serviço.

As contas de serviço precisam ter permissões na imagem.

O seguinte erro ocorre ao implantar o app:

The App Engine appspot and App Engine flexible environment service accounts must
have permissions on the image IMAGE_NAME

Esse erro ocorre por um dos seguintes motivos:

Falha ao criar o Cloud Build

O erro a seguir ocorre se você usar o comando gcloud app deploy de uma conta de serviço que não tem o papel de Editor do Cloud Build (roles/cloudbuild.builds.editor).

Failed to create cloud build: Permission denied

Para resolver esse problema, conceda o papel de editor do Cloud Build à conta de serviço.

Erro ao buscar o aplicativo

O erro a seguir ocorre quando a conta de serviço usada para implantar o app não tem o papel de Implantador do App Engine.

Permissions error fetching application apps/app_name. Please make sure you are using the correct project ID and that you have permission to view applications on the project.

If you are running Google Cloud CLI version 328 or later, the following error occurs
when you deploy your app:

make sure that you have permission to view applications on the project and that
SERVICE_ACCOUNT has the App Engine Deployer (roles/appengine.deployer) role.

Para resolver esse problema, conceda o papel de Implantador do App Engine à conta de serviço usada para implantar o app.

Erro ao implantar um serviço com um conector de acesso VPC sem servidor

O erro a seguir ocorre quando o usuário ou a conta de serviço que está tentando implantar o app com um conector de acesso VPC sem servidor não tem as permissões necessárias:

Please ensure you have [compute.globalOperations.get] on the service project

Para resolver esse problema, verifique se o usuário ou a conta de serviço usada para a implantação tem os papéis Usuário de acesso VPC sem servidor e IAM do visualizador do Compute.

Tempo limite excedido para a infraestrutura do app se tornar íntegra

O seguinte erro ocorre ao implantar o app:

Timed out waiting for the app infrastructure to become flex_await_healthy

Vários fatores podem causar esse erro, como permissões ausentes, erros de código, CPU ou memória insuficiente ou verificações de integridade com falha.

Para resolver esse problema, elimine as seguintes causas possíveis:

  1. Verifique se a política da organização do seu projeto restringe o acesso a endereços IP externos. Para mais informações, consulte Problemas conhecidos do ambiente flexível do App Engine.

  2. Verifique se você concedeu os seguintes papéis à conta de serviço usada para executar o aplicativo (geralmente a conta de serviço padrão, app-id@appspot.gserviceaccount.com):

  3. Conceda os papéis restantes com base nos erros de implantação, se a conta de serviço não tiver.

  4. Se você implantar em uma configuração de VPC compartilhada e configurar um instance_tag no arquivo app.yaml, consulte Erro de valor inválido ao implantar em uma configuração de VPC compartilhada para corrigir o problema.

Erro ao reiniciar instâncias em versões em execução

O seguinte erro ocorre ao implantar o app:

error when restarting the instance under the running versions

Desde maio de 2024, Google Cloud o Google Cloud aplica as políticas da organização com segurança por padrão a todas as novas organizações. Essa política exige que todas as instâncias de VM criadas em novos projetos ativem o VM Manager. Nos projetos novos e atuais, essa restrição impede atualizações de metadados que desativem o VM Manager no nível do projeto e da instância.

Para resolver esse problema, desative a restrição da política da organização Requer configuração do SO (constraints/compute.requireOsConfig).

Se o problema persistir, desative as políticas a seguir que podem ter sido ativadas no nível do projeto ou da organização:

Permissão compute.firewalls.list necessária

O seguinte erro ocorre quando você implanta o aplicativo em uma rede VPC compartilhada:

Request to https://compute.googleapis.com/compute/v1/projects/projects/PROJECT_ID/global/firewalls?key failed, details: Required 'compute.firewalls.list' permission for 'projects/PROJECT_ID'

Esse erro ocorrerá se as seguintes contas de serviço do projeto host não tiverem o papel de Usuário da rede do Compute (roles/compute.networkUser):

Para resolver esse problema, conceda o papel de usuário da rede do Compute às contas de serviço do agente de serviço de APIs do Google e de agente de ambiente do App Engine para o projeto host.

A implantação falha devido a uma restrição de política da organização

O seguinte erro ocorre ao implantar um app:

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred while processing task /app-engine-flex/....: Request to https://compute.googleapis.com/compute/VERSION/projects/PROJECT_ID/... failed, details: Constraint constraints/compute.disableGuestAttributesAccess violated for project PROJECT_ID.

Isso pode ser devido à aplicação da restrição constraints/compute.disableGuestAttributesAccess ao implantar o app. Todos os apps no ambiente flexível do App Engine aplicam essa política da organização por padrão.

Para resolver esse problema, desative a restrição constraints/compute.disableGuestAttributesAccess.

Erros comuns de implantação

Esta seção descreve estratégias de solução de problemas para erros de configuração no app ou projeto.

Erro de valor inválido ao implantar em uma configuração de VPC compartilhada

O seguinte erro é exibido no Cloud Logging para instâncias de VM flexíveis quando você implanta o app:

Invalid value for field 'resource.tags.items[1]': 'aef-instance'. Duplicate
tags are not allowed: aef-instance on compute.instances.insert

Esse é um problema conhecido em que a configuração de instance_tag no arquivo app.yaml resulta em erros ao criar instâncias.

Para resolver o problema, remova o campo instance_tag do arquivo app.yaml e reimplante.

Erros ao implantar apps com até três instâncias ou menos

Apps implantados com max_instances definido como 3 ou menos podem apresentar erros ou inatividade inesperados. Para resolver o problema, especifique pelo menos quatro instâncias máximas no arquivo app.yaml e implante novamente.

Exceder o limite de instâncias máximas

O seguinte erro ocorre ao implantar o app:

You may not have more than 'xx' total max instances in your project.

Há um limite para o número máximo de instâncias que podem ser criadas por projeto. As solicitações para criar instâncias extras falharão se você exceder esse limite.

Para resolver esse problema, defina o valor de max_instances no arquivo app.yaml como um valor abaixo desse limite ou exclua alguns serviços ou versões para somar max_instances dentro do limite.

A criação durante a implantação apresenta falha sem erros nos registros

O seguinte erro ocorre ao implantar o app:

ERROR: (gcloud.app.deploy) Cloud build failed. Check logs at https://console.cloud.google.com/cloud-build/builds/BUILD_ID?project=PROJECT_NUMBER Failure status: UNKNOWN: Error Response: [2] Build failed; check build logs for details

Se você clicar no link na mensagem de erro e descobrir que todas as etapas de criação foram concluídas, mas o app ainda não foi criado, isso pode ser devido a um dos seguintes motivos:

Para resolver esse problema, mude as seguintes configurações do bucket:

Erros ao implantar em uma versão do App Engine

O seguinte erro pode ocorrer ao implantar em uma versão existente no ambiente flexível do App Engine:

ERROR: (gcloud.app.deploy) Error Response: [9] An internal error occurred while
processing task /app-engine-flex/flex_await_healthy/flex_await_healthy

Esse erro indica que a atualização de uma implantação não íntegra com uma imagem Docker funcional nem sempre resulta em uma implantação íntegra. O resultado depende do estado das instâncias da implantação não íntegra. Apesar do erro, se você fornecer uma boa imagem Docker, a implantação poderá se tornar íntegra. Atualizar uma versão existente com uma nova imagem Docker, embora seja permitido, não é uma prática recomendada. Não há reversão em caso de falha da versão.