Create an App Hub application using a single project

This tutorial shows you how to set up an App Hub application in a single project. In a service project that acts as the App Hub host project, you deploy a load balanced managed instance group (MIG). Then, you view the infrastructure resources as services and workloads in applications on the App Hub host project.

This tutorial is intended for people who set up and administer App Hub. It is expected that you have some background with load balancers.

Objectives

This tutorial shows you how to complete the following tasks:

Create a Google Cloud project. This project is your App Hub host project.
On the Google Cloud, using Terraform, deploy a load balanced MIG.
Provide the appropriate roles and permissions to the host project.
Attach the App Hub host project as a service project.
Create an application on the App Hub host project.
Discover the infrastructure resources as App Hub services and workloads.
Register services and a workload from the service project on the application and assign attributes.
View details of the registered services and workloads on App Hub.

Costs

For an estimate of the cost of the Google Cloud resources that the load balanced managed VM solution uses, see the precalculated estimate in the Google Cloud Pricing Calculator.

Use the estimate as a starting point to calculate the cost of your deployment. You can modify the estimate to reflect any configuration changes that you plan to make for the resources that are used in the solution.

The precalculated estimate is based on assumptions for certain factors, including the following:

The Google Cloud locations where the resources are deployed.
The amount of time that the resources are used.

For more information on App Hub costs, see the Pricing page.

Before you begin

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

If you are not 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 roles on your project:

Service Usage Admin (roles/serviceusage.services.enable)
Service Account Admin (roles/iam.serviceAccounts.create)
Project IAM Admin (roles/resourcemanager.projectIamAdmin)
Cloud Infrastructure Manager (roles/config.admin)
App Hub Admin (roles/apphub.admin)

For more information about granting roles, see Manage access.

You might also be able to get the required permissions through custom roles or other predefined roles.

Console

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

Go to project selector
Select or create a Google Cloud project, to be your App Hub host project.
Enable the required APIs.
Enable the APIs

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
```
Create or select a new project, HOST_PROJECT_ID, to be the host project for App Hub.
- Create a Google Cloud project:
```
gcloud projects create HOST_PROJECT_ID
```
- Select the Google Cloud project that you created:
```
gcloud config set project HOST_PROJECT_ID
```

Enable the APIs:

gcloud services enable apphub.googleapis.com \
   cloudresourcemanager.googleapis.com \
   compute.googleapis.com \
   config.googleapis.com \
   serviceusage.googleapis.com

Preparing the environment

To help you deploy this solution with minimal effort, a Terraform configuration is provided in GitHub. The Terraform configuration defines all the Google Cloud resources that are required for the solution. Download the Terraform configuration from GitHub, optionally customize the code as necessary, and then deploy the solution by using the Terraform CLI. After you deploy the solution, you can continue to use Terraform to manage the solution.

**Figure 1.**App Hub workloads and services with a load balancer and managed instance group.

The following is the request processing flow of the topology that the load balanced managed VM solution deploys.

The user makes a request to the application, which is deployed on Compute Engine. The request first lands on Cloud Load Balancing.
Cloud Load Balancing routes traffic to the Compute Engine managed instance group, using information in the forwarding rule, URL map, and backend service.

Set up the Terraform client

You can run Terraform either in Cloud Shell or on your local host. This guide describes how to run Terraform in Cloud Shell, which has Terraform preinstalled and configured to authenticate with Google Cloud.

The Terraform code for this solution is available in a GitHub repository.

In Cloud Shell, clone the GitHub repository to Cloud Shell.

git clone https://github.com/terraform-google-modules/terraform-docs-samples

In Cloud Shell, check whether the current working directory is terraform-docs-samples/lb/regional_external_http_load_balancer. This is the directory that contains the Terraform configuration files for the solution. If you need to change to that directory, run the following command:
```
cd terraform-docs-samples/lb/regional_external_http_load_balancer 
```
Initialize Terraform by running the following command:
```
terraform init
```
Wait until you see the following message:
```
Terraform has been successfully initialized!
```

Validate and review the Terraform configuration

Make sure that the current working directory is terraform-docs-samples/lb/regional_external_http_load_balancer. If it isn't, go to that directory.
Verify that the Terraform configuration has no errors:
```
terraform validate
```
If the command returns any errors, make the required corrections in the configuration and then run the terraform validate command again. Repeat this step until the command returns the following message:
```
Success! The configuration is valid.
```
Review the resources that are defined in the configuration:
```
terraform plan
```
The output of the terraform plan command is a list of the resources that Terraform provisions when you apply the configuration.

If you want to make any changes, edit the configuration and then run the terraform validate and terraform plan commands again.

Provision the resources

When no further changes are necessary in the Terraform configuration, deploy the resources.

Make sure that the current working directory is terraform-docs-samples/lb/regional_external_http_load_balancer. If it isn't, go to that directory.
Apply the Terraform configuration:
```
terraform apply
```
Terraform displays a list of the resources that will be created.
When you're prompted to perform the actions, enter yes.

Terraform displays messages showing the progress of the deployment.

If the deployment can't be completed, Terraform displays the errors that caused the failure. Review the error messages and update the configuration to fix the errors. Then run the terraform apply command again.

After all the resources are created, Terraform displays the following message:
```
Apply complete!
```

Wait until Terraform displays the "Apply complete!" message.

Cloud Load Balancing distributes traffic to the forwarding rule, URL map, backend service, and a Compute Engine MIG. The backend service, URL map, and forwarding rules become discovered services in the App Hub host project. The Compute Engine MIG becomes a discovered workload in the App Hub host project.

When you no longer need the solution, you can delete the deployment to avoid continued billing for the Google Cloud resources. For more information, see Delete the deployment.

Grant IAM permissions

If required, provide the appropriate IAM roles and permissions to the App Hub host project.

Console

Optionally, to get the permissions that you need to complete this tutorial, ask your administrator to grant you the required IAM roles on your project:
1. In the Google Cloud console, go to the IAM page.
  
  Go to IAM
2. Click Grant access. The Grant access pane opens.
3. In the New principals field, enter the email address of the individual who will administer App Hub, the App Hub Admin role in the host project.
4. Click Select a role and in the Filter field, enter App Hub.
5. Select the App Hub Admin role and click Save.

gcloud

Optionally, to grant the roles to individuals who will administer App Hub, repeat the following command by replacing the IAM roles, as required.
```
gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
    --member='user:HOST_PROJECT_ADMIN' \
    --role='roles/apphub.admin'
```
Replace HOST_PROJECT_ADMIN with the user who has the App Hub Admin role in the host project. This value has the format username@yourdomain, for example, robert.smith@example.com.
Grant the App Hub Admin role in the service project to the individuals who administers App Hub. They must have the App Hub Admin role to add service projects to the host project. You need at least one person with this role for each service project. In this example, the host project acts as the service project.
```
gcloud projects add-iam-policy-binding SERVICE_PROJECT_ID \
   --member='user:HOST_PROJECT_ADMIN' \
   --role='roles/apphub.admin'
```
Replace SERVICE_PROJECT_ID with the name of the HOST_PROJECT_ID.

Attach a service project

Attach the host project on which you deployed the resources, as the service project.

Console

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

Go to Settings
On the Settings page, click Attach projects.
On the pane that opens, search for projects or from the displayed list, select the checkbox for the host project.
Click Select. The Attached Service Project(s) table displays the selected host project as the service project.
Click Close.

gcloud

Add your host project as the service project to the App Hub host project.

gcloud apphub service-projects add HOST_PROJECT_ID \
  --project=HOST_PROJECT_ID

Create an application

Create an application to be the container of your services and workloads.

Console

Make sure that you're in the host project.
In the Google Cloud console, go to the App Hub Applications page.

Go to Applications
Click Create application. The Create Application pane is displayed.
In the Location list, select us-west1.
In the Application Name field, enter tutorial-application.
Click Continue.
In the Add attributes section, enter a Display name, sample-application.
In the Criticality list, select High. Criticality indicates how critical an application, service, or workload is to your business operations.
In the Environment field, to indicate the stage of the software lifecycle, select Production.
Click Continue.
In the Add owners section, add the following details 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, robert.smith@example.com.
Repeat these steps for each developer, operator, and business owner.
Click Create.

The new application gets created and is listed on the Applications page.

gcloud

Select the host project that you created:

gcloud config set project HOST_PROJECT_ID

Create a new application called tutorial-application in the region, us-west1and give it a display name, Tutorial:

gcloud apphub applications create tutorial-application \
    --display-name='Tutorial' \
    --scope-type=REGIONAL \
    --project=HOST_PROJECT_ID \
    --location=us-west1

List the applications in your host project.

gcloud apphub applications list \
    --project=HOST_PROJECT_ID \
    --location=us-west1

You see output similar to the following:

ID: tutorial-application
DISPLAY_NAME: Tutorial
CREATE_TIME: 2023-10-31T18:33:48

Update your application with the criticality-type, environment-type, and owner attributes:
```
gcloud apphub applications update tutorial-application \
  --criticality-type='HIGH' \
  --environment-type='PRODUCTION' \
  --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=HOST_PROJECT_ID \
  --location=us-west1
```
Replace the following:
- DISPLAY-NAME-DEVELOPER, DISPLAY-NAME-OPERATOR, and DISPLAY-NAME-BUSINESS: display names of the developer, operator, and business owners, respectively.
- EMAIL-NAME-DEVELOPER, EMAIL-NAME-OPERATOR, and EMAIL-NAME-BUSINESS: email addresses of the developer, operator, and business owners, respectively. These values must have the format username@yourdomain, for example, robert.smith@example.com.
Notes:
- criticality-type: indicates how critical an application, service, or workload is to your business operations.
- environment-type: indicates the stages of the software lifecycle.

Get details for the application that you created.

gcloud apphub applications describe tutorial-application \
  --project=HOST_PROJECT_ID \
  --location=us-west1

The command returns information in YAML format, similar to the following:

attributes:
businessOwners:
– displayName: [DISPLAY-NAME-BUSINESS]
  email: [EMAIL-BUSINESS]
criticality:
  type: HIGH
developerOwners:
– displayName: [DISPLAY-NAME-DEVELOPER]
  email: [EMAIL-DEVELOPER]
environment:
  type: PRODUCTION
operatorOwners:
– displayName: [DISPLAY-NAME-OPERATOR]
  email: [EMAIL-OPERATOR]
createTime: '2023-10-31T18:33:48.199394108Z'
displayName: Tutorial
name: projects/HOST_PROJECT_ID/locations/us-west1/applications/tutorial-application
scope:
  type: REGIONAL
state: ACTIVE
uid: 9d991a9d-5d8a-4c0d-b5fd-85e39fb58c73
updateTime: '2023-10-31T18:33:48.343303819Z'

Register services and a workload

Registering services and workloads adds them to an application.

Console

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

Go to Applications
Click the name of your application, sample-application. The Services and workloads tab is displayed with a list of registered services and workloads that are in your service projects.
Register a service:
1. On the Services and workloads tab, click Register service/workload.
2. In the Register service or workload pane, in the Choose service or workload section, select the Name of the service, l7-xlb-backend-service, and click Continue.
3. In the Add attributes section, enter the Name of the attribute, sample-service-backend.
4. Enter a Display name, service-backend.
5. In the Criticality list, to indicate the importance of the application, select High.
6. In the Environment field, to indicate the stage of the software lifecycle, select Production.
7. Click Continue.
8. 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, robert.smith@example.com.
9. Repeat these steps for each developer, operator, and business owner.
10. Click Register.
On the Services and workloads tab, in the Registered services and workloads section, you can see the new service added.
Repeat the previous steps to register the other services as sample-service-forwarding-rule and sample-service-url-map, respectively.
Register a workload by repeating the earlier steps to register a service with the following exceptions:
1. In the Register service or workload pane, in the Choose service or workload section, select the Name of the workload, l7-xlb-backend-example, and click Continue.
2. In the Add attributes section, enter the Name of the attribute, sample-workload.
3. Enter a Display name, workload-instance-group.
On the Services and workloads tab, in the Registered services and workloads section, you can see the new workload added.

gcloud

Add an individual with App Hub Editor permissions.
```
gcloud projects add-iam-policy-binding HOST_PROJECT_ID \
  --member='user:APP_HUB_EDITOR' \
  --role='roles/apphub.editor'
```
Replace APP_HUB_EDITOR with the user who has the App Hub Editor role in the host project. This value has the format username@yourdomain, for example, robert.smith@example.com.

List all discovered services in the host project. This command returns services that are available to be registered to an application.

gcloud apphub discovered-services list \
    --project=HOST_PROJECT_ID \
    --location=us-west1

You see output similar to the following:

ID: 71dd6fa4-5644-43ee-918f-c5fda03ffe24
SERVICE_REFERENCE: {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/backendServices/l7-xlb-backend-service'}
SERVICE_PROPERTIES: {'gcpProject': 'projects/SERVICE_PROJECT_ID', 'location': 'us-west1'}

ID: fe831ba4-ec16-4eb8-9ea4-b394fd30f561
SERVICE_REFERENCE: {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/forwardingRules/l7-xlb-forwarding-rule'}
SERVICE_PROPERTIES: {'gcpProject': 'projects/SERVICE_PROJECT_ID', 'location': 'us-west1'}

ID: 637a3216-c6cc-410e-8bf9-83b7ef66a62f
SERVICE_REFERENCE: {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/urlMaps/regional-l7-xlb-map'}
SERVICE_PROPERTIES: {'gcpProject': 'projects/SERVICE_PROJECT_ID', 'location': 'us-west1'}

Copy the service ID, for example, 71dd6fa4-5644-43ee-918f-c5fda03ffe24 from the output to use in the next step.

Register the services from the previous step to your application. Copy the service IDs from the output field in the previous step.

gcloud apphub applications services create sample-service-backend \
    --discovered-service='projects/HOST_PROJECT_ID/locations/us-west1/discoveredServices/BACKEND_SERVICE_ID' \
    --display-name='service-backend' \
    --criticality-type='HIGH' \
    --environment-type='PRODUCTION' \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

gcloud apphub applications services create sample-service-forwarding-rule \
    --discovered-service='projects/HOST_PROJECT_ID/locations/us-west1/discoveredServices/FORWARDING_RULE_SERVICE_ID' \
    --display-name='service-forwarding-rule' \
    --criticality-type='HIGH' \
    --environment-type='PRODUCTION' \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

gcloud apphub applications services create sample-service-url-map \
    --discovered-service='projects/HOST_PROJECT_ID/locations/us-west1/discoveredServices/URL_MAP_SERVICE_ID' \
    --display-name='url-map' \
    --criticality-type='HIGH' \
    --environment-type='PRODUCTION' \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

Replace the following:

BACKEND_SERVICE_ID: the service ID of the backend service that you want to register.
FORWARDING_RULE_SERVICE_ID: the service ID of the forwarding rule that you want to register.
URL_MAP_SERVICE_ID: the service ID of the URL map that you want to register.

List all registered services in the application.

gcloud apphub applications services list \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

You see output similar to the following:

ID: sample-service-backend
DISPLAY_NAME: service-backend
SERVICE_REFERENCE:  {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/backendServices/l7-xlb-backend-service'}
CREATE_TIME: 2024-02-13T00:31:45

ID: sample-service-forwarding-rule
DISPLAY_NAME: service-forwarding-rule
SERVICE_REFERENCE:  {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/forwardingRules/l7-xlb-forwarding-rule'}
CREATE_TIME: 2024-02-13T00:31:45

ID: sample-service-url-map
DISPLAY_NAME: url-map
SERVICE_REFERENCE:  {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/regions/us-west1/urlMaps/regional-l7-xlb-map'}
CREATE_TIME: 2024-02-13T00:31:45

Registered, but detached services are denoted by an empty value in the SERVICE_REFERENCE field. For more information on the registration statuses, see the properties and attributes of App Hub.

List all discovered workloads in the host project. This command returns workloads that are available to be registered to an application.

gcloud apphub discovered-workloads list \
    --project=HOST_PROJECT_ID \
    --location=us-west1

You see output similar to the following:

ID: c9c08669-0fd2-4f7c-b2b1-2cf3c57662c2
WORKLOAD_REFERENCE: {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/zones/us-west1-a/instanceGroups/l7-xlb-backend-example'}
WORKLOAD_PROPERTIES: {'gcpProject': 'projects/SERVICE_PROJECT_ID', 'location': 'us-west1', 'zone': 'us-west1-a'}

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

Register the workload from the previous step to your application as sample-workload. Copy the workload ID from the output field in the previous step.

gcloud apphub applications workloads create sample-workload \
    --discovered-workload='projects/HOST_PROJECT_ID/locations/us-west1/discoveredWorkloads/WORKLOAD_ID' \
    --display-name='workload-instance-group' \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

Replace WORKLOAD_ID with the ID of the workload that you want to register.

List all registered workloads in the application.

gcloud apphub applications workloads list \
    --application=tutorial-application \
    --project=HOST_PROJECT_ID \
    --location=us-west1

You see output similar to the following:

ID: sample-workload
DISPLAY_NAME: workload-instance-group
WORKLOAD_REFERENCE: {'uri': '//compute.googleapis.com/projects/[SERVICE_PROJECT_NUMBER]/zones/us-west1-a/instanceGroups/l7-xlb-backend-example'}
CREATE_TIME: 2024-02-13T00:31:45

Registered, but detached workloads are denoted by an empty value in the WORKLOAD_REFERENCE field. For more information on the registration statuses, see the properties and attributes of App Hub.

View all services and workloads

You can view details of the services and workloads from all the service projects that are attached to the host project.

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

Go to Services and Workloads
All the services and workloads from the attached service projects are displayed.
In the Region list, select us-west1. The workload-instance-group workload is displayed with details such as App Hub Type, Criticality, and Registered to.
To filter the services or workloads based on its state:
1. In the Filter field, select filters such as Registration status.
2. Click Registered. A list of services and workloads registered to the application appears.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Delete the App Hub resources

Console

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

Go to Applications
Click the name of an application, sample-application.
On the Services and workloads tab, from the Registered services and workloads section, click the name of the service, service-forwarding-rule.
On the Services and Workloads page, click Unregister. An alert notifies that the service is unregistered.
On the Services and workloads tab, from the Registered services and workloads section, click the name of the workload, workload-instance-group.
On the Services and Workloads page, click Unregister. An alert notifies that the workload is unregistered.
Go to the App Hub Applications page.

Go to Applications
Click the name of an application.
On the tutorial-application page, click Delete.
In the Google Cloud console, go to the App Hub Settings page.

Go to Settings
On the Settings page, select the checkbox for the SERVICE_PROJECT_ID you want to remove from the host project.
Click Detach projects.

gcloud

List the registered services in the application:

gcloud apphub applications services list \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

Unregister the services from the application:

gcloud apphub applications services delete sample-service-backend \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

gcloud apphub applications services delete sample-service-forwarding-rule \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

gcloud apphub applications services delete sample-service-url-map \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

The services are now discovered services that can be registered to the application.

List the registered workloads in the application:

gcloud apphub applications workloads list \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

Unregister the workload from the application:

gcloud apphub applications workloads delete sample-workload \
  --application=tutorial-application --project=HOST_PROJECT_ID \
  --location=us-west1

The workload is now a discovered workload that can be registered to the application.

Delete the application:

gcloud apphub applications delete tutorial-application \
  --project=HOST_PROJECT_ID \
  --location=us-west1

Remove the service project from the host project:

gcloud apphub service-projects remove SERVICE_PROJECT_ID \
  --project=HOST_PROJECT_ID

Delete the deployment

When you no longer need the solution, to avoid continued billing for the resources that you created in this solution, delete all the resources.

Use this procedure if you deployed the solution by using the Terraform CLI.

In Cloud Shell, make sure that the current working directory is terraform-docs-samples/lb/regional_external_http_load_balancer. If it isn't, go to that directory.
Remove the resources that were provisioned by Terraform:
```
terraform destroy
```
Terraform displays a list of the resources that will be destroyed.
When you're prompted to perform the actions, enter yes.

Terraform displays messages showing the progress. After all the resources are deleted, Terraform displays the following message:
```
Destroy complete!
```

When you no longer need the Google Cloud project that you used for the solution, you can delete the project.

Delete the project

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Replace PROJECT_ID with the HOST_PROJECT_ID

What's next

App Hub overview