Skip to content
Support Downloads Contact Us Sign In

Writing a Pipeline to Rotate the Foundation Certificate Authority

This how-to-guide shows you how to write a pipeline for rotating the certificate authority on an existing Ops Manager.

Prerequisites

  1. A pipeline, such as one created in Installing Ops Manager or Upgrading an Existing Ops Manager.
  2. A fully configured Ops Manager and Director.
  3. The Platform Automation Toolkit Docker Image imported and ready to run.

Creating the Pipeline

We will be creating a new pipeline for this workflow. It will ultimately rotate the certificate authority for a single foundation via a series of jobs, but it will start with some resources. Create a file titled ca-rotation.yml with this content: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
---
resource_types:
- name: pivnet
  type: docker-image
  source:
    repository: pivotalcf/pivnet-resource
    tag: latest-final
resources:
- name: platform-automation
  type: pivnet
  source:
    product_slug: platform-automation
    api_token: ((pivnet-refresh-token))
- name: config
  type: git
  source:
    uri: ((pipeline-repo))
    private_key: ((plat-auto-pipes-deploy-key.private_key))
    branch: main

This will give us access to the Platform Automation tasks and the environment configuration file.

We will also set this new pipeline. 

1
fly -t control-plane set-pipeline -p foundation -c ca-rotation.yml

Generating a Root Certificate Authority

There are two methods to configure a new root certificate authority in Ops Manager:

  1. Use Ops Manager to generate a new certificate authority.
  2. Give Ops Manager an existing root certificate authority to use.

Use with pivotal-container-service tile

Rotating certificate authority with the pivotal-container-service tile installed will cause warnings in the pipeline. Only certificates managed by Ops Manager will be rotated in this process!

Regardless of method, we are going to add our first job to the pipeline. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
jobs:
- name: configure-new-ca
  plan:
  - get: env
    resource: config
  - get: platform-automation-image
    resource: platform-automation
    params:
      globs: ["*image*.tgz"]
      unpack: true
  - get: platform-automation-tasks
    resource: platform-automation
    params:
      globs: ["*tasks*.zip"]
      unpack: true
  - task: configure-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/configure-new-certificate-authority.yml

Generate a New Certificate Authority

If we want a certificate authority generated by Ops Manager, the above job will create it for us.

Configure Ops Manager to Use an Existing Certificate Authority

If we want to provide a certificate authority to the Ops Manager to use (e.g. an externally signed certificate), we can provide that to the Ops Manager with an input resource and additional configuration of the task.

We'll add an S3 resource and the configuration repo to the resources section: 

1
2
3
4
5
6
7
8
resources:
- name: certificate-authority
  type: s3
  source:
    access_key_id: ((s3-access-key-id))
    secret_access_key: ((s3-secret-key))
    bucket: ((certificate-authority-bucket))
    regexp: (certificate|privatekey)\.pem
Also, we will fetch the resource before the task. This will configure the task to use the certificate.pem and privatekey.pem files from the s3 resource as the new CA in Ops Manager. 
1
2
3
4
5
6
7
  - get: certs
    resource: certificate-authority
  - get: env
    resource: config
  - task: configure-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/configure-new-certificate-authority.yml

Apply Changes

After configuring a new certificate authority, Ops Manager needs to apply changes before the new CA is available to generate and sign certificates. This also registers the CA with components so that they will trust certificates from the new CA. This next job will be appended after the configure-new-ca job. 

1
2
3
4
5
6
7
8
9
- name: apply-changes
  plan:
  - get: env
    resource: config
    passed:
    - configure-new-ca
  - task: apply-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/apply-changes.yml

Activate the New Certificate Authority

We need to set our new certificate authority as the active certificate authority. After this, any certificates created by the Credhub will be signed by the new CA. Append a new job to the end of the jobs list. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
- name: activate-new-ca
  plan:
  - get: env
    resource: config
    passed:
    - apply-changes
  - get: platform-automation-image
    resource: platform-automation
    params:
      globs: ["*image*.tgz"]
      unpack: true
  - get: platform-automation-tasks
    resource: platform-automation
    params:
      globs: ["*tasks*.zip"]
      unpack: true
  - task: activate-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/activate-certificate-authority.yml

Regenerate Certificates

Non-configurable Leaf Certificates

Now that a new certificate authority is active, any internal, non-configurable certificates need to be regenerated and signed by the new CA. We are going to add another job that will regenerate the non configurable leaf certificates. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
- name: regenerate-non-configurable-leaf-certificates
  plan:
  - get: env
    resource: config
    passed:
    - activate-new-ca
  - get: platform-automation-image
    resource: platform-automation
    params:
      globs: ["*image*.tgz"]
      unpack: true
  - get: platform-automation-tasks
    resource: platform-automation
    params:
      globs: ["*tasks*.zip"]
      unpack: true
  - task: regenerate-certificates
    image: platform-automation-image
    file: platform-automation-tasks/tasks/regenerate-certificates.yml
This will delete the existing certificates from Credhub, which causes Credhub to generate new certificates on the next run of Apply Changes.

Configurable Certificates

Any manually configured certificates that are signed by the foundation root certificate authority need to be regenerated as well. Tanzu Application Service needs at least two configurable certificates, one for networking components and one for UAA. After generating a new certificate, it needs to be configured in Ops Manager with a manifest file specific to the certificate.

Please check the docs on how to rotate CAs and leaf certificates to manually rotate.

Apply Changes

Now we need to apply changes in order to create and use the new certificates. 

1
2
3
4
5
6
7
8
9
- name: apply-certificate-changes
  plan:
  - get: env
    resource: config
    passed:
    - regenerate-non-configurable-leaf-certificates
  - task: apply-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/apply-changes.yml

Cleaning Up

Once the function of the foundation is validated with new certificates, the old certificate authority can be deleted by adding a job that will cleanup the certificate authority and applying the changes. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
- name: cleanup-certificate-authorities
  plan:
  - get: env
    resource: config
    passed:
    - apply-certificate-changes
  - get: platform-automation-image
    resource: platform-automation
    params:
      globs: ["*image*.tgz"]
      unpack: true
  - get: platform-automation-tasks
    resource: platform-automation
    params:
      globs: ["*tasks*.zip"]
      unpack: true
  - task: delete-certificate-authority
    image: platform-automation-image
    file: platform-automation-tasks/tasks/delete-certificate-authority.yml
  - task: apply-new-ca
    image: platform-automation-image
    file: platform-automation-tasks/tasks/apply-changes.yml


1
[activate-certificate-authority]: ../tasks.md#activate-certificate-authority