Set up App Hub for app-enabled folders
Stay organized with collections Save and categorize content based on your preferences.

This document provides instructions for setting up App Hub using an app-enabled folder to build, operate, and manage App Hub applications on Google Cloud. It's intended for people who set up and administer App Hub.

You can also set up App Hub on a host project. However, we recommend using app-enabled folders over host projects to manage your applications since app-enabled folders have access to features such as Application Design Center and Gemini Cloud Assist. For more information about how to set up App Hub on a host project, see Set up App Hub on host projects.

After you set up an App Hub application on an app-enabled folder, you can use natural language assistance to retrieve information about your application. For more information, see Use Gemini Cloud Assist in the Google Cloud console.

Services and workloads

Using App Hub, the resources from Google Cloud projects that are descendants to the app-enabled folder are available to you as services and workloads. Registering your services and workloads to an application enable you to observe and monitor the resources. App Hub supports global and regional resources. For more information about the resources that you can add to applications, see App Hub supported resources.

Overall setup process

The following list summarizes the steps to set up App Hub:

Determine which existing resources to include in your application and which projects they belong to. For more information on how to manage your application, see Application management.
Enable application management on a folder. You can now manage resources from all the descendant projects of the app-enabled folder. If new projects with underlying resources that your applications need are added to the folder, those projects are automatically enabled for application management.
Note the following:
1. The projects must be in the same organization as the app-enabled folder. After you attach a project to an app-enabled folder, if you want to move the project to a different organization, you must migrate the project. For more information, see Migrating projects between organization resources.
2. After you attach projects to an app-enabled folder, querying the app-enabled folder for services or workloads automatically returns all services and workloads in all of the projects attached to the app-enabled folder.
3. If an app-enabled folder is moved to a different organization, all the registered services and workloads will be detached.
Designate App Hub users as App Hub Admins, App Hub Editors, or App Hub Viewers.
Create an application to organize multiple workloads and services.
Note the following:
1. Make sure the application has a name that is unique in the app-enabled folder and location.
2. A project can be attached to an app-enabled folder with multiple applications, but its individual resources can be registered to only one application.
3. If a project is moved to a different folder or organization, the application will continue to exist in the app-enabled folder with its services and workloads in a detached state.
Query for services and workloads and register them to your application. After you create an application, you can query the app-enabled folder for available services and workloads. The queries run against the app-enabled folder and all projects that are attached to the app-enabled folder. The query also returns all services and workloads in those projects. Note the following:
1. You can only register a service or workload to a single application.
2. You must register services and workloads from a specific region to a regional application in the same region or to a global application. The instructions and commands that follow assume that all resources are in the same region. For information on which regions you can designate, see Locations.
3. Registered services and workloads aren't affected by updates to the underlying infrastructure resource. In other words, if you delete the underlying resources that act as services and workloads, App Hub doesn't delete the associated workloads and services from your application. You have to separately unregister the workload or service.

Prerequisites

Before you set up App Hub, complete the following tasks.

Ensure that you have the required IAM role to activate or create a billing account for your management project.
Decide on an existing folder or create a new folder on which you can enable application management. For more information about how to create a folder, see Creating folders.
Ensure that you have decided which individuals hold the Identity and Access Management (IAM) roles for App Hub: App Hub Admin, App Hub Editor, and App Hub Viewer. For more information about the roles and permissions, see App Hub roles and permissions.

Required roles

To get the permissions that you need to Modify App Hub resources, ask your administrator to grant you the following IAM roles on the app-enabled folder:

To create and update applications and register and unregister services and workloads:
- App Hub Admin (roles/apphub.admin)
- App Hub Editor (roles/apphub.editor)
To enable application management on a folder: Folder Admin (resourcemanager.folderAdmin)
To view applications, services, and workloads, and their attributes across Google Cloud services that support application management: App Hub Management Viewer (roles/apphub.appManagementViewer)

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

In this section, you select a folder and enable application management on the folder. When you configure application management for a folder, the enablement process includes the following actions:

Creation of a new management project in the folder. The management project is a Google-owned project that you cannot move or delete. Only one management project is associated with an app-enabled folder. The management project is used to manage quota and billing for all the descendant projects associated with the app-enabled folder.
Enabling APIs for services such as App Hub and Gemini Cloud Assist that support application management.

In the Google Cloud console, go to the App Hub page.

Go to App Hub
Based on the following scenarios, follow these steps:
- If you are on a Google Cloud project or a Google Cloud folder that isn't app-enabled:
  1. Click Select a folder.
  2. On the Select a folder dialog, select an app-enabled folder. If you need information about folders that are app-enabled, ask your administrator. If you selected a folder that isn't app-enabled, and you have the Folder Admin (resourcemanager.folderAdmin) IAM role, enable application management on the folder. For more information, see Enabling application management and APIs on a folder.
- If you are on Google Cloud folder that is app-enabled, on this page, go to Designate App Hub users.
Enabling application management on a folder creates a Google-owned project called a Management project with the following format FOLDER_DISPLAY_NAME-mp. The management project hosts the descendant projects of the app-enabled folder and helps to manage cross-project functionalities. You can now create App Hub applications for the descendant projects in this app-enabled folder.
Optional: Enable Shared VPC on this management project. For more information, see Using VPC Service Controls with App Hub.
Optional: You can create projects or move projects from a different folder to the app-enabled folder. You can then create applications on the app-enabled folder to manage the services and workloads in the project. For more information about creating projects, see Creating projects. For more information about how to move a project see, Moving a project.

Designate App Hub users

If you are the project creator, you are granted the basic Owner role (roles/owner). By default, this IAM role includes the permissions necessary for full access to most Google Cloud resources.

If you aren't the project creator, required permissions must be granted on the project to the appropriate principal. For example, a principal can be a Google Account (for end users) or a service account (for applications and compute workloads). To get the permissions that you need to complete this tutorial, ask your administrator to grant you the following IAM role on your project:

Console

In the Google Cloud console, go to the IAM page.

Go to IAM
Ensure that the project selector on the top navigation bar displays the app-enabled folder. The Purview picker lets you know what organization, folder, or project you are working in. If you are not on the app-enabled folder, follow these steps to select an app-enabled folder:
1. On the Purview picker, click the selected option.
2. On the Select a resource dialog, do one of the following:
  - From the list of folders, select the FOLDER_DISPLAY_NAME folder.
  - Search for the FOLDER_DISPLAY_NAME folder, and then select it.
On the IAM page, click Grant access. The Grant access pane opens.
In the New principals field, enter the email address of the individual who is responsible for administering App Hub, the App Hub Admin role in the app-enabled folder.
Click Select a role and in the Filter field, enter App Hub.
Select the App Hub Admin role and click Save.
Repeat the steps to grant the App Management Viewer role to the individuals to view the application data and their attributes across Google Cloud services that support application management. This role is granted to the individual across all the projects and sub-folders of the app-enabled folder.
Click Save.

gcloud

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.
Make sure that the most recent version of Google Cloud CLI is installed. Run the following command from the Cloud Shell:
```
gcloud components update
```
Grant the individuals who will administer App Hub, the App Hub administrator role in the app-enabled folder. Repeat the following command for each administrator. They must have the App Hub Admin role to create applications.
```
gcloud projects add-iam-policy-binding MANAGEMENT_PROJECT_ID \
    --member='user:MANAGEMENT_PROJECT_ADMIN' \
    --role='roles/apphub.admin'
```
Replace the following:
- MANAGEMENT_PROJECT_ID: the ID of the management project in the format google-mpf-FOLDER_ID. You can find your management project ID on the Identity and Access Management (IAM) & Admin Settings page of the Google Cloud console. If you can't find the Management project ID, you might not be on an app-enabled folder. From the project selector, select your app-enabled folder.
- MANAGEMENT_PROJECT_ADMIN: the user who has the App Hub Admin role in the project. This value has the format username@yourdomain, for example, robert.smith@example.com.
Grant the App Management Viewer role in the app-enabled folder to the individuals to view the application data and their attributes across Google Cloud services that support application management. This role is granted to the individual across all the projects and sub-folders of the app-enabled folder.
```
gcloud resource-manager folders add-iam-policy-binding FOLDER_ID \
    --member='user:MANAGEMENT_PROJECT_ADMIN' \
    --role='roles/apphub.appManagementViewer'
```
Replace FOLDER_ID with the ID of the project. You can find your app-enabled folder ID on the IAM & Admin Settings page of the Google Cloud console. To ensure that the folder is app-enabled, the Settings page should display the Management project ID. If you can't find the Management project ID, you might not be on an app-enabled folder. From the project selector, select your app-enabled folder.

Create an application

If you don't already have one, create an application to be the container for your services and workloads. Based on the scope of your services and workloads on your app-enabled folder, create a global or regional application.

A global application lets you register discovered services and workloads from regional and global Google Cloud resources.
A regional application lets you register discovered services and workloads from regional Google Cloud resources.

Note that after you create an application, you can't change the application scope. For more information about global and regional applications, see Global and regional App Hub applications.

Console

Make sure that you're in an app-enabled folder.
In the Google Cloud console, go to the App Hub Applications page.

Go to Applications
Click Create application.
On the Create application page, in the Choose application region and name pane, based on the scope of services and workloads you'd like to register to the application, do one of the following:
- To create an application that lets you register services and workloads from a global location, select Global.
- To create an application that lets you register services and workloads from a single location:
  1. Select Regional.
  2. Select a Region.
Enter the Application name and click Continue.
Optional: In the Add attributes section, enter the Display name.
Optional: In the Criticality list, to indicate the importance of the application, select one of the following:
- Mission critical
- High
- Medium
- Low
Optional: In the Environment list, to indicate the stage of the software lifecycle, select one of the following:
- Production
- Staging
- Development
- Test
Optional: Add the following details as required for Developer Owners, Operator Owners, and Business Owners. Note that you must enter the owner's email address if you add a display name.
1. Enter an owner's display name.
2. Enter the owner's email address. This value must have the format username@yourdomain, for example, 222larabrown@gmail.com.
Repeat these steps for each developer, operator, and business owner.
Click Create.

gcloud

Create a new application called APPLICATION_NAME and give it a display name, APPLICATION_DISPLAY_NAME.
```
gcloud apphub applications create APPLICATION_NAME \
    --display-name='APPLICATION_DISPLAY_NAME' \
    --scope-type=SCOPE_TYPE \
    --criticality-type='CRITICALITY_LEVEL' \
    --environment-type='ENVIRONMENT' \
    --developer-owners=display-name=DISPLAY-NAME-DEVELOPER,email=EMAIL-DEVELOPER \
    --operator-owners=display-name=DISPLAY-NAME-OPERATOR,email=EMAIL-OPERATOR \
    --business-owners=display-name=DISPLAY-NAME-BUSINESS,email=EMAIL-BUSINESS \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION
```
Replace the following:
- APPLICATION_NAME: the name of your application. The name must include only lowercase alphanumeric characters without spaces.
- APPLICATION_DISPLAY_NAME: the display name of your application.
- SCOPE_TYPE: the scope of your application that defines which services and workloads are available for you to register to the application. Use one of the following values:
  - REGIONAL
  - GLOBAL
- CRITICALITY_LEVEL: (optional) indicates how critical an application, service, or workload is to your business operations. Provide one of the following values:
  - MISSION_CRITICAL
  - HIGH
  - MEDIUM
  - LOW
- ENVIRONMENT: (optional) indicates the stages of the software lifecycle. Provide one of the following values:
  - PRODUCTION
  - STAGING
  - DEVELOPMENT
  - TEST
- DISPLAY-NAME-DEVELOPER, DISPLAY-NAME-OPERATOR, and DISPLAY-NAME-BUSINESS: (optional) display names of the developer, operator, and business owners, respectively.
- EMAIL-NAME-DEVELOPER, EMAIL-NAME-OPERATOR, and EMAIL-NAME-BUSINESS: (optional) email addresses of the developer, operator, and business owners, respectively. These values must have the format username@yourdomain, for example, 222larabrown@gmail.com.
- MANAGEMENT_PROJECT_ID: the ID of the management project in the format google-mpf-FOLDER_ID.
- REGION: the region of the application. Depending on the --scope-type, give this the value us-east1 or global.
For example:
```
gcloud apphub applications create my-application \
    --display-name='application-display-name' \
    --scope-type=REGIONAL \
    --criticality-type='MEDIUM' \
    --environment-type='STAGING' \
    --developer-owners=display-name=developer-name,email=username@yourdomain \
    --project=host-project \
    --location=us-east1
```

List the applications in your app-enabled folder.

gcloud apphub applications list \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION

The output is similar to the following:

ID                DISPLAY_NAME              CREATE_TIME
APPLICATION_NAME  APPLICATION_DISPLAY_NAME  2023-10-31T18:33:48

Register services and workloads

When you register infrastructure services and workloads to an application, the services and workloads get registered as App Hub resources. Use a global application to register resources that are global or spread across multiple regions. Use a regional application to register resources from the same region as the application.

Console

In the Google Cloud console, go to the App Hub Applications page.

Go to Applications
Click the name of your application. The Services and workloads tab is displayed with a list of registered services and workloads that are in your app-enabled folder.
For each service or workload you want to register, do the following:
1. On the Services and workloads tab, click Register service/workload.
2. On the Register service or workload page, in the Select resource pane, click Browse to select the service or workload as a Resource.
3. In the Select resource pane, choose a service or workload and click Select.
4. In the Select resource pane, enter a Name for the service or workload and click Continue.
5. Optionally, in the Add attributes pane, add more details for the service or workload in the fields that follow. For more information, in this document, see Create an application. Note that you can select values for Criticality and Environment fields that are different from the values you set when you create the application.
6. Click Continue.
7. Optionally, in the Add owners section, add more details about the owners of the service or workload in the fields that follow. For more information, in this document, see Create an application.
8. Click Register.

The Services and workloads tab displays the registered service or workload. For more information about the registration statuses, see the properties and attributes of App Hub.

gcloud

List discovered services from an app-enabled folder. In the following command, you optionally specify the filter flag to return services from the specified project that are available to be registered to an application.
```
gcloud apphub discovered-services list \
    --filter='FILTER_RESOURCES' \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION
```
Replace FILTER_RESOURCES with filters such as:
- service_properties.gcp_project=projects/PROJECT_ID
- service_properties.gcp_project=projects/PROJECT_ID AND service_reference.uri~"forwardingRules" The output is similar to the following:
```
ID                           SERVICE_REFERENCE                                                                                                                    SERVICE_PROPERTIES
[DISCOVERED_SERVICE_ID]    {'uri': '//compute.googleapis.com/projects/[PROJECT_NUMBER]/regions/REGION/forwardingRules/forwarding-rule'}     {'gcpProject': 'projects/PROJECT_1', 'location': 'REGION'}
```
Copy the service ID, DISCOVERED_SERVICE_ID from the output to use in the next step.

gcloud apphub applications services create SERVICE_NAME \
    --discovered-service='projects/MANAGEMENT_PROJECT_ID/locations/REGION/discoveredServices/DISCOVERED_SERVICE' \
    --display-name='SERVICE_DISPLAY_NAME' \
    --application=APPLICATION_NAME \
    --criticality-type='CRITICALITY_LEVEL' \
    --environment-type='ENVIRONMENT' \
    --developer-owners=display-name=DISPLAY-NAME-DEVELOPER,email=EMAIL-DEVELOPER \
    --operator-owners=display-name=DISPLAY-NAME-OPERATOR,email=EMAIL-OPERATOR \
    --business-owners=display-name=DISPLAY-NAME-BUSINESS,email=EMAIL-BUSINESS \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION

Replace the following:

SERVICE_NAME: a name to register the service as.
DISCOVERED_SERVICE_ID: the service ID from the output of the previous step.
SERVICE_DISPLAY_NAME: the display name of your application.

Notes:

criticality-type and environment-type: (optional) You must provide one of the specified values but these values can be different from the values you set when you create the application. For more information, in this document, see Create an application.
developer-owners,operator-owners, and business-owners: (optional). For more information, in this document, see Create an application.

For example:

gcloud apphub applications services create my-service \
    --display-name='mywebserver-service' \
    --application=my-application \
    --criticality-type='MEDIUM' \
    --environment-type='STAGING' \
    --developer-owners=display-name=developer-name,email=username@yourdomain \
    --folder=folder-ID \
    --location=us-east1

List discovered workloads from an app-enabled folder. In the following command, you optionally specify the filter flag to return workloads from the specified project that are available to be registered to an application.

gcloud apphub discovered-workloads list \
    --filter='FILTER_RESOURCES' \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION

Replace FILTER_RESOURCES with a filter such as workload_properties.gcp_project=projects/PROJECT_ID.

You see output similar to the following, which includes an unregistered MIG:

ID                           WORKLOAD_REFERENCE                                                                                                      WORKLOAD_PROPERTIES
[DISCOVERED_WORKLOAD]   {'uri': '//compute.googleapis.com/projects/[PROJECT_NUMBER]/regions/REGION/instanceGroups/mig-name'}     {'gcpProject': 'projects/PROJECT', 'location': 'REGION'}

Copy the workload ID from the output to use in the next step.

gcloud apphub applications workloads create WORKLOAD_NAME \
    --discovered-workload='projects/MANAGEMENT_PROJECT_ID/locations/REGION/discoveredWorkloads/DISCOVERED_WORKLOAD_ID' \
    --display-name=WORKLOAD_DISPLAY_NAME' \
    --application=APPLICATION_NAME \
    --criticality-type='CRITICALITY_LEVEL' \
    --environment-type='ENVIRONMENT' \
    --developer-owners=display-name=DISPLAY-NAME-DEVELOPER,email=EMAIL-DEVELOPER \
    --operator-owners=display-name=DISPLAY-NAME-OPERATOR,email=EMAIL-OPERATOR \
    --business-owners=display-name=DISPLAY-NAME-BUSINESS,email=EMAIL-BUSINESS \
    --project=MANAGEMENT_PROJECT_ID \
    --location=REGION

Replace the following:

WORKLOAD_NAME: a name to register the workload as.
DISCOVERED_WORKLOAD_ID: the workload ID from the output of the previous step.
WORKLOAD_DISPLAY_NAME: the display name of your application.

Notes:

criticality-type and environment-type: (optional) You must provide one of the specified values but these values can be different from the values you set when you create the application. For more information, in this document, see Create an application.
developer-owners,operator-owners, and business-owners: (optional). For more information, in this document, see Create an application.

For example:

gcloud apphub applications workloads create my-workload \
    --display-name='mywebserver-deployment1' \
    --application=my-application \
    --criticality-type='MEDIUM' \
    --environment-type='STAGING' \
    --developer-owners=display-name=developer-name,email=username@yourdomain \
    --folder=folder-ID \
    --location=us-east1

The App Hub setup process is complete.

Add or remove projects

You can modify project attachments to make different infrastructure resources available to group into an application.

Console

Add a project to an app-enabled folder

In the Google Cloud console, go to the project selector page.

Go to project selector
Click Create project.
Name your project. Make a note of your generated project ID.
Edit the other fields as needed.
Click Create.

Remove a project from an app-enabled folder

In the Google Cloud console, go to the Manage resources page.
Go to Manage resources
In the project list, select the project that you want to delete, and then click Delete.
In the dialog, type the project ID, and then click Shut down to delete the project.

gcloud

Add a project to an app-enabled folder

gcloud projects create PROJECT_ID \
    --folder FOLDER_ID

Remove a project from an app-enabled folder

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Set up App Hub for app-enabled folders Stay organized with collections Save and categorize content based on your preferences.

Services and workloads

Overall setup process

Prerequisites

Required roles

Enable application management

Designate App Hub users

Console

gcloud

Create an application

Console

gcloud

Register services and workloads

Console

gcloud

Add or remove projects

Console

Add a project to an app-enabled folder

Remove a project from an app-enabled folder

gcloud

Add a project to an app-enabled folder

Remove a project from an app-enabled folder

What's next

Set up App Hub for app-enabled folders
Stay organized with collections Save and categorize content based on your preferences.