Set up App Hub with app-enabled folders

This page describes how to set up an app-enabled folder to build, operate, and manage App Hub applications on Google Cloud, as well as support users who set up and administer App Hub.

Overview of app-enabled folders

Application-centric Google Cloud offers application management capabilities to organize, deploy, and view Google Cloud resources in a way that aligns with business functions.

The app-enabled folder is a standard Google Cloud folder where you enable application management. This folder acts as an administrative boundary for applications and contains a Google-created management project to store application metadata and configurations.

By setting up App Hub with an app-enabled folder, you can organize resources from your Google Cloud projects, such as services and workloads, into logical applications.

You use Resource Manager to configure and manage app-enabled folders. For more information about this application-centric model and its resource organization, see Application-centric Google Cloud.

Configure an app-enabled folder

This section summarizes the essential steps for administrators to configure an app-enabled folder with Resource Manager and start using App Hub. Each step requires roles that depend on the user's responsibilities during the configuration process.

Enable application management on a folder

This initial action configures a standard Google Cloud folder for application-centric management. It automatically creates a dedicated management project and enables the required APIs to store application metadata and configurations. After enabling application management, the folder is referred to as the app-enabled folder.

For detailed instructions, see Enable application management.

You can start using App Hub's core features for organizing and observing your applications at no cost.

Optionally, to unlock all application lifecycle features, including paid APIs and services like Application Design Center, or to use the service for production-scale workloads, you can link an active billing account to the management project.

When you set up an app-enabled folder, the required APIs for application-centric capabilities are enabled automatically in the management project to provide basic features.

However, you can choose to expand application management capabilities by enabling additional recommended APIs. While optional, these APIs provide the full application lifecycle experience, including advanced design, deployment, and observability features. Review the recommended APIs listed on the Enable APIs on a management project page to understand their benefits, enablement steps, and associated costs.

Optional: Grant roles to users

Depending on your team's responsibilities, assign appropriate application-centric IAM roles to your team members, such as platform administrators, application developers, and operators. This step provides the necessary permissions to manage, develop, and monitor applications.

For a list of recommended roles for different application-centric user responsibilities at the project or folder level, see Grant application-centric roles to your users. To learn how to grant permissions for varying levels of application access, see Grant permissions to applications.

Configure the observability scope

After configuring an app-enabled folder, you can let services like Cloud Hub display telemetry data from all projects associated with your applications.

The observability scope determines where the Google Cloud console searches for telemetry data to display. Each Google Cloud project has a single observability scope, which identifies the default log and trace scopes. For metric data, the project's metrics scope determines where the Google Cloud console searches for data.

To view or analyze all of your application's telemetry data, configure the observability scope and the metrics scope for the management project. By configuring these scopes, Cloud Hub and other services can find and display your application's log, metric, and trace data, even when that data is stored in multiple projects.

This section summarizes the required configuration. For detailed instructions, see Set up application monitoring. The following table shows the required configuration scopes.

Scope component Configuration scenario Key actions and considerations
Log scope You use an aggregated sink to route all logs in the organization to a central log bucket.
  1. Create a log view that only includes application logs stored in the bucket.
  2. Configure the default log scope on the management project to include the log view.
You don't have an organization-level aggregated sink, and the app-enabled folder doesn't have nested folders.
  1. Configure an aggregated sink to route application logs to the _Default log bucket of the management project.
  2. Make sure that the log scope named _Default is the default log scope.
You don't want to use an aggregated sink. Configure the default log scope on the management project to list the storage locations of your application's log data.
Metrics scope You configured an app-enabled folder containing all the projects that store the metric data you want to view. Google Cloud Observability attempts to synchronize the list of projects in your app-enabled folder with the list of projects on the scope of the metrics.

As long as the number of projects in the app-enabled folder doesn't exceed your metric scope quota, Google Cloud Observability can keep the list of projects on the scope of the metrics updated when you add or remove projects in the app-enabled folder.
Trace scope You want to monitor application trace data across multiple projects.
  1. Create a custom trace scope on the management project that lists the projects that store your application's trace data.
  2. Set your custom trace scope as the default trace scope.

Disable application management

You can disable application management from your Google Cloud folder if you don't want it to be an app-enabled folder anymore. For detailed instructions, see Disable application management.

Create an application

After configuring the app-enabled folder, application developers can use App Hub to perform the following tasks:

  1. Create an application: Create a regional or global application that will serve as a logical container for your services and workloads. 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.

  2. Register services and workloads: Discover the available infrastructure resources within the projects in your app-enabled folder and register them to your application. This action formally associates your underlying infrastructure with the logical application in App Hub.

If you have Gemini Cloud Assist, after configuring an App Hub application in 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.

You can also use Application Design Center to design new applications from templates.

Follow these steps to create an application:

Console

  1. Make sure that you're in an app-enabled folder.

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

    Go to Applications

  3. Click Create application.

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

  5. Enter the Application name and click Continue.

  6. Optional: In the Add attributes section, enter the Display name.

  7. Optional: In the Criticality list, to indicate the importance of the application, select one of the following:

    • Mission critical
    • High
    • Medium
    • Low

  8. Optional: In the Environment list, to indicate the stage of the software lifecycle, select one of the following:

    • Production
    • Staging
    • Development
    • Test

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

  10. Repeat these steps for each developer, operator, and business owner.

  11. Click Create.

gcloud

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

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

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

    Go to Applications

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

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

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

  2. Register the forwarding rule, forwarding-rule-name` in a project as a service to your application.

    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

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

  4. Register the MIG, mig-name from the project as a workload to your application.

    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.

Manage projects in your app-enabled folder

App-enabled folders automatically make infrastructure resources from all descendant projects available to group into an application. You don't need to attach projects manually.

To control which resources are available, you can modify the folder hierarchy in the following ways:

  • Create or delete projects: Add or remove projects in the app-enabled folder or its subfolders.
  • Move projects: Move existing projects into or out of the app-enabled folder or its subfolders.
  • Move folders: Move entire folders of projects into or out of the app-enabled folder or its subfolders.

Create or delete projects

You can add new projects to your app-enabled folder's hierarchy or delete existing ones. For detailed instructions, see the Resource Manager documentation:

Move projects or folders

You can move existing projects and folders into or out of your app-enabled folder's hierarchy. For detailed instructions, see the Resource Manager documentation:

What's next