Manage certificates

This page describes how to use Certificate Manager to create and manage Transport Layer Security (TLS) (SSL) certificates. Certificate Manager supports the following types of TLS (SSL) certificates:

  • Google-managed certificates are certificates that Google Cloud obtains and manages for you. You can create the following types of Google-managed certificates with Certificate Manager:
    • Global certificates
      • Google-managed certificates with load balancer authorization
      • Google-managed certificates with DNS authorization
      • Google-managed certificates with Certificate Authority Service (CA Service)
    • Regional certificates
      • Regional Google-managed certificates
      • Regional Google-managed certificates with CA Service
  • Self-managed certificates are certificates that you obtain, provision, and renew yourself.

For more information about certificates, see How Certificate Manager works.

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

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

Create a Google-managed certificate with load balancer authorization

To create a Google-managed certificate with load balancer authorization, complete the steps in this section. You can only create Google-managed certificates with load balancer authorization in the global location.

To specify multiple domain names for the certificate, provide a comma-delimited list of target domain names for the certificate.

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

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose Global.

  7. For Scope, choose Default.

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Public.

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

  11. For Authorization type, choose Load Balancer Authorization.

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

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud 

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

Replace the following:

  • CERTIFICATE_NAME: a unique name that describes this 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.

Terraform

To create a Google-managed certificate, you can use a google_certificate_manager_certificate resource with a managed block.

resource "google_certificate_manager_certificate" "default" {
  name        = "prefixname-rootcert-${random_id.default.hex}"
  description = "Google-managed cert"
  managed {
    domains = ["example.me"]
  }
  labels = {
    "terraform" : true
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

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

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

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • CERTIFICATE_NAME: a unique name that describes this certificate.
  • DOMAIN_NAME: the target domain for this certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.

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

Create a Google-managed certificate with DNS authorization

To create a global Google-managed certificate with DNS authorization, do the following:

  1. Create the corresponding DNS authorizations that reference each of the domain names covered by the certificate. For instructions, see Creating a DNS authorization.
  2. Configure a valid CNAME record for the validation sub-domain in the DNS zone of the target domain. For instructions, see Adding the CNAME record to your DNS configuration.
  3. Complete the steps in this section.

You can create both regional and global Google-managed certificates. For information about how to create a regional Google-managed certificate, see Create a regional Google-managed-certificate.

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

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose Global.

  7. For Scope, choose Default.

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Public.

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

  11. For Authorization type, choose DNS Authorization. If the domain name has an associated DNS authorization, it will get automatically picked up. If the domain name does not have an associated DNS authorization then, do the following:

    1. Click Create missing DNS authorization to display the Create DNS Authorization dialog.
    2. In the DNS Authorization Name field, specify the DNS authorization name.
    3. To independently manage certificates across multiple projects, select Per project authorization.
    4. Click Create DNS authorization. Verify that the DNS name gets associated to the domain name.

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

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud 

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="DOMAIN_NAMES" \
    --dns-authorizations="AUTHORIZATION_NAMES"

Replace the following:

  • CERTIFICATE_NAME: a unique name that describes this 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.
  • AUTHORIZATION_NAMES: a comma-delimited list of names of the DNS authorizations you created for this certificate.

To create a Google-managed certificate with a wildcard domain name, use the following command. A wildcard domain name certificate covers all first-level subdomains of a given domain.

gcloud certificate-manager certificates create CERTIFICATE_NAME \
    --domains="*.DOMAIN_NAME,DOMAIN_NAME" \
    --dns-authorizations=AUTHORIZATION_NAME

Replace the following:

  • CERTIFICATE_NAME: a unique name that describes this certificate.
  • DOMAIN_NAME: the target domain for this certificate. The asterisk dot prefix (*.) prefix signifies a wildcard certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization that you created for this certificate.

Terraform

To create a Google-managed certificate with DNS authorization, you can use a google_certificate_manager_certificate resource with the dns_authorizations attribute in the managed block.

resource "google_certificate_manager_certificate" "root_cert" {
  name        = "${local.name}-rootcert-${random_id.tf_prefix.hex}"
  description = "The wildcard cert"
  managed {
    domains = [local.domain, "*.${local.domain}"]
    dns_authorizations = [
      google_certificate_manager_dns_authorization.default.id
    ]
  }
  labels = {
    "terraform" : true
  }
}

To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.

API

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

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

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • CERTIFICATE_NAME: a unique name that describes this certificate.
  • DOMAIN_NAME: the target domain for this certificate. The asterisk dot prefix (*.) signifies a wildcard certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorizations you created for this certificate.

To independently manage certificates across multiple projects, you can use per-project DNS authorization. For information about creating certificates with per-project DNS authorization, see Creating a DNS authorization.

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

Create a Google-managed certificate issued by CA Service

To create a Google-managed certificate issued by a CA Service instance under your control, complete the steps in this section. You can create both regional and global Google-managed certificates. For information on how to create a regional Google-managed certificate issued by CA Service, see Create a regional Google-managed-certificate issued by CA Service

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

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

Configure CA Service integration with Certificate Manager

If you have not already done so, you must configure Certificate Manager to integrate with CA Service as described in this section. 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 because 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 because the certificate has been issued, even if it is not fully compatible with Certificate Manager.

For any problems related to issuance policy restrictions, see the Troubleshooting page.

To configure CA Service integration with Certificate Manager, do the following:

  1. Grant Certificate Manager the ability to request certificates from the target CA pool:

    1. 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 account. For example:

      service-520498234@gcp-sa-certificatemanager.iam.gserviceaccount.com

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

  2. Create a certificate issuance configuration resource for your CA pool:

Console

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

    Go to Certificate Manager

  2. On the Issuance Configs tab, click Create.

  3. In the Name field, enter a unique name for the certificate issuance configuration.

  4. For Location, select Global.

  5. Optional: In the Description field, enter a description for the issuance configuration.

  6. In the Lifetime field, specify the lifetime of issued certificate in days. The value must be between 21 to 30 days (inclusive).

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

  8. From the Key algorithm list, select the key algorithm to use when generating the private key.

  9. From the CA pool list, select the name of the CA pool to assign to this certificate issuance config.

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

  11. 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: a unique name that identifies this certificate issuance configuration resource.
  • CA_POOL: the full resource path and name of the CA pool you want to assign to this certificate issuance configuration resource.
  • CERTIFICATE_LIFETIME: the certificate lifetime in days. Valid values are from 21 to 30 days in standard duration format. The default is 30 days (30D). This setting is optional.
  • ROTATION_WINDOW_PERCENTAGE: the percentage of the certificate's lifetime when the certificate's renewal triggers. To find the range of valid values, see Lifetime and Rotation window percentage. This setting is optional.
  • KEY_ALGORITHM: the encryption algorithm used to generate the private key. Valid values are ecdsa-p256 or rsa-2048. The default is rsa-2048. This setting is optional.

For more information about certificate issuance configuration resources, see Manage certificate issuance configuration.

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

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose Global.

  7. For Scope, choose Default.

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Private.

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

  11. For Certificate Issuance Config, select the name of the certificate issuance configuration resource referencing the target CA pool.

    To create an issuance configuration, click Add certificate issuance config, specify the following details, and click Create.

    • Name: a unique name for the certificate issuance configuration.
    • Description: a description for the issuance configuration.
    • Lifetime: the lifetime of issued certificate in days. The value must be between 21 to 30 days (inclusive).
    • Rotation window percentage: the percentage of the certificate's lifetime when the certificate's renewal triggers. To find the range of valid values, see Lifetime and Rotation window percentage.
    • Key algorithm: the key algorithm to use when generating the private key.
    • CA pool: the name of the CA pool to assign to this certificate issuance configuration.
    • Label: labels to associate to the certificate issuance configuration.

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

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud 

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

Replace the following:

  • CERTIFICATE_NAME: a unique name that describes this 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.

API

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

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 that describes this 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 an overview of the certificate deployment process, see Deployment overview.

Create a regional Google-managed certificate issued by CA Service

To create a regional Google-managed certificate issued by a CA Service instance under your control, complete the steps in this section.

Configure CA Service integration with Certificate Manager

Configure Certificate Manager to integrate with CA Service as follows:

  1. 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, as shown in the following example:

    service-520498234@gcp-sa-certificatemanager.iam.gserviceaccount.com

  2. 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 LOCATION \
    --member "serviceAccount:SERVICE_ACCOUNT" \
    --role roles/privateca.certificateRequester

    Replace the following:

    • CA_POOL: the ID of the target CA pool.
    • LOCATION: the target Google Cloud location. You must specify the same location as the CA pool, certificate issuance configuration resource, and managed certificate.
    • SERVICE_ACCOUNT: the full name of the service account you created in step 1.

  3. Create a certificate issuance configuration resource for your CA pool:

Console

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

    Go to Certificate Manager

  2. On the Issuance Configs tab, click Create.

  3. In the Name field, enter a unique name for the certificate issuance configuration.

  4. Optional: In the Description field, enter a description for the issuance configuration.

  5. For Location, select Regional.

  6. From the Region list, select the region.

  7. In the Lifetime field, specify the lifetime of issued certificate in days. The value must be between 21 to 30 days (inclusive).

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

  9. From the Key algorithm list, select the key algorithm to use when generating the private key.

  10. From the CA pool list, select the name of the CA pool to assign to this certificate issuance config.

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

  12. Click Create.

gcloud 

gcloud beta certificate-manager issuance-configs create ISSUANCE_CONFIG_NAME \
    --ca-pool=CA_POOL \
    --location=LOCATION> \
    [--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 configuration resource.
  • CA_POOL: the full resource path and name of the CA pool you want to assign to this certificate issuance configuration resource.
  • LOCATION: the target Google Cloud location. You must specify the same location as the CA pool, certificate issuance configuration resource, and managed certificate.
  • 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 when the it's renewal process begins. To find the range of valid values, see Lifetime and Rotation window percentage.
  • 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.
  • DESCRIPTION: a description for the certificate issuance configuration resource. This setting is optional.

For more information about certificate issuance configuration resources, see Manage certificate issuance configuration.

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

Create a regional Google-managed certificate issued by your CA Service using the certificate issuance configuration resource created in the preceding step:

Console

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose Regional.

  7. From the Region list, select a region.

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Private.

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

  11. For Certificate Issuance Config, select the name of the certificate issuance configuration resource referencing the target CA pool.

    To create an issuance configuration, click Add certificate issuance config, specify the following details, and click Create.

    • Name: a unique name for the certificate issuance configuration.
    • Description: a description for the issuance configuration.
    • Lifetime: the lifetime of issued certificate in days. The value must be between 21 to 30 days (inclusive).
    • Rotation window percentage: the percentage of the certificate's lifetime when the it's renewal process begins. To find the range of valid values, see Lifetime and Rotation window percentage.
    • Key algorithm: the key algorithm to use when generating the private key.
    • CA pool: the name of the CA pool to assign to this certificate issuance configuration.
    • Label: labels to associate to the certificate issuance configuration.

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

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud

Run the following command:

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

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.
  • LOCATION: the target Google Cloud location. You must specify the same location as the CA pool, certificate issuance configuration resource, and managed certificate.

API

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

POST /v1/projects/PROJECT_ID/locations/LOCATION/certificates?
{
certificate: {
    name: "/projects/example-project/locations/LOCATION/certificates/my-cert",
    "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 example.com, www.example.com.
  • ISSUANCE_CONFIG_NAME: the name of the certificate issuance configuration resource referencing the target CA pool.
  • LOCATION: the target Google Cloud location. You must specify the same location as the CA pool, certificate issuance configuration resource, and managed certificate.

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

Create a regional Google-managed certificate

To create a Google-managed certificate with DNS authorization, do the following:

  1. Create the corresponding DNS authorizations that reference each of the domain names covered by the certificate. For instructions, see Creating a DNS authorization.
  2. Configure a valid CNAME record for the validation sub-domain in the DNS zone of the target domain. For instructions, see Adding the CNAME record to your DNS configuration.
  3. Complete the steps in this section.

You can create both regional and global Google-managed certificates. For information about how to create a global Google-managed certificate, see Create a Google-managed-certificate with DNS authorization.

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

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose Regional.

  7. From the Region list, select a region.

  8. For Certificate type, choose Create Google-managed certificate.

  9. For Certificate Authority type, choose Public.

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

  11. For Authorization type, choose DNS Authorization. If the domain name has an associated DNS authorization, it will get automatically picked up. If the domain name does not have an associated DNS authorization then, do the following:

    1. Click Create missing DNS authorization to display the Create DNS Authorization dialog.
    2. In the DNS Authorization Name field, specify the DNS authorization name.
    3. Click Create DNS authorization. Verify that the DNS name gets associated to the domain name.

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

  13. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud

Run the following command:

gcloud certificate-manager certificates create CERTIFICATE_NAME \
   --domains=DOMAIN_NAME \
   --dns-authorizations=AUTHORIZATION_NAME \
   --location=LOCATION

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization you created for this certificate.
  • LOCATION: the location where you create the Google-managed certificate.

To create a Google-managed certificate with a wildcard domain name, use the following command. A wildcard domain name certificate covers all first-level subdomains of a given domain.

gcloud certificate-manager certificates create CERTIFICATE_NAME \
   --domains="*.DOMAIN_NAME,DOMAIN_NAME" \
   --dns-authorizations=AUTHORIZATION_NAME
   --location=LOCATION

Replace the following:

  • CERTIFICATE_NAME: a unique name of the certificate.
  • DOMAIN_NAME: the target domain of the certificate. The asterisk dot prefix (*.) signifies a wildcard certificate. The domain name must be a fully qualified domain name, such as myorg.example.com.
  • AUTHORIZATION_NAME: the name of the DNS authorization that you created for this certificate.
  • LOCATION: the location where you create the Google-managed certificate.

Upload a self-managed certificate

To upload a self-managed certificate, complete the steps in this section. You can upload global and regional X.509 TLS (SSL) certificates of the following types:

  • Certificates generated by third-party certificate authorities (CAs) of your choice
  • Certificates generated by certificate authorities under your control
  • Self-signed certificates, as described in Create a private key and certificate

You must upload the following PEM-encoded files:

  • The certificate (.crt) file
  • The corresponding private key (.key) file

See Deployment overview for the steps necessary to begin serving the certificate on your load balancer.

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

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. Click Add Certificate.

  4. Enter a Name for the certificate.

    This name must be unique for the project.

  5. Optional: Enter the Description for the certificate. The description helps you identify a specific certificate later.

  6. For Location, choose any of the following:

    • Global: Select Global so that the certificate can be used globally. If you choose Global, then from the Scope drop-down menu, select any of the following:
      • Default: Certificates with default scope are served from core Google data centers.
      • Edge Cache: Certificates with this scope are special certificates and are served from non-core Google data centers.
      • All Regions: Certificates are served from all regions.
    • Regional: Select Regional so that the certificate can be used in a particular region. If you choose Regional, then from the Region list, select a region.

  7. For Certificate type, choose Create Self-managed certificate.

  8. For the Certificate field, do any of the following:

    • Click the Upload button and select your PEM-formatted certificate file.
    • Copy and paste the contents of a PEM-formatted certificate. The contents must start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----.

  9. For the Private key certificate field, do any of the following:

    • Click the Upload button and select your private key. Your private key must be PEM-formatted and not protected with a passphrase.
    • Copy and paste the contents of a PEM-formatted private key. The private keys must start with -----BEGIN PRIVATE KEY----- and end with -----END PRIVATE KEY-----.

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

  11. Click Create. Verify that the new certificate appears in the list of certificates.

gcloud 

gcloud certificate-manager certificates create  CERTIFICATE_NAME \
    --certificate-file="CERTIFICATE_FILE" \
    --private-key-file="PRIVATE_KEY_FILE" \
    [--location="REGION"]

Replace the following:

  • CERTIFICATE_NAME: a unique name that describes this certificate.
  • CERTIFICATE_FILE: the path and filename of the .crt certificate file.
  • PRIVATE_KEY_FILE: the path and filename of the .key private key file.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.

Terraform

To upload a self-managed certificate, you can use a google_certificate_manager_certificate resource with the self_managed block.

API

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

POST /v1/projects/PROJECT_ID/locations/[REGION]/certificates?certificate_id=CERTIFICATE_NAME
{
  self_managed: {
    pem_certificate: "PEM_CERTIFICATE",
    pem_private_key: "PEM_KEY",
  }
}

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • CERTIFICATE_NAME: a unique name that describes this certificate.
  • PEM_CERTIFICATE: the certificate PEM.
  • PEM_KEY: the key PEM.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.

Update a certificate

To update an existing certificate without modifying its assignments to domain names within the corresponding certificate map, complete the steps in this section. The SANs in the new certificate must exactly match the SANs in the existing certificate.

For Google-managed certificates, you can only update the description and labels fields. To update a self-managed certificate, you must upload the following PEM-encoded files:

  • The certificate (.crt) file
  • The corresponding private key (.key) file

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.

gcloud 

gcloud certificate-manager certificates update CERTIFICATE_NAME \
    --certificate-file="CERTIFICATE_FILE" \
    --private-key-file="PRIVATE_KEY_FILE" \
    --description="DESCRIPTION" \
    --update-labels="LABELS" \
    [--location="REGION"]

Replace the following:

  • CERTIFICATE_NAME: the name of the target certificate.
  • CERTIFICATE_FILE: the path and filename of the .crt certificate file.
  • PRIVATE_KEY_FILE: the path and filename of the .key private key file.
  • DESCRIPTION: a unique description value for this certificate.
  • LABELS: a comma-separated list of labels applied to this certificate.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.

API

Update the certificate by making a PATCH request to the certificates.patch method as follows:

PATCH /v1/projects/PROJECT_ID/locations/[REGION]/certificates/CERTIFICATE_NAME?updateMask=self_managed,labels,description
{
   self_managed: { // Self-managed certificates only
    pem_certificate: "PEM_CERTIFICATE",
    pem_private_key: "PEM_KEY",
  }
  "description": "DESCRIPTION",
  "labels": {
    "LABEL_KEY": "LABEL_VALUE",
  }

}

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.
  • CERTIFICATE_NAME: the name of the target certificate.
  • PEM_CERTIFICATE: the certificate PEM.
  • PEM_KEY: the key PEM.
  • DESCRIPTION: a meaningful description for this certificate.
  • LABEL_KEY: a label key applied to this certificate.
  • LABEL_VALUE: a label value applied to this certificate.

List certificates

To list certificates managed by Certificate Manager, complete the steps in this section. For example, you can perform the following queries:

  • List certificates by their assigned domain names
  • List certificates that have expired

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

If you have more than 10,000 certificates in your project that are managed by Certificate Manager, the Certificate Manager page in the Google Cloud console cannot list them. In such cases, use the gcloud CLI command to list your certificates instead.

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab. This tab lists all of the certificates managed by Certificate Manager in the selected project.

The Classic Certificates tab lists certificates in the selected project that have been provisioned directly through Cloud Load Balancing. These certificates are not managed by Certificate Manager. For instructions about managing those certificates, see one of the following articles in the Cloud Load Balancing documentation:

gcloud 

gcloud certificate-manager certificates list \
    [--location="REGION"] \
    --filter="FILTER" \
    --page-size="PAGE_SIZE" \
    --limit="LIMIT" \
    --sort-by="SORT_BY"

Replace the following:

  • REGION: the target Google Cloud region; to list certificates from all regions, use - as the value. The default is global. This setting is optional.
  • FILTER: an expression that constrains the returned results to specific values. For example, you can filter results by the following criteria:
    • Expiration time: --filter='expire_time >= "2021-09-01T00:00:00Z"'
    • SAN DNS names: --filter='san_dnsnames:"example.com"'
    • Certificate state: --filter='managed.state=FAILED'
    • Certificate type: --filter='managed:*'
    • Labels and creation time: --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: the number of results to return per page.
  • LIMIT: the maximum number of results to return.
  • SORT_BY: 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 ~.

API

List the certificates by making a LIST request to the certificates.list method as follows:

GET /v1/projects/PROJECT_ID/locations/REGION/certificates?filter=FILTER&pageSize=PAGE_SIZE&sortBy=SORT_BY

Replace the following:

  • REGION: the target Google Cloud region; to list certificates from all regions, use - as the value.
  • PROJECT_ID: the ID of the target Google Cloud project.
  • FILTER: an expression that constrains the returned results to specific values.
  • PAGE_SIZE: the number of results to return per page.
  • SORT_BY: 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

To view the state of an existing certificate, including its provisioning state and other detailed information, 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

If you have more than 10,000 certificates in your project that are managed by Certificate Manager, the Certificate Manager page in the Google Cloud console cannot list them. In such cases, use the gcloud CLI command to list your certificates instead. However, if you have a direct link to the certificate's Details page, the Certificate Manager page in the Google Cloud console can display those details.

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

    Go to Certificate Manager

  2. On the page that appears, select the Certificates tab.

  3. On the Certificates tab, go to the target certificate, and then click the certificate's name.

The Certificate details page displays detailed information about the selected certificate.

  1. Optional: To view the REST response from the Certificate Manager API for this certificate, click Equivalent REST.

  2. Optional: If the certificate has an associated certificate issuance configuration that you want to view, then in the Issuance config field, click the name of the associated certificate issuance configuration.

    The Google Cloud console displays the full configuration of the certificate issuance configuration.

gcloud 

gcloud certificate-manager certificates describe CERTIFICATE_NAME \
    [--location="REGION"]

Replace the following:

  • CERTIFICATE_NAME: the name of the target certificate.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.

API

View the certificate state by making a GET request to the certificates.get method as follows:

GET /v1/projects/PROJECT_ID/locations/REGION/certificates/CERTIFICATE_NAME

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • REGION: the target Google Cloud region.
  • CERTIFICATE_NAME: the name of the target certificate.

Delete a certificate

To delete a certificate from Certificate Manager, complete the steps in this section. Before you can delete a certificate, you must remove it from all certificate map entries that reference it; otherwise the deletion fails.

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

  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 that you want to delete.

  3. Click Delete.

  4. In the dialog that appears, click Delete to confim.

gcloud 

gcloud certificate-manager certificates delete CERTIFICATE_NAME \
   [--location="REGION"]

Replace the following:

  • CERTIFICATE_NAME: the name of the target certificate.
  • REGION: the target Google Cloud region. The default is global. This setting is optional.

API

Delete the certificate by making a DELETE request to the certificates.delete method as follows:

DELETE /v1/projects/PROJECT_ID/locations/REGION/certificates/CERTIFICATE_NAME

Replace the following:

  • PROJECT_ID: the ID of the target Google Cloud project.
  • REGION: the target Google Cloud region.
  • CERTIFICATE_NAME: the name of the target certificate.

What's next