Overview

Cloud Foundry has recently improved support for secure inter-process communications, which has been reflected in the cf-deployment release. This change in v1.8.0 is to better approximate the certificate tree with regards to the CA used to sign each certificate, as well as CN and SANs used. This version also contains future-looking configuration to support extended key usage that is supported but not validated currently in Cloud Foundry.

Impact

The impact of this feature is minimal to the runtime and stability of your Cloud Foundry deployment. It requires rotating the certificates and associated CA certificates. Genesis provides the tooling to do this.

There is no downtime incurred by applying this feature.

The Process

You will need to be using Genesis v2.7.7 or later. If you are still using an earlier version, please use GMP-CF-0003, or better yet, first upgrade to the latest version of Genesis first, then perform the following:

1. Ensure you're at least upgraded to v1.7.2 -- while it is possible to upgrade directy from earlier versions, the 1.7.x series have their own migration processes, and doing too many things at once is a recipe for disaster.

2. Update your environment file to the desired version of the kit. These changes originated in v1.8.0, but further changes also happened in v1.9.x. We would recommend targetting the latest v1.10.x at this time. Just set the kit.version in your environment yaml.

3. Update your certificates. Genesis v2.7.7 makes this easy. Just run:

   genesis rotate-secrets <env> -I

   This will rotate all the secrets that are invalid, while leaving secrets that don't need to change alone. For further peace of mind, you can use a -i option to run it interactively, or for the ultra-precautious, first take a backup of your vault using: safe export <path/for/env/secrets/ > my-secrets.json

4. Verify your secrets are all now valid using genesis check-secrets <env>.

5. Deploy (manually*)

   * Because there are steps that have to be taken between updating the environment file and deploying the environment, it is not recommended that this process be done via the pipelines. However it is possible as long as you regenerate the impacted secrets beforehand, and then push the version bump as a common value in your ancestral yml file so it can propagate through the pipeline. In this case, do not commit your version bumps in each of your environment files.

Help & Support

If you have concerns about the impact of this migration process, or need assistance running through it, please don't hesitate to find us in #help on Slack.