Resolva problemas de implementação no App Engine

Vários fatores podem causar erros de implementação no App Engine, incluindo autorizações em falta, alterações às políticas da organização e problemas na configuração da sua app.

Esta página descreve os seguintes erros de implementação comuns no App Engine e métodos para os resolver:

Erros de autorização

Esta secção descreve os erros que podem ocorrer quando implementa a sua app devido a autorizações de conta em falta ou alterações às políticas da organização.

Para identificar a conta ativa que usa para aceder à Google Cloud CLI e a outras ferramentas na Google Cloud plataforma, faça uma das seguintes ações:

  • Se usou a CLI do Google Cloud para a implementação, execute o comando gcloud auth list.

  • Se fez a implementação a partir de um IDE, veja as definições do plug-in Cloud Tools.

Para saber por que motivo a atribuição apenas da função App Engine Deployer (roles/appengine.deployer) pode não ser suficiente em alguns casos, consulte o artigo Funções do App Engine.

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

A implementação falha para novos projetos

Pode ver o seguinte erro quando implementar a sua app pela primeira vez num 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 este problema, conceda a função Administrador de armazenamento (roles/storage.admin) à conta de serviço predefinida. Para mais informações, consulte o artigo Armazene registos de compilação num contentor criado pelo utilizador.

Se já tiver concedido a função de administrador de armazenamento, juntamente com as outras funções necessárias com base nos diferentes erros de autorização que encontra durante a implementação, e ainda não conseguir implementar a sua app, tal pode dever-se às seguintes alterações às políticas da organização:

  • Desde maio de 2024,o Google Cloud aplica políticas da organização seguras por predefinição a todos os recursos da organização. Google Cloud Esta política impede o App Engine de conceder a função Editor às contas de serviço predefinidas do App Engine.

  • Em junho de 2024, o Cloud Build alterou o comportamento predefinido da forma como o Cloud Build usa as contas de serviço em novos projetos. Isto está detalhado no artigo Alteração da conta de serviço do Cloud Build. Como resultado desta alteração, os novos projetos que implementam versões pela primeira vez podem estar a usar a conta de serviço do App Engine predefinida com autorizações insuficientes para implementar versões.

Para resolver este problema, faça o seguinte:

O autor da chamada não tem autorização para aceder ao projeto

O seguinte erro ocorre se a conta de serviço não tiver autorização para implementar apps no projeto atual:

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

Para resolver este problema, conceda a função Implementador do App Engine (roles/appengine.deployer) à conta de serviço.

Falha ao obter metadados do registo

O seguinte erro ocorre se usar o comando gcloud app deploy a partir de uma conta de serviço que não tenha a função Administrador de armazenamento (roles/storage.admin):

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

Para resolver este problema, atribua a função de administrador de armazenamento à conta de serviço.

As contas de serviço têm de ter autorizações na imagem

Ocorre o seguinte erro quando implementa a sua app:

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

Este erro ocorre devido a um dos seguintes motivos:

  • A conta de serviço predefinida do App Engine não tem a função Visualizador de objetos do armazenamento (roles/storage.objectViewer).

    Para resolver este problema, conceda a função Storage Object Viewer à conta de serviço.

  • O seu projeto tem um perímetro de serviço dos VPC Service Controls que limita o acesso à API Cloud Storage através de níveis de acesso.

    Para resolver este problema, adicione a conta de serviço que usa para implementar a sua app ao perímetro de serviço dos VPC Service Controls correspondente accessPolicies.

  • Após 15 de maio de 2024, o Artifact Registry aloja imagens para o domínio gcr.io nos Google Cloud projetos sem utilização anterior do Container Registry. Se implementar uma aplicação existente num novo projeto criado após esta data, a conta de serviço pode não ter as autorizações necessárias para implementar a app. Para conceder as autorizações necessárias, consulte o artigo Implementação no App Engine.

Falha ao criar o Cloud Build

O seguinte erro ocorre se usar o comando gcloud app deploy a partir de uma conta de serviço que não tenha a função de Editor do Cloud Build (roles/cloudbuild.builds.editor).

Failed to create cloud build: Permission denied

Para resolver este problema, conceda a função de editor do Cloud Build à conta de serviço.

Erro ao obter a aplicação

O seguinte erro ocorre quando a conta de serviço que usou para implementar a sua app não tem a função de implementador 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 este problema, conceda a função App Engine Deployer à conta de serviço que usou para implementar a sua app.

Erro ao implementar um serviço com um conetor do Acesso a VPC sem servidor

O seguinte erro ocorre quando o utilizador ou a conta de serviço que está a tentar implementar a app com um conetor do Acesso a VPC sem servidor não tem as autorizações necessárias:

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

Para resolver este problema, certifique-se de que o utilizador ou a conta de serviço usada para a implementação tem as funções Utilizador do acesso a VPC sem servidor e IAM do leitor de computação.

Foi excedido o tempo limite enquanto aguardava que a infraestrutura da app ficasse em bom estado

Ocorre o seguinte erro quando implementa a sua app:

Timed out waiting for the app infrastructure to become flex_await_healthy

Vários fatores podem causar este erro, como autorizações em falta, erros de código, CPU ou memória insuficientes ou verificações de estado com falhas.

Para resolver este problema, elimine as seguintes potenciais causas:

  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 o artigo Problemas conhecidos do ambiente flexível do App Engine.

  2. Verifique se concedeu as seguintes funções à conta de serviço que usa para executar a sua aplicação (normalmente, a conta de serviço predefinida, app-id@appspot.gserviceaccount.com):

  3. Conceda as funções restantes com base nos erros de implementação, se a conta de serviço não as tiver.

  4. Se fizer a implementação numa configuração de VPC partilhada e configurar um instance_tag no ficheiro app.yaml, consulte o artigo Erro de valor inválido ao fazer a implementação numa configuração de VPC partilhada para corrigir o problema.

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

Ocorre o seguinte erro quando implementa a sua app:

error when restarting the instance under the running versions

Desde maio de 2024, Google Cloud aplica as políticas organizacionais seguras por predefinição a todas as novas organizações. Esta política requer que todas as instâncias de VM criadas em novos projetos ativem o VM Manager. Para projetos novos e existentes, esta restrição impede atualizações de metadados que desativam o VM Manager ao nível do projeto ou da instância.

Para resolver este problema, tem de desativar a restrição da política da organização Require OS Config (constraints/compute.requireOsConfig).

Se este problema persistir, também tem de desativar as seguintes políticas da organização que podem ter sido ativadas ao nível do projeto ou da organização:

Autorização compute.firewalls.list necessária

Ocorre o seguinte erro quando implementa a sua app numa rede de VPC partilhada:

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'

Este erro ocorre se as seguintes contas de serviço do projeto anfitrião não tiverem a função Utilizador da rede de computação (roles/compute.networkUser):

Para resolver este problema, conceda a função de utilizador da rede de computação às contas de serviço do agente de serviço das APIs Google e do agente de serviço do ambiente flexível do App Engine para o projeto anfitrião.

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

Ocorre o seguinte erro quando implementa uma 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.

Isto pode dever-se à aplicação da restrição constraints/compute.disableGuestAttributesAccess quando implementa a sua app. Todas as apps no ambiente flexível do App Engine aplicam esta política organizacional por predefinição.

Para resolver este problema, tem de desativar a restrição constraints/compute.disableGuestAttributesAccess.

Erros de implementação comuns

Esta secção descreve as estratégias de resolução de problemas para erros de configuração na sua app ou projeto.

Erro de valor inválido ao implementar numa configuração de VPC partilhada

O seguinte erro é apresentado no Cloud Logging para instâncias de VM flexíveis quando implementa a sua app:

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

Este é um problema conhecido em que a definição do elemento instance_tag no ficheiro app.yaml resulta em erros ao criar instâncias.

Para resolver o problema, remova o campo instance_tag do ficheiro app.yaml e implemente novamente.

Exceder o limite de instâncias máximas

Ocorre o seguinte erro quando implementa a sua app:

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

Existe um limite para o número máximo de instâncias que pode criar por projeto. As solicitações para criar instâncias adicionais falham se exceder este limite.

Para resolver este problema, defina o valor de max_instances no seu ficheiro app.yaml para um valor inferior a este limite ou elimine alguns serviços ou versões para que a soma de max_instances fique dentro do limite.

A compilação durante a implementação falha sem erros nos registos

Ocorre o seguinte erro quando implementa a sua 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 clicar no link na mensagem de erro e verificar que todos os passos de compilação foram bem-sucedidos, mas a compilação da app continua a falhar, tal pode dever-se a um dos seguintes motivos:

Para resolver este problema, altere as seguintes definições do seu contentor:

Erros ao implementar numa versão existente do App Engine

O seguinte erro pode ocorrer quando fizer a implementação numa 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

Este erro indica que a atualização de uma implementação não saudável com uma imagem do Docker funcional nem sempre resulta numa implementação saudável. O resultado depende do estado das instâncias da implementação não saudável. Apesar do erro, se fornecer uma boa imagem do Docker, a implementação pode eventualmente ficar em bom estado. A atualização de uma versão existente com uma nova imagem do Docker, embora permitida, não é uma boa prática. Não existe reversão em caso de falha da versão.

Erro de IP interno ao implementar numa configuração de VPC partilhada

O seguinte erro pode ocorrer quando implementa numa rede de VPC partilhada configurada num projeto de serviço onde é usada a predefinição de endereço IP privado (private-ranges-only).

ERROR: (gcloud.app.deploy) Error Response: [13] An internal error occurred.

Este erro pode indicar que o agente de serviço do ambiente flexível do App Engine no projeto de anfitrião da VPC partilhada não está disponível. O agente de serviço do ambiente flexível do App Engine foi removido ou a API App Engine não está ativada no projeto anfitrião.

Para resolver este problema:

  1. Ative a API App Engine no projeto anfitrião da rede VPC partilhada.
  2. Se a API App Engine estiver ativada, o agente de serviço do ambiente flexível do App Engine não existe no projeto. Consulte o artigo Restaurar a função necessária para o agente do serviço.

Falha na implementação devido à falta de conetividade com as APIs Google

Ocorre o seguinte erro quando implementa a sua app:

Your deployment has failed to become healthy in the allotted time and therefore was rolled back. If you believe this was an error, try adjusting the app_start_timeout_sec setting in the readiness_check section.

Para resolver este problema, certifique-se de que a VPC associada à sua aplicação tem uma rota estática local com o destino 0.0.0.0/0 e um próximo salto do gateway de Internet predefinido. Se usar serviços privados apenas internos, ative a PGA na sub-rede selecionada.