Creating and Using SSL Certificates

To use HTTPS or SSL load balancing, you must associate at least one SSL certificate with the load balancer's target proxy. You can configure the target proxy with up to ten SSL certificates. For each SSL certificate, you first create an SSL certificate resource. The SSL certificate resource contains the SSL certificate information.

Your SSL certificates can be either certificates that you obtain and manage yourself (self-managed certificates), or certificates that Google obtains and manages for you (Google-managed certificates).

SSL certificate resources are used only with target HTTPS proxy and target SSL proxy load balancers. See that documentation for when and how to use SSL certificate resources.

SAN certificates are supported for HTTPS load balancing.

Using multiple SSL certificates

You can configure the target proxy of your HTTPS or SSL proxy load balancer with up to ten SSL certificates. These can be any combination of self-managed and Google-managed SSL certificates. Use multiple SSL certificates when you are serving from multiple domains using the same load balancer IP address and port, and you want to use a different SSL certificate for each domain. Google Cloud Platform implements Server Name Indication (SNI), as defined in RFC 6066, for this purpose.

SSL certificates are used with target HTTPS proxy (TargetHttpsProxy) and target SSL proxy (TargetSslProxy) resources. You must specify at least one SSL certificate for each of these resources and you can specify up to ten. When you specify more than one, the first certificate in the list of SSL certificates is considered the primary SSL certificate associated with the load balancer.

When a client sends a request, the load balancer uses the SNI hostname specified by the client to select the certificate to use in negotiating the client SSL connection. Whenever possible, the load balancer selects a certificate whose common name (CN) or subject alternative name (SAN) matches the SNI hostname specified by the client and which is compatible with the client's ability to use RSA or ECDSA for digital signatures. If none of the available certificates can be selected, or if the client does not specify an SNI hostname, the load balancer negotiates SSL using the primary certificate, which is the first certificate in the list.

Multiple SSL certificates (click to enlarge)
Multiple SSL certificates (click to enlarge)

Wildcards in common names

Your self-managed SSL certificates can use a wildcard in the common name. For example, a certificate with the common name *.example.com. matches the hostnames www.example.com and foo.example.com, but not a.b.example.com or example.com. When the load balancer selects a certificate, it always prefers to match a hostname to certificates without wildcards over certificates with wildcards.

Certificates with wildcard fragments, such as f*.example.com, are not supported.

Google-managed SSL certificates do not support using wildcards.

Multiple SSL certificate example

Here is an example of how multiple SSL certificates work with HTTPS load balancing. The example assumes that you have three hostnames and three SSL certificates.

How multiple SSL certificates work with HTTPS load balancing (click to enlarge)
How multiple SSL certificates work with HTTPS load balancing (click to enlarge)

The hostnames are:

  • www.example.com
  • www.example.org
  • www.example.net

You are serving content from www.example.com, www.example.org, and www.example.net using the HTTPS load balancer at IP address 203.0.113.1. You want to configure the SSL certificates so that the load balancer uses cert-1 for www.example.com, cert-2 for www.example.org, and cert-3 for www.example.net. You also want the load balancer to use cert-1 when clients do not use SNI or when the client-provided server name does not match any of the available certificates.

The SSL certificates are cert-1, cert-2, and cert-3. SSL certificate cert-1 is the primary certificate. When you create the certificates, you associate each of them with a hostname. In this example, the result is:

  • cert-1:www.example.com
  • cert-2:www.example.org
  • cert-3:www.example.net

If the client uses SNI to provide a hostname during the TLS (SSL) handshake, the load balancer uses the certificate associated with that hostname. For instance, as shown in the illustration above, when user-2’s client provides www.example.org as the SNI hostname during the TLS handshake, the load balancer serves cert-2. If a user’s client does not provide an SNI hostname, or provides one that does not match any of the load balancer’s certificates, the load balancer uses the primary certificate, cert-1.

When you use the primary certificate as a fallback for clients that support SNI, the client typically reports certificate validation errors when the fallback occurs. This is preferable to failing the handshake on the server side, because it makes debugging easier. However, while users can ignore certificate warnings, intentionally serving requests with a fallback certificate is a poor security practice.

Types of SSL certificates

Two types of SSL certificates are available to you:

  • Self-managed SSL certificates, which are certificates that you obtain, provision, and renew yourself.

  • Google-managed SSL certificates, which are certificates that Google Cloud Platform obtains and manages for your domain, renewing them automatically.

Google-managed SSL certificates are Domain Validation (DV) certificates only, and do not demonstrate the identity of an organization or individual associated with the certificate. Self-managed certificates can be any of Domain Validation (DV), Organization Validation (OV), or Extended Validation (EV) certificates. For more information on Domain Validation, Organization Validation, and Extended Validation certificates, see Public key certificate.

Google-managed SSL certificates support only a single domain name per certificate. They do not support wildcard common names or multiple subject alternate names.

You can have any mix of Google-managed and self-managed SSL certificates in one target proxy, and the certificates can be in any order in the target proxy.

Working with self-managed SSL certificates

Obtaining a private key and signed certificate

You need an unencrypted private key and a certificate generated using that key. If you already have a private key and a certificate from a certificate authority, you can skip ahead to Creating an SSL certificate resource. If not, you can create a new private key and generate a self-signed certificate that can be used to create an SSL certificate resource.

To create a new private key, first create a new folder to store your key and certificate, then use openssl to generate the key. See the openssl-genrsa man page for information about command options.

gcloud

  $ mkdir ssl_cert
  $ cd ssl_cert
  $ openssl genrsa -out example.key 2048

To generate a signed certificate, you need a certificate signing request (CSR). Run the following command to create one. See the openssl-req man page for information about command options.

$ openssl req -new -key example.key -out example.csr

You can use your new CSR to obtain a valid certificate from a certificate authority. Alternatively, you can generate a self-signed certificate by running the following command. See the openssl-x509 man page for information about command options.

$ openssl x509 -req -days 365 -in example.csr -signkey example.key -out example.crt

Creating an SSL certificate resource from existing certificate files

You can create an SSL certificate resource from existing certificate files by using the Cloud Console or by running a gcloud command. You must already have a certificate to create a certificate resource.

Google Cloud Platform only validates that all certificates in a chain have valid PEM encoding. It does not validate whether all certificates are chained in a legitimate way. It is your responsibility to provide valid certificate chains.

If you are configuring a load balancer with multiple SSL certificates, make sure that you create an SSL certificate resource for each certificate.

Console


In the Cloud console, you create a new SSL certificate resource when you create or edit a frontend for an HTTPS or SSL proxy load balancer.

To create a new SSL certificate resource for a frontend:

  1. Go to the Load balancing page in the Google Cloud Platform Console.
    Go to the Load balancing page
  2. Click the Edit pencil for an existing HTTPS or SSL load balancer.
  3. Select Frontend Configuration.
    1. For an existing frontend, click the Edit pencil for that frontend. In the Certificate drop-down menu, select the visible certificate, then click Create a new certificate.
    2. For a new frontend, in the Certificate drop-down menu, click Select a certificate, then click Create a new certificate.
  4. In the Create a new certificate dialog box, enter a Name for your certificate resource, and optionally click Add a description and enter a description.
  5. Choose Upload my certificate or Create Google-managed certificate.
  6. If you chose Upload my certificate, complete these steps.
    1. In the Public key certificate field, choose one of the following methods.
    2. Click the Upload button to upload your .crt file.
      1. Paste the entire contents of your .key file into the field, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- that encloses the file contents.
      2. Repeat for the Certificate chain field using the .csr file. Paste the entire contents of your .csr file into the field, including the -----BEGIN CERTIFICATE REQUEST----- and -----END CERTIFICATE REQUEST----- that encloses the file contents.
      3. Repeat for the Private key certificate field using the .key file generated previously. This file uses, for example, -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- to enclose the file contents.
    3. Click Create.
  7. If you chose Create Google-managed certificate, enter Domains and click Create.
  8. To create additional certificates, click the additional certificates link, click Select a Certificate, then click Create a new certificate. Follow the previous steps to upload or paste in the appropriate files.

gcloud


To create an SSL certificate with the gcloud command-line tool, use this command:

gcloud compute ssl-certificates create [SSL_CERTIFICATE] \
    --certificate [CRT_FILE_PATH] \
    --private-key [KEY_FILE_PATH]
  • [SSL_CERTIFICATE]: the name you want to give the certificate resource.

  • [CRT_FILE_PATH]: the path and filename of your certificate file (.crt file).

  • [KEY_FILE_PATH]: the path and filename of your key file (.key file).

Working with Google-managed SSL certificates

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

Google-managed SSL certificates are certificates that Google Cloud Platform obtains and manages for your domain. These are Domain Validation (DV) certificates supporting a single hostname per certificate. For more information, see Types of SSL Certificates.

Setting up a load balancer using Google-managed SSL certificates

The general process for creating a load balancer with Google-managed SSL certificates using the gcloud command-line tool is as follows. Most of these steps are performed on the Google Cloud Platform site, but step 5 must be performed at your domain registrar's site.

  1. Create a Google-managed SSL certificate resource for your domain, using the instructions in Creating a Google-managed SSL certificate resource
  2. Create the HTTPS or SSL proxy load balancer. For instructions on creating an HTTPS load balancer, see Setting up HTTP(S) Load Balancing, Creating Cross-Region Load Balancing, and Creating Content-Based Load Balancing. For instructions on creating an SSL proxy load balancer, see Setting Up SSL proxy for Google Cloud Load Balancing.
  3. Create a target HTTPS proxy or target SSL proxy that references the Google-managed SSL certificate resource. For more details on target proxies, see Target Proxies or Setting Up SSL proxy for Google Cloud Load Balancing. When you create the target proxy, reference the Google-managed SSL certificate resource that you created.
  4. Create one or more forwarding rules to the target proxy on port 443. For more details on creating forwarding rules, see Global Forwarding Rules.
  5. At your registrar's site, add or update the DNS record for your domain so that it points to the IP address associated with the forwarding rule or rules that you just created.
  6. Wait for the SSL certificate resource to have the ACTIVE status. See Google-managed SSL certificate resource status for more information.

You can also create Google-managed SSL certificates when you create a load balancer using the Google Cloud Platform Console.

For the Google-managed certificate to be issued and its resource state to become ACTIVE, you must have a load balancer setup, including a target proxy and forwarding rule, that references the certificate resource, as well as a DNS configuration that resolves your domain's hostname to the forwarding rule's IP address. For more information, see Google-managed SSL certificate resource status.

Migrating a load balancer from using 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, do not delete any self-managed SSL certificates before the Google-managed SSL certificates are active. After the Google-managed SSL certificates are successfully provisioned, they automatically become active. When the Google-managed SSL certificates are active, you can delete your self-managed SSL certificates.

Use these instructions for migrating from self-managed to Google-managed SSL certificates.

  1. Create the Google-managed certificate resource.
  2. Associate the Google-managed certificate resource with the correct target proxy, while maintaining the existing self-managed certificate resource in the target proxy's list.
  3. Wait until the status of the Google-managed certificate resource is ACTIVE.
  4. When the status is ACTIVE, update the target proxy to remove the self- managed certificate resource from its list of certificates.

Google-managed SSL certificate renewal

Google-managed SSL certificates are automatically renewed in advance of their expiration date. For more information on the renewal process, see Google-managed SSL certificate resource status.

Creating a Google-managed SSL certificate resource

Use the following gcloud command to create a Google-managed SSL certificate resource:

gcloud beta compute ssl-certificates create [SSL_CERTIFICATE_NAME] \
    --domains [DOMAIN]

Associating a Google-managed SSL certificate with a target proxy

Use the following gcloud commands to associate a Google-managed SSL certificate with a target proxy.

gcloud beta compute [target-https-proxies | target-ssl-proxies] update [NAME] \
    --ssl-certificates [SSL-CERTIFICATE-NAME]

Google-managed SSL certificate resource status

This section explains the SSL certificate resource's status field, which you can use to monitor and resolve issues with certificate provisioning.

The value of the status field of a Google-managed SSL certificate resource changes during provisioning and can indicate failures in provisioning or renewal.

To determine the value of the status field, use the follow command:

gcloud beta compute ssl-certificates list

You see output similar to this:

NAME               TYPE          CREATION_TIMESTAMP             EXPIRE_TIME              MANAGED_STATUS
managed-cert       MANAGED       2018-08-10T08:44:30.220-07:00  2018-11-08T06:50:19.000-08:00  ACTIVE
    example.com: ACTIVE
self-managed-cer  SELF_MANAGED  2018-03-08T05:11:20.170-08:00  2019-03-08T02:15:21.000-08:00

The status PROVISIONING indicates that the Google-managed certificate resource has been created but its provisioning is not yet complete.

For the certificate provisioning process to proceed, all of the following conditions must be met:

  • The DNS records for your domain must reference the IP address of your load balancer's target proxy,

  • Your target proxy must reference the Google-managed certificate resource.

  • Your load balancer configuration must be complete, including the creation of a forwarding rule.

With a correct configuration the total time for provisioning certificates is likely to take from 30 to 60 minutes.

If one of the above configuration steps is not done correctly, the Google-managed certificate resource ultimately has the status PROVISIONING_FAILED.

Because of propagation delays, the status might briefly be PROVISIONING_FAILED even though your setup is correct. If you see the status PROVISIONING_FAILED, recheck your configuration and allow some time for the system to retry, then check the status again. Additionally, you can consult the domainStatus field for information on which domain failed if there was a DNS failure.

The status PROVISIONING_FAILED_PERMANENTLY indicates that the certificate provisioning process failed because of an issue with DNS configuration or load balancing configuration. The provisioning process is not retried.

If provisioning fails with the status PROVISIONING_FAILED_PERMANENTLY, check your load balancer configuration and correct any issues, then recreate the SSL certificate resource by following this general procedure:

  1. Create a new certificate resource.
  2. Add the new certificate resource to the target proxy.
  3. Update the target proxy so that it no longer lists the old certificate resource.
  4. Remove the old certificate resource.

The status RENEWAL_FAILED indicate that certificate renewal failed because of an issue with DNS configuration or load balancing configuration. The existing certificate continues to serve, but expires shortly. Check your configuration, and if the status remains RENEWAL_FAILED, provision a new certificate, switch to using the new certificate, and then delete the old certificate.

The status ACTIVE indicates that the SSL certificate has been obtained from the Certificate Authority, the provisioning of the Google-managed certificate resource is complete, and the load balancer is using the certificate.

Google-managed SSL certificate resource domain status

This section explains the values that the domainStatus field can have and provides information on how to handle issues with provisioning.

To determine the value of the status field, use the follow command:

gcloud beta compute ssl-certificates list

You see output similar to this:

NAME               TYPE          CREATION_TIMESTAMP             EXPIRE_TIME              MANAGED_STATUS
managed-cert       MANAGED       2018-08-10T08:44:30.220-07:00  2018-11-08T06:50:19.000-08:00  ACTIVE
    example.com: ACTIVE
self-managed-cer  SELF_MANAGED  2018-03-08T05:11:20.170-08:00  2019-03-08T02:15:21.000-08:00

The domainStatus field of the Google-managed SSL certificate resource contains the status of the domains requests for Google-managed SSL certificate resources. This section contains information on the possible values of the field.

The status PROVISIONING indicates that certificate provisioning for the domain is in process and it will take 30 to 60 minutes before the certificate is activated.

The status FAILED_NOT_VISIBLE indicates that certificate provisioning failed for a domain because of a problem with DNS or the load balancing configuration. Make sure that DNS is configured so that the certificate's domain resolves to the IP address of the load balancer.

The status FAILED_CAA_CHECKING indicates that there was a failure to check CAA records for the domain.

The status FAILED_CAA_FORBIDDEN indicates that certificate issuance is forbidden by an explicit CAA record for the domain.

If you have a CAA record that limits the authorities that can issue certificates, remove the limitation from your CAA record.

The status FAILED_RATE_LIMITED indicates that you have reached a limit that applies to Google-managed SSL certificates. This is a temporary condition that should clear without requiring any action on your part.

The status ACTIVE indicates that a Google-managed SSL certificate is provisioned and there are no issues for this domain. Note that this might take 30 to 60 minutes to propagate through the system. The provisioned certificate is fully effective when you can see the certificate when requests are made against the load balancer, not just when the status is ACTIVE.

Viewing SSL certificate resource properties

To see information about your SSL certificate resource, run the following command:

gcloud beta compute ssl-certificates describe [SSL_CERTIFICATE]
  • [SSL_CERTIFICATE]: the name of the SSL certificate resource.

Listing SSL certificate resources

To view a list of all of your SSL certificate resources, run the following command:

gcloud beta compute ssl-certificates list

The output of this command shows the distinction between self-managed and Google-managed SSL certificates. Note that MANAGED in the output indicates Google-managed.

NAME               TYPE          CREATION_TIMESTAMP             EXPIRE_TIME              MANAGED_STATUS
managed-cert       MANAGED       2018-08-10T08:44:30.220-07:00  2018-11-08T06:50:19.000-08:00  ACTIVE
    example.com: ACTIVE
self-managed-cer  SELF_MANAGED  2018-03-08T05:11:20.170-08:00  2019-03-08T02:15:21.000-08:00

Associating SSL certificate resources with a target proxy

Use the following gcloud command to associate SSL certificate resources with a target proxy, whether the SSL certificates are self-managed or Google-managed.

gcloud compute target-https-proxies create [NAME] \
    --url-map=[URL_MAP] \
    --ssl-certificates=[SSL_CERTIFICATE1][,[SSL_CERTIFICATE2],[SSL_CERTIFICATE3],...]

Updating a proxy to use different SSL certificate resources

To update the certificates associated with a target HTTPS proxy or target SSL proxy, first create any new SSL certificate resources, then update the proxy using the appropriate command.

For target HTTPS proxies, use the following command, in which you can specify up to ten SSL certificate resources:

gcloud compute target-https-proxies update [PROXY_NAME] \
    --ssl-certificates [SSL_CERT_1][,[SSL_CERT_2],...]
  • [PROXY_NAME]: the name of the target-https-proxies resource you are updating.
  • [[SSL_CERT_1][,[SSL_CERT_2],...]: the full list of up to ten names of the SslCertificate resources.

For target SSL proxies, use the following, in which you can specify up to ten SSL certificate resources:

gcloud compute target-ssl-proxies update  [PROXY_NAME] \
    --ssl-certificates [SSL_CERT_1][,[SSL_CERT_2],...]
  • [PROXY_NAME]: the name of the target-ssl-proxies resource you are updating.
  • [SSL_CERT_1][,[SSL_CERT_2],...]: the full list of up to ten names of the SslCertificate resources.

Deleting SSL certificate resources

To delete one or more SSL certificate resources:

Console


  1. In the left panel of the Edit HTTP(S) load balancer page, click Frontend configuration.
  2. In the right panel, click the X next to the certificate resource you want to delete.
  3. Click Done.

gcloud


gcloud compute ssl-certificates delete [SSL_CERT_1][,[SSL_CERT_2],...]
  • [SSL_CERTIFICATE]: the name of the SslCertificate resource you are deleting.

Limits

  • An HTTPS or SSL proxy load balancer must have at least one SSL certificate and can have up to ten SSL certificates, in any mix of self-managed and Google-managed certificates.

  • A Google-managed certificate can only have a single domain specified.

  • When you use Google-managed certificates with SSL Proxy Load Balancing, the frontend port for traffic must be 443 to enable the Google-managed certificates to be provisioned and renewed.

  • The maximum supported domain name length is 64 bytes.

  • You should not set CAA records that limit the authorities that can issue certificates. This may prevent Google-managed certificates from being issued.

Troubleshooting

Error message when uploading an SSL certificate

You might see the following error message when you try to upload an SSL certificate:

The SSL certificate could not be parsed.

Google Cloud Platform requires certificates in PEM format. If the certificate is PEM formatted, it might be invalid.

To validate the certificate, run the following command on a Linux command line, or on your Cloud Shell:

    openssl x509 -in certificate.crt -text -noout

If you see the following response, the certificate is invalid:

  • unable to load certificate
  • Expecting: TRUSTED CERTIFICATE

If the invalid file is from a self-generated certificate, you may want to generate a new certificate using the instructions in Obtaining a private key and signed certificate. If it is a certificate supplied by a certificate authority (CA), contact that CA for help.

Error message when uploading an SSL key

You might see the following error message when you try to upload an SSL key:

The SSL key could not be parsed.

To obtain more information about the key, run the following command:

    openssl rsa -in privateKey.pem -check

If you see the following responses, the key is invalid:

  • unable to load Private Key
  • Expecting: ANY PRIVATE KEY
  • RSA key error: n does not equal p q
  • RSA key error: d e not congruent to 1
  • RSA key error: dmp1 not congruent to d
  • RSA key error: dmq1 not congruent to d
  • RSA key error: iqmp not inverse of q

If you see these responses, follow the instructions in Obtaining a private key and signed certificate.

If the invalid key is encrypted, you'll see the following response:

  • Enter pass phrase for privateKey.pem

Google Cloud Platform requires the key to be uploaded in an unencrypted format. To decrypt your key, run the following command and enter your password when prompted. See the openssl-rsa man page for information about command options.

    openssl rsa -in privateKey.pem -out privateKeyUnencrypted.pem

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Load Balancing