An App Hub host project lets you create a multiple-project
[boundary](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#app-mgmt-boundary) in
environments where you already use App Hub. You can attach service
projects to the host project and assign App Hub roles to manage
application resources across those projects. Because host projects are a
legacy setup model, set up an
[app-enabled folder](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-folder.md.txt) for new
deployments to access all Application-centric Google Cloud features, such as Application Design Center
and Gemini Cloud Assist. For a comparison of the available setup
models, see
[Choose your application setup model](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub.md.txt).

## Overview of host and service projects

A [host project](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#host-project) is a Google Cloud
project to which you attach other projects that contain the services and
workloads you want to group as App Hub applications. The projects you
attach to the host project are called
[service projects](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#service-project). The attachment
of the host project and service projects define a multiple-project
[boundary](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#app-mgmt-boundary).

A host project can manage its own resources directly by attaching to itself.
However, for a single-project setup, we recommend using
[the single-project approach](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-single-project.md.txt).

> [!IMPORTANT]
> **Important:** The host and service project model in App Hub is distinct from the model used by [Shared VPC](https://docs.cloud.google.com/vpc/docs/shared-vpc.md.txt). 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 components, not for sharing VPC networks.

## Before you begin

Before you set up a Google Cloud project as a host project and attach service
projects to it, complete the following steps:

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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt).
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. Service projects have the following requirements:

   - Service projects must be in the same [organization](https://docs.cloud.google.com/resource-manager/docs/creating-managing-organization.md.txt) 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.
   - Choose a host project and service projects that aren't descendants of [folders](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-folder.md.txt) that you configured for application management. This separation ensures that all resources in a folder are managed with the same type of setup model.

### 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](https://docs.cloud.google.com/iam/docs/roles-permissions/apphub.md.txt#apphub.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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Set up the host project

To configure a Google Cloud project as a host project, follow these steps:

### Console

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

2. Navigate to the **Overview** page from App Hub:


   [Go to Overview](https://console.cloud.google.com/apphub)

   <br />

3. Click **Set up App Hub**.

4. In the **Enable App Hub** page, choose **Full setup** to create a
   multiple-project boundary.

5. Make note of the project name and ID. This information identifies the
   host project and you'll use these values to grant access.

6. Review the list of [APIs being enabled](https://docs.cloud.google.com/app-hub/docs/enabled-apis.md.txt).
   Some APIs have associated costs.
   [Learn more about the costs of APIs](https://docs.cloud.google.com/app-hub/docs/enabled-apis.md.txt#costs)
   or click each API to see associated costs.

   > [!NOTE]
   > **Note:** This setup process enables several APIs, but only App Hub and Application Monitoring support host projects. Therefore, other enabled APIs might not function as expected in this legacy setup model. For more information, see [Feature support by boundary type](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub.md.txt#support).

7. Click **Continue**.

8. In the **Define boundary** tab, verify your project information.

9. Click **Add project** to
   [add service projects to your boundary](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-host-project.md.txt#attach-service-projects)
   or add those later.

10. Click **Continue**.

11. In the **Grant access** tab, choose the appropriate
    [IAM roles and permissions](https://docs.cloud.google.com/app-hub/docs/roles-permissions.md.txt)
    for administrators in the project.
    For a list of recommended application-centric roles across
    Google Cloud products, see
    [Grant application-centric roles to your users](https://docs.cloud.google.com/resource-manager/docs/manage-applications.md.txt#assign-roles).

12. In the **New principals** box, enter the users, groups, or
    service accounts who should have administrator access to
    application-centric tasks in the project.

13. Click **Grant roles** and then click **Complete**.

Later, you can grant additional IAM roles to your principals
from the **IAM** page. For more information, see
[Grant an IAM role by using the Google Cloud console](https://docs.cloud.google.com/iam/docs/grant-role-console.md.txt).

### gcloud


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

   [Activate Cloud Shell](https://console.cloud.google.com/?cloudshell=true)


   At the bottom of the Google Cloud console, a
   [Cloud Shell](https://docs.cloud.google.com/shell/docs/how-cloud-shell-works.md.txt)
   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:

   ```bash
   gcloud components update
   ```
3. [Find the project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects)
   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:

   ```bash
   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](https://docs.cloud.google.com/app-hub/docs/reference/rest.md.txt) in the
   host project:

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

## Add service projects

Add service projects to your
[application management boundary](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#app-mgmt-boundary) by
attaching them to the host project.

To attach service projects to the host project and create a multiple-project
boundary, follow these steps:

### Console

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

   [Go to Welcome](https://console.cloud.google.com/welcome)
2. Navigate to the **Boundary settings** page from App Hub:


   [Go to Boundary settings](https://console.cloud.google.com/apphub/settings)

   <br />

3. Click **Add project**.

4. Select the service projects that you want to attach to the host project
   and add to your boundary 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 **Projects in your boundary** table displays the selected service
   projects. The attachment process might take some time to complete.
6. Verify the list of service projects is complete.

### gcloud

1. [Find the project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects) of each of the Google Cloud projects that you want to configure as service projects.
2. Attach each service project:

   ```bash
   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.

### Terraform

To attach a service project to a host project using Terraform, use
[the `google_apphub_service_project_attachment` resource](https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/apphub_service_project_attachment),
for example:

```terraform
resource "google_apphub_service_project_attachment" "example" {
    service_project_attachment_id = google_project.service_project.project_id
    depends_on = [time_sleep.wait_120s]
}

resource "google_project" "service_project" {
    project_id ="project-1"
    name = "Service Project"
    org_id = "123456789"
    deletion_policy = "DELETE"
}

resource "time_sleep" "wait_120s" {
    depends_on = [google_project.service_project]

    create_duration = "120s"
}
```

To detach a service project from a host project, see [Remove service projects](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-host-project.md.txt#remove-service-projects).

## Assign App Hub roles and permissions

To grant appropriate
[App Hub roles and permissions](https://docs.cloud.google.com/app-hub/docs/roles-permissions.md.txt) to
App Hub users in the host project and service projects, follow these
steps:

### Console

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

   [Go to Welcome](https://console.cloud.google.com/welcome)
2. Navigate to the **IAM** page:


   [Go to IAM](https://console.cloud.google.com/projectselector/iam-admin/iam)

   <br />

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](https://docs.cloud.google.com/app-hub/docs/roles-permissions.md.txt)
   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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects)
   of each of the Google Cloud projects that you configured as host and
   service projects.

2. Grant access to principals in the host project:

   ```bash
   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](https://docs.cloud.google.com/app-hub/docs/roles-permissions.md.txt) 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:

   ```bash
   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

To protect your applications with a VPC Service Controls perimeter, add
your App Hub host project and service projects to the perimeter before
you create your applications. For more information, see
[Use VPC Service Controls with App Hub](https://docs.cloud.google.com/app-hub/docs/using-vpc-service-controls.md.txt).

## 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](https://docs.cloud.google.com/monitoring/settings.md.txt). The host project serves as a scoping
project for time-series data, enabling the charting and monitoring of data. For
more information and configuration instructions, see
[Configure a metrics scope](https://docs.cloud.google.com/monitoring/settings/multiple-projects.md.txt) and
[Configure a metrics scope by using the API](https://docs.cloud.google.com/monitoring/settings/manage-api.md.txt).

## Remove service projects

Remove service projects from your
[application management boundary](https://docs.cloud.google.com/app-hub/docs/key-concepts.md.txt#app-mgmt-boundary) by
detaching them from the host project.

To detach a service project from a host project, follow these steps:

### Console

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

   [Go to Welcome](https://console.cloud.google.com/welcome)
2. Navigate to the **Boundary settings** page from App Hub:


   [Go to Boundary settings](https://console.cloud.google.com/apphub/settings)

   <br />

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

4. Click **Detach projects**.

   The **Projects in your boundary** table refreshes to display only the
   projects that remain attached to the host project.
5. Verify the list of service projects is updated.

### gcloud

1. [Find the project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects.md.txt#identifying_projects) of each of the service projects that you want to remove from the host project.
2. Remove each service project:

   ```bash
   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.

> [!IMPORTANT]
> **Important:** When you remove a service project from a host project, the [registration status of services and workloads](https://docs.cloud.google.com/app-hub/docs/overview.md.txt#registration-status) from that project that are registered to applications changes to *detached*.

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](https://docs.cloud.google.com/app-hub/docs/set-up-app-hub-host-project.md.txt#metrics-scope). For more information, see
[Remove projects from a metrics scope](https://docs.cloud.google.com/monitoring/settings/multiple-projects.md.txt#remove-monitored-project).

## What's next

- [Register existing resources to an application](https://docs.cloud.google.com/app-hub/docs/register-resources.md.txt)
- [Set up application monitoring](https://docs.cloud.google.com/monitoring/docs/setup-application-monitoring.md.txt)
- [App Hub IAM roles and permissions](https://docs.cloud.google.com/app-hub/docs/roles-permissions.md.txt)
- [App Hub overview](https://docs.cloud.google.com/app-hub/docs/overview.md.txt)