Creating a KeyControl Mapping

A KeyControl Mapping lets you create a list of KeyControl IP addresses that you maintain in KeyControl. Each KeyControl node in the Mapping is associated with an externally-visible IP address or hostname that the VMs can use to access that KeyControl node. If you ever change the list of KeyControl nodes in the Mapping, KeyControl automatically disseminates the changes to the each associated VM at its next heartbeat.

Associating a Mapping with a VM enables High Availability between the VM and KeyControl by enabling failover among the KeyControl nodes, and it means you do not need to update the individual VMs when KeyControl nodes are added to, or removed from, the cluster.

For more information on High Availability and failover, see High Availability Between a VM and the KeyControl Cluster.

Procedure 

1. Log into the KeyControl webGUI using an account with Cloud Admin privileges.
2. In the top menu bar, click Cloud.
3. Click the Mappings tab.
4. Select Actions > Create Mapping.

5. On the Mapping tab, specify the options you want to use.

   Options

   Field	Description
   Name	Enter the name for this KeyControl Mapping. You can use - (hyphen) and _ (underscore) as well as any alphanumeric characters.
   Group drop-down	Select the Cloud Admin Group associated with this Mapping. The Mapping will be available to all VMs that are registered with the Cloud VM Sets assigned to the selected Cloud Admin Group.
   Description	Enter a description for the KeyControl Mapping. This description will be displayed on the VMs when they are associated with the KeyControl Mapping.

6. When you are done, click Next.

7. On the Servers tab, create an entry for the first KeyControl node by specifying the options you want to use.

   Options

   Field	Description
   Description	Enter a description for this node that lets you distinguish it from other nodes in the KeyControl Mapping.
   Hostname or IP	The externally-visible hostname or IP address to which this node should be mapped. Each node in the cluster can be associated with one and only one externally-visible IP address. Note: If the VMs will be communicating with the KeyControl node through a firewall or in an environment like Amazon Web Services or Microsoft Azure, the externally-visible IP address may not be the same as the internal KeyControl node IP address. Make sure that all VMs that will use this Mapping can communicate with the KeyControl node via the specified IP address/port number combination.
   Port	The port number for the specified Hostname or IP address. The default is 443.
   Node drop-down	Select the appropriate KeyControl node in the drop-down list. You can only have one entry for each KeyControl node.
   Enabled/Disabled	Select Enabled if the node is available to the VMs associated with this KeyControl Mapping. If you want to use this as a placeholder until you bring the node online, select Disabled. The default is Enabled.

8. If you want to add another node, click the + button and enter the appropriate information.

9. When you are done adding nodes, make sure that the order is correct because the order of the IP addresses in the list determines the order of precedence. The first node in a KeyControl Mapping is considered the preferred node, and all VMs will use that node as long as it is available. If the preferred node is offline when a VM heartbeats, the VM will try the other IP addresses in the Mapping, starting with the second IP address in the list and working downwards. Once the VM finds an available KeyControl node, it will use that node to complete the current heartbeat, and it will continue to use that node until the cluster returns to a healthy state. After the cluster becomes healthy, the VM will resume using the preferred node at its next heartbeat.

   If you need to change the order, click and hold on the arrow icon at the beginning of the line to drag the entry to the proper position. Release the mouse to drop the entry in the new location.

10. When all nodes are included and the order is correct, click Create.
11. At the Mapping Successfully Created message, click Close.

12. If you want to associate the KeyControl Mapping with an existing VM that already has the Policy Agent installed:

    1. Log into the VM as an administrator.

    2. Enter the command hcl updatekc -a and enter the credentials for a KeyControl user account with Cloud Admin privileges at the prompt. KeyControl displays a list of available KeyControl Mapping that you can use with the VM.

    3. Select the KeyControl Mapping you want to use from the list. KeyControl echoes the IP addresses in the list for confirmation.

       Example

       # hcl updatekc -a
       Getting KeyControl Mapping information
       Please provide the KeyControl login details
       username: cloudadmin
       password: ********
       		
       This VM can be added to one of the following KeyControl Mappings
       ---------------------------------------------------
       1 : San Francisco Datacenter
       2 : AWS VMs
       ---------------------------------------------------
       Please select KeyControl Mapping (0 to skip): 1
       							
       KeyControl Mapping
       server description KC-1, ip 192.168.140.151, port 443
       server description KC-2, ip 192.168.140.152, port 443
       Updated KeyControl list with KeyControl nodes 192.168.140.151:443,192.168.140.152:443

    Note:

    For details about specifying a KeyControl Mapping when you install the Policy Agent, see Linux Policy Agent Installation or Windows Policy Agent Installation.