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 Alteração da 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.

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:

A criação falha ao executar um aplicativo Node.js

Erros de build podem ocorrer quando você implanta um aplicativo Node.js.

Por padrão, o ambiente de execução do Node.js vai executar npm run build se um script de build for detectado no arquivo package.json. Isso pode causar comportamentos inesperados, como builds de longa duração ou erros de memória insuficiente.

Para resolver esse problema, especifique NODE_ENV=development no arquivo app.yaml para garantir que a execução tenha todas as dependências necessárias.

Apesar do erro, é possível forçar a produção especificando NODE_ENV: 'production' em build-env-variables no arquivo app.yaml:

  build_env_variables:
    NODE_ENV: 'production'

Para mais informações, consulte Como executar etapas personalizadas de versão durante a implantação.