Deploy a global Google-managed certificate with DNS authorization

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

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

  • Global external Application Load Balancer
  • Classic Application Load Balancer
  • Cross-region internal Application Load Balancer
  • Global external proxy Network Load Balancer

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

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 certificate authority with DNS 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.

Before you begin

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

    Go to project selector

  2. The gcloud CLI version 465.0.0 or later is required to deploy the certificate. To check your gcloud CLI version, run the following command:

    gcloud --version

  3. To update the gcloud CLI run the following command.

    gcloud components update

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

Create a Google-managed certificate with DNS authorization

Complete the steps in this section to create a DNS authorization and a Google-managed certificate that references that DNS authorization.

Create a DNS authorization

Create the DNS authorization as described in this section. If you're creating a DNS authorization for a wildcard certificate, such as *.myorg.example.com, configure the DNS authorization for the parent domain—for example, myorg.example.com.

gcloud 

gcloud certificate-manager dns-authorizations create AUTHORIZATION_NAME \
    --domain="DOMAIN_NAME"
gcloud certificate-manager dns-authorizations describe AUTHORIZATION_NAME

The default DNS authorization type for a global Google-managed certificate is FIXED_RECORD. To use per-project DNS authorization, run the following commands:

gcloud certificate-manager dns-authorizations create AUTHORIZATION_NAME \
    --domain="DOMAIN_NAME" \
    --type="PER_PROJECT_RECORD"
gcloud certificate-manager dns-authorizations describe AUTHORIZATION_NAME

Replace the following:

  • AUTHORIZATION_NAME: the name of the DNS authorization.
  • DOMAIN_NAME: the name of the domain for which you are creating this DNS authorization. The domain name must be a fully qualified domain name, such as myorg.example.com.

The command returns an output similar to the following. Use the CNAME record from the output to add to your DNS configuration.

createTime: '2022-01-14T13:35:00.258409106Z'
dnsResourceRecord:
data: 0e40fc77-a37d-4eb8-8fe1-eea2e18d12d9.4.authorize.certificatemanager.goog.
name: _acme-challenge.myorg.example.com.
type: CNAME
domain: myorg.example.com
name: projects/myProject/locations/global/dnsAuthorizations/myAuthorization
updateTime: '2022-01-14T13:35:01.571086137Z'

Terraform

To create a DNS authorization, you can use a google_certificate_manager_dns_authorization resource.

resource "google_certificate_manager_dns_authorization" "default" {
  name        = "${local.name}-dnsauth-${random_id.tf_prefix.hex}"
  description = "The default dns auth"
  domain      = local.domain
  labels = {
    "terraform" : true
  }
}

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

Add the CNAME record to your DNS configuration

If you're using Google Cloud to manage your DNS, complete the steps in this section. Otherwise, consult the documentation for your third-party DNS solution.

Before completing the steps in this section, make sure you have created a public DNS zone.

When you create a DNS authorization, the gcloud CLI command returns the corresponding CNAME record. You must add this CNAME record to your DNS configuration in the DNS zone of the target domain as follows:

gcloud

  1. Initiate the DNS record transaction:

    gcloud dns record-sets transaction start --zone="DNS_ZONE_NAME"

    Replace DNS_ZONE_NAME with the name of the target DNS zone.

  2. Add the CNAME record to the target DNS zone:

    gcloud dns record-sets transaction add CNAME_RECORD \
    --name="_acme-challenge.DOMAIN_NAME." \
    --ttl="30" \
    --type="CNAME" \
    --zone="DNS_ZONE_NAME"

    Replace the following:

    • CNAME_RECORD: the full data value of the CNAME record returned by the Google Cloud CLI command that created the corresponding DNS authorization.
    • DOMAIN_NAME: the name of the target domain. The domain name must be a fully qualified domain name, such as myorg.example.com. You must also include the trailing period after the target domain name.
    • DNS_ZONE_NAME: the name of the target DNS zone.

    See the following example:

    gcloud dns record-sets transaction add 0e40fc77-a37d-4eb8-8fe1-eea2e18d12d9.4.authorize.certificatemanager.goog. \
    --name="_acme-challenge.myorg.example.com." \
    --ttl="30" \
    --type="CNAME" \
    --zone="myorg-example-com"

  3. Run the DNS record transaction to save your changes:

    gcloud dns record-sets transaction execute --zone="DNS_ZONE_NAME"

    Replace DNS_ZONE_NAME with the name of the target DNS zone.

Terraform

To add the CNAME record to your DNS configuration, you can use a google_dns_record_set resource.

resource "google_dns_record_set" "cname" {
  name         = google_certificate_manager_dns_authorization.default.dns_resource_record[0].name
  managed_zone = google_dns_managed_zone.default.name
  type         = google_certificate_manager_dns_authorization.default.dns_resource_record[0].type
  ttl          = 300
  rrdatas      = [google_certificate_manager_dns_authorization.default.dns_resource_record[0].data]
}

Create a Google-managed certificate referencing the DNS authorization

To create a Google-managed certificate that references the DNS authorization you created in the previous steps, do the following:

Console

  1. In the Google Cloud console, go to the Certificate Manager page.

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For location, choose Global.

  7. For Scope, choose any of the following options:

    1. Default: Choose default for Global external Application Load Balancer, a Classic Application Load Balancer, or a Global external proxy Network Load Balancer
    2. All-regions: Choose all-regions for a Cross-region internal Application Load Balancer

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Public.

  10. Specify the Domain Names of the certificate. Enter a comma-delimited list of the target domains. Also, each domain name must be a fully qualified domain name, such as myorg.example.com.

  11. For Authorization type, choose DNS Authorization. If the domain name has an associated DNS authorization, it will get automatically picked up. If the domain name does not have an associated DNS authorization then, do the following:

    1. Click Create missing DNS authorization to display the Create DNS Authorization dialog.
    2. In the DNS Authorization Name field, specify the DNS authorization name.
    3. Click Create DNS authorization. Verify that the DNS name gets associated to the domain name.

  12. Specify a label to associate to the certificate. You can add more than one label, if needed. To add a label, click the Add label button, and specify a key and a value for your label.

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud

For a Global external Application Load Balancer, a Classic Application Load Balancer, or a Global external proxy Network Load Balancer

Run the following command:

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains=DOMAIN_NAME \
    --dns-authorizations=AUTHORIZATION_NAME

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization you created for this certificate.

To create a Google-managed certificate with a wildcard domain name, use the following command. A wildcard domain name certificate covers all first-level subdomains of a given domain.

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="*.DOMAIN_NAME,DOMAIN_NAME" \
    --dns-authorizations=AUTHORIZATION_NAME

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The asterisk dot prefix (*.) signifies a wildcard certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization that you created for this certificate.

For a Cross-region internal Application Load Balancer

Run the following command:

  gcloud certificate-manager certificates create CERTIFICATE_NAME \
      --domains=DOMAIN_NAME \
      --dns-authorizations=AUTHORIZATION_NAME \
      --scope=all-regions

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization you created for this certificate.

To create a Google-managed certificate with a wildcard domain name, use the following command. A wildcard domain name certificate covers all first-level subdomains of a given domain.

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="*.DOMAIN_NAME,DOMAIN_NAME" \
    --dns-authorizations=AUTHORIZATION_NAME \
    --scope=all-regions

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The asterisk dot prefix (*.) signifies a wildcard certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization that you created for this certificate.

Terraform

Use a google_certificate_manager_certificate resource.

resource "google_certificate_manager_certificate" "root_cert" {
  name        = "${local.name}-rootcert-${random_id.tf_prefix.hex}"
  description = "The wildcard cert"
  managed {
    domains = [local.domain, "*.${local.domain}"]
    dns_authorizations = [
      google_certificate_manager_dns_authorization.default.id
    ]
  }
  labels = {
    "terraform" : true
  }
}

Verify that the certificate is active

Use the following command to verify that the certificate itself is active before deploying it to your load balancer. It can take up to several hours for the certificate state to change to ACTIVE.

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:

expireTime: '2022-05-07T05:03:49Z'
managed:
  authorizationAttemptInfo:
  -   domain: myorg.example.com
    state: AUTHORIZED
  dnsAuthorizations:
  -   projects/my-project/locations/global/dnsAuthorizations/myAuth
  domains:
  -   myorg.example.com
  state: ACTIVE
name: projects/myProject/locations/global/certificates/myCert
pemCertificate: |
  -----BEGIN CERTIFICATE-----
  [...]
  -----END CERTIFICATE-----
sanDnsnames:
-   myorg.example.com
updateTime: '2021-10-20T12:19:55.083385630Z'

Deploy the certificate to a load balancer

This section walks you through the steps required to deploy the Google-managed certificate to a load balancer.

Before you proceed with the tasks in this section, make sure you have completed the tasks listed in the Create a Google-managed certificate with DNS authorization section.

Depending on the load balancer type, you can deploy certificates as follows:

Deploy the certificate using a certificate map

This section describes the steps to deploy a certificate using a certificate map.

Create a certificate map

Create a certificate map that references the certificate map entry that is 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

To create a certificate map, you can use a google_certificate_manager_certificate_map resource.

resource "google_certificate_manager_certificate_map" "certificate_map" {
  name        = "${local.name}-certmap-${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.

If you are creating certificates with a wildcard domain, specify the hostname with a wildcard too, such as *.example.com.

Terraform

To create a certificate map entry, you can use a google_certificate_manager_certificate_map_entry resource.

resource "google_certificate_manager_certificate_map_entry" "first_entry" {
  name        = "${local.name}-first-entry-${random_id.tf_prefix.hex}"
  description = "example certificate map entry"
  map         = google_certificate_manager_certificate_map.certificate_map.name
  labels = {
    "terraform" : true
  }
  certificates = [google_certificate_manager_certificate.root_cert.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:

certificates:
createTime: '2021-09-06T10:01:56.229472109Z'
hostname: example.com
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 target proxy:

gcloud

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

    Go to Target proxies

  2. Note the name of the target proxy.

  3. Attach the certificate map to the target proxy:

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

    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 the associated certificate.

Terraform

To attach the certificate map to the target proxy, you can use a google_compute_target_https_proxy resource.

When configuring a target proxy, if you attach TLS (SSL) certificates directly and also through a certificate map, the proxy uses the certificates referenced by the certificate map and ignores the directly attached TLS (SSL) certificates.

Attach the certificate directly to the target proxy

To attach the certificate directly to the proxy, run the following command:

gcloud compute target-https-proxies update PROXY_NAME \
    --url-map=URL_MAP \
    --global \
    --certificate-manager-certificates=CERTIFICATE_NAME

Replace the following:

  • PROXY_NAME: a unique name of the proxy.
  • URL_MAP: the name of the URL map. You created the URL map when you created the load balancer.
  • CERTIFICATE_NAME: the name of the certificate.

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

    Replace PROXY_NAME with the name of the target proxy.

  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.

  5. Delete the DNS authorization:

    gcloud certificate-manager dns-authorizations delete AUTHORIZATION_NAME

    Replace AUTHORIZATION_NAME with the name of the target DNS authorization.

What's next