IBM Cloud Docs
Migrating from Hyper Protect Crypto Services to Key Protect for COS

Migrating from Hyper Protect Crypto Services to Key Protect for COS

Migrate your Hyper Protect Crypto Services (HPCS) encryption for the IBM Cloud Object Storage s3fs plugin to use Key Protect (KP) instead.

Before you begin

Before you begin, follow these steps to determine if you need to migrate your COS plugin to use Key Protect instead of HPCS.

  1. Get the CRN of your HPCS and KP instances. Run the following command for each instance.

    ibmcloud resource service-instance <instance-name>

    Example output.

    Name:  my-hpcs-instance
ID:    crn:v1:bluemix:public:kms:us-south:a/1ab234cd5e678fgh9a0123bc4de567:f89gh01a-bcd2-3456-e789-f0g1234h5ab6::

  2. List all secrets in your cluster that are the ibm/ibmc-s3fs type.

    kubectl get secrets --field-selector type=ibm/ibmc-s3fs

  3. For each ibm/ibmc-s3fs secret, review the secret contents and find the kp-root-key-crn root key in the data section. Note any secret with a kp-root-key-crn value that includes the string hs-crypto, which indicates that it is an HPCS root key and must be migrated. Save this list of secrets to migrate. If there are no kp-root-key-crn values that contain hs-crypto, then you do not need to follow the migration steps.

Prerequisites for migration

Complete these steps before you begin.

  1. If you have a COS helm chart installed on your cluster, ensure that it runs the latest version.
  2. If you do not already have one, make a new Key Protect instance and a new set of Key Protect keys for encryption. Make sure your Key Protect instance is created in the same region as your cluster. This is required for the Key Protect instance to access your COS resources.
  3. Create a service-to-service authorization for Key Protect to access your COS resources. Set the source service as Key Protect and the target service as COS, and set the access level to at least Reader.

Migration steps

Follow these steps to migrate your COS plugin to Key Protect.

If all of your COS secrets and PVCs are in a specific namespace, you can scope the following steps to that namespace. Otherwise, search through all namesapces on your cluster.

Step 1. List PVCs to migrate

Determine which PVCs must be migrated.

  1. List all PVCs on your cluster or in the relevant namespace.
    oc get pvc [-n <namespace>]
  2. Describe each PVC.
    oc describe pvc <pvc-name>
  3. In the PVC output, find the Annotations section and check if the volume.kubernetes.io/storage-provisioner: ibm.io/ibmc-s3fs is listed.
  4. If the annotation is listed, look for the ibm.io/secret-name annotation.
  5. If the volume.kubernetes.io/storage-provisioner: ibm.io/ibmc-s3fs annotation is listed and the ibm.io/secret-name value matches any of the secrets you found to have an HPCS root key, the PVC must be migrated. Note the PVC name.
  6. Repeat these steps for each PVC. Save the list of PVCs to migrate.

Step 2. List pods to migrate

Determine which pods must be migrated.

  1. List all pods on your cluster or in the relevant namespace.
    oc get pods [-n <namespace>]
  2. Describe each pod.
    oc describe pod <pod-name>
  3. In the output, find the Volumes section and check the name of each PersistentVolumeClaim. If any of the PVCs in the output are also included in the list of PVCs to migrate, then the pod must be migrated. Note the name of the pod.
  4. Repeat these steps for each pod. Save the list of pods to migrate.

Step 3. Create new secrets

Create new secrets that use the Key Protect root key instead of the HPCS root key.

  1. Get the CRN of your Key Protect instance and encode it to base64.

    ibmcloud resource service-instance <kp-instance-name>

    echo  -n "<root_key_CRN>" | base64

  2. For each secret that you must migrate, get the secret yaml.

    oc get secret <secret-name> -o yaml

  3. Copy the yaml into a file to create a new secret. Change the kp-root-key-crn to instead point to the base64 encoded CRN of the Key Protect instance. Append a string to the end of the secret name to help differentiate the new secret from the old one.

    When you recreate your PVCs, you must specify the new copy of the secret used by the PVC. Make sure the name of the new secret corresponds to the old secret, but still allows you to differentiate between the two.

  4. Apply the secret.

    kubectl apply -f <secret-file-name>

  5. Repeat these steps for each secret that needs to be migrated.

Step 4. Recreate PVCs

Recreate your PVCs so they point to the new secrets.

  1. For each PVC that you must migrate, get the PVC yaml.

    oc get PVC <pvc-name> -o yaml

  2. Copy the yaml into a file to create a new PVC. Change the ibm.io/secret-name and ibm.io/secret-namespace annotations to point to the new secret that corresponds to the secret previously listed. Append a string to the end of the PVC name to help differentiate it from the old PVC.

  3. Apply the new PVC.

    oc apply -f <pvc-file-name>

  4. Get the details of the PVC and verify that it is in the Bound state.

    oc get PVC <pvc>

  5. Repeat these steps for each PVC that needs to be migrated.

Step 5. Update pods

Update the pods so they point to the new PVCs.

  1. Determine the type of resource that was used. In the output, find the ownerReferences section and note the kind of resource and the name of the resource listed.
    oc describe pod <pod-name>
  2. Follow the update strategies based on the resource listed in the ownerReferences section.

Manually recreating the pod

  1. Get the pod yaml.

    oc describe <resource-type> <resource-name> -o yaml

  2. Copy the yaml into a file to create a new pod. In the volumes section of the yaml, change the PersistentVolumeClaim to point to the new PVC that corresponds to the PVC previously listed. Append a string to the end of the new resource name to help differentiate it from the old resource.

  3. Apply the new yaml file.

    oc apply -f <pod-yaml-file>

  4. Verify that the pod is running.

    oc get pods

  5. Repeat these steps for each pod that needs to be manually migrated.