Deploy a regional Google-managed certificate with DNS authorization (original) (raw)

Skip to main content

Deploy a regional Google-managed certificate with DNS authorization

This tutorial shows you how to use Certificate Manager to deploy a regional Google-managed certificate with DNS authorization to a regional external Application Load Balancer or to a regional internal Application Load Balancer.

If you want to deploy to global external load balancers or cross-region load balancers, see the following:

Objectives

This tutorial shows you how to complete the following tasks:

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission. Learn how to grant roles.
      Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Compute Engine, Certificate Manager APIs.
    Roles required to enable APIs
    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
    Enable the APIs

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command:
    gcloud init

  8. Create a public DNS zone

Required roles

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

For more information, see the following:

Domain names

To create certificates, get the fully qualified domain names (FQDNs) of the domains you own. If you don't have a domain, you can use Cloud Domains to register a domain.

Create the load balancer

This tutorial assumes that you've already created and configured the load balancer's backends, health checks, backend services, and URL maps. Make a note of the URL map's name because you need it later in this tutorial.

Before you create the certificate, create a public DNS zone. Then, create a DNS authorization and add the CNAME record to the target DNS zone.

Important: For regional Google-managed certificates, you must create a regional DNS authorization in the same region as the certificate. You can't use global DNS authorizations with regional certificates.

A DNS authorization only covers a single domain name. You must create a separate DNS authorization for each domain name that you want to use with the target certificate.

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.

For regional Google-managed certificates, you can create only thePER_PROJECT_RECORD type of DNS authorization.

Console

You can create a DNS authorization or attach an existing DNS authorization when creating a certificate. For more information, seeCreate a Google-managed certificate referencing the DNS authorization.

gcloud

To create a PER_PROJECT_RECORD DNS authorization, use the followinggcloud certificate-manager dns-authorizations create command:

gcloud certificate-manager dns-authorizations create AUTHORIZATION_NAME
--domain="DOMAIN_NAME"
--location="LOCATION"

Replace the following:

After creating the PER_PROJECT_RECORD DNS authorization, verify it with the gcloud certificate-manager dns-authorizations describe command:

gcloud certificate-manager dns-authorizations describe AUTHORIZATION_NAME
--location="LOCATION"

The output is similar to the following. In the output, find thednsResourceRecord section. Locate the CNAME record and add the record's details (data,name, and type) 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_ujmmovf2vn55tgye.myorg.example.com type: CNAME domain: myorg.example.com name: projects/myProject/locations/global/dnsAuthorizations/myAuthorization updateTime: '2022-01-14T13:35:01.571086137Z'

API

To create a DNS authorization, make a POST request to the dnsAuthorizations.create method:

POST /v1/projects/PROJECT_ID/locations/LOCATION/dnsAuthorizations?dns_authorization_id=AUTHORIZATION_NAME { "domain": "DOMAIN_NAME", "type": "PER_PROJECT_RECORD" }

Replace the following:

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 Certificates tab, click Add Certificate.
  3. In the Certificate name field, enter a unique name for the certificate.
  4. Optional: In the Description field, enter a description for the certificate. The description lets you identify the certificate.
  5. For Location, select Regional.
  6. From the Region list, select your region.
  7. For Certificate type, select Create Google-managed certificate.
  8. For Certificate Authority type, select Public.
  9. In the Domain Names field, specify a comma-separated list of domain names of the certificate. Each domain name must be a fully qualified domain name, such as myorg.example.com. The domain name can also be a wildcard domain name, such as *.example.com.
  10. For Authorization type, select DNS authorization.
    The page lists DNS authorizations of the domain names. If a domain name doesn't have an associated DNS authorization, follow these steps to create one:
  11. Click Create missing DNS authorization.
  12. In the DNS authorization name field, specify the name of the DNS authorization.
  13. Click Create DNS authorization.
  14. In the Labels field, specify labels to associate to the certificate. To add a label, clickAdd label, and specify a key and a value for your label.
  15. Click Create.
    The new certificate appears in the list of certificates.

gcloud

To create a regional Google-managed certificate with DNS authorization, run the certificate-manager certificates create command with thedns-authorizations and location flags:

gcloud certificate-manager certificates create CERTIFICATE_NAME
--domains="DOMAIN_NAME, *.DOMAIN_NAME"
--dns-authorizations="AUTHORIZATION_NAMES"
--location=LOCATION

Replace the following:

API

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

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

Replace the following:

Add the CNAME record to your DNS configuration

If you're using a third-party DNS solution to manage your DNS, refer to its documentation to add the CNAME record to the DNS configuration. If you're using Google Cloud to manage your DNS, complete the steps in this section.

Console

To create a record set, follow these steps:

  1. In the Google Cloud console, go to the DNS zones page.
    Go to Cloud DNS zones
  2. Click the name of the DNS zone where you want to add the record.
  3. On the Zone details page, click Add standard.
  4. On the Create record set page, in the DNS name field, enter the subdomain of the DNS zone.
    When entering the subdomain name, make sure that the subdomain name, including the greyed-out text displayed in the DNS name field, matches the full value of thednsResourceRecord.name field as displayed in the output of thegcloud certificate-manager dns-authorizations describe command.
    See the following examples:
    • If the dnsResourceRecord.name field value is_acme-challenge.myorg.example.com., and the greyed-out text in theDNS name field is .example.com., then enter_acme-challenge.myorg.
    • If the dnsResourceRecord.name field value is_acme-challenge.myorg.example.com. , and the greyed-out text in theDNS name field is .myorg.example.com., then enter_acme-challenge.
    • If the value of the dnsResourceRecord.name field is_acme-challenge_ujmmovf2vn55tgye.myorg.example.com., and the greyed-out text in the DNS name field is .myorg.example.com., then enter _acme-challenge_ujmmovf2vn55tgye.
  5. In the Resource record type field, select CNAME.
  6. In the TTL field, enter a positive numeric value for the resource record's time to live, which is the amount of time that it can be cached.
  7. From the TTL unit list, select the unit of time—for example,30 minutes.
  8. In the Canonical name field, enter the full value of thednsResourceRecord.data field as displayed in the output of the gcloud certificate-manager dns-authorizations describe command.
  9. To enter additional information, click Add item.
  10. Click Create.

gcloud

When you create a DNS authorization, the gcloud CLI command returns the corresponding CNAME record. To add the CNAME record to your DNS configuration in the DNS zone of the target domain, follow these steps:

  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="VALIDATION_SUBDOMAIN_NAME.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.
    • VALIDATION_SUBDOMAIN_NAME: the prefix subdomain of the DNS zone, such as _acme-challenge. You can copy the name from the gcloud certificate-manager dns-authorizations describecommand log, as described in Create a 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.
      For more information about the difference betweenFIXED_RECORD and PER_PROJECT_RECORD DNS authorizations, see the following examples. The only difference between the two examples is the value of the --name flag.
      FIXED_RECORD DNS authorization
      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"
      PER_PROJECT_RECORD DNS authorization
      gcloud dns record-sets transaction add 0e40fc77-a37d-4eb8-8fe1-eea2e18d12d9.4.authorize.certificatemanager.goog. \
      --name="_acme-challenge_ujmmovf2vn55tgye.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 agoogle_dns_record_set resource.

Verify the status of the certificate

Before deploying a certificate to a load balancer, verify that it's active. It can take several minutes for the certificate state to change to ACTIVE.

Console

  1. In the Google Cloud console, go to the Certificate Manager page.
    Go to Certificate Manager
  2. On the Certificates tab, check the Status column for the certificate.

gcloud

To verify the status of the certificate, run the following command:

gcloud certificate-manager certificates describe CERTIFICATE_NAME
--location=LOCATION

Replace the following:

The output is similar to the following:

createTime: '2021-10-20T12:19:53.370778666Z' expireTime: '2022-05-07T05:03:49Z' managed: authorizationAttemptInfo:

If the certificate state is not ACTIVE after several hours, check that you correctly added the CNAME record to your DNS configuration.

For more troubleshooting steps, see Troubleshoot Certificate Manager.

Deploy the certificate to a load balancer

To deploy the regional Google-managed certificate to a regional external Application Load Balancer or regional internal Application Load Balancer, attach it directly to the target proxy.

Attach the certificate directly to the target proxy

You can attach the certificate to a new target proxy or an existing target proxy.

To attach the certificate to a new target proxy, use the gcloud compute target-https-proxies createcommand:

gcloud compute target-https-proxies create PROXY_NAME
--certificate-manager-certificates=CERTIFICATE_NAME
--url-map=URL_MAP
--region=LOCATION

Replace the following:

To attach certificate to an existing target HTTPS proxy, use the gcloud compute target-https-proxies updatecommand. If you don't know the name of the existing target proxy, go to the Target proxiespage and note the name of the target proxy.

gcloud compute target-https-proxies update PROXY_NAME
--region=LOCATION
--certificate-manager-certificates=CERTIFICATE_NAME

After creating or updating the target proxy, run the following command to verify it:

gcloud compute target-https-proxies list

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, delete them.

  1. Delete the load balancer and its resources.
    See Clean up a load balancing setup.
  2. Delete the Google-managed certificate:

Console

  1. In the Google Cloud console, go to the Certificate Manager page.
    Go to Certificate Manager
  2. On the Certificates tab, select the checkbox of the certificate.
  3. Click Delete.
  4. In the dialog that appears, click Delete to confirm.

gcloud

gcloud certificate-manager certificates delete CERTIFICATE_NAME \
--location=LOCATION
Replace the following:

  1. Delete the DNS authorization:
    gcloud certificate-manager dns-authorizations delete AUTHORIZATION_NAME
    --location=LOCATION
    Replace the following:
    • AUTHORIZATION_NAME: the name of the DNS authorization.
    • LOCATION: the target Google Cloud location where you created the DNS authorization.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-06-18 UTC.