Set up App Hub for app-enabled folders

Preview — App-enabled folders and Management projects

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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:

1. 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.
2. 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.
3. Designate App Hub users as App Hub Admins, App Hub Editors, or App Hub Viewers.
4. 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.
5. 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.

1. Ensure that you have the required IAM role to activate or create a billing account for your management project.
2. 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.
3. 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 how to view your application's data in one place, see Cloud Hub overview.

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

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

   Go to App Hub

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

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

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

   Go to IAM

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

3. On the IAM page, click Grant access. The Grant access pane opens.

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

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

6. Select the App Hub Admin role and click Save.

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

8. Click Save.

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. Run the following command from the Cloud Shell:

   gcloud components update

3. 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, [e-mail].

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

Note: To turn off application management on a folder, you must submit a support request.

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

Create a Google Cloud project.

gcloud projects create PROJECT_ID

Replace PROJECT_ID with a name for the Google Cloud project you are creating.

Roles required to create a project

To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Remove a project from an app-enabled folder

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

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

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as an appspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

What's next

• Set up application monitoring
• Modify App Hub resources
• App Hub IAM roles and permissions
• App Hub overview