Changing the database encryption key

Replace the value of the secret that is used for encrypting database fields in the management subsystem.

Before you begin

Take a backup of your existing management database encryption key. If you need to restore a management database backup, you must have the encryption key that was in use at the time the database backup was created.

To take backup of your encryption key:

Identify the name of the management database encryption secret:
```
kubectl get mgmt <mangement CR name> -o=jsonpath='{.status.encryptionSecret}'
```
where <mangement CR name> can be determined by running:
```
kubectl get mgmt
```

Copy the secret to a YAML file:

kubectl get secret <management enc secret> -o yaml > management_enc_key_backup_<date>.yaml

The key is backed up to the file management_enc_key_backup_<date>.yaml. Set <date> to the current date, for example management_enc_key_backup_20240101.yaml, so that you can identify when this backup was taken.

Keep your backed up encryption secret with your management infrastructure configuration backup: Taking a management infrastructure configuration backup. If you want to restore a database backup that was taken when a previous encryption key was in use, then see restore backup.

About this task

This update does not require an outage; however some operations might take longer than usual due to database locking.

Procedure

Create a file called rotate_mgmt_enc_secret.yaml, and paste in the following contents:
```
apiVersion: management.apiconnect.ibm.com/v1beta1
kind: ManagementSecretRotation
metadata:
  name: rotate-secret
spec:
  managementCluster: <mangement CR name>
  rotateEncryptionSecret:
    rotate: true
```
Note: If your deployment was originally installed at V2018.4.1, then the database encryption key is called managementUpgradeName-encryption-secret.
Run the following command to apply the rotate-secret CR:
```
kubectl create -f rotate_mgmt_enc_secret.yaml
```
The update can take a few minutes. You can monitor the progress with:
```
kubectl get managementsecretrotation
```
The update is complete when the status shows Completed:
```
NAME            READY   STATUS      AGE
rotate-secret   1/1     Completed   13m
```
If you installed API Connect on VMware and if you want to update the management encryption secret on VMware, then you can now use the apicup command to rotate the encryption secret without needing to open a support case. For a standalone installation, run the following command:
```
apicup subsys rotate-secrets <stack-name> --rotate-encryption-secret
```
For 2DC setup, run the following command:
```
apicup subsys rotate-secrets <active-stack-name> --rotate-encryption-secret
```

What to do next

If you need to restore a management database backup that was taken before you updated the encryption key, then you must restore your previous encryption key from your backup.

Edit your secret backup file: management_enc_key_backup_<date>.yaml and change metadata.name to a unique name for your backup secret. Delete all other metadata contents. Your updated YAML file should look like this:

apiVersion: v1
data:
  encryption_secret.bin: If7HlVzZeAgrYrwvcEhv1Ub0LVXNQsN0mGISy1GvYXKA4d1tSWLB80hB89sn+VvN0/vAVTU90AP6jPOsi5LpOaddfoqT85ugvjEwHLnEtSI6CbEr05NtMUwJGAr5/KWfjj6mwCn+EMp4VBsEDppU54yvycyb7iBLRtGyrPktTaw=
kind: Secret
metadata:
  name: backup_mgmt_encryption_secret
type: Opaque

Restore the encryption secret from your updated backup file:
```
kubectl create -f management_enc_key_backup_<date>.yaml
```

Verify that the backup secret was created:

kubectl get secrets

You should see your restored backup secret in the output:


NAME                                TYPE            DATA   AGE
...
backup_mgmt_encryption_secret       Opaque          3      10s
...

In your mgmtrestore_cr.yaml file, add the property spec.mgmtEncKeyName and set it to your newly created backup secret name:
```
apiVersion: management.apiconnect.ibm.com/v1beta1
kind: ManagementRestore
metadata:
  generateName: management- # this the prefix for the name of the restore CR that is created
spec:
  backupName: <backup CR name>
  subsystemName: <management CR name>   
  mgmtEncKeyName: backup_mgmt_encryption_secret
```
The encryption key that is contained in backup_mgmt_encryption_secret is copied to your active encryption secret. After you restore the backup, you might want to update the encryption key again (for the same reason that you previously updated the secret).

For more information about management database backup restore, see Restoring from a management database backup.

If you have a two data center disaster recovery deployment, you must copy the updated encryption secret to your warm-standby data center. Follow these steps:

Extract the management database encryption secret from the active data center:

kubectl get secret <mgmt encryption secret> --template='{{ index .data "encryption_secret.bin" }}' > mgmt-enc-secret.txt

Verify that the mgmt-enc-secret.txt file contains your secret:

cat mgmt-enc-secret.txt

Expected output should be a long string, for example:

YSXft4YoApS+UJHpaXjdu8OUovFGhLT9YsBaWeRCI5sUigPdchY/cq18Z5UKaW5afZDXxQDWUcY6tx9xTXVGzEm9oZCDV1hmq4mu7qM015rBjZIJ7FPrA3gNgxflxim9SORSybnhW2JT6S41ZH9QJwfUtIUUpe981h8sraSEtOQ=

In your warm-standby data center, identify the name of the management database encryption secret:
```
kubectl get mgmt <mangement CR name> -o=jsonpath='{.status.encryptionSecret}'
```

Update the warm-standby secret with the secret from the active that you obtained in step 1:

kubectl patch secret <warm-standby enc secret name> -p "{\"data\": {\"encryption_secret.bin\":\"$(<mgmt-enc-secret.txt)\"}}"