Using Google-managed SSL certificates

This page discusses how to create and use Google-managed SSL certificates.

Google-managed SSL certificates are certificates that Google Cloud obtains and manages for your domains, renewing them automatically. These are Domain Validation (DV) certificates supporting multiple hostnames in each certificate.

An SSL certificate is required for certain types of Google Cloud load balancers, including:

You can also use managed SSL certificates with Google Kubernetes Engine. For more information, see Using Google-managed SSL certificates.

You can create a Google-managed certificate before, during, or after creating your load balancer. This page assumes that you're creating the certificate before or after creating the load balancer, not during. To create the certificate while creating your load balancer, see the load balancer how-to pages.

Multiple domains

Multiple subject alternative names are supported. Each Google-managed SSL certificate supports up to the maximum number of domains per Google-managed SSL certificate.

If you have more than the maximum number of domains, you must request multiple Google-managed certificates. For example, if you try to create a Google-managed certificate with (the maximum + 1) domains, Google doesn't issue any certificates. Instead, you must create two or more Google-managed certificates and explicitly state which domains are associated with each certificate.

Google Cloud implements Server Name Indication (SNI), as defined in RFC 6066.

When Google renews a managed certificate that has multiple domains, if any of the domains or subdomains aren't pointing to the load balancer's IP address, the renewal process fails. After your managed certificate is provisioned, make sure that all of your domains and subdomains are still pointing to the load balancer's IP address to avoid renewal failure.

Before you begin

Permissions

To follow this guide, you must have the permission to create and modify SSL certificates in your project. You have this permission if you have one of the following roles or permissions:

  • You are a project owner or editor.
  • You have the compute.loadBalancerAdmin role in the project OR you have both compute.securityAdmin and compute.networkAdmin roles in the project.
  • You have a custom role for the project that includes the compute.sslCertificates.* permissions and one or both of compute.targetHttpsProxies.* and compute.targetSslProxies.*, depending on the type of load balancer you are using.

Step 1. Create a Google-managed SSL certificate

You can create a Google-managed certificate before, during, or after creating your load balancer. During the process of creating a load balancer in the Cloud Console, you can use the Cloud Console to create your certificate. Alternatively, you can create your certificate before or after creating your load balancer. This step shows you how to create a certificate that you can later add to one or more load balancers.

If you have already created your Google-managed SSL certificate, you can skip this step.

Console

You can work with global SSL certificates on the Certificates tab on the Load Balancing page.

  1. Go to the Certificates page in the Google Cloud Console.
    Go to the Certificates page
  2. Click Create SSL certificate.
  3. Enter a name and an optional description for the certificate.
  4. Select Create Google-managed certificate.
  5. Add the domains.
  6. Click Create.

gcloud

Use the gcloud compute ssl-certificates create command to create a global Google-managed SSL certificate for an external HTTP(S) load balancer or SSL proxy load balancer:

gcloud compute ssl-certificates create CERTIFICATE_NAME \
    --description=DESCRIPTION \
    --domains=DOMAIN_LIST \
    --global

Replace the following placeholders with valid values:

  • CERTIFICATE_NAME: a name for the global SSL certificate
  • DESCRIPTION: a description for the global SSL certificate
  • DOMAIN_LIST: a single domain name or a comma-delimited list of domain names to use for this certificate

api

Create the Google-mananged certificate resource sslCertificates.insert method, replacing PROJECT_ID with your project ID.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/global/sslCertificates
{
  "name": "ssl-certificate-name",
  "managed": {
    "domains": [
      "www.example.com"
    ]
  },
  "type": "MANAGED"
}

Checking the Google-managed SSL certificate status

Console

You can check the status of your global SSL certificates on the Certificates tab on the Load Balancing page.

  1. Go to the Certificates page in the Google Cloud Console.
    Go to the Certificates page
  2. (Optional) Filter the list of SSL certificates.
  3. Check the Status column.
  4. To view more details, click the certificate name.

gcloud

You can use gcloud compute commands to determine the status of your Google-managed certificate. After running the appropriate command, note the following:

  • The managed status.
  • The domain status.

Use the gcloud compute ssl-certificates list command with the --global flag to list your Google-managed SSL certificates.

gcloud compute ssl-certificates list \
   --global

You can use the gcloud compute ssl-certificates describe command, replacing CERTIFICATE_NAME:

gcloud compute ssl-certificates describe CERTIFICATE_NAME \
   --global \
   --format="get(name,managed.status, managed.domainStatus)"

At this point, the certificate status and the domain status are PROVISIONING. The statuses changes to ACTIVE after you complete all of the steps on this page.

For more information about the statuses, see the troubleshooting page.

Step 2: Create or update your load balancer

To become ACTIVE, the Google-managed SSL certificate must be associated with a load balancer, specifically the load balancer's target proxy.

After you've created your SSL certificate and it's in the PROVISIONING state, you can use it during the creation of your load balancer, as descibed in the following how-to guides:

Or you can use it to update an existing load balancer, as described here:

Console

When you update an external HTTP(S) load balancer or SSL proxy load balancer using the Google Cloud Console, Google Cloud automatically associates your SSL certificate with the correct target proxy.

  1. Go to the Load balancing page in the Google Cloud Console.
    Go to the Load balancing page
  2. Click the name of your load balancer.
  3. Click Edit .
  4. Click Frontend configuration.
  5. Click the correct front end (must be HTTPS, HTTP/2, SSL).
  6. Click Additional certificates, and select your Google-managed certificate from the drop-down list.
  7. Click Create.

gcloud

To associate an SSL certificate with the target HTTPS proxy for an external HTTP(S) load balancer, use the gcloud compute target-https-proxies update command with the --global-ssl-certificates and --global flags:

gcloud compute target-https-proxies update TARGET_PROXY_NAME \
    --ssl-certificates SSL_CERTIFICATE_LIST \
    --global-ssl-certificates \
    --global

To associate an SSL certificate with the target SSL proxy for an SSL proxy load balancer, use the gcloud compute target-ssl-proxies update command:

gcloud compute target-ssl-proxies update TARGET_PROXY_NAME \
    --ssl-certificates SSL_CERTIFICATE_LIST

Replace the placeholders with valid values:

  • TARGET_PROXY_NAME: The name of the load balancer's target proxy
  • SSL_CERTIFICATE_LIST: A comma delimited list of SSL certificates

Each target HTTPS proxy or target SSL proxy must reference at least one SSL certificate. A target proxy can reference more than one SSL certificate. For details, see Target pools and target proxies in the load balancing resource quotas and limits.

Step 3: Verify the target proxy association

After you've created or updated your load balancer, you can make sure that the SSL certificate is associated with your load balancer's target proxy by running the following command.

For external HTTPS load balancers:

gcloud compute target-https-proxies describe target-https-proxy-name \
    --global \
    --format="get(sslCertificates)"

For SSL proxy load balancers:

gcloud compute target-ssl-proxies describe target-ssl-proxy-name \
    --format="get(sslCertificates)"

At this point, your Google-managed certificate status might still be PROVISIONING. Google Cloud is working with the Certificate Authority to issue the certificate. Provisioning a Google-managed certificate might take up to 60 minutes.

Step 4: Update the DNS A and AAAA records to point to the load balancer's IP address

At your registrar's site, DNS host, or ISP (wherever your DNS records are managed), add or update the DNS A records (for IPv4) and DNS AAAA records (for IPv6) for your domains and any subdomains so that they point to the IP address associated with the load balancer's forwarding rule or rules.

If you're using Cloud DNS and Google Domains, set up your domains and update your name servers.

If you're using multiple domains for a single Google-managed certificate, you must add or update DNS records for all of the domains and any subdomains so that they all point to your load balancer's IP address.

After waiting for DNS propagation to complete, you can verify your setup by running the dig command. For example, suppose your domain is www.example.com. Run the following dig command:

dig www.example.com
; <<>> DiG 9.10.6 <<>> www.example.com
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 31748
;; flags: qr rd ra; QUERY: 1, ANSWER: 4, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 512
;; QUESTION SECTION:
;www.example.com.           IN  A

;; ANSWER SECTION:
www.example.com.        1742    IN  CNAME   www.example.com.edgekey.net.
www.example.com.edgekey.net. 21330 IN   CNAME   www.example.com.edgekey.net.globalredir.akadns.net.
www.example.com.edgekey.net.globalredir.akadns.net. 3356 IN CNAME   e6858.dsce9.akamaiedge.net.
e6858.dsce9.akamaiedge.net. 212 IN  A   203.0.113.5

;; Query time: 43 msec
;; SERVER: 8.8.8.8#53(8.8.8.8)
;; WHEN: Wed Jun 03 16:54:44 PDT 2020
;; MSG SIZE  rcvd: 193

In this example, 203.0.113.5 is your load balancer's IP address.

Also, rerun the following command:

gcloud compute ssl-certificates describe CERTIFICATE_NAME \
    --format="get(managed.domainStatus)"

If your domain status is FAILED_NOT_VISIBLE, see the Google-managed SSL certificate domain status section on the Troubleshooting page.

Step 5: Test with OpenSSL

After the certificate and domain statuses are active, it can take up to 30 minutes for your load balancer to begin using your Google-managed SSL certificate.

To test, run the following OpenSSL command, replacing DOMAIN with your DNS name and IP_ADDRESS with the IP address of your load balancer.

echo | openssl s_client -showcerts -servername DOMAIN -connect IP_ADDRESS:443 -verify 99 -verify_return_error

This command outputs the certificates that the load balancer presents to the client. Along with other detailed information, the output should include the certificate chain and Verify return code: 0 (ok).

Google-managed SSL certificate renewal

Google Cloud provisions managed certificates valid for 90 days. About one month before expiry, the process to renew your certificate automatically begins. For this, a Certificate Authority (CA) is chosen that's both in your domain's CAA DNS record and in the list of CAs.

The CA used for renewal might be different from the CA used to issue a previous version of your Google-managed certificate. You can control the CA that Google Cloud uses for renewal by ensuring that your domain's Certification Authority Authorization (CAA) DNS record specifies a single CA from the list of CAs that Google-managed certificates use.

When Google renews a managed certificate that has multiple domains, if any of the domains or subdomains aren't pointing to the load balancer's IP address, the renewal process fails. After your managed certificate is provisioned, make sure that all of your domains and subdomains are still pointing to the load balancer's IP address to avoid renewal failure.

Optional procedures

Specifying the CAs that are allowed to issue your Google-managed certificate

In your DNS server software, specify the CAs that you want to allow to issue your Google-managed certificate. To do this, create or modify a CAA record to include pki.goog, or letsencrypt.org, or both. If you don't have a CAA record, the default behavior is to allow both pki.goog and letsencrypt.org.

DOMAIN. CAA 0 issue "pki.goog"
DOMAIN. CAA 0 issue "letsencrypt.org"

Support for letsencrypt.org certificates is provided on a best-effort basis. For best reliability, allow both pki.goog and letsencrypt.org. If you specify just one of the CAs, only that CA is used to create and renew your certificate. This approach isn't recommeneded.

When you first create your certificate, Google Cloud selects either pki.goog or letsencrypt.org and uses it to issue your certificate. When Google renews your certificate, your certificate might be issued by the other CA, depending on the CAs that you have specified in the CAA record (if you created one). Your certificate might be renewed by a different CA in either of the following cases:

  • You don't have a DNS CAA record for your domain.
  • You have included both the CAs in the DNS CAA record.

For more information, see the RFC, Certification Authority Authorization (CAA) DNS record.

Internationalized Domain Names (IDNs) are issued by letsencrypt.org. They are currently unsupported by pki.goog.

If you're using Cloud DNS, learn how to add a record, and make sure to set the --type flag to CAA.

Replacing an existing SSL certificate

To replace an existing SSL certificate:

  1. Start the process for creating the replacement Google managed SSL certificate. Note that this certificate will not become ACTIVE at this point.

  2. Update the target proxy so that the list of referenced certificate(s) includes the replacement SSL certificate along with the current SSL certificate(s). The steps to update the target proxy vary, as follows:

  3. Wait for the replacement SSL certificate to complete provisioning. This might take up to 60 minutes. When provisioning has successfully completed, the certificate status becomes ACTIVE.

  4. Wait an additional 30 minutes to ensure that the replacement certificate is available to all Google Front Ends (GFEs).

  5. Update the target proxy to remove the SSL certificate that you're replacing from the list of referenced certificates. The steps to update a target proxy vary, as follows:

  6. Wait 10 minutes, and confirm that the load balancer is using the replacement SSL certificate instead of the old one.

  7. Optionally, delete the old SSL certificate resource.

If you don't delete the old SSL certificate, it remains ACTIVE until it expires.

Migrating from self-managed SSL certificates to Google-managed SSL certificates

When you migrate a load balancer from using self-managed SSL certificates to Google-managed SSL certificates, you must perform the following steps in this sequence:

  1. Create a new Google-managed certificate.
  2. Associate new Google-managed certificate with the correct target proxy while maintaining the target proxy's association with the existing self-managed certificate.
  3. Wait until the Google-managed certificate status is ACTIVE.
  4. Wait 30 minutes to allow the new certificate to propagate to serving Google Front Ends (GFEs)
  5. Update the target proxy again, removing the self-managed certificate.

Deleting SSL certificates

Before deleting an SSL certificate, make sure that no HTTPS or SSL target proxy references this certificate. You can do this in two ways:

To delete one or more SSL certificates:

Console

You can delete global SSL certificates on the Certificates tab on the Load Balancing page.

  1. Go to the Certificates page in the Google Cloud Console.
    Go to the Certificates page
  2. Select the SSL certificate that you want to delete.
  3. Click Delete.
  4. To confirm, click Delete again.

gcloud

To delete a global SSL certificate (for external HTTP(S) load balancers or SSL proxy load balancers), use the gcloud compute ssl-certificates delete command with the --global command:

gcloud compute ssl-certificates delete CERTIFICATE_NAME \
    --global

Replace the placeholders with valid values:

  • CERTIFICATE_NAME: The name of the SSL certificate

What's next