Wildcard Certificates
This section describes the usage and configuration of a wildcard certificate for the TLS/SSL service plans of an a9s Data Service.
A Platform Operator can define a wildcard certificate via the configuration of the a9s SPI for the corresponding a9s Data Service. This wildcard certificate is then used for all Service Instances across all versions of the corresponding a9s Data Service.
For the list of the supported a9s Data Services and the Limitations please refer to the a9s TLS/SSL Service Plans overview.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Installation
In order to use a wildcard certificate for an a9s Data Service, the Ops file <data_service_name>-service/ops/use-wildcard-certificate.yml
MUST be applied to the corresponding a9s Data Service deployment manifest.
data_service=<data_service_name>-service
bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-wildcard-certificate.yml
The CredHub variable /a9s_<data_service_name>_service_spi_wildcard
MUST be set to use the Ops file. The CredHub
variable MUST be of type certificate
. The option certificate
is used to set wildcard.certificate
, the option
private
is used to set wildcard.private_key
, and the option root
is used to set wildcard.ca
.
credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert.pem -p ~/certs/cert-key.pem -r ~/certs/chain.pem
Configuration
Each a9s SPI provides the following properties to configure a wildcard certificate:
Property | Note |
---|---|
wildcard.certificate | The single wildcard certificate (server/leaf certificate) that is used for all Service Instances. The X.509 certificate MUST be in PKCS#1 format and PEM encoded. |
wildcard.private_key | The private key for the wildcard.certificate . The private key MUST be in PKCS#1 format and PEM encoded. The private key MUST NOT be encrypted. |
wildcard.ca | The ordered certificate chain for the wildcard.certificate . The individual X.509 certificates MUST be in PKCS#1 format and PEM encoded. The first certificate MUST be the CA certificate that signed the certificate in wildcard.certificate . The last certificate MUST be the root CA certificate. The certificate chain can also only consist of the root CA. |
wildcard:
certificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
private_key: |
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
ca: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
...
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
Common Name And Subject Alternative Name
The wildcard certificate MUST meet the following requirements as it is used to verify all internal communication between the cluster nodes. Furthermore, as the service instance hostnames are propagated to the applications via the service bindings, they provide a way to verify the server they are connecting to.
- The Common Name (CN) of the wildcard certificate MUST be set to
*.node.dc1.<iaas.consul.domain>
. - The Subject Alternative Name (SAN) of the wildcard certificate MUST contain the DNS name entries
*.node.dc1.<iaas.consul.domain>
and*.service.dc1.<iaas.consul.domain>
.
All a9s Data Services with a vendored dashboard MUST contain an additional SAN entry to enable them correctly.
This affects the following a9s Data Services:
- a9s Messaging
*.<dashboard_hostname>.<iaas.cf.system_domain>
- a9s LogMe2
<dashboard_hostname>.<iaas.cf.system_domain>
Only the a9s Messaging dashboard needs a leading *
, because the url will contain the id of the service instance.
The <dashboard_hostname>
property will be the name of the a9s Data Service deployment, like rabbitmq-service
. And the
<iaas.cf.system_domain>
property can be found in the infrastructure configuration file, where it is set for the
whole environment.
Rotation
In the case of a wildcard certificate, it may be necessary to rotate either only the wildcard certificate itself or the CA of the wildcard certificate as well. Depending on the use case, further steps are required. These are explained in the following sections.
Certificate Rotation
The procedure below rotates only the wildcard certificate across all Service Instances and keeps the CA. It can be only used when the wildcard certificate is still valid.
Always rotate the wildcard certificate before it expires, as rotating an expired wildcard certificate will lead to a failure and your a9s Data Service will be in a broken state.
When the wildcard certificate is still valid this should cause, from the application's point of view, for non-single Service Instances no downtime, or if any it will be negligible.
The new wildcard certificate MUST be signed by the same CA as the current wildcard certificate.
Step 1: Update the wildcard certificate
Set the certificate
and private
options of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard
to
the new wildcard certificate to use and the corresponding private key.
credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert-new.pem -p ~/certs/cert-key-new.pem -r ~/certs/chain.pem
To apply the new wildcard certificate, the corresponding a9s Data Service MUST be redeployed.
bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-wildcard-certificate.yml
Step 2: Redeploy each service instance
There are two options to update the wildcard certificate of the corresponding Service Instances of an a9s Data Service:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- The Platform Operator can update all Service Instances using the a9s Deployment Updater of the corresponding a9s Data
Service. For this, the
strategy.update.instance_type
property of the a9s Deployment Updater MUST be set toprovisioned
.
CA Rotation
The procedure below rotates the CA and the related wildcard certificate across all Service Instances. It can be only used when the CA and the wildcard certificate is still valid.
Always rotate the CA and the related wildcard certificate before they expire, as rotating an expired CA or the related wildcard certificate will lead to a failure and your a9s Data Service will be in a broken state.
When the certificates are still valid this should cause, from the application's point of view, for non-single service instances no downtime, or if any it will be negligible.
Step 1: Append the new CA to the old CA
Concatenate the old and the new CA (first old CA, then new CA) and set it as the root
option of the CredHub variable
/a9s_<data_service_name>_service_spi_wildcard
. This allows the service instance's nodes and the clients to trust the
wildcard certificate presented by the service instance that can be either signed by the new or the old CA.
cat ~/certs/chain-old.pem ~/certs/chain-new.pem > ~/certs/chain.pem
credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert-old.pem -p ~/certs/cert-key-old.pem -r ~/certs/chain.pem
To apply the old and the new CA, the corresponding a9s Data Service MUST be redeployed.
bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-wildcard-certificate.yml
Step 2: Roll out both, the old and the new CA, to each service instance
There are two options to update the CA of the corresponding Service Instances of an a9s Data Service:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- The Platform Operator can update all Service Instances using the a9s Deployment Updater of the corresponding a9s Data
Service. For this, the
strategy.update.instance_type
property of the a9s Deployment Updater MUST be set toprovisioned
.
Before continuing with the next step, all service bindings MUST be renewed to propagate the new CA to the clients, unless the new CA is already trusted by the client's runtime.
Step 3: Replace the wildcard certificate
Set the certificate
and private
options of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard
to
the new wildcard certificate that is signed by the new CA to use and the corresponding private key.
cat ~/certs/chain-new.pem ~/certs/chain-old.pem > ~/certs/chain.pem
credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert-new.pem -p ~/certs/cert-key-new.pem -r ~/certs/chain.pem
To apply the new wildcard certificate, the corresponding a9s Data Service MUST be redeployed.
bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-wildcard-certificate.yml
Step 4: Roll out the new wildcard certificate to each service instance
There are two options to update the wildcard certificate of the corresponding Service Instances of an a9s Data Service:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- The Platform Operator can update all Service Instances using the a9s Deployment Updater of the corresponding a9s Data
Service. For this, the
strategy.update.instance_type
property of the a9s Deployment Updater MUST be set toprovisioned
.
Step 5: Remove the old CA
Set the root
option of the CredHub variable /a9s_<data_service_name>_service_spi_wildcard
to only contain the new
CA. The old CA is no longer needed since all existing Service Instances are only using the new wildcard certificate that
is signed by the new CA.
credhub set -n /a9s_${data_service}_spi_wildcard -t certificate -c ~/certs/cert-new.pem -p ~/certs/cert-key-new.pem -r ~/certs/chain-new.pem
To apply only the new CA, the corresponding a9s Data Service MUST be redeployed.
bosh -d ${data_service} deploy ${data_service}/${data_service}.yml -l config/iaas-config.yml -l config/${data_service}.yml -o ${data_service}/ops/use-wildcard-certificate.yml
Step 6: Roll out only the new CA to each service instance
There are two options to update the CA of the corresponding Service Instances of an a9s Data Service:
- An individual service instance is automatically updated when the Application Developer updates their service
instance, for example, via a
cf update-service
- The Platform Operator can update all Service Instances using the a9s Deployment Updater of the corresponding a9s Data
Service. For this, the
strategy.update.instance_type
property of the a9s Deployment Updater MUST be set toprovisioned
.
To continue using your Service Instances, all service bindings SHOULD be renewed to clean up the old CA from the clients.