Migrate certificates to Certificate Manager

This page describes the steps for migrating one or more certificates to Certificate Manager. It covers the following scenarios:

  • Migrate third-party certificates to Certificate Manager.
  • Migrate Cloud Load Balancing certificates to Certificate Manager. For more information on Cloud Load Balancing certificates, see SSL certificates overview in the Cloud Load Balancing documentation.

Both scenarios incur no downtime as long as no errors occur during configuration.

For more information on the Certificate Manager entities mentioned on this page, see How Certificate Manager works.

Migrate third-party certificates to Certificate Manager

This section describes how to migrate one or more certificates served by a third-party service to Certificate Manager.

Before you begin, you must select and set up a supported load balancer. Certificate Manager lets you acquire and manage Transport Layer Security (TLS) certificates for use with the following load balancer resources:

  • Target HTTPS proxies used by Application Load Balancers:

    • Global external Application Load Balancer
    • Classic Application Load Balancer
    • Regional external Application Load Balancer (Preview)
    • Regional internal Application Load Balancer (Preview)
    • Cross-region internal Application Load Balancer (Preview)

  • Target SSL proxies used by proxy Network Load Balancers:

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

Complete the following steps for each certificate that you want to migrate:

  1. Deploy the target certificate with DNS authorization as described in Deploy a Google-managed certificate with DNS authorization (tutorial) up to but not including the clean-up steps. Use a single certificate map for all certificates you are migrating to your load balancer.

  2. For each certificate you have deployed in the previous step, test the connectivity to each domain covered by the certificate on your load balancer's IP address using the following command:

    openssl s_client -showcerts -servername DOMAIN_NAME -connect IP_ADDRESS:443

    Replace the following:

    • DOMAIN_NAME: the name of the target domain
    • IP_ADDRESS: the IP address of your load balancer

    For more information about testing connectivity, see Test with OpenSSL

  3. Switch over the traffic from your third-party service to Cloud Load Balancing by completing the steps in Update the DNS A and AAAA records to point to the load balancer's IP address.

Migrate Cloud Load Balancing certificates to Certificate Manager

This section describes how to migrate one or more Cloud Load Balancing certificates to Certificate Manager.

Identify the certificates to migrate

Complete the following steps to identify the certificates you want to migrate:

  1. On the target load balancer, identify the name of the target proxy.

  2. Identify the certificates you want to migrate by using the following command to get information about the target proxy, including the attached certificates:

    gcloud compute target-https-proxies describe TARGET_PROXY_NAME

    Replace TARGET_PROXY_NAME with the name of the target proxy.

    The output is similar to the following:

    creationTimestamp: '2021-10-06T04:05:07.520-07:00'
fingerprint: c9Txdx6AfcM=
id: '365692570234384780'
kind: compute#targetHttpsProxy
name: my-proxy
selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/targetHttpsProxies/my-proxy
sslCertificates:
- https://www.googleapis.com/compute/v1/projects/my-project/global/sslCertificates/my-first-certificate
- https://www.googleapis.com/compute/v1/projects/my-project/global/sslCertificates/my-second-certificate
urlMap: https://www.googleapis.com/compute/v1/projects/my-project/global/urlMaps/my-map

    For more information, see Getting information about a target proxy.

Create the certificates in Certificate Manager

Create the selected certificates in Certificate Manager as follows:

Before moving on to the next step, wait until each certificate's state has changed to ACTIVE as described in Verify that the certificate is active. It can take several hours for each certificate to be issued and its state change to ACTIVE.

Create the certificate map

To deploy the certificate to a global external Application Load Balancer or a classic Application Load Balancer, create a certificate map by completing the steps in Create a certificate map.

You don't need a certificate map to deploy the certificate to a regional external Application Load Balancer or a regional internal Application Load Balancer.

Create the certificate map entries

To deploy the certificate to a global external Application Load Balancer or a classic Application Load Balancer, create a certificate map entry. You don't need a certificate map entry to deploy a certificate to a regional external Application Load Balancer or a regional internal Application Load Balancer.

For each certificate you want to migrate, create certificate map entries referencing those certificates as follows:

  1. Obtain the details of the certificate using the following command:

    gcloud compute ssl-certificates --project=my-project describe CERTIFICATE_NAME

    Replace CERTIFICATE_NAME with the name of the target certificate.

    The output is similar to the following:

       -----BEGIN CERTIFICATE-----
   MIIFYjCCBEqgAwIBAgIQd70NbNs2+RrqIQ/E8FjTDTANBgkqhkiG9w0BAQsFADBX
   MQswCQYDVQQGEwJCRTEZMBcGA1UEChMQR2xvYmFsU2lnbiBudi1zYTEQMA4GA1UE
   CxMHUm9vdCBDQTEbMBkGA1UEAxMSR2xvYmFsU2lnbiBSb290IENBMB4XDTIwMDYx
   OTAwMDA0MloXDTI4MDEyODAwMDA0MlowRzELMAkGA1UEBhMCVVMxIjAgBgNVBAoT
   GUdvb2dsZSBUcnVzdCBTZXJ2aWNlcyBMTEMxFDASBgNVBAMTC0dUUyBSb290IFIx
   MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAthECix7joXebO9y/lD63
   ladAPKH9gvl9MgaCcfb2jH/76Nu8ai6Xl6OMS/kr9rH5zoQdsfnFl97vufKj6bwS
   iV6nqlKr+CMny6SxnGPb15l+8Ape62im9MZaRw1NEDPjTrETo8gYbEvs/AmQ351k
   KSUjB6G00j0uYODP0gmHu81I8E3CwnqIiru6z1kZ1q+PsAewnjHxgsHA3y6mbWwZ
   DrXYfiYaRQM9sHmklCitD38m5agI/pboPGiUU+6DOogrFZYJsuB6jC511pzrp1Zk
   j5ZPaK49l8KEj8C8QMALXL32h7M1bKwYUH+E4EzNktMg6TO8UpmvMrUpsyUqtEj5
   cuHKZPfmghCN6J3Cioj6OGaK/GP5Afl4/Xtcd/p2h/rs37EOeZVXtL0m79YB0esW
   CruOC7XFxYpVq9Os6pFLKcwZpDIlTirxZUTQAs6qzkm06p98g7BAe+dDq6dso499
   iYH6TKX/1Y7DzkvgtdizjkXPdsDtQCv9Uw+wp9U7DbGKogPeMa3Md+pvez7W35Ei
   Eua++tgy/BBjFFFy3l3WFpO9KWgz7zpm7AeKJt8T11dleCfeXkkUAKIAf5qoIbap
   sZWwpbkNFhHax2xIPEDgfg1azVY80ZcFuctL7TlLnMQ/0lUTbiSw1nH69MG6zO0b
   9f6BQdgAmD06yK56mDcYBZUCAwEAAaOCATgwggE0MA4GA1UdDwEB/wQEAwIBhjAP
   BgNVHRMBAf8EBTADAQH/MB0GA1UdDgQWBBTkrysmcRorSCeFL1JmLO/wiRNxPjAf
   BgNVHSMEGDAWgBRge2YaRQ2XyolQL30EzTSo//z9SzBgBggrBgEFBQcBAQRUMFIw
   JQYIKwYBBQUHMAGGGWh0dHA6Ly9vY3NwLnBraS5nb29nL2dzcjEwKQYIKwYBBQUH
   MAKGHWh0dHA6Ly9wa2kuZ29vZy9nc3IxL2dzcjEuY3J0MDIGA1UdHwQrMCkwJ6Al
   oCOGIWh0dHA6Ly9jcmwucGtpLmdvb2cvZ3NyMS9nc3IxLmNybDA7BgNVHSAENDAy
   MAgGBmeBDAECATAIBgZngQwBAgIwDQYLKwYBBAHWeQIFAwIwDQYLKwYBBAHWeQIF
   AwMwDQYJKoZIhvcNAQELBQADggEBADSkHrEoo9C0dhemMXoh6dFSPsjbdBZBiLg9
   NR3t5P+T4Vxfq7vqfM/b5A3Ri1fyJm9bvhdGaJQ3b2t6yMAYN/olUazsaL+yyEn9
   WprKASOshIArAoyZl+tJaox118fessmXn1hIVw41oeQa1v1vg4Fv74zPl6/AhSrw
   9U5pCZEt4Wi4wStz6dTZ/CLANx8LZh1J7QJVj2fhMtfTJr9w4z30Z209fOU0iOMy
   +qduBmpvvYuR7hZL6Dupszfnw0Skfths18dG9ZKb59UhvmaSGZRVbNQpsg3BZlvi
   d0lIKO2d1xozclOzgjXPYovJJIultzkMu34qQb9Sz/yilrbCgj8=
   -----END CERTIFICATE-----
   creationTimestamp: '2021-05-06T04:39:21.736-07:00'
   expireTime: '2022-06-07T01:10:34.000-07:00'
   id: '6422259403966690822'
   kind: compute#sslCertificate
   managed:
      domainStatus:
      a.my-domain1.example.com: ACTIVE
      b.my-domain2.example.com: ACTIVE
      domains:
      - a.my-domain1.example.com
      - b.my-domain2.example.com
      status: ACTIVE
   name: my-certificate
   selfLink: https://www.googleapis.com/compute/v1/projects/my-project/global/sslCertificates/my-certificate
   subjectAlternativeNames:
   - a. my-domain1.example.com
   - b. my-domain2.example.com
   type: MANAGED

  2. For each domain listed in the subjectAlternativeNames field, create a certificate map entry covering that domain by completing the steps in Create a certificate map entry. If more than one certificate covers a single domain, you only need to create one certificate map entry and use any valid certificate covering that domain.

  3. Optional: Create a primary certificate map entry referencing the certificate that corresponds to the first certificate from the list of certificates originally attached to the proxy as described in Create a primary certificate map entry.

  4. Use the following command to verify that each certificate map entry you have created is active:

    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 output is similar to the following:

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

Optional: Test your configuration on a new load balancer

To minimize downtime, we recommend that you test your newly configured certificate maps on a new load balancer that is not serving production traffic. This allows you to detect and resolve any errors before proceeding with the migration in your production environment.

Test your configuration as follows:

  1. Create a new load balancer with a new target proxy a described in Setting up an external Application Load Balancer.

  2. If you're using external Application Load Balancer, attach the certificate map you want to test to the new load balancer's target proxy as described in Attach the certificate map to the target proxy.

    If you're using regional external Application Load Balancer or regional internal Application Load Balancer, attach the certificate to the target proxy as described Deploy a regional self-managed certificate.

  3. For each target domain included in your migration, test the connectivity to the domain on the new load balancer's IP address using the following command:

    openssl s_client -showcerts -servername DOMAIN_NAME -connect IP_ADDRESS:443

    Replace the following:

    • DOMAIN_NAME: the name of the target domain
    • IP_ADDRESS: the IP address of your new load balancer

    For more information about testing connectivity, see Test with OpenSSL

Clean up the test environment

Clean up the test environment you created in the previous steps as follows:

  1. Detach the certificate map from the proxy:

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

    Replace PROXY_NAME with the name of the target proxy.

  2. Delete the test load balancer as described in Deleting the load balancer.

Do not delete the certificates, certificate map, or certificate map entries you created in the previous steps.

Apply the new certificate map to the target load balancer

After you have tested your new certificate configuration and confirmed that it's valid, apply the new certificate map to the target load balancer as follows.

  1. If you're using external Application Load Balancer, attach the new certificate map to the appropriate target proxy as described in Attach the certificate map to the target proxy.

    If you're using regional external Application Load Balancer or regional internal Application Load Balancer, attach the certificate to the target proxy as described Deploy a regional self-managed certificate.

  2. Wait until the configuration change has been applied and the load balancer has started serving the new certificate. This typically takes a few minutes, but can take up to 30 minutes.

  3. If you notice any problems with your traffic, detach the new certificate map from the target proxy by completing the steps in Detach a certificate map from a proxy. This reverts your load balancer to its original configuration. Otherwise, your new configuration is now complete.

    If you're using regional external Application Load Balancer or regional internal Application Load Balancer, revert the change by attaching the previously attached classic certificates.

What's next