Migrate certificates to Certificate Manager

Stay organized with collections Save and categorize content based on your preferences.

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 load balancer as described in External HTTP(S) Load Balancing overview. Certificate Manager supports the following types of load balancers:

  • External HTTP(S) load balancer (Classic) supports target HTTPS proxies and target SSL proxies.
  • Global external HTTP(S) load balancer only supports target HTTPS proxies.

Complete the steps below for each certificate 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 is the name of the target domain.
    • IP_ADDRESS is 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 gcloud tool returns output 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
    

    See Getting information about a target proxy for more information.

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

Create a certificate map by completing the steps in Create a certificate map.

Create the certificate map entries

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 gcloud tool returns output 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 is the name of the target certificate map entry.
    • CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.

    The gcloud tool returns output 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 HTTPS load balancer.

  2. 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.

  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 is the name of the target domain.
    • IP_ADDRESS is 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. Attach the new certificate map to the appropriate target proxy as described in Attach the certificate map to the target proxy.

  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.

What's next