Set up App Hub with a host project

This page describes how to set up a host project to group services and workloads as App Hub applications.

Host projects are a supported setup model for existing App Hub users. However, we recommend using app-enabled folders to set up App Hub for new implementations. App-enabled folders provide access to the complete set of Application-centric Google Cloud features, such as Application Design Center and Gemini Cloud Assist. For a comparison of key differences between the available App Hub setup models, see Choose your App Hub setup model.

Overview of host and service projects

A host project is a standard Google Cloud project that you designate to group supported resources as App Hub applications. You manually attach other projects, called service projects, to this host project so that App Hub can discover services and workloads within those projects and register them.

The host and service project model in App Hub is distinct from the model used by Shared VPC. You cannot use a Shared VPC host project and its attached service projects for App Hub. In App Hub, host and service projects are for logically grouping application resources, not for sharing VPC networks.

Before you begin

You must complete the following steps before configuring Google Cloud projects as host and service projects for your applications:

  1. Identify the Google Cloud project you want to use as the host project. You can use an existing project or create a new project.

  2. Identify the Google Cloud projects that you want to attach to the host project as service projects. You must identify all the projects that contain the services and workloads that you intend to register to App Hub applications. Resources in other projects won't be visible to App Hub. Consider the following aspects for service projects:

    • Service projects must be in the same organization as the host project.
    • A service project can only be attached to one host project at a time.
    • A host project can act as a service project for itself to manage its own resources, but you cannot attach it as a service project to any other host project.

Required roles

To get the permissions that you need to attach service projects to the host project, ask your administrator to grant you the App Hub Admin (roles/apphub.admin) IAM role on the host project and on each service project that you want to attach. 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.

Set up the host project

Follow these steps to configure a project as a host project:

Console

  1. In the Welcome page of the Google Cloud console, use the project picker to select the project that you want to configure as the host project.

    Go to Welcome

  2. Enable the required API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

gcloud

  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 of the Google Cloud project that you want to configure as the host project.

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

    gcloud config set project HOST_PROJECT_ID

    Replace HOST_PROJECT_ID with the ID of the project you want to configure as the host project.

  5. Enable the App Hub API in the host project:

    gcloud services enable apphub.googleapis.com \
    --project=HOST_PROJECT_ID

Attach service projects

Attach the service projects containing the services and workloads you want to group as App Hub applications to the host project:

Console

  1. In the Welcome page of the Google Cloud console, use the project picker to select the host project.

    Go to Welcome

  2. Navigate to the App Hub Settings page:

    Go to Settings

  3. Click Attach projects.

  4. Select the service projects to attach to the host project in one of the following ways:

    • From the list of projects, select the checkboxes for the projects you want to attach as service projects.
    • Filter the project names and select their checkboxes.

  5. Click Select.

    The Attached Service Project(s) table displays the selected service projects.

  6. Click Close.

gcloud

  1. Find the project ID of each of the Google Cloud projects that you want to configure as service projects.

  2. Attach each service project:

    gcloud apphub service-projects add SERVICE_PROJECT_ID \
    --project=HOST_PROJECT_ID

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the service project to attach.
    • HOST_PROJECT_ID: the ID of the host project.

  3. Repeat the previous process for each service project you want to attach to the host project.

Detaching a service project requires removing the attachment. For more information, see Remove service projects.

Assign App Hub roles and permissions

Follow these steps to grant appropriate App Hub roles and permissions to App Hub users in the host and service projects:

Console

  1. In the Welcome page of the Google Cloud console, use the project picker to select the host project.

    Go to Welcome

  2. Go 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.

  7. In each of the App Hub service projects you attached to the host project, repeat the previous process to grant the same roles to the same users.

gcloud

  1. Find the project ID of each of the Google Cloud projects that you configured as host and service projects.

  2. Grant access to principals in the host project:

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

    Replace the following:

    • HOST_PROJECT_ID: the ID of the host project.
    • EMAIL_ADDRESS: the email address of the principal who must obtain App Hub access in the host project. 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.

  3. In each of the App Hub service projects you attached to the host project, grant the same roles to the same users:

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

    Replace SERVICE_PROJECT_ID with the ID of the service project you are granting access to.

Set up VPC Service Controls

If you want to protect your applications with a VPC Service Controls perimeter, add your App Hub host and service projects to the perimeter before you create your applications. For more information, see Using VPC Service Controls with App Hub.

You can now register existing resources to an application.

Optional: Configure the metrics scope

To view system metrics for applications within your host project in Cloud Monitoring, add the attached service projects to the host project's metrics scope. The host project serves as a scoping project for time-series data, enabling the charting and monitoring of data. For more information and detailed configuration instructions, see Configure a metrics scope and Configure a metrics scope by using the API.

Remove service projects

You can modify service project attachments to let different services and workloads be available to group into an application. You can either attach more service projects to the host project or follow these steps to remove the attachment of a service project from a host project:

Console

  1. In the Welcome page of the Google Cloud console, use the project picker to select the host project.

    Go to Welcome

  2. Navigate to the App Hub Settings page:

    Go to Settings

  3. Select the checkboxes of the service projects that you want to remove from the host project.

  4. Click Detach projects.

    The Attached Service Project(s) table refreshes to display only the projects that remain attached to the host project.

gcloud

  1. Find the project ID of each of the service projects that you want to remove from the host project.

  2. Remove each service project:

    gcloud apphub service-projects remove SERVICE_PROJECT_ID \
    --project=HOST_PROJECT_ID

    Replace the following:

    • SERVICE_PROJECT_ID: the ID of the service project to remove.
    • HOST_PROJECT_ID: the ID of the host project.

  3. Repeat the previous process for each service project you want to remove from the host project.

When you remove a service project from a host project, consider removing it also from the host project's metrics scope if you previously configured the metrics scope. For more information, see Remove projects from a metrics scope.

What's next