Deploy a global Google-managed certificate with load balancer authorization

---

This tutorial walks you through the certificate deployment process using a Google-managed certificate with load balancer authorization as an example.

For a comparison of the supported types of domain authorization, see Domain authorization.

The following load balancers support Google-managed certificates with load balancer authorization:

• Global external Application Load Balancer
• Classic Application Load Balancer
• Global external proxy Network Load Balancer

If you want to migrate an existing certificate to Certificate Manager, follow the steps in Migrate certificates to Certificate Manager instead.

Objectives

This tutorial shows you how to complete the following tasks:

• Create a Google-managed certificate issued by a publicly trusted CA with load balancer authorization by using Certificate Manager.
• Deploy the certificate to a supported load balancer by using a target HTTPS proxy.

For more information about the certificate deployment process, see Deployment overview.

If you are following the steps in this tutorial to deploy a certificate for a domain that is already serving production traffic keep in mind that traffic for that domain will be interrupted while the certificate is provisioned and activated on the corresponding load balancer.

Before you begin

1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

2. Make sure that you have the following roles to complete the tasks in this tutorial:

   • Certificate Manager Owner: Required to create and manage Certificate Manager resources.
   • Compute Load Balancer Admin or Compute Network Admin: Required to create and manage HTTPS target proxy.
   • DNS Administrator: Required if you want to use Cloud DNS as your DNS solution.

   For more information, see the following:

   • Roles and permissions for Certificate Manager
   • Compute Engine IAM roles and permissions for Compute Engine
   • Access control with IAM for Cloud DNS
   Note: If you aren't assigned the permissions or roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to request the missing roles.

Create a Google-managed certificate with load balancer authorization

Note: For information on when to use load balancer authorization with a Google-managed certificate, see Domain authorizations.

To create a Google-managed certificate with load balancer authorization, complete the steps in this section.

To specify multiple domain names for the certificate, provide a comma-delimited list of target domain names for the certificate.

For more information, see Permissions and roles.

gcloud

gcloud certificate-manager certificates create CERTIFICATE_NAME \
--domains="DOMAIN_NAMES"

Replace the following:

• CERTIFICATE_NAME: a unique name of the certificate.
• DOMAIN_NAMES: a comma-delimited list of the target domains for this certificate. Each domain name must be a fully qualified domain name, such as myorg.example.com.

Terraform

Use a google_certificate_manager_certificate resource.

resource "google_certificate_manager_certificate" "default" {
  name        = "${local.name}-rootcert-${random_id.tf_prefix.hex}"
  description = "Cert with LB authorization"
  managed {
    domains = [local.domain]
  }
  labels = {
    "terraform" : true
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

Create the certificate by making a POST request to the certificates.create method as follows:

POST /v1/projects/PROJECT_ID/locations/global/certificates?certificate_id=CERTIFICATE_NAME"
{
 "managed": {
  "domains": ["DOMAIN_NAME"],
 }
}

Replace the following:

• PROJECT_ID: the ID of the target Google Cloud project.
• CERTIFICATE_NAME: a unique name that describes this certificate.
• DOMAIN_NAME: the target domain for this certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.

For an overview of the certificate deployment process, see Deployment overview.

Deploy the certificate to a load balancer

Complete the steps in this section to deploy the Google-managed certificate you created in the previous steps to a load balancer.

Create a certificate map

Create a certificate map that references the certificate map entry associated with your certificate.

gcloud

gcloud certificate-manager maps create CERTIFICATE_MAP_NAME

Replace CERTIFICATE_MAP_NAME with the name of the target certificate map.

Terraform

Use a google_certificate_manager_certificate_map resource.

resource "google_certificate_manager_certificate_map" "default" {
  name        = "${local.name}-certmap1-${random_id.tf_prefix.hex}"
  description = "${local.domain} certificate map"
  labels = {
    "terraform" : true
  }
}

Create a certificate map entry

Create a certificate map entry and associate it with your certificate as well as your certificate map.

gcloud

gcloud certificate-manager maps entries create CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME" \
    --certificates="CERTIFICATE_NAME" \
    --hostname="HOSTNAME"

Replace the following:

• CERTIFICATE_MAP_ENTRY_NAME: a unique name of the certificate map entry
• CERTIFICATE_MAP_NAME: the name of the certificate map to which this certificate map entry attaches
• CERTIFICATE_NAME: the name of the certificate you want to associate with this certificate map entry
• HOSTNAME: the hostname that you want to associate with this certificate map entry

Terraform

Use a google_certificate_manager_certificate_map_entry resource.

resource "google_certificate_manager_certificate_map_entry" "default" {
  name        = "${local.name}-first-entry-${random_id.tf_prefix.hex}"
  description = "example certificate map entry"
  map         = google_certificate_manager_certificate_map.default.name
  labels = {
    "terraform" : true
  }
  certificates = [google_certificate_manager_certificate.default.id]
  hostname     = local.domain
}

Verify that the certificate map entry is active

Use the following command to verify that the certificate map entry is active before attaching its corresponding certificate map to the target proxy:

gcloud certificate-manager maps entries describe CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME"

Replace the following:

• CERTIFICATE_MAP_ENTRY_NAME: the name of the target certificate map entry
• CERTIFICATE_MAP_NAME: the name of the certificate map to which this certificate map entry attaches

The command returns output similar to the following:

createTime: '2021-09-06T10:01:56.229472109Z'
name: projects/my-project/locations/global/certificateMaps/myCertMap/certificateMapEntries/myCertMapEntry
state: ACTIVE
updateTime: '2021-09-06T10:01:58.277031787Z'

Attach the certificate map to the target proxy

Attach the configured certificate map to the desired target proxy.

Console

1. In the Google Cloud console, go to the Target proxies page.

Go to Target proxies

1. Note the name of the target proxy.

2. Attach the certificate map to the target proxy:

   gcloud compute target-https-proxies update PROXY_NAME \
       --certificate-map="CERTIFICATE_MAP_NAME"
   

Replace the following:

*   `PROXY_NAME`: the name of the target proxy
*   `CERTIFICATE_MAP_NAME`: the name of the certificate
    map referencing your certificate map entry and its associated
    certificate

Terraform

Use a google_compute_target_https_proxy resource.

resource "google_compute_target_https_proxy" "default" {
  name            = "test-proxy"
  certificate_map = "//certificatemanager.googleapis.com/${google_certificate_manager_certificate_map.default.id}"
  url_map         = google_compute_url_map.default.id
}

If there are any existing TLS (SSL) certificates attached directly to the proxy, the proxy gives preference to the certificates referenced by the certificate map over the directly attached TLS (SSL) certificates.

Wait until the certificate has been activated

After you have attached the certificate to the target proxy, it can take up to several hours for the certificate to be issued and its status change to ACTIVE. Once the status is ACTIVE, it can take up to 30 minutes for the load balancer to start using the certificate.

Use the following command to check the status of the certificate:

gcloud certificate-manager certificates describe CERTIFICATE_NAME

Replace CERTIFICATE_NAME with the name of the target Google-managed certificate.

The command returns output similar to the following:

certificatePem: myPEM
createTime: '2021-10-20T12:19:53.370778666Z'
expireTime: '2022-05-07T05:03:49Z'
managed:
  authorizationAttemptInfo:
  -   domain: myorg.example.com
    state: AUTHORIZED
  domains:
  -   myorg.example.com
    state: ACTIVE
name: projects/myProject/locations/global/certificates/myCert
scope: myScope
sanDnsnames:
  -   myorg.example.com
updateTime: '2021-10-20T12:19:55.083385630Z'

If the certificate status has not changed to ACTIVE after several hours, check the following:

• The certificate map referencing this certificate has been attached to the correct target proxy as described in Attach a certificate map to a proxy.
• The target proxy has been attached to the correct load balancer as described in Verify the target proxy association.
  • The target domain's DNS configuration points to the target load balancer's IP address as described in Update the DNS A and AAAA records to point to the load balancer's IP address.

For more troubleshooting steps, see Troubleshooting SSL certificates.

Clean up

To revert the changes you have made in this tutorial, complete the following steps:

1. Detach the certificate map from the proxy.

   Before you detach the certificate map, note the following:

   • If there were any TLS (SSL) certificates attached directly to the proxy, detaching the certificate map causes the proxy to resume using those directly attached TLS (SSL) certificates.
   • If there were no TLS (SSL) certificates attached directly to the proxy, the certificate map can't be detached from the proxy. You must first attach at least one TLS (SSL) certificate directly to the proxy before you can detach the certificate map.

   To detach the certificate map, run the following command:

   gcloud compute target-https-proxies update PROXY_NAME \
      --clear-certificate-map
   

2. Delete the certificate map entry from the certificate map:

   gcloud certificate-manager maps entries delete CERTIFICATE_MAP_ENTRY_NAME \
     --map="CERTIFICATE_MAP_NAME"
   

   Replace the following:

   • CERTIFICATE_MAP_ENTRY_NAME: the name of the target certificate map entry
   • CERTIFICATE_MAP_NAME: the name of the target certificate map

3. Delete the certificate map:

   gcloud certificate-manager maps delete CERTIFICATE_MAP_NAME
   

   Replace CERTIFICATE_MAP_NAME with the name of the target certificate map.

4. Delete the Google-managed certificate:

   gcloud certificate-manager certificates delete CERTIFICATE_NAME
   

   Replace CERTIFICATE_NAME with the name of the target certificate.

What's next

• Migrate certificates to Certificate Manager
• Manage certificates
• Manage certificate maps
• Manage certificate map entries
• Manage DNS authorizations