Map custom domains using a global external Application Load Balancer

To set up a new public endpoint for your Cloud Run service, you can use Cloud Load Balancing to add a global external Application Load Balancer in front of your Cloud Run service. The global external Application Load Balancer lets you control your custom domain setup, but requires setup steps if you don't already own a TLS certificate or use a global external Application Load Balancer.

By using the Cloud Run integrations (Preview) described on this page, you can quickly set up a new custom domain mapping for your Cloud Run service using a global external Application Load Balancer. If you want to use an existing global external Application Load Balancer, refer to setting up a global external Application Load Balancer with Cloud Run.

Before you begin

Ensure you have the required access to make DNS changes for the domain you want to map to the Cloud Run service.

Make sure the Cloud Run service you are integrating with is already deployed.
Review the global external Application Load Balancer pricing page. You are billed for individual resources used in the integration.

Required roles

To use the Cloud Run integrations, you or your administrator must grant IAM roles on two different principals.

Click to view required roles for your Google Account

To get the permissions that you need to use Cloud Run integrations, ask your administrator to grant your Google Account the following IAM roles on your project:

Cloud Run Developer (roles/run.developer)
Compute Viewer (roles/compute.viewer)
Serverless Integrations Developer (roles/runapps.developer)
Serverless Integrations Operator (roles/runapps.operator)
Service Account User (roles/iam.serviceAccountUser)

Click to view the required roles for the service account

To deploy the Cloud Run service, you can either use the auto-created Compute Engine default service account, or specify a user-managed service account. The service account must have the following roles:

Cloud Run Developer (roles/run.developer)
Logs Bucket Writer (roles/logging.bucketWriter)
Service Account User (roles/iam.serviceAccountUser)
Storage Admin (roles/storage.admin)

Compute Load Balancer Admin (roles/compute.loadBalancerAdmin)

Map a custom domain with a global external Application Load Balancer

You can map a custom domain using the console or the command line. Note that it may take up to an hour for the SSL certificate to provision and for your domain to begin routing HTTPS traffic to your Cloud Run service.

Console

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

Go to Cloud Run
Click the service in the services list that you want to use in this integration.
Click the Integrations tab.
Click Add integration.
Click Custom Domains - Google Cloud load balancing.
Enter the domain in the Domain field.
Enter the domain path you are using in the Path field.
Enter the name of the service you are mapping to this custom domain in the Service field.
If you are mapping other domains, click Add Item and repeat the previous steps to map domain to service as needed.
If prompted to enable a list of APIs, click Enable and wait for the APIs to be enabled.
Under Resources, note the new resources that will be created as a result of this integration.
Click Submit and wait for the integration and resources to be created:
- When complete, a table is created with the DNS records you need to configure: use this to update your DNS records at your DNS provider.
- After you update your DNS at your DNS provider, it can take up to 45 minutes to provision the SSL certificate and begin routing traffic to your service.

Command line

Update to the latest Google Cloud CLI:
```
gcloud components update
```
Create the integration:
```
gcloud beta run integrations create \
--type=custom-domains \
--parameters='set-mapping=DOMAIN:SERVICE' \
```
Replace:
- DOMAIN with your custom domain, for example, example.com or subdomain.example.com
  - Can also contain path, like example.com/subpath/*
- SERVICE with your Cloud Run service name.
Optionally, include the --service-account=SERVICE_ACCOUNT_EMAIL flag.
- Replace SERVICE_ACCOUNT_EMAIL with the user-managed service account email address (PROJECT_NUMBER-compute@developer.gserviceaccount.com) that is used to deploy the service. Omit this flag if you want to use the default compute service account (SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com).
  
  To continue using the specified service account when deploying Cloud Run integrations, run:
```
gcloud config set runapps/deployment-service-account
```

Wait about 2 to 5 minutes, during which time a fully configured load balancer is created. When the process is complete, the following message is shown:

[custom-domains] integration [custom-domains] has been created successfully.
To complete the process, please ensure the following DNS records are configured for the domains:
NAME    TTL   TYPE  DATA
DOMAIN  3600  A     IP_ADDRESS
It can take up to an hour for the SSL certificate to be provisioned.

You can check the status using gcloud beta run integrations describe.

Update your DNS records at your DNS provider with the IP_ADDRESS value displayed. After you update your DNS at your DNS provider, it can take up to 45 minutes to provision the SSL certificate and begin routing traffic to your service.

Update custom domains with load balancer integrations

Updating an integration will update all of the Google Cloud resources associated with that integration. To update a custom domains with load balancer integration from your Cloud Run service:

Console

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

Go to Cloud Run
Click the service you want to update.
Click the Integrations tab.
Locate the custom domains with load balancer integration and click Edit.
When you are finished with updating the fields, click Update.

Command line

Use the following command to get a list of available integrations:
```
gcloud beta run integrations list
```

Run the command to update the integration:

gcloud beta run integrations update INTEGRATION_NAME

Replace:

INTEGRATION_NAME with the name of your custom domains with load balancer integration.

Optionally, you can use the following flag options:

Option	Description
`--parameters`	The custom domain to set for the service.
`--service-account`	The user-managed service account email address to specify when updating the service. This service account overrides the previous service account that was used at deployment.

View custom domains with load balancer integrations

To view the current status of custom domains with load balancer integrations for your Cloud Run service:

Console

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

Go to Cloud Run
Click the service in the services list that you want to use in this integration.
Click the Integrations tab.
Locate the custom domains with load balancer integration you are interested in and click View details.

Command line

Use the following command to get a list of available integrations:
```
gcloud beta run integrations list
```
Using a name from the returned list, display the details for it:
```
gcloud beta run integrations describe INTEGRATION_NAME
```
Replace INTEGRATION_NAME with the name of your custom domains with load balancer integration.

Delete custom domains with load balancer integrations

Deleting an integration will also delete all of the Google Cloud resources associated with that integration, but it will not delete your Cloud Run service.

To delete a custom domains with load balancer integration from your Cloud Run service:

Console

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

Go to Cloud Run
Click the service you want to delete an integration from.
Click the Integrations tab.
Locate the custom domains with load balancer integration you are interested in and click the ellipsis icon to the right of the integration, then click Delete.

Command line

Use the following command to get a list of available integrations:
```
gcloud beta run integrations list
```
Using a name from the returned list, delete the integration:
```
gcloud beta run integrations delete INTEGRATION_NAME
```
Replace:
- INTEGRATION_NAME with the name of your custom domains with load balancer integration.
Optionally, you can use the following flag options:

Option Description

--service-account The user-managed service account email address to perform the delete operation.

Option	Description
`--service-account`	The user-managed service account email address to perform the delete operation.

Limitations

The Cloud Run integrations is only supported in certain regions. If you need to use a region that is not supported by the Cloud Run integrations, refer to setting up a global external Application Load Balancer with Cloud Run.