Deploy a global Google-managed certificate with Certificate Authority Service

This tutorial walks you through the certificate deployment process using a Google-managed certificate with Certificate Authority Service as an example.

The following load balancers support Google-managed certificates with CA Service:

Global external Application Load Balancer
Classic Application Load Balancer
Cross-region internal Application Load Balancer
Global external proxy Network Load Balancer

If a certificate issuance policy is in effect on the target CA pool, certificate provisioning might fail for one of the following reasons:

The certificate issuance policy has blocked the requested certificate. In this case, you are not billed since the certificate has not been issued.
The policy has applied changes to the certificate that are not supported by Certificate Manager. In this case, you are still billed since the certificate has been issued, even if it is not fully compatible with Certificate Manager.

Certificates issued by following the steps in this tutorial are not publicly trusted. If you want to issue certificates that are publicly trusted, follow the steps in one of the following tutorials instead:

If you want to migrate an existing certificate to Certificate Manager, follow the steps in Migrate certificates to Certificate Manager instead.

Keep in mind that even though you are using a regional CA pool to issue a Google-managed TLS certificate, the certificate itself is global and can be used in any region.

Objectives

This tutorial shows you how to complete the following tasks:

Create a Google-managed certificate with CA Service by using Certificate Manager.
Deploy the certificate to a supported load balancer by using a target HTTPS proxy.

For more information about the certificate deployment process, see Deployment overview.

Before you begin

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector
Make sure that you have the following roles to complete the tasks in this tutorial:
- Certificate Manager Owner: Required to create and manage Certificate Manager resources.
- Compute Load Balancer Admin or Compute Network Admin: Required to create and manage HTTPS target proxy.
- Certificate Authority Service Admin: Required to perform actions within CA Service.
For more information, see the following:
- Roles and permissions for Certificate Manager
- Compute Engine IAM roles and permissions for Compute Engine
- Permissions and roles for CA Service
Note: If you aren't assigned the permissions or roles, contact the IAM Administrator who has the Project IAM Admin role (roles/resourcemanager.projectIamAdmin) to request the missing roles.
Enable the CA Service API.
Create a CA pool. You must create and enable at least one CA in this CA pool.

Configure CA Service integration with Certificate Manager

Configure Certificate Manager to integrate with CA Service as follows:

Use the following command to create a Certificate Manager service account in the target Google Cloud project:
```
gcloud beta services identity create --service=certificatemanager.googleapis.com \
   --project=PROJECT_ID
```
Replace PROJECT_ID with the ID of the target Google Cloud project.

The command returns the name of the created service identity. See the following example:
```
service-520498234@gcp-sa-certificatemanager.iam.gserviceaccount.com
```
Grant the Certificate Manager service account the Certificate Requester role within the target CA pool as follows:
```
gcloud privateca pools add-iam-policy-binding CA_POOL \
   --location REGION \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/privateca.certificateRequester
```
Replace the following:
- CA_POOL: the ID of the target CA pool.
- REGION: the target Google Cloud region.
- SERVICE_ACCOUNT: the full name of the service account you created in step 1.
Create a certificate issuance config resource for your CA pool:
```
gcloud certificate-manager issuance-configs create ISSUANCE_CONFIG_NAME \
   --ca-pool=CA_POOL \
   [--lifetime=CERTIFICATE_LIFETIME] \
   [--rotation-window-percentage=ROTATION_WINDOW_PERCENTAGE] \
   [--key-algorithm=KEY_ALGORITHM]
```
Replace the following:
- ISSUANCE_CONFIG_NAME: the unique name of the certificate issuance config resource.
- CA_POOL: the full resource path and name of the CA pool you want to assign to this certificate issuance config resource.
- CERTIFICATE_LIFETIME: the certificate lifetime in days. Valid values are from 21 to 30 days in standard duration format. The default value is 30 days (30D). This setting is optional.
- ROTATION_WINDOW_PERCENTAGE: the percentage of the certificate's lifetime at which a renewal triggers. This setting is optional.
  
  The default value is 66 percent. You must set the rotation window percentage in relation to the certificate lifetime so that certificate renewal occurs at least 7 days after the certificate has been issued and at least 7 days before it expires.
- KEY_ALGORITHM: the encryption algorithm used to generate the private key. Valid values are ecdsa-p256 or rsa-2048. The default value is rsa-2048. This setting is optional.

For more information about certificate issuance configs, see Manage certificate issuance configs.

Create a Google-managed certificate issued by your CA Service instance

Create a Google-managed certificate issued by your CA Service instance as follows:

Console

In the Google Cloud console, go to the Certificate Manager page.

Go to Certificate Manager
On the page that appears, select the Certificates tab.
Click Add Certificate.
Enter a Name for the certificate.

This name must be unique for the project.
Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.
For location, choose Global.
For Scope, choose any of the following options:
1. Default: Choose default for Global external Application Load Balancer, a Classic Application Load Balancer, or a Global external proxy Network Load Balancer
2. All-regions: Choose all-regions for a Cross-region internal Application Load Balancer
For Certificate type, choose Create Google-managed certificate.
For Certificate Authority type, choose Private.
Specify the Domain Names of the certificate. Enter a comma-delimited list of the target domains. Also, each domain name must be a fully qualified domain name, such as myorg.example.com.
For the Certificate Issuance Config, select the name of the certificate issuance configuration resource referencing the target CA pool.
Specify a label to associate to the certificate. You can add more than one label, if needed. To add a label, click the Add label button, and specify a key and a value for your label.
Click Create. Verify that the new certificate appears in the list of certificates.

gcloud

For a Global external Application Load Balancer, a Classic Application Load Balancer or a Global external proxy Network Load Balancer:

Run the following command:

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="DOMAIN_NAMES" \
    --issuance-config=ISSUANCE_CONFIG_NAME

Replace the following:

CERTIFICATE_NAME: a unique name of the certificate.
DOMAIN_NAMES: a comma-delimited list of the target domains for this certificate. Each domain name must be a fully qualified domain name, such as myorg.example.com.
ISSUANCE_CONFIG_NAME: the name of the certificate issuance configuration resource referencing the target CA pool.

For a Cross-region internal Application Load Balancer:

Run the following command:

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="DOMAIN_NAMES" \
    --issuance-config=ISSUANCE_CONFIG_NAME \
    --scope=all-regions

Replace the following:

CERTIFICATE_NAME: a unique name of the certificate.
DOMAIN_NAMES: a comma-delimited list of the target domains for this certificate. Each domain name must be a fully qualified domain name, such as myorg.example.com.
ISSUANCE_CONFIG_NAME: the name of the certificate issuance config resource referencing the target CA pool.

API

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

For a Global external Application Load Balancer, a Classic Application Load Balancer, or a Global external proxy Network Load Balancer:

POST /v1/projects/PROJECT_ID/locations/global/certificates?certificate_id=CERTIFICATE_NAME"
{
 "managed": {
  "domains": ["DOMAIN_NAME"],
  "issuanceConfig": "ISSUANCE_CONFIG_NAME",
 }
}

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
CERTIFICATE_NAME: a unique name of the certificate.
DOMAIN_NAME: the target domain for this certificate . The domain name must be a fully qualified domain name, such as myorg.example.com.
ISSUANCE_CONFIG_NAME: the name of the certificate issuance configuration resource referencing the target CA pool.

For a Cross-region internal Application Load Balancer:

POST /v1/projects/PROJECT_ID/locations/global/certificates?certificate_id=CERTIFICATE_NAME"
{
 "managed": {
  "domains": ["DOMAIN_NAME"],
  "issuanceConfig": "ISSUANCE_CONFIG_NAME",
  "scope": "ALL_REGIONS"
 }
}

Replace the following:

PROJECT_ID: the ID of the target Google Cloud project.
CERTIFICATE_NAME: a unique name of the certificate.
DOMAIN_NAME: the target domain for this certificate . The domain name must be a fully qualified domain name, such as myorg.example.com.
ISSUANCE_CONFIG_NAME: the name of the certificate issuance config resource referencing the target CA pool.

For an overview of the certificate deployment process, see Deployment overview.

Verify that the certificate is active

Use the following command to verify that the certificate itself is active before deploying it to your load balancer. It can take several minutes for the certificate state to change to ACTIVE.

gcloud certificate-manager certificates describe CERTIFICATE_NAME

Replace CERTIFICATE_NAME with the name of the target Google-managed certificate.

The command returns output similar to the following:

createTime: '2021-10-20T12:19:53.370778666Z'
expireTime: '2022-05-07T05:03:49Z'
managed:
  domains:
  - myorg.example.com
  issuanceConfig: projects/myProject/locations/global/certificateIssuanceConfigs/myIssuanceConfig
  state: ACTIVE
name: projects/myProject/locations/global/certificates/myCert
pemCertificate: |
  -----BEGIN CERTIFICATE-----
  [...]
  -----END CERTIFICATE-----
sanDnsnames:
- myorg.example.com
updateTime: '2021-10-20T12:19:55.083385630Z'

Deploy the certificate to a load balancer

This section walks you through the steps required to deploy the Google-managed certificate to a load balancer.

Before you proceed with the tasks in this section, make sure you have completed the tasks listed in the Configure CA Service integration with Certificate Manager and Create a Google-managed certificate issued by your CA Service instance sections.

Depending on the load balancer type, you can deploy certificates as follows:

For the following load balancers, deploy the certificate using a certificate map:
- Global external Application Load Balancer
- Global external proxy Network Load Balancer
- Classic Application Load Balancer
For the Cross-region internal Application Load Balancer, deploy the certificate by attaching it directly to the target proxy.

Deploy the certificate using a certificate map

This section describes the steps to deploy a certificate using a certificate map.

Create a certificate map

Create a certificate map that will reference the certificate map entry associated with your certificate:

gcloud certificate-manager maps create CERTIFICATE_MAP_NAME

Replace CERTIFICATE_MAP_NAME with the name of the target certificate map.

Create a certificate map entry

Create a certificate map entry and associate it with your certificate as well as your certificate map:

gcloud certificate-manager maps entries create CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME" \
    --certificates="CERTIFICATE_NAME" \
    --hostname="HOSTNAME"

Replace the following:

CERTIFICATE_MAP_ENTRY_NAME: a unique name of the certificate map entry
CERTIFICATE_MAP_NAME: the name of the certificate map to which this certificate map entry attaches
CERTIFICATE_NAME: the name of the certificate you want to associate with this certificate map entry
HOSTNAME: the hostname that you want to associate with this certificate map entry

Verify that the certificate map entry is active

Use the following command to verify that the certificate map entry is active before attaching its corresponding certificate map to the target proxy:

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

certificates:
createTime: '2021-09-06T10:01:56.229472109Z'
hostname: example.com
name: projects/my-project/locations/global/certificateMaps/myCertMap/certificateMapEntries/myCertMapEntry
state: ACTIVE
updateTime: '2021-09-06T10:01:58.277031787Z'

Attach the certificate map to the target proxy

Attach the configured certificate map to the target proxy:

In the Google Cloud console, go to the Target proxies page.

Go to Target proxies
Note the name of the target proxy.
Attach the certificate map to the target proxy:
```
gcloud compute target-https-proxies update PROXY_NAME \
   --certificate-map="CERTIFICATE_MAP_NAME"
```
Replace the following:
- PROXY_NAME: the name of the target proxy
- CERTIFICATE_MAP_NAME: the name of the certificate map referencing your certificate map entry and its associated certificate

If there are any existing TLS (SSL) certificates attached directly to the proxy, the proxy gives preference to the certificates referenced by the certificate map over the directly attached TLS (SSL) certificates.

Attach the certificate directly to the target proxy

To attach the certificate directly to the proxy, run the following command:

gcloud compute target-https-proxies update PROXY_NAME \
    --url-map=URL_MAP \
    --global \
    --certificate-manager-certificates=CERTIFICATE_NAME

Replace the following:

PROXY_NAME: a unique name of the proxy.
URL_MAP: the name of the URL map. You created the URL map when you created the load balancer.
CERTIFICATE_NAME: the name of the certificate.

Troubleshooting

For troubleshooting steps, see Problems related to certificates issued by a CA Service instance.

Clean up

To revert the changes you have made in this tutorial, complete the following steps:

Detach the certificate map from the proxy.

Before you detach the certificate map, note the following:
- If there were any TLS (SSL) certificates attached directly to the proxy, detaching the certificate map causes the proxy to resume using those directly attached TLS (SSL) certificates.
- If there were no TLS (SSL) certificates attached directly to the proxy, the certificate map cannot be detached from the proxy. You must first attach at least one TLS (SSL) certificate directly to the proxy before you can detach the certificate map.
To detach the certificate map, run the following command:
```
gcloud compute target-https-proxies update PROXY_NAME \
   --clear-certificate-map
```
Replace PROXY_NAME with the name of the target proxy.
Delete the certificate map entry from the certificate map:
```
gcloud certificate-manager maps entries delete 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 target certificate map
Delete the certificate map:
```
gcloud certificate-manager maps delete CERTIFICATE_MAP_NAME
```
Replace CERTIFICATE_MAP_NAME with the name of the target certificate map.
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
```
Replace CERTIFICATE_NAME with the name of the target certificate.
Delete the certificate issuance configuration resource:
Console
1. In the Google Cloud console, go to the Certificate Manager page.
  
  Go to Certificate Manager
2. On the Issuance Configs tab, select the checkbox of the issuance config.
3. Click Delete.
4. In the dialog that appears, click Delete to confirm.
gcloud
```
 gcloud certificate-manager issuance-configs delete ISSUANCE_CONFIG_NAME
 
```
Replace ISSUANCE_CONFIG_NAME with the name of the target certificate issuance config resource.
Delete the CA pool as described in Deleting a CA pool.

Keep in mind that to disable the last CA you enabled in the CA pool referenced in the certificate issuance config, or to delete the referenced CA pool altogether, you must first delete every certificate issuance config that references that CA pool.

Deploy a global Google-managed certificate with Certificate Authority Service

Objectives

Before you begin

Configure CA Service integration with Certificate Manager

Create a Google-managed certificate issued by your CA Service instance

Console

gcloud

API

Verify that the certificate is active

Deploy the certificate to a load balancer

Deploy the certificate using a certificate map

Create a certificate map

Create a certificate map entry

Verify that the certificate map entry is active

Attach the certificate map to the target proxy

Attach the certificate directly to the target proxy

Troubleshooting

Clean up

Console

gcloud

Console

gcloud

What's next