A certificate map entry associates a certificate with a target hostname and a target certificate map. This page describes how to create and manage certificate map entries.
For more information, see Certificate map entries.
Create a certificate map entry
You can create a certificate map entry and associate a maximum of four certificates with it. We recommend that you use a different key algorithm for each certificate when specifying multiple certificates for a hostname. For example, you can use ECDSA for one certificate and RSA for another. Associating multiple certificates with a single certificate map entry also helps when migrating self-managed certificates to Google-managed certificates.
To associate multiple certificates with a certificate map entry, provide a comma-delimited list of certificate names. For each subdomain, you must create a separate certificate map entry.
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Editor role (
roles/certificatemanager.editor
) - Certificate Manager Owner role (
roles/certificatemanager.owner
)
For more information, see Roles and permissions.
To create a certificate map entry, use the gcloud certificate-manager maps
entries create
command:
gcloud certificate-manager maps entries createCERTIFICATE_MAP_ENTRY_NAME \ --map="CERTIFICATE_MAP_NAME " \ --certificates="CERTIFICATE_NAMES " \ --hostname="HOSTNAME "
Replace the following:
CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_NAMES
: a comma-delimited list of the names of the certificates you want to associate with this certificate map entry.HOSTNAME
: the hostname that you want to associate with the certificate map entry.
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_NAME1 ","projects/PROJECT_ID /locations/global/certificates/CERTIFICATE_NAME2 "] }
Replace the following:
PROJECT_ID
: the ID of the Google Cloud project.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.HOSTNAME
: the hostname that you want to associate with the certificate map entry.CERTIFICATE_NAME1
: the name of the first certificate you want to associate with this certificate map entry.CERTIFICATE_NAME2
: the name of the second certificate you want to associate with this certificate map entry.
To create a certificate map entry, you can use a
google_certificate_manager_certificate_map_entry
resource.
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands.
For information about 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 for the load balancer to serve if the client doesn't provide a hostname, or if the load balancer can't match the hostname to a configured certificate map entry.
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Editor role (
roles/certificatemanager.editor
) - Certificate Manager Owner role (
roles/certificatemanager.owner
)
For more information, see Roles and permissions.
To create a primary certificate map entry, use the gcloud
certificate-manager maps entries create
command
with the set-primary
flag:
gcloud certificate-manager maps entries createCERTIFICATE_MAP_ENTRY_NAME \ --map="CERTIFICATE_MAP_NAME " \ --certificates="CERTIFICATE_NAMES " \ --set-primary
Replace the following:
CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_NAMES
: a comma-delimited list of the names of the certificates you want to associate with this certificate map entry.
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_NAME1 ","projects/PROJECT_ID /locations/global/certificates/CERTIFICATE_NAME2 "] }
Replace the following:
PROJECT_ID
: the ID of the Google Cloud project.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_NAME1
: the name of the first certificate you want to associate with the primary certificate map entry.CERTIFICATE_NAME2
: the name of the second certificate you want to associate with the primary certificate map entry.
For information about how the load balancer selects certificates during a handshake, see Certificate selection logic.
Update a certificate map entry
When you update a certificate map entry, you can do the following:
- Assign or unassign certificates
- Modify the description
- Modify the labels
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Editor role (
roles/certificatemanager.editor
) - Certificate Manager Owner role (
roles/certificatemanager.owner
)
For more information, see Roles and permissions.
To update a certificate map entry, use the gcloud certificate-manager maps
entries update
command:
gcloud certificate-manager maps entries updateCERTIFICATE_MAP_ENTRY_NAME \ --map="CERTIFICATE_MAP_NAME " \ --certificates="CERTIFICATE_NAME ,CERTIFICATE_NAME " \ --description="DESCRIPTION " \ --update-labels="LABELS "
Replace the following:
CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_NAME
: the name of the certificate you want to associate with the certificate map entry.DESCRIPTION
: a meaningful description for this certificate map entry.LABELS
: a list of labels applied to this certificate map entry.
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:
CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.PROJECT_ID
: the ID of the Google Cloud project.CERTIFICATE_NAME
: the name of the certificate.DESCRIPTION
: a meaningful description for this certificate map entry.LABEL_KEY
: a label key applied to this certificate map entry.LABEL_VALUE
: a label value applied to this certificate map entry.
List certificate map entries
You can list, filter, and sort all configured certificate map entries of the project.
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Viewer role (
roles/certificatemanager.viewer
) - Certificate Manager Editor role (
roles/certificatemanager.editor
) - Certificate Manager Owner role (
roles/certificatemanager.owner
)
For more information, see Roles and permissions.
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
: the name of the certificate map to which the certificate map entry is attached.FILTER
: an expression that constrains the returned results to specific values.For example, you can filter the 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.
- Serving state:
PAGE_SIZE
: the number of results to return per page.LIMIT
: the maximum number of results to return.SORT_BY
: a comma-delimited list ofname
fields by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the field with a tilde (~
).
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
: the ID of the Google Cloud project.CERTIFICATE_MAP_NAME
: the name of the target certificate map.FILTER
: an expression that constrains the returned results to specific values.For example, you can filter the 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.
- Serving state:
PAGE_SIZE
: the number of results to return per page.SORT_BY
: a comma-delimited list ofname
fields by which the returned results are sorted. The default sort order is ascending; for descending sort order, prefix the field with a tilde (~
).
View the state of a certificate map entry
You can view the state of a certificate map entry.
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Viewer role (
roles/certificatemanager.viewer
) - Certificate Manager Editor role (
roles/certificatemanager.editor
) - Certificate Manager Owner role (
roles/certificatemanager.owner
)
For more information, see Roles and permissions.
gcloud certificate-manager maps entries describeCERTIFICATE_MAP_ENTRY_NAME \ --map="CERTIFICATE_MAP_NAME "
Replace the following:
CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.
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
: the ID of the Google Cloud project.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.
Delete a certificate map entry
Deleting a certificate map entry detaches the certificates associated with the certificate map entry from the target proxy. Deleting a certificate map entry doesn't delete the associated certificates from Google Cloud. You must manually delete those certificates.
Roles required for this task
To perform this task, you must have one of the following IAM roles on the target Google Cloud project.
- Certificate Manager Editor role (
roles/certificatemanager.editor
)
For more information, see Roles and permissions.
gcloud certificate-manager maps entries deleteCERTIFICATE_MAP_ENTRY_NAME \ --map="CERTIFICATE_MAP_NAME "
Replace the following:
CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.
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
: the ID of the Google Cloud project.CERTIFICATE_MAP_NAME
: the name of the certificate map to which the certificate map entry is attached.CERTIFICATE_MAP_ENTRY_NAME
: the name of the certificate map entry.
What's next
- Manage certificates
- Manage certificate maps
- Manage DNS authorizations
- Manage certificate issuance configuration resources