Manage certificate issuance configuration

This page describes how to create and manage a certificate issuance configuration.

For more information about certificate issuance configuration resources, see How Certificate Manager works.

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

To learn how to deploy a certificate with Certificate Manager, see Deployment overview.

For more information about the gcloud commands used on this page, see the Certificate Manager CLI reference.

Create a certificate issuance configuration

To create a certificate issuance configuration, complete the steps in this section.

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.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

Console

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

Go to Certificate Manager
On the Issuance Configs tab, click Create.
In the Name field, enter a unique name for the certificate issuance configuration.
Optional: In the Description field, enter a description for the issuance configuration.
For Location, select Global or Regional.

If you selected Regional, select the Region.
In the Lifetime field, specify the lifetime of issued certificate in days. The value must be between 21 to 30 days (inclusive).
In the Rotation window percentage, specify the percentage of the certificate's lifetime when its renewal process begins. To find the range of valid values, see Lifetime and Rotation window percentage.
From the Key algorithm list, select the key algorithm to use when generating the private key.
From the CA pool list, select the name of the CA pool to assign to this certificate issuance config.
In the Labels field, specify labels to associate to the certificate. To add a label, click Add label, and specify a key and a value for your label.
Click Create.

gcloud

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 is a unique name that identifies this certificate issuance configuration resource.
CA_POOL is the full resource path and name of the CA pool you want to assign to this certificate issuance configuration resource.
CERTIFICATE_LIFETIME (optional) is the certificate lifetime in days. Valid values are from 21 to 30 days. Default is 30 days.
ROTATION_WINDOW_PERCENTAGE (optional) is the percentage of the certificate's lifetime when its renewal process begins. Default is 66 percent. To find the range of valid values, see Lifetime and Rotation window percentage.
KEY_ALGORITHM (optional) is the encryption algorithm to generate private key. Valid values are ecdsa-p256 or rsa-2048. Default is rsa-2048.

API

Create the certificate issuance configuration by making a POST request to the certificateIssuanceConfigs.create method as follows:

POST /v1/projects/PROJECT_ID/locations/global/certificateIssuanceConfigs?issuanceConfig_id=ISSUANCE_CONFIG_NAME
 {
  "name": "ISSUANCE_CONFIG_NAME",
  "description": "DESCRIPTION",
  "certificateAuthorityConfig": {
    "certificateAuthorityServiceConfig" {
          "caPool": "CA_POOL"
    },
  },
  "lifetime": "CERTIFICATE_LIFETIME",
  "rotationWindowPercentage": "ROTATION_WINDOW_PERCENTAGE",
  "keyAlgorithm": "KEY_ALGORITHM",
  }

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
ISSUANCE_CONFIG_NAME is a unique name that identifies this certificate issuance configuration resource.
DESCRIPTION (optional) is a meaningful description for this certificate issuance configuration resource.
CA_POOL is the full resource path and name of the CA pool you want to assign to this certificate issuance configuration resource.
CERTIFICATE_LIFETIME (optional) is the certificate lifetime in days. Valid values are from 21 to 30 days in standard duration format. Default is 30 days (30D).
ROTATION_WINDOW_PERCENTAGE (optional) is the percentage of the certificate's lifetime at which its renewal process begins. Default is 66 percent. To find the range of valid values, see Lifetime and Rotation window percentage.
KEY_ALGORITHM is the encryption algorithm used to generate private key. Valid values are ecdsa-p256 or rsa-2048. Default is rsa-2048.

Lifetime and Rotation window percentage

When you create a certificate issuance configuration, you also define the certificate's lifetime in the Lifetime field, and when the certificate's renewal process begins before it expires in the Rotation window percentage field.

To make sure that the certificate renews at least seven days before its expiry and seven days after its issuance, set the rotation window percentage relative to the certificate's lifetime. To calculate the allowed range for the rotation window percentage, use the following formulas:

Minimum value: Rotation window percentage ≥ (7 / Lifetime) * 100
Maximum value: Rotation window percentage ≤ ( (Lifetime - 7) / Lifetime) * 100

In the previous formulas, 7 is seven days.

If the minimum value is a decimal value, round it up to the nearest whole number. If the maximum value is a decimal value, round it down to the nearest whole number.

List certificate issuance configurations

To list the certificate issuance configurations, complete the steps in this section.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Viewer
Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

Console

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

Go to Certificate Manager
Click the Issuance Configs tab.

The tab lists all of the certificate issuance configuration resources managed by Certificate Manager in the selected project.

gcloud

gcloud certificate-manager issuance-configs list \
    --filter="FILTER" \
    --page-size="PAGE_SIZE" \
    --limit="LIMIT" \
    --sort-by="SORT_BY"

Replace the following:

FILTER is an expression that constrains the returned results to specific values. For example, to filter results by the labels and creation time, you can specify: --filter='labels.key:value AND create_time > "2021-09-01T00:00:00Z"'

For more filtering examples that you can use with Certificate Manager, see Sorting and filtering list results in the Cloud Key Management Service documentation.
PAGE_SIZE is the number of results to return per page.
LIMIT is the maximum number of results to return.
SORT_BY is a comma-delimited list of name fields by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the field with a tilde (~).

API

List configured certificate issuance configuration resources by making a LIST request to the certificateIssuanceConfigs.list method as follows:

GET /v1/projects/PROJECT_ID/locations/global/certificateIssuanceConfigs?filter=FILTER&pageSize=PAGE_SIZE&sortBy=SORT_BY

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
FILTER is an expression that constrains the returned results to specific values.
PAGE_SIZE is the number of results to return per page.
SORT_BY is a comma-delimited list of field names by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the field with ~.

View the state of a certificate issuance configuration

To view the state of a certificate issuance configuration, complete the steps in this section.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Viewer
Certificate Manager Editor
Certificate Manager Owner

For more information, see Roles and permissions.

Console

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

Go to Certificate Manager
Click the Issuance Configs tab.
Click the name of the certificate issuance configuration that you want to view.

The Google Cloud console displays the certificate issuance configuration details.

gcloud

gcloud certificate-manager issuance-configs describe ISSUANCE_CONFIG_NAME

Replace the following:

ISSUANCE_CONFIG_NAME is the name of the target certificate issuance configuration.

API

View the state of the certificate issuance configuration by making a GET request to the certificateIssuanceConfigs.get method as follows:

  GET /v1/projects/PROJECT_ID/locations/global/certificateIssuanceConfigs/ISSUANCE_CONFIG_NAME

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
ISSUANCE_CONFIG__NAME is the name of the target certificate issuance configuration.

Update a certificate issuance configuration

You can add or change the labels and descriptions of your certificate issuance configuration using either the Google Cloud CLI or API.

To complete this task, you must have one of the following roles on the target Google Cloud project:

Certificate Manager Editor
Certificate Manager Owner

Learn more about Roles and permissions.

gcloud

Use the gcloud certificate-manager issuance-configs update command to update a certificate issuance configuration:

gcloud certificate-manager issuance-configs update \
    ISSUANCE_CONFIG_NAME
    --update-labels="LABELS" \
    --description="DESCRIPTION"

Replace the following:

ISSUANCE_CONFIG_NAME is the name of the target certificate issuance configuration that you want to update.
Optional: LABELS is one or more labels that you want to specify for the certificate issuance configuration. Labels must be specified in a comma-delimited list as KEY=VALUE pairs.
Optional: DESCRIPTION describes the certificate issuance configuration.

API

Use the certificateIssuanceConfigs.patch method to update a certificate issuance configuration:

PATCH /v1/projects/PROJECT_ID/locations/global/certificateIssuanceConfigs/ISSUANCE_CONFIG_NAME?updateMask=labels,description
{
  labels: { "LABEL_KEY": "LABEL_VALUE" },
  description: "DESCRIPTION"
}

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
ISSUANCE_CONFIG_NAME is the name of the target certificate issuance configuration that you want to update.
Optional: You can specify one or more labels for each certificate issuance configuration.
- LABEL_KEY is the label key.
- LABEL_VALUE_ is the value of the label.
Optional: DESCRIPTION describes the certificate issuance configuration.

Delete a certificate issuance configuration

To delete a certificate issuance configuration, complete the steps in this section. Before deleting a certificate issuance configuration, you must first delete the Google-managed certificate that references it.

To complete this task, you must have the Certificate Manager Owner role on the target Google Cloud project.

For more information, see Roles and permissions.

Console

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

Go to Certificate Manager
On the Issuance Configs tab, select the checkbox of the issuance config that you want to delete.
Click Delete.
In the dialog that appears, click Delete to confirm.

gcloud

gcloud certificate-manager issuance-configs delete ISSUANCE_CONFIG_NAME

Replace the following:

ISSUANCE_CONFIG_NAME is the name of the target certificate issuance configuration.

API

Delete the certificate issuance configuration by making a DELETE request to the certificateIssuanceConfigs.delete method as follows:

  DELETE /v1/projects/PROJECT_ID/locations/global/certificateIssuanceConfigs/ISSUANCE_CONFIG_NAME

Replace the following:

PROJECT_ID is the ID of the target Google Cloud project.
ISSUANCE_CONFIG_NAME is the name of the target certificate issuance configuration.

Manage certificate issuance configuration

Create a certificate issuance configuration

Console

gcloud

API

Lifetime and Rotation window percentage

List certificate issuance configurations

Console

gcloud

API

View the state of a certificate issuance configuration

Console

gcloud

API

Update a certificate issuance configuration

gcloud

API

Delete a certificate issuance configuration

Console

gcloud

API

What's next