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 comuns de implantação no App Engine e métodos para resolver problemas:

Erros de permissão

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

Para identificar a conta ativa que você usa para acessar a Google Cloud CLI e outras ferramentas na plataforma Google Cloud , 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 mudanças nas políticas da organização:

  • Desde maio de 2024,o 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. Isso está detalhado 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 seguinte erro 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 seguinte erro 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:

  • A conta de serviço padrão do App Engine não tem o papel Leitor de objetos do Storage (roles/storage.objectViewer).

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

  • O projeto tem um perímetro de serviço do VPC Service Controls que limita o acesso à API Cloud Storage usando níveis de acesso.

    Para resolver esse problema, adicione a conta de serviço usada para implantar o app ao perímetro de serviço correspondente do VPC Service Controls accessPolicies.

  • Após 15 de maio de 2024, o Artifact Registry vai hospedar imagens para o domínio gcr.io em projetos Google Cloud sem uso anterior do Container Registry. Se você implantar um aplicativo em um novo projeto criado após essa data, a conta de serviço talvez não tenha as permissões necessárias para implantar o app. Para conceder as permissões necessárias, consulte Implantação no App Engine.

Falha ao criar o Cloud Build

O seguinte erro ocorre se você usar o comando gcloud app deploy de uma conta de serviço que não tem o papel 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 seguinte erro 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, caso a conta de serviço não os tenha.

  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,o Google Cloud aplica as políticas da organização 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 Exigir configuração do SO (constraints/compute.requireOsConfig).

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

Permissão de compute.firewalls.list obrigató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 flexível 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 ocorrer 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

Nesta seção, descrevemos estratégias de solução de problemas para erros de configuração no seu 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 implante novamente.

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 seu 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 build foram concluídas com êxito, 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 atual 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.

Erro de IP interno ao implantar em uma configuração de VPC compartilhada

O seguinte erro pode ocorrer ao implantar em uma configuração de rede VPC compartilhada em um projeto de serviço em que a configuração padrão de endereço IP particular (private-ranges-only) é usada.

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

Esse erro pode indicar que o agente de serviço do ambiente flexível do App Engine no projeto host da VPC compartilhada 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 host.

Para resolver o problema:

  1. Habilite a API App Engine no projeto host da rede VPC compartilhada.
  2. Se a API App Engine estiver ativada, o agente de serviço do ambiente flexível do App Engine não existirá no projeto. Consulte Restaurar o papel necessário para o agente de serviço.

Falha na implantação devido à falta de conectividade com as APIs do Google

O seguinte erro ocorre ao implantar o 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 esse problema, verifique se a VPC associada ao seu aplicativo tem uma rota estática local com o destino 0.0.0.0/0 e um próximo salto de gateway de Internet padrão. Se você usa serviços internos particulares, ative o PGA na sub-rede selecionada.