Joining a KeyControl Cluster

The following procedure describes how to configure a newly deployed node to join an existing KeyControl cluster.

Before You Begin 

  • Make sure you know the IP address of any KeyControl node that is already part of the cluster you want to join.
  • If the node is currently part of a different cluster, you should remove the node from the original cluster so that the original cluster does not become degraded. For details, see Removing a KeyControl Node from a Cluster.

  • Make sure that you have tested the port connection between the joining node and the existing cluster node to ensure that they can communicate with each other. You can test the port connection through the console.

  • If you are re-joining a node to an existing cluster and you are using an externally signed SSL certificate for KeyControl, make sure that you use the same hostname for the KeyControl node that it had originally. If you change the hostname, you will need to reinstall the externally signed SSL certificate on that node.
  • A KeyControl node cannot be joined to an existing KeyControl cluster if the internal web server of the joining node is configured with a custom SSL certificate.
  • Entrust recommends that you configure the KeyControl node with a private IP address.

Procedure 

  1. Log into the webGUI on the KeyControl node you want to join with the cluster.

  2. Review the EULA (end user license agreement). When you are done, click I Agree to accept the license terms.

  3. On the Welcome to KeyControl screen, click Join an Existing Cluster.

    The Join Existing Cluster window displays.

  4. On the Get Started page, review the overview information to determine that you are ready to begin. This includes: 

    • Access to the cluster you are joining the node to. We recommend that you open the webGUI for the cluster in a different tab or browser window.
    • Permissions on both this node and the cluster node so you can download and import the required certificates and files.
    • A passphrase to use during the joining process. Passphrase requirements are configured by a KeyControl administrator in the System Settings. This phrase is a temporary string used to encrypt the initial communication between this node and the existing KeyControl cluster.
    • Verifying that both this node and the cluster node are running the same KeyControl version and build. The version number for the cluster node is on the Settings > System Upgrade page.
  5. Click Continue.
  6. On the Download CSR page, click Generate and Download CSR.
  7. Click Continue.
  8. Switch to one of the existing nodes in the cluster and navigate to the Cluster page.
  9. Select Actions > Add a Node.

  10. On the Add a Node window, upload the CSR that you downloaded from the new node (in .pem format) and enter a passphrase to use during the joining process.

  11. Click Save and Download Bundle to download the certificate bundle from the cluster node.

    The certificate bundle is a .zip file you must unpack. It contains both an encrypted SSL certificate in .p12 format and a CA certificate in .pem format.

  12. Click OK to close the Add a Node window.
  13. Return to the new node and click Continue.

  14. On the Node page, upload the encrypted SSL certificate and CA certificate that you downloaded from the cluster node, enter the private IP address of any node in the existing cluster, and enter the passphrase that you selected.

    Note: KeyControl uses the private IP address of its cluster members for cluster communication, such as heartbeat and object store synchronization.

  15. Click Join.

    During the joining process, a status page is displayed on the new node. Do not refresh the browser while this is in process.

    The cluster will automatically be placed in maintenance mode.

    The node will restart after the join is complete.

  16. When the node has successfully restarted, click Login.

What to Do Next 

If necessary, update the list of KeyControl IP addresses on the VMs associated with this cluster. If you are maintaining the list of IP addresses on the VMs, see Updating KeyControl Node IP Addresses on an Individual VM. If you are using KeyControl Mappings, see Changing a KeyControl Mapping.

If you are using an HSM, see the appropriate link to rejoin the cluster: