Configurar um único projeto

Neste documento, descrevemos como configurar um único projeto do Google Cloud para gerenciar aplicativos. Essa configuração também é conhecida como o limite de projeto único.

Nessa configuração, o projeto Google Cloud é configurado para gerenciar os próprios aplicativos e componentes, atuando como um projeto de gerenciamento independente. Essa abordagem é a maneira mais rápida de começar a gerenciar aplicativos se todos os componentes de aplicativo estiverem nesse único projeto. O App Hub descobre automaticamente todos os recursos compatíveis no projeto, deixando-os prontos para serem organizados em aplicativos.

Limitações

O limite de projeto único tem suporte a recursos diferente do limite no nível da pasta. O App Hub, o Application Design Center e o Application Monitoring oferecem suporte total a projetos únicos, mas outros serviços do Google Cloud centrados em aplicativos, como o Cloud Hub e o Gemini Cloud Assist, exigem um limite no nível da pasta.

Para uma comparação do suporte a recursos entre os modelos de projeto único e de pasta, consulte Suporte a recursos por tipo de limite.

Antes de começar

Escolha o projeto do Google Cloud que você quer usar para gerenciar seus aplicativos. Esse projeto vai funcionar como o projeto de gerenciamento independente. Use um projeto atual ou crie um novo.

Funções exigidas

Para receber as permissões necessárias para configurar um único projeto para gerenciamento de aplicativos, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto que você quer configurar como o projeto de gerenciamento independente:

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

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar o gerenciamento de aplicativos em um projeto

Essa ação configura o projeto como um projeto de gerenciamento independente e ativa as APIs necessárias para metadados e configurações de aplicativos. O projeto é chamado de projeto com app ativado.

Para ativar o gerenciamento de aplicativos em um único projeto, siga estas etapas:

Console

  1. No console do Google Cloud , use o seletor de projetos para selecionar seu projeto.

  2. Acesse a página Visão geral no App Hub:

    Ir para Visão geral

  3. Clique em Configurar o App Hub.

    Se o projeto já estiver em uma pasta habilitada para apps, a página não vai mostrar a opção Configurar o App Hub. Em vez disso, você vai precisar selecionar a pasta habilitada para apps ou usar o projeto atual em um menu. Selecione o projeto atual para continuar com a configuração de projeto único. Para saber mais sobre as considerações de hierarquia de recursos para o gerenciamento de aplicativos, consulte Planejar sua hierarquia de recursos para o gerenciamento de aplicativos.

  4. Na página Ativar o App Hub, escolha uma das seguintes opções:

    • Configuração rápida: gerencie uma configuração padrão para recursos neste projeto e defina seu primeiro aplicativo para adoção inicial.
    • Configuração completa: gerencie configurações personalizadas para seus aplicativos, incluindo a configuração de controles de acesso antecipados e, opcionalmente, a adição de mais projetos para limites de vários projetos.

  5. Anote o nome e o ID do projeto. Essas informações identificam o projeto de gerenciamento, e você vai usar esses valores para conceder acesso.

  6. Revise a lista de APIs que estão sendo ativadas. Algumas APIs têm custos associados. Saiba mais sobre os custos das APIs ou clique em cada uma delas para ver os custos associados.

  7. Clique em Continuar.

  8. Conclua a configuração com base na sua seleção:

    • Se você selecionou Configuração rápida, a guia Definir aplicativo permite definir um aplicativo agora ou concluir a configuração sem criar um. Agora você pode criar aplicativos e registrar recursos neles. Você também pode começar com um guia de início rápido para aplicativos.

    • Se você selecionou Configuração completa, conceda acesso personalizado centrado em aplicativos para seus administradores:

      1. Na guia Definir limite, verifique as informações do projeto. A tabela Projetos no seu limite mostra apenas o projeto que define seu limite de projeto único. Para a configuração de limite de projeto único, não adicione outros projetos.

      2. Clique em Continuar.

      3. Na guia Conceder acesso, escolha os papéis e permissões do IAM adequados para administradores no projeto. Para conferir uma lista de papéis recomendados focados em aplicativos nos produtos do Google Cloud , consulte Conceder papéis focados em aplicativos aos usuários.

      4. Na caixa Novos principais, insira os usuários, grupos ou contas de serviço que precisam ter acesso de administrador a tarefas centradas em aplicativos no projeto.

      5. Clique em Conceder papéis e em Concluir.

      Agora é possível registrar recursos atuais em um aplicativo ou criar um modelo de aplicativo com o App Design Center.

Depois, é possível conceder outros papéis do IAM aos principais na página IAM. Para mais informações, consulte Conceder um papel do IAM usando o console do Google Cloud .

gcloud

  1. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte inferior do console do Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. Verifique se a versão mais recente da Google Cloud CLI está instalada:

    gcloud components update

  3. Encontre o ID do projeto.

  4. Defina o projeto como o padrão para os comandos:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto.

  5. Ative a API App Hub:

    gcloud services enable apphub.googleapis.com \
    --project PROJECT_ID

  6. Anexe o projeto a si mesmo para criar um limite de gerenciamento de aplicativos:

    gcloud apphub boundary update \
    --crm-node=projects/PROJECT_ID \
    --project=PROJECT_ID \
    --location=global

    Esse comando configura o projeto como o próprio projeto de gerenciamento, permitindo que o App Hub descubra automaticamente todos os recursos compatíveis nele.

  7. Confirme o status do anexo:

    gcloud apphub boundary describe \
    --project=PROJECT_ID \
    --location=global

    Você vai receber uma saída semelhante ao exemplo a seguir:

    name: projects/PROJECT_ID/locations/LOCATION/boundary
crmNode: projects/PROJECT_ID
createTime: 2025-08-28T19:04:47Z
updateTime: 2025-08-28T19:04:47Z
type: AUTOMATIC

Quando você terminar de configurar o projeto de gerenciamento, as APIs necessárias para o gerenciamento de aplicativos serão ativadas, e você poderá começar a usar o App Hub para agrupar serviços e cargas de trabalho em aplicativos. Se quiser, revise as APIs recomendadas para ter acesso a recursos avançados.

Atribuir papéis e permissões do App Hub

Para permitir que os usuários descubram, registrem e gerenciem componentes de aplicativos nesse projeto usando o App Hub, conceda a eles as funções e permissões adequadas do App Hub.

Siga estas etapas:

Console

  1. No console Google Cloud , use o seletor de projetos para escolher o projeto de gerenciamento.

  2. Acesse a página do IAM:

    Acessar IAM

  3. Clique em Conceder acesso. O painel Conceder acesso será aberto.

  4. No campo Novos principais, insira o endereço de e-mail do principal a quem você quer conceder acesso ao App Hub.

  5. Clique em Selecionar um papel e insira App Hub no campo Filtro.

  6. Selecione o papel do IAM do App Hub que você quer atribuir ao principal e clique em Salvar.

gcloud

  1. Conceda acesso aos principais no projeto de gerenciamento:

    gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:EMAIL_ADDRESS' \
    --role='ROLE_NAME'

    Substitua:

    • PROJECT_ID: o ID do projeto de gerenciamento.
    • EMAIL_ADDRESS: o endereço de e-mail do principal que precisa ter acesso ao App Hub. Esse valor precisa ter o formato username@yourdomain, por exemplo, my.user@example.com.
    • ROLE_NAME: o papel do IAM do App Hub que você quer atribuir ao principal, por exemplo, roles/apphub.admin.

Mudar o limite do gerenciamento de aplicativos

Se você quiser mudar o projeto que define o limite de projeto único, desative o gerenciamento de aplicativos no projeto antigo e ative-o no novo. Os dados do aplicativo não são migrados, e você precisa recriar os aplicativos no novo projeto.

Para migrar de um limite de projeto único para um limite no nível da pasta, configure uma pasta habilitada para apps. Essa ação configura um novo projeto de gerenciamento na pasta. Será necessário recriar os aplicativos nesse novo projeto de gerenciamento.

Desativar o gerenciamento de aplicativos em um projeto

É possível desativar o gerenciamento de aplicativos em um projeto se você não quiser mais gerenciar os recursos dele em aplicativos do App Hub.

Quando você desativa o gerenciamento de aplicativos no projeto, ele é separado do limite de gerenciamento de aplicativos. Os serviços e as cargas de trabalho nos aplicativos continuam existindo, mas o status de registro deles muda para desanexado. Se você decidir reativar o gerenciamento de aplicativos no projeto, o App Hub poderá redescobrir seus aplicativos, serviços e cargas de trabalho e atualizar o status de registro se os recursos subjacentes ainda existirem.

Para desativar o gerenciamento de aplicativos em um único projeto, siga estas etapas:

Console

  1. No console Google Cloud , use o seletor de projetos para escolher o projeto de gerenciamento.

    Acessar "Boas-vindas"

  2. Acesse a página Configurações de limite no App Hub:

    Acessar as configurações de limite

  3. Marque a caixa de seleção do projeto para separar do limite e desativar o gerenciamento de aplicativos.

  4. Clique em Desanexar projetos.

    A tabela Projetos no seu perímetro é atualizada e não mostra mais as informações do projeto.

gcloud

  1. No console do Google Cloud , ative o Cloud Shell.

    Ativar o Cloud Shell

    Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

  2. Verifique se a versão mais recente da Google Cloud CLI está instalada:

    gcloud components update

  3. Encontre o ID do projeto.

  4. Defina o projeto como o padrão para os comandos:

    gcloud config set project PROJECT_ID

    Substitua PROJECT_ID pelo ID do projeto.

  5. Separe o projeto do limite para desativar o gerenciamento de aplicativos:

    gcloud apphub boundary update \
    --project=PROJECT_ID \
    --location=global \
    --crm-node=""

    Esse comando atualiza o recurso de limite e remove o anexo, desativando o gerenciamento de aplicativos para o projeto.

  6. Confirme o desvinculação descrevendo o limite:

    gcloud apphub boundary describe \
    --project=PROJECT_ID \
    --location=global

    A saída não contém um campo crmNode, confirmando que o gerenciamento de aplicativos está desativado no projeto.

  7. Se quiser, exclua todos os aplicativos do projeto e desative a API App Hub se não for mais usar os recursos de aplicativos nesse projeto:

    gcloud services disable apphub.googleapis.com \
    --project=PROJECT_ID

A seguir