Migrating Classic Block Storage from HPCS to Key Protect

Migrate your Hyper Protect Crypto Services (HPCS) encryption for Classic Block Storage volumes to use IBM Key Protect (Key Protect) instead.

Before you begin

Before you begin, follow these steps to determine if you need to migrate your Classic Block Storage volumes to use Key Protect instead of HPCS.

Verify that HPCS encryption is being used by the block storage plugin on your cluster.
1. List all kms-config secrets in your cluster.
```
kubectl get secrets -A --field-selector type=ibm.io/kms-config
```
2. For each kms-config secret found, verify that it is of type hpcs by checking if the configuration contains hs-crypto.
```
kubectl get secret <kms-config-name> -n <namespace> -o json | jq '.data | map_values(@base64d)' | grep "hs-crypto"
```
3. For each HPCS configuration found, identify the PVCs that use them.
```
kubectl get pvc -A -l "encryptionKeySecret=<kms-config-name>"
```
If no HPCS-encrypted PVCs are found, no migration is required. If HPCS-encrypted PVCs are found, proceed with the migration steps.

Prerequisites for migration

Complete these steps before you begin the migration.

Back up all cluster resources before starting the migration process.

Plan to keep your resource backups for several weeks in case a rollback is required.

kubectl get pvc --all-namespaces -o yaml > all-pvcs.yaml
kubectl get pv -o yaml > all-pv.yaml
kubectl get storageclass -o yaml > all-storage-classes.yaml
kubectl get secrets --field-selector type=ibm.io/kms-config --all-namespaces -o yaml > all-kms-config.yaml
kubectl get secrets -n ibm-block-secrets --field-selector type=ibm.io/dek-secret -o yaml > all-dek-secrets.yaml

Create a new or use an existing IBM Key Protect instance.
Create a root key in your Key Protect instance. Note the root key ID for use in the migration steps.
Ensure you have the necessary IAM permissions to access both the HPCS and Key Protect instances.
Install the Key Protect CLI plug-in if not already installed.
```
ibmcloud plugin install kp -r "IBM Cloud"
```

Migration steps

Follow these steps to migrate your Classic Block Storage volumes from HPCS to Key Protect.

Step 1: Replace the HPCS secret with a Key Protect configuration

Create a new KMS configuration file for your Key Protect instance. Save the following file as target-kp-config.yaml. Make sure to replace the placeholder values with your Key Protect instance details.
```
apiVersion: v1
kind: Secret
metadata:
  name: <kms-config-name>
  namespace: <namespace>
stringData:
  config: |-
    {
      "api_key":"<your-api-key>",
      "iam_endpoint":"https://iam.cloud.ibm.com",
      "key_protect_endpoint":"https://<region>.api.<region>.kms.appdomain.cloud",
      "instance_id":"<kp-instance-id>",
      "root_key_id":"<kp-root-key-id>"
    }
type: ibm.io/kms-config
```
Values
- <kms-config-name>: The name of your existing HPCS KMS configuration secret.
- <namespace>: The namespace where the secret is located.
- <your-api-key>: An API key with access to your Key Protect instance.
- <region>: The region where your Key Protect instance is located.
- <kp-instance-id>: Your Key Protect instance ID.
- <kp-root-key-id>: The root key ID you created in Key Protect.

Delete the existing HPCS KMS configuration secret.

kubectl delete secret <kms-config-name> -n <namespace>

Create the new Key Protect configuration secret.
```
kubectl create -f target-kp-config.yaml
```

Step 2: Update PVC encryption keys to use Key Protect

For each encrypted PVC that needs to be migrated, follow these steps to unwrap the data encryption key (DEK) from HPCS and rewrap it with Key Protect.

Configure the Key Protect CLI to point to your HPCS instance.

export KP_PRIVATE_ADDR=https://<hpcs-instance-id>.api.<region>.hs-crypto.appdomain.cloud
export KP_INSTANCE_ID=<hpcs-instance-id>
export ROOT_KEY_ID=<hpcs-root-key-id>

Retrieve the HPCS wrapped DEK (WDEK) for the encrypted PVC.

Find the DEK secret for your PVC.

kubectl get secrets -n ibm-block-secrets --field-selector type=ibm.io/dek-secret | grep <pv-name>

Extract the wrapped DEK from the secret.

kubectl get secrets -n ibm-block-secrets <pv-secret-name> -o yaml | grep wrappedDEK | awk '{print $2}' | base64 --decode

Unwrap the wrapped DEK using the HPCS root key. Save the unwrapped DEK from the output.
```
ibmcloud kp key unwrap $ROOT_KEY_ID <wrapped-dek>
```
Configure the Key Protect CLI to point to your Key Protect instance.

Use a separate terminal window to avoid accidentally switching between HPCS and Key Protect configurations.
```
export KP_PRIVATE_ADDR=https://<kp-instance-id>.api.<region>.kms.appdomain.cloud
export KP_INSTANCE_ID=<kp-instance-id>
export ROOT_KEY_ID=<kp-root-key-id>
```
Rewrap the DEK using the Key Protect root key. Save the wrapped DEK from the output.
```
ibmcloud kp key wrap $ROOT_KEY_ID -p <unwrapped-dek-base64>
```
Replace the HPCS wrapped DEK with the Key Protect wrapped DEK in the PVC secret.
1. Encode the new wrapped DEK to base64.
```
echo <kp-wrapped-dek> | base64
```
2. Edit the DEK secret and replace the wrappedDEK value with the new base64-encoded Key Protect wrapped DEK.
```
kubectl edit secret -n ibm-block-secrets <pv-secret-name>
```
Optional: Verify the volume by restarting the pod that uses the encrypted PVC.
```
kubectl delete pod <pod-name> -n <namespace>
```
Repeat these steps for all encrypted PVCs that need to be migrated from HPCS to Key Protect.
Check that all pods using encrypted PVCs are in a running state.
```
kubectl get pods -A
```

Next steps

Update your documentation and runbooks to reflect the new Key Protect configuration.
Consider setting up key rotation policies for your Key Protect root keys.
If you encounter any issues during or after the migration, open an IBM Cloud support ticket.