Set up a host project (Legacy)

This document describes how to set up a host project in App Hub.

The host project is a legacy application setup model supported for existing App Hub users. We recommend defining folder-level boundaries by setting up an app-enabled folder for new implementations. Folder-level boundaries 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 models for application management, see Choose your application setup model.

Overview of host and service projects

A 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.

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.

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.

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

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 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 register in App Hub applications to the host project:

Console

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

    Go to Welcome

  2. Navigate to the Settings page from App Hub:

    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.

Terraform

To attach a service project to a host project using Terraform, use the google_apphub_service_project_attachment resource, for example:

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.

Assign App Hub roles and permissions

To grant appropriate App Hub roles and permissions 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

  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.

  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

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 Using VPC Service Controls with App Hub.

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 configuration instructions, see Configure a metrics scope and Configure a metrics scope by using the API.

Remove service projects

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

  2. Navigate to the Settings page from App Hub:

    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