Manage certificate maps

This page describes how to create and manage certificate maps.

For more information on certificate maps, see How Certificate Manager works.

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

Note: The gcloud instructions on this page assume that you are using Cloud Shell or another environment with bash installed.

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

Create a certificate map

To create a certificate map, 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 Editor
• Certificate Manager Owner

For more information, see Roles and permissions.

gcloud

gcloud certificate-manager maps create CERTIFICATE_MAP_NAME

Replace the following:

• CERTIFICATE_MAP_NAME is a unique name that describes this certificate map.

Terraform

To create a certificate map, you can use a google_certificate_manager_certificate_map resource.

resource "google_certificate_manager_certificate_map" "default" {
  name        = "${local.name}-certmap1-${random_id.tf_prefix.hex}"
  description = "${local.domain} certificate map"
  labels = {
    "terraform" : true
  }
}

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

API

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

POST /v1/projects/PROJECT_ID/locations/global/certificateMaps?certificate_map_id=CERTIFICATE_MAP_NAME

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is a unique name that describes this certificate map.

Attach a certificate map to a proxy

After you create a certificate map and populate it with properly configured certificate map entries, you must attach it to the desired proxy. Certificate Manager supports target HTTPS proxies and target SSL proxies. For more information on the differences between these proxy types, see Using target proxies.

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.

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

gcloud

gcloud compute PROXY_TYPE update PROXY_NAME \
    --certificate-map="CERTIFICATE_MAP_NAME"

Replace the following:

• PROXY_TYPE is the type of the target proxy. Supported types are:
  • For target HTTP proxies, use target-https-proxies.
  • For target SSL proxies, use target-ssl-proxies.
• PROXY_NAME is the name of the target proxy.
• CERTIFICATE_MAP_NAME is the name of the certificate map containing one or more certificate map entries referencing the desired certificates.

API

Attach the certificate map by making a POST request to the targetHttpsProxies or targetSslProxies method as follows:

POST /projects/PROJECT_ID/global/PROXY_TYPE/PROXY_NAME/setCertificateMap
{
  certificateMap: "//certificatemanager.googleapis.com/projects/PROJECT_ID/locations/global/certificateMaps/CERTIFICATE_MAP_NAME",
}

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• PROXY_TYPE is the type of the target proxy. Supported types are:
  • For target HTTP proxies, use targetHttpsProxies.
  • For target SSL proxies, use targetSslProxies.
• PROXY_NAME is the name of the target proxy.
• CERTIFICATE_MAP_NAME is the name of the certificate map containing a certificate map entries that reference the target certificates.

Detach a certificate map from a proxy

To detach a certificate map from a proxy, complete the steps in this section.

Keep the following in mind:

• 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 complete this task, you must have the Compute Load Balancer Admin role on the target Google Cloud project.

gcloud

gcloud compute PROXY_TYPE update PROXY_NAME \
    --clear-certificate-map

Replace the following:

• PROXY_TYPE is the type of the target proxy. Supported types are:
  • For target HTTP proxies, use target-https-proxies.
  • For target SSL proxies, use target-ssl-proxies.
• PROXY_NAME is the name of the target proxy.

API

Detach the certificate map by making a POST request to the targetHttpsProxies or targetSslProxies method with an empty certificateMap value as follows:

POST /projects/PROJECT_ID/global/PROXY_TYPE/PROXY_NAME/setCertificateMap
{
  certificateMap: "",
}

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• PROXY_TYPE is the type of the target proxy. Supported types are:
  • For target HTTP proxies, use targetHttpsProxies.
  • For target SSL proxies, use targetSslProxies.
• PROXY_NAME is the name of the target proxy.

Update a certificate map

To update a certificate map's description, 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 Editor
• Certificate Manager Owner

For more information, see Roles and permissions.

gcloud

gcloud certificate-manager maps update CERTIFICATE_MAP_NAME \
    --description="DESCRIPTION"
    --update-labels="LABELS"

Replace the following:

• CERTIFICATE_MAP_NAME is the name of the target certificate map.
• DESCRIPTION is the new description for this certificate map.
• LABELS is a comma-separated list of labels applied to this certificate map.

API

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

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

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is the name of the target certificate map.
• DESCRIPTION is the new description for this certificate map.
• LABEL_KEY is a label key applied to this certificate map.
• LABEL_VALUE is a label value applied to this certificate map.

List certificate maps

To list the currently configured certificate maps, 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.

gcloud

gcloud certificate-manager maps 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, you can filter results by the following criteria:

  • 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 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 desired field with ~.

API

List configured certificate maps by making a LIST request to the certificateMaps.list method as follows:

GET /v1/projects/PROJECT_ID/locations/global/certificateMaps?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 desired field with ~.

View the state of a certificate map

To view the state of a certificate map, 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.

gcloud

gcloud certificate-manager maps describe CERTIFICATE_MAP_NAME

Replace the following:

• CERTIFICATE_MAP_NAME is the name of the target certificate map.

API

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

  GET /v1/projects/PROJECT_ID/locations/global/certificateMaps/CERTIFICATE_MAP_NAME

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is the name of the target certificate map.

Delete a certificate map

To delete a certificate map, complete the steps in this section. Before deleting a certificate map, you must first detach it from its target proxy.

If there are any certificate map entries assigned to the map you want to delete, you must manually delete them before you can delete the map; otherwise map 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.

gcloud

gcloud certificate-manager maps delete CERTIFICATE_MAP_NAME

Replace the following:

• CERTIFICATE_MAP_NAME is the name of the target certificate map.

API

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

  DELETE /v1/projects/PROJECT_ID/locations/global/certificateMaps/CERTIFICATE_MAP_NAME

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is the name of the target certificate map.

What's next

• Manage certificates
• Manage certificate map entries
• Manage DNS authorizations
• Manage certificate issuance configs