Upgrading Key Trustee KMS

Continue reading:

Setting Up an Internal Repository

You must create an internal repository to upgrade Key Trustee KMS. For instructions on creating internal repositories (including Cloudera Manager, CDH, and Cloudera Navigator encryption components), see Configuring a Local Parcel Repository if you are using parcels, or Configuring a Local Package Repository if you are using packages.

Validating Private Key Synchronization (Key Trustee KMS HA Only)

Key Trustee KMS provides logic to detect and warn users about a potential problem where the GPG private keys have not been properly synchronized across all Key Trustee KMS HA hosts. If you have been running Key Trustee KMS on different hosts, and have not maintained private key synchronization, it is possible that the hosts may continue to operate and appear in a healthy state. However, when private keys are not synchronized between hosts, you can end up in a "split brain" scenario. In this scenario, the keys are actually only intermittently accessible, depending on which Key Trustee KMS host a client interacts with, because cryptographic key material encrypted by one Key Trustee KMS host cannot be decrypted by another. In the event of a catastrophic failure of one Key Trustee KMS host, any keys it has encrypted and any data encrypted by those keys will become inaccessible.

Key Trustee KMS detects this error state using a GPG validation check, which runs automatically when the Key Trustee KMS is restarted as part of the upgrade process. When the validation check discovers that private keys between hosts do not match, it returns the following error and aborts the restart operation: 
java.io.IOException: Unable to verify private key match between KMS hosts. Verify private key files have been synced
between all KMS hosts. Aborting to prevent data inconsistency.

To determine whether or not the Key Trustee KMS private keys are different, compare the MD5 hash of the private keys by executing the following command on each Key Trustee KMS host:

md5sum /var/lib/kms-keytrustee/keytrustee/.keytrustee/secring.gpg

Upgrading Key Trustee KMS Using Parcels

  1. Go to Hosts > Parcels.
  2. Click Configuration and add your internal repository to the Remote Parcel Repository URLs section. See Configuring Cloudera Manager to Use an Internal Remote Parcel Repository for more information.
  3. Click Save Changes.
  4. Download, distribute, and activate the KEYTRUSTEE parcel for the version to which you are upgrading. See Parcels for detailed instructions on using parcels to install or upgrade components.
  5. Restart the Key Trustee KMS service (Key Trustee KMS service > Actions > Restart).

Upgrading Key Trustee KMS Using Packages

  1. After Setting Up an Internal Repository, configure the Key Trustee KMS host to use the repository. See Configuring Hosts to Use the Internal Repository for more information.
  2. Add the CDH repository. See Configuring a Local Package Repository for instructions.
  3. Upgrade the keytrustee-keyprovider package using the appropriate command for your operating system:
    • RHEL-compatible 
      sudo yum install keytrustee-keyprovider
    • SLES 
      sudo zypper install keytrustee-keyprovider
    • Ubuntu or Debian 
      sudo apt-get install keytrustee-keyprovider
  4. Restart the Key Trustee KMS service (Key Trustee KMS service > Actions > Restart).