Register existing resources to an application

Registering your existing services and workloads into an application lets you simplify management by organizing resources based on their business purpose. This approach provides unified visibility, monitoring, governance, and operational control.

This guide shows you how to group existing services and workloads running in Google Cloud that are not yet formally defined as an application.

Before you begin

You must complete the initial setup for application management before organizing resources into applications. This process typically involves the following roles and steps:

  • For administrators:

    1. Set up application management. Configure an app-enabled folder or a host project to act as the administrative boundary for your applications.
    2. Enable required APIs. Enable APIs for all resources you intend to use.
    3. Grant access to users. Assign appropriate IAM roles based on user's responsibilities in the application lifecycle.

  • For developers and operators:

    1. Confirm with your administrator that the initial setup is finalized.
    2. Make sure you have the necessary IAM roles for the tasks you want to perform.
    3. Open your app-enabled folder or host project, depending on your setup model.

Create an application

Create an application in App Hub to act as a logical container for your existing services and workloads:

Console

  1. In the Google Cloud console, use the project picker to select your host project or the management project of the app-enabled folder, depending on your setup model.

  2. Navigate to the Applications page from App Hub:

    Go to Applications

  3. Click Create application.

  4. In the Choose application region and name pane, select the best location for your application based on your geographic distribution requirements:

    • Select Regional to create a regional application. Then, select the specific region for your application based on App Hub supported regions.
    • Select Global to create a global application.

    For more information about the best location for your application, see Global and regional applications.

  5. Enter the Application name and click Continue.

  6. Optional: Define the application's top-level attributes to support discoverability and governance:

    • In the Add attributes section, enter the Display name.
    • In the Criticality list, select a value to indicate the importance of the application.
    • In the Environment list, select a value to indicate the stage of the software lifecycle.
    • Add contact information details for owners, including their display name and email address. Note that email addresses must have the format username@yourdomain, for example, jane-doe@gmail.com.

  7. Click Create.

gcloud

  1. Use Google Cloud CLI to create an application from your terminal or Cloud Shell:

    gcloud apphub applications create APPLICATION_NAME \
  --project=PROJECT_ID \
  --scope-type=LOCATION \
  --location=REGION \
  --display-name=DISPLAY_NAME \
  --criticality-type=CRITICALITY \
  --environment-type=ENVIRONMENT \
  --developer-owners=display-name=DEV_NAME,email=DEV_EMAIL \
  --operator-owners=display-name=OPERATOR_NAME,email=OPERATOR_EMAIL \
  --business-owners=display-name=BUSINESS_NAME,email=BUSINESS_EMAIL

    Replace APPLICATION_NAME with the name of your application. The name must only include lowercase alphanumeric characters without spaces.

    Use optional flags such as --criticality-type to define the application's top-level attributes and support discoverability and governance.

    For required and optional flags, replace the following:

    • Required: PROJECT_ID: the ID of the host project or management project, depending on your setup model.

    • Required: LOCATION: the location for your application based on your geographic distribution requirements. Use one of the following values:

      • REGIONAL for regional applications.
      • GLOBAL for global applications.

      For more information about the best location for your application, see Global and regional applications.

    • Required: REGION: the specific region for your application. Use one of the following values:

      • If the --scope-type location for your application is set to REGIONAL, specify an App Hub supported region name.
      • If the --scope-type location for your application is set to GLOBAL, use global.

    • Optional: DISPLAY_NAME: the display name of your application.

    • Optional: CRITICALITY: the importance level of the application for your operations. Use one of the following values:

      • MISSION_CRITICAL
      • HIGH
      • MEDIUM
      • LOW

    • Optional: ENVIRONMENT: the stage of the software lifecycle. Use one of the following values:

      • PRODUCTION
      • STAGING
      • DEVELOPMENT
      • TEST

    • Optional: DEV_NAME and DEV_EMAIL: the display name and email address of the developer owner, respectively.

    • Optional: OPERATOR_NAME and OPERATOR_EMAIL: the display name and email address of the operator owner, respectively.

    • Optional: BUSINESS_NAME and BUSINESS_EMAIL: the display name and email address of the business owner, respectively.

  2. List the applications in your project:

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

    You must obtain an output similar to the following:

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

Register services and workloads

After creating an application, register your existing services and workloads to it:

Console

  1. In the Google Cloud console, use the project picker to select your host project or the management project of the app-enabled folder, depending on your setup model.

  2. Navigate to the Applications page from App Hub:

    Go to Applications

  3. Click the name of the application for which you want to register existing services and workloads.

  4. From the application's details page, select the Services and workloads tab. This tab displays the list of existing resources that you can register to the application. App Hub lets you select supported resources located within your resource hierarchy as services and workloads.

  5. For each service or workload you want to register, do the following:

    1. In the Services and workloads tab, click Register service/workload.
    2. Navigate to the Select resource pane and click Browse to find the service or workload you want to register.
    3. Choose the service or workload and click Select.
    4. In the Select resource pane, enter a name for the service or workload and click Continue.

    5. Optional: In the Add attributes pane, define the resource's top-level attributes to support discoverability and governance.

    6. Click Continue.

    7. Optional: In the Add owners section, add more details about the owners of the service or workload.

    8. Click Register.

The Services and workloads tab displays the registered service or workload.

gcloud

App Hub lets you select supported resources located within your resource hierarchy as services and workloads. Use Google Cloud CLI to list services or workloads that you can register to the application from your terminal or Cloud Shell. Commands are slightly different for services and workloads:

Register services

  1. List the available services that you can register to an application:

    gcloud apphub discovered-services list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter=FILTER_EXPRESSION

    For required and optional flags, replace the following:

    • Required: PROJECT_ID: the ID of the host project or management project, depending on your setup model.

    • Required: REGION: the specific region of your service based on your geographic distribution. Use one of the following values:

    • Optional: FILTER_EXPRESSION: the filter expression for the --filter flag to only display services from a specified project or with a specific property, for example:

      • 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 example:

    ID            SERVICE_REFERENCE                                                                                             SERVICE_PROPERTIES
SERVICE_ID    {'uri': '//compute.googleapis.com/projects/PROJECT_NUMBER/regions/REGION/forwardingRules/forwarding-rule'}    {'gcpProject': 'projects/PROJECT_ID', 'location': 'REGION'}

  2. Copy the service ID, SERVICE_ID, from the output.

  3. Register the service to your application:

    gcloud apphub applications services create SERVICE_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --application=APPLICATION_NAME \
  --discovered-service=projects/PROJECT_ID/locations/REGION/discoveredServices/SERVICE_ID \
  --display-name=SERVICE_DISPLAY_NAME \
  --criticality-type=CRITICALITY \
  --environment-type=ENVIRONMENT \
  --developer-owners=display-name=DEV_NAME,email=DEV_EMAIL \
  --operator-owners=display-name=OPERATOR_NAME,email=OPERATOR_EMAIL \
  --business-owners=display-name=BUSINESS_NAME,email=BUSINESS_EMAIL

    Replace SERVICE_NAME with the name you want to use to register the service to the application.

    Use optional flags such as --criticality-type to define the service's top-level attributes and support discoverability and governance.

    For required and optional flags, replace the following:

    • Required: PROJECT_ID: the ID of the host project or management project, depending on your setup model.

    • Required: REGION: the specific region of your service based on your geographic distribution. Use one of the following values:

    • Required: APPLICATION_NAME: the name of the application for which you want to register the service.

    • Required: SERVICE_ID: the service ID you copied from the previous output.

    • Optional: SERVICE_DISPLAY_NAME: the display name of your service.

    • Optional: CRITICALITY: the importance level of the service for your operations. Use one of the following values:

      • MISSION_CRITICAL
      • HIGH
      • MEDIUM
      • LOW

    • Optional: ENVIRONMENT: the stage of the software lifecycle. Use one of the following values:

      • PRODUCTION
      • STAGING
      • DEVELOPMENT
      • TEST

    • Optional: DEV_NAME and DEV_EMAIL: the display name and email address of the developer owner, respectively.

    • Optional: OPERATOR_NAME and OPERATOR_EMAIL: the display name and email address of the operator owner, respectively.

    • Optional: BUSINESS_NAME and BUSINESS_EMAIL: the display name and email address of the business owner, respectively.

  4. List the registered services in your application:

    gcloud apphub applications services list \
  --application=APPLICATION_NAME
  --project=PROJECT_ID \
  --location=REGION

    You must obtain an output similar to the following for each registered service:

    ID              DISPLAY_NAME            SERVICE_REFERENCE                                                                                             CREATE_TIME
SERVICE_NAME    SERVICE_DISPLAY_NAME    {'uri': '//compute.googleapis.com/projects/PROJECT_NUMBER/regions/REGION/forwardingRules/forwarding-rule'}    2023-11-01T21:38:08

Register workloads

  1. List the available workloads that you can register to an application:

    gcloud apphub discovered-workloads list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter=FILTER_EXPRESSION

    For required and optional flags, replace the following:

    • Required: PROJECT_ID: the ID of the host project or management project, depending on your setup model.

    • Required: REGION: the specific region of your workload based on your geographic distribution. Use one of the following values:

    • Optional: FILTER_EXPRESSION: the filter expression for the --filter flag to only display workloads from a specified project or with a specific property, for example, workload_properties.gcp_project=projects/PROJECT_ID.

    The output is similar to the following example:

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

  2. Copy the workload ID, WORKLOAD_ID, from the output.

  3. Register the workload to your application:

    gcloud apphub applications workloads create WORKLOAD_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --application=APPLICATION_NAME \
  --discovered-workload=projects/PROJECT_ID/locations/REGION/discoveredWorkloads/WORKLOAD_ID \
  --display-name=WORKLOAD_DISPLAY_NAME \
  --criticality-type=CRITICALITY \
  --environment-type=ENVIRONMENT \
  --developer-owners=display-name=DEV_NAME,email=DEV_EMAIL \
  --operator-owners=display-name=OPERATOR_NAME,email=OPERATOR_EMAIL \
  --business-owners=display-name=BUSINESS_NAME,email=BUSINESS_EMAIL

    Replace WORKLOAD_NAME with the name you want to use to register the workload to the application.

    Use optional flags such as --criticality-type to define the workload's top-level attributes and support discoverability and governance.

    For required and optional flags, replace the following:

    • Required: PROJECT_ID: the ID of the host project or management project, depending on your setup model.

    • Required: REGION: the specific region of your workload based on your geographic distribution. Use one of the following values:

    • Required: APPLICATION_NAME: the name of the application for which you want to register the workload.

    • Required: WORKLOAD_ID: the workload ID you copied from the previous output.

    • Optional: WORKLOAD_DISPLAY_NAME: the display name of your workload.

    • Optional: CRITICALITY: the importance level of the workload for your operations. Use one of the following values:

      • MISSION_CRITICAL
      • HIGH
      • MEDIUM
      • LOW

    • Optional: ENVIRONMENT: the stage of the software lifecycle. Use one of the following values:

      • PRODUCTION
      • STAGING
      • DEVELOPMENT
      • TEST

    • Optional: DEV_NAME and DEV_EMAIL: the display name and email address of the developer owner, respectively.

    • Optional: OPERATOR_NAME and OPERATOR_EMAIL: the display name and email address of the operator owner, respectively.

    • Optional: BUSINESS_NAME and BUSINESS_EMAIL: the display name and email address of the business owner, respectively.

  4. List the registered workloads in your application:

    gcloud apphub applications workloads list \
  --application=APPLICATION_NAME
  --project=PROJECT_ID \
  --location=REGION

    You must obtain an output similar to the following for each registered workload:

    ID               DISPLAY_NAME             WORKLOAD_REFERENCE                                                                                    CREATE_TIME
WORKLOAD_NAME    WORKLOAD_DISPLAY_NAME    {'uri': '//compute.googleapis.com/projects/PROJECT_NUMBER/regions/REGION/instanceGroups/mig-name'}    2023-11-01T21:38:08

Grant permissions and begin operations

After creating an application and registering your resources in App Hub, you grant user access based on responsibilities and manage this logic grouping as a single unit:

  1. Depending on your access needs, you can grant permissions to your application. For a list of recommended roles, see Grant application-centric roles to your users.
  2. Navigate to Cloud Hub to see a unified operational dashboard for your defined application, including its health, performance, and cost data.