Set up a single project

This document describes how to set up a single Google Cloud project to manage applications. This configuration is also known as the single-project boundary.

In this setup, the Google Cloud project is configured to manage its own applications and components, acting as a standalone management project. This approach is the quickest way to begin managing applications if all your application components reside within this single project. App Hub automatically discovers all supported resources within the project, making them ready to be organized into applications.

Limitations

The single-project boundary has different feature support compared to the folder-level boundary. App Hub, Application Design Center, and Application Monitoring fully support single projects, but other Application-centric Google Cloud services, like Cloud Hub and Gemini Cloud Assist, require a folder-level boundary.

For a comparison of feature support between the single-project and folder-level models, see Feature support by boundary type.

Before you begin

Choose the Google Cloud project you want to use for managing your applications. This project will function as the standalone management project. You can use an existing project or create a new one.

Required roles

To get the permissions that you need to configure a single project for application management, ask your administrator to grant you the following IAM roles on the project that you want to configure as the standalone management project:

  • Manage resources, permissions, and billing on the project: Project Owner (roles/owner)
  • Manage all application components on the project: App Hub Admin (roles/apphub.admin)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Enable application management on a project

This action configures the project as a standalone management project and enables the required APIs for application metadata and configurations. The project is then called an app-enabled project.

To enable application management on a single project, follow these steps:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Make sure that the most recent version of Google Cloud CLI is installed:

    gcloud components update

  3. Find the project ID.

  4. Set the project as the default project for commands:

    gcloud config set project PROJECT_ID

    Replace PROJECT_ID with the ID of the project.

  5. Enable the App Hub API:

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

  6. Attach the project to itself to create an application management boundary:

    gcloud alpha apphub boundary update \
    --crm-node="projects/$(gcloud projects describe PROJECT_ID --format='value(projectNumber)')" \
    --project=PROJECT_ID \
    --location=global

    This command configures the project as its own management project, letting App Hub automatically discover all supported resources within it.

  7. Confirm the attachment status:

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

    You obtain an output similar to the following example:

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

    PROJECT_NUMBER is the project number corresponding to your project ID.

When you finish configuring the management project, the required APIs for application management are enabled, and you can start using App Hub to group services and workloads in applications. Optionally, review recommended APIs to gain access to advanced features.

Assign App Hub roles and permissions

To let users discover, register, and manage application components within this project using App Hub, you need to grant them the appropriate App Hub roles and permissions.

Follow these steps:

Console

  1. In the Google Cloud console, use the project picker to select the management project.

  2. Navigate to the IAM page:

    Go to IAM

  3. Click Grant access. The Grant access pane opens.

  4. In the New principals field, enter the email address of the principal that you want to grant access to App Hub.

  5. Click Select a role and enter App Hub in the Filter field.

  6. Select the App Hub IAM role you intend to assign to the principal and click Save.

gcloud

  1. Grant access to principals in the management project:

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

    Replace the following:

    • PROJECT_ID: the ID of the management project.
    • EMAIL_ADDRESS: the email address of the principal who must obtain App Hub access. This value must have the format username@yourdomain, for example, my.user@example.com.
    • ROLE_NAME: the App Hub IAM role you want to assign to the principal, for example, roles/apphub.admin.

Change the application management boundary

If you want to change the project that defines your single-project boundary, disable application management on the old project and enable it on the new one. Your application data isn't migrated, and you must recreate your applications in the new project.

To move from a single-project boundary to a folder-level boundary, set up an app-enabled folder. This action configures a new management project in the folder. You'll need to recreate applications in this new management project.

Disable application management on a project

You can disable application management on a project if you no longer want to manage its resources in App Hub applications.

When you disable application management on the project, the project is detached from its application management boundary. The services and workloads in your applications continue to exist, but their registration status changes to detached. If you decide to re-enable application management on the project, App Hub can rediscover your applications, services, and workloads and update the registration status if the underlying resources still exist.

To disable application management on a single project, follow these steps:

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  2. Make sure that the most recent version of Google Cloud CLI is installed:

    gcloud components update

  3. Find the project ID.

  4. Set the project as the default project for commands:

    gcloud config set project PROJECT_ID

    Replace PROJECT_ID with the ID of the project.

  5. Detach the project from its boundary to disable application management:

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

    This command updates the boundary resource and removes the attachment, disabling application management for the project.

  6. Confirm the detachment by describing the boundary:

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

    The output doesn't contain a crmNode field, confirming that application management is disabled on the project.

  7. Optionally, delete all the applications in the project and then disable the App Hub API if you won't use application features in this project anymore:

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

What's next