Rotate the credential encryption key

If your encryption key is compromised, or your security policy requires you to rotate encryption keys periodically, use the key rotation command to re-encrypt all stored credentials with a new key.

Before you begin

The automation orchestrator backend is stopped. The rotation command runs offline to prevent concurrent access during re-encryption.
You have generated a new 64-character hexadecimal encryption key:
```
$ openssl rand -hex 32
```

Procedure

Run the key rotation command from within the backend pod:

$ oc exec -n automation-orchestrator deploy/my-orchestrator-backend -- \
    python -m syntara.credentials.cli rotate-keys \
    --old-key current-64-char-hex-key \
    --new-key new-64-char-hex-key

Alternatively, set the keys as environment variables inside the pod:

$ oc exec -n automation-orchestrator deploy/my-orchestrator-backend -- \
    bash -c 'APP_OLD_ENCRYPTION_KEY=current-64-char-hex-key \
    APP_NEW_ENCRYPTION_KEY=new-64-char-hex-key \
    python -m syntara.credentials.cli rotate-keys'

Verify that the command exits with code 0 (success).

If the command exits with a non-zero code, see the exit code table below before proceeding.
Update the encryption key Secret referenced by spec.secrets.secretEncryptionKeySecretRef in the custom resource with the new key value. If you are using an auto-generated secret, update the Secret named {cr-name}-secret-encryption-key in the deployment namespace.
Verify that the pods restart successfully.

The automation orchestrator operator detects the Secret change and triggers a rolling restart of the affected pods automatically.

Results

Exit codes:

Table 1. Exit codes
Exit code	Meaning
0	All credentials were re-encrypted successfully.
1	Partial failure. Some credentials could not be re-encrypted. Review the output and re-run the command after resolving the issue.
2	Fatal error. No credentials were modified. Typically indicates an invalid key format or a database connection failure.

If the rotation is interrupted, you can safely re-run the command with the same old and new keys. The rotation command skips credentials that were already re-encrypted.

Options:

Table 2. Options
Option	Description
`--dry-run`	Verify that all credentials can be decrypted and re-encrypted without writing changes to the database.
`--batch-size`	Number of credential rows to process per database commit (default: 50).