Certificate Rotation

This page describes the rotation of certificates for the standalone components, such as the a9s Backup Manager or the a9s SPIs, as well as the components that are colocated on a Service Instance like the a9s Backup Agent.

It may be necessary to rotate either only the leaf certificates themselves or the CA certificate as well. Depending on the use case, further steps are required. These are explained in the following sections.

Leaf Certificate Rotation

Service Instance's Colocated Components

The leaf certificates of components that are colocated on an individual Service Instance can be rotated by using the custom parameter force_certificate_rotation:

cf update-service <service_instance_name> -c '{"force_certificate_rotation": true}'

Standalone Components

To rotate a leaf certificate of a standalone component, CredHub must be used to regenerate the related certificate:

credhub regenerate -n '<path-to-certificate>'

And apply the new leaf certificate with bosh deploy:

bosh -d <deployment-name> deploy (...)

CA Certificate Rotation

For the CA certificates rotation, the rotation steps provided by CredHub are used. For more information, see CredHub CA Rotation documentation.

To simplify the interaction with the CredHub server, you can use the bin/rotate_ca_certificate.rb script inside anynines-deployment. Execute the following command to see the help output for the script:

./rotate_ca_certificate.rb -h

Prerequisites

1. CredHub MUST have the credhub.certificates.concatenate_cas configuration set to true.
2. Ensure you're targeting and logged-in to the proper CredHub server with your local CredHub client.

danger

Always rotate the CA and the related certificate(s) before they expire, as rotating an expired CA, or related certificate, will lead to a failure and your a9s Data Service will be in a broken state.

This means that every step described in this section must take place, in order to ensure that such failure does not occur.

Step 1: Regenerate the Root CA

Execute the bin/rotate_ca_certificate.rb script and specify step 1:

./rotate_ca_certificate.rb --step 1

After this step, the old CA and the new CA have been concatenated.

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. The a9s Template Uploader errand of the corresponding a9s Data Service must be executed to update all templates with the concatenated CAs.
3. Colocated components must be updated 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 to provisioned.

Step 2: Regenerate Leaf Certificates with the New CA Certificate

Execute the bin/rotate_ca_certificate.rb script and specify step 2:

./rotate_ca_certificate.rb --step 2

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. The a9s Template Uploader errand of the corresponding a9s Data Service must be executed to update all templates with the regenerated leaf certificates.
3. Colocated components must be updated 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 to provisioned.

Step 3: Remove the Old CA Certificate

Execute the bin/rotate_ca_certificate.rb script and specify step 3:

./rotate_ca_certificate.rb --step 3

They must now be applied as follows:

1. Standalone components must be updated with bosh deploy.
2. The a9s Template Uploader errand of the corresponding a9s Data Service must be executed to update all templates with the new CA only.
3. Colocated components must be updated 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 to provisioned.

After that, the old CA certificate should have been removed, and there should only be the new CA certificate and the new leaf certificates signed by the new CA.