optional_crypto_secret_rotation.md

(Optional) Crypto Secret Rotation

This page describes how to rotate the crypto secret of an already-deployed Seqera Platform instance via the cx-field-tools-installer project.

NOTE: This activity is not required for first-time deployments.

Steps

1. Mandatory Before Anything Else

   1. Go read the official Seqera documentation about this feature (TODO: Add link)
   2. Backup your existing database before implementing any change.
   3. If you have pre-existing database backups, capture the existing crypto secret and ensure you have a way to associate it with the relevant backups.
   4. Initiate an outage via docker compose down.

2. Prepare Keys in SSM

   1. In the omnibus file:

      1. In line with all the other keys, add an entry that holds the previous key value (i.e. the value currently defined in the TOWER_CRYPTO_SECRET block):

         "TOWER_CRYPTO_PREVIOUS_SECRET": {
             "ssm_key": "/config/<REPLACE_ME_WITH_YOUR_APP_NAME>/tower/secret-rotation/previous-key",
             "value": "<POPULATE_WITH_CURRENT_VALUE_OF_SSM_KEY: /config/tower-template/tower/crypto/secretKey>"
         },

      2. In line with all the other keys, add an entry activating the key rotation:

         "TOWER_CRYPTO_ROTATE_KEYS": {
             "ssm_key": "/config/<YOUR_APP_NAME>/tower/secret-rotation/enabled",
             "value": "true"
         },

      3. In line with all the other keys, add an entry specifying how many :

         "TOWER_CRYPTO_ROTATE_CHUNK_SIZE": {
             "ssm_key": "/config/<YOUR_APP_NAME>/tower/secret-rotation/chunk-size",
             "value": "50",
             "description": "The number of records to extract in chunks until all secrets and credentials are processed. Only applied if key rotation is enabled."
         },

      4. Double-check that you updated <YOUR_APP_NAME> to your own installation's name.

      5. Update TOWER_CRYPTO_SECRET entry's value to new desired key.

   2. Delete the standalone SSM crypto secret key:

      1. Delete /config/<YOUR_APP_NAME>/tower/crypto/secretKey

         This ensures the key will be recreated with the new value.

3. Initiate Key Rotation

   1. Start the Seqera Platform instance.
   2. Verify key rotation activity. TODO: Figure out how to determine this.
   3. Wait for cron container to complete all necessary rotation activities. TODO: Figure out how to determine this.

4. (Optional) Delete Rotation Keys

   1. Key rotation Initiate an outage via docker compose down.

   2. In the omnibus file:

      1. Delete entry TOWER_CRYPTO_PREVIOUS_SECRET.
      2. Delete entry TOWER_CRYPTO_ROTATE_KEYS.
      3. Delete entry TOWER_CRYPTO_ROTATE_CHUNK_SIZE.

   3. Delete standalone SSM keys:

      1. Delete SSM key /config/<YOUR_APP_NAME>/tower/secret-rotation/secretKey.
      2. Delete SSM key /config/<YOUR_APP_NAME>/tower/secret-rotation/enabled.
      3. Delete SSM key /config/<YOUR_APP_NAME>/tower/secret-rotation/chunk-size.

5. Restart Seqera Platform

   1. Restart Seqera Platform via docker compose up -d.

      With the key-rotation keys no longer available, rotation activities are completely ceased.