Manage certificate map entries

This section describes how to create and manage certificate map entries. A certificate map entry associates a certificate with a target hostname and a target certificate map.

For more information on certificate map entries, 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 entry

To create a certificate map entry and associate one or more certificates with it, complete the steps in this section. You must specify at least one certificate within a certificate map entry. If you want to specify more than one certificate for a given hostname, you can only do so if each certificate uses a different cypher suite—for example, ECDSA and RSA.

To associate multiple certificates with a certificate map entry, provide a comma-delimited list of certificate names to associate with the entry. You can associate a maximum of 4 certificates with a single certificate map entry. For each subdomain, you must create a separate certificate map entry.

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 entries create CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME" \
    --certificates="CERTIFICATE_NAMES" \
    --hostname="HOSTNAME"

Replace the following:

• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_NAMES is a comma-delimited list of the names of the certificates you want to associate with this certificate map entry.
• HOSTNAME is the hostname that you want to associate with this certificate map entry.

Terraform

To create a certificate map entry, you can use a google_certificate_manager_certificate_map_entry resource.

resource "google_certificate_manager_certificate_map_entry" "default" {
  name        = "${local.name}-first-entry-${random_id.tf_prefix.hex}"
  description = "example certificate map entry"
  map         = google_certificate_manager_certificate_map.default.name
  labels = {
    "terraform" : true
  }
  certificates = [google_certificate_manager_certificate.default.id]
  hostname     = local.domain
}

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

API

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

POST /v1/projects/PROJECT_ID/locations/global/certificateMaps/CERTIFICATE_MAP_NAME/certificateMapEntries?certificate_map_entry_id=CERTIFICATE_MAP_ENTRY_NAME"
{
 hostname: "HOSTNAME"
 certificates: ["projects/PROJECT_ID/locations/global/certificates/CERTIFICATE_NAME"],
}

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• HOSTNAME is the hostname that you want to associate with this certificate map entry.
• CERTIFICATE_NAME is the name of the certificate you want to associate with this certificate map entry.

For information on how the load balancer selects certificates during a handshake, see Certificate selection logic.

Create a primary certificate map entry

You can specify a primary certificate that the load balancer serves if the client does not provide a hostname or provides a hostname that the load balancer cannot match to any configured certificate map entry.

Note: When using Certificate Manager with Identity-Aware Proxy (IAP), create a dedicated certificate map entry for each hostname. Primary certificate map entry is incompatible with IAP.

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 entries create CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME" \
    --certificates="CERTIFICATE_NAMES" \
    --set-primary

Replace the following:

• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_NAMES is a comma-delimited list of the names of the certificates you want to associate with this certificate map entry.

API

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

POST /v1/projects/PROJECT_ID/locations/global/certificateMaps/CERTIFICATE_MAP_NAME/certificateMapEntries?certificate_map_entry_id=CERTIFICATE_MAP_ENTRY_NAME"
{
   matcher: "PRIMARY",
   certificates: ["projects/PROJECT_ID/locations/global/certificates/CERTIFICATE_NAME"],
}

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_NAME is the name of the certificate you want to associate with this certificate map entry.

For information on how the load balancer selects certificates during a handshake, see Certificate selection logic.

Update a certificate map entry

To update a certificate map entry, complete the steps in this section. You can update a certificate map entry as follows:

• Assign or unassign certificates
• Modify the description
• Modify the labels

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 entries update CERTIFICATE_MAP_ENTRY_NAME \
    --map="CERTIFICATE_MAP_NAME" \
    --certificates="CERTIFICATE_NAME,CERTIFICATE_NAME" \
    --description="DESCRIPTION"
    --update-labels="LABELS"

Replace the following:

• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_NAME is the name of the certificate you want to associate with this certificate map entry.
• DESCRIPTION is a meaningful description for this certificate map entry.
• LABELS is a list of labels applied to this certificate map entry.

API

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

PATCH  /v1/projects/example-project/locations/global/certificateMaps/CERTIFICATE_MAP_NAME/certificateMapEntries/CERTIFICATE_MAP_ENTRY_NAME?updateMask=labels,description,certificates
{
  "certificates": ["projects/PROJECT_ID/locations/global/certificates/CERTIFICATE_NAME"],
  "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 certificate map to which this certificate map entry attaches.
• CERTIFICATE_MAP_ENTRY_NAME is a unique name that describes this certificate map entry.
• CERTIFICATE_NAME is the name of the certificate you want to associate with this certificate map entry.
• DESCRIPTION is a meaningful description for this certificate map entry.
• LABEL_KEY is a label key applied to this certificate map entry.
• LABEL_VALUE is a label value applied to this certificate map entry.

List certificate map entries

To list the certificate map entries currently configured within a target 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 entries list --map=CERTIFICATE_MAP_NAME \
    --filter="FILTER" \
    --page-size="PAGE_SIZE" \
    --limit="LIMIT" \
    --sort-by="SORT_BY"

Replace the following:

• CERTIFICATE_MAP_NAME is the name of the target certificate map.

• FILTER is an expression that constrains the returned results to specific values. For example, you can filter results by the following criteria:

  • Serving state: --filter='state=ACTIVE'
  • Matcher (set as primary): --filter='-matcher=PRIMARY'
  • Hostname: --filter='hostname=example.com'
  • Assigned certificates: --filter='certificates:my-cert'
  • 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 certificate map entries configured within a given certificate map by making a LIST request to the certificateMaps.certificateMapEntries.list method as follows:

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

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

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

API

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

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

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_MAP_ENTRY_NAME is the name of the target certificate map entry.

Delete a certificate map entry

To delete a certificate map entry from a certificate map, complete the steps in this section. This action detaches the certificates associated with the certificate map entry from the target proxy.

Deleting a certificate map entry does not delete the associated certificates. To remove those certificates from Google Cloud, you must manually delete them.

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

API

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

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

Replace the following:

• PROJECT_ID is the ID of the target Google Cloud project.
• CERTIFICATE_MAP_NAME is the name of the certificate map to which this certificate map entry attaches.
• CERTIFICATE_MAP_ENTRY_NAME is the name of the target certificate map entry.

What's next

• Manage certificates
• Manage certificate maps
• Manage DNS authorizations
• Manage certificate issuance configs