Cloudera Docs

Key migration

This procedure describes how to migrate keys from Key Trustee Server to Ranger KMS.

  • Locate the keys in Key Trustee Server.
    • Login to Ranger UI with Key Admin credentials.
    • Go to Key Management -> Select Service, to view the HDFS encryption zone keys with service Ranger KMS KTS.
  • If Navigator Encrypt is setup, locate its keys.
    • SSH in to the active KTS node.
    • Login to Postgres 14 database for Cloudera Runtime version 7.1.9.
    • The 'keytrustee' user is created with 'nologin' by default. Update the keytrustee user in /etc/passwd before accessing the database by running the following command: 
      sed -i "/keytrustee:x:$( id -u keytrustee ):$( id -g keytrustee ):Keytrustee User:\/var\/lib\/keytrustee:\/sbin\/nologin/c\keytrustee:x:$( id -u keytrustee ):$( id -g keytrustee ):Keytrustee User:\/var\/lib\/keytrustee:\/bin\/bash" /etc/passwd
    • Run the following commands: 
      select handle from deposit;

      For Cloudera Runtime version 7.1.9:

      # sudo -u keytrustee LD_LIBRARY_PATH=/opt/cloudera/parcels/KEYTRUSTEE_SERVER/PG_DB/opt/postgres/14.2/lib /opt/cloudera/parcels/KEYTRUSTEE_SERVER/PG_DB/opt/postgres/14.2/bin/psql -p 11381 keytrustee
                           
keytrustee=# select handle from deposit;
handle  
---------
mykey1
mykey2
                           
control
                           
control
(6 rows)
  1. Backup the KTS database.
    The backup will be created at /var/lib/keytrustee/ on Active KTS node.
  2. Export the Navigator Encrypt keys.
    1. Go to Cloudera Manager > Key Trustee Server > Click on Actions > Export NavEncrypt Deposits from Keytrustee Server.
      This will generate the CSV required to import Navigator Encrypt keys in Ranger KMS DB after migration. The deposits.csv file will be created at /var/lib/keytrustee/.keytrustee.
  3. Back up the Ranger KMS KTS directory and generate a keystore file of existing encryption zone keys.
    The keystore file is protected using Store password (default value : mystorepass) and Key password (default value : mykeypass), that are configurable in RANGER KMS KTS configuration.
    1. Go to Cloudera Manager > Ranger KMS KTS > Actions and select Export keys from Ranger KMS KTS
    The service GPG keys backup and keystore file will be created at /var/lib/kms-keytrustee on Ranger KMS KTS node.
  4. Stop HDFS and Ranger KMS KTS.
  5. Delete the Ranger KMS KTS service from Cloudera Manager UI.
  6. Add the Ranger KMS service from Cloudera Manager UI and follow the steps as per wizard. For more info, see related links for 'Configuring a database for Ranger or Ranger KMS' and 'Installing Ranger KMS backed by a Database and HA'
  7. Enable the migration flag and complete the wizard.
    1. Go to Cloudera Manager > Ranger KMS > Configurationand check Enable Ranger KMS KTS Migration.
  8. Configure the Key password (default value : mykeypass) and Store password (default value : mystorepass) in Ranger KMS configuration.
    These are the same passwords that were configured in Step 3 in Ranger KMS KTS.
  9. If Navigator Encrypt is configured on the cluster, copy deposits.csv file to the Ranger KMS node, and grant permission kms:kms.
    The location is configurable using the property Key Trustee NavEncrypt Keys Full Path.
     # scp root@dsktstokms-4.vpc.cloudera.com:/var/lib/keytrustee/.keytrustee/deposits.csv /var/lib/kms-keytrustee
                                                                                                                                                              100%   10KB   8.2MB/s   00:00    
 # ls -ltr /var/lib/kms-keytrustee/deposits.csv 
 -rw-r--r-- 1 root root 10401 Jun 15 03:34 /var/lib/kms-keytrustee/deposits.csv
 # chown kms:kms /var/lib/kms-keytrustee/deposits.csv 
 # ls -ltr /var/lib/kms-keytrustee
 total 64
 -rw-r--r-- 1 kms kms 20480 Jun 14 11:22 kms_bak_dsktstokms-3_vpc_cloudera_com_2023-06-14_11-22-42.tar
 -rw-r--r-- 1 kms kms   352 Jun 14 11:22 kt_bak_dsktstokms-3_vpc_cloudera_com_2023-06-14_11-22-42.log
 -rw-r--r-- 1 kms kms 20480 Jun 15 03:20 kms_bak_dsktstokms-3_vpc_cloudera_com_2023-06-15_03-20-54.tar
 -rw-r--r-- 1 kms kms   352 Jun 15 03:20 kt_bak_dsktstokms-3_vpc_cloudera_com_2023-06-15_03-20-54.log
  drwxr-xr-x 3 kms kms    55 Jun 15 03:21 keytrustee
 -rw-r--r-- 1 kms kms 10401 Jun 15 03:34 deposits.csv
    If you want to migrate the KMS hosts, then also copy the migratedKeyStore.jceks file to the Ranger KMS node.
     # scp root@dsktstokms-4.vpc.cloudera.com:/var/lib/keytrustee/.keytrustee/migratedKeyStore.jceks /var/lib/kms-keytrustee/keytrustee
                
 #ls -ltr /var/lib/kms-keytrustee/keytrustee
  -rw-r--r-- 1 kms kms  1210 Jun 15 03:21 migratedKeyStore.jceks
  10. Start Ranger KMS.
  11. Import the keys from the keystore file and deposits.csv file for NavEncrypt.
    1. Go to Cloudera Manager > Ranger KMS > Actions and select Import Keys from KTS.
  12. Restart Ranger KMS.
  13. Start HDFS from Cloudera Manager UI.
  14. Stop the Key Trustee Server from Cloudera Manager UI.
After the keys are successfully imported, the keys are visible on Ranger UI.
The Navigator Encrypt keys will be visible in Ranger KMS DB. 
 # mysql -u root -p 
                
 MariaDB [(none)]> use rangerkms;
 
 MariaDB [rangerkms]> show tables;
                +---------------------+
                | Tables_in_rangerkms |
                +---------------------+
                | navencrypt_deposit  |
                | ranger_keystore     |
                | ranger_masterkey    |
                +---------------------+
                3 rows in set (0.00 sec)
Post migration, after you verify that all the keys are migrated, delete KTS service from Cloudera Manager UI.