Creating a KeyControl Mapping

A KeyControl Mapping lets you associate each KeyControl node with an externally-visible IP address or hostname.

You can create multiple KeyControl Mappings and associate those Mappings with one or Policy Agents. If a KeyControl node is added or removed, you can update the relevant KeyControl Mappings in the KeyControl webGUI and the changes are then disseminated to the VMs on their next heartbeat.

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 goes offline, the VMs will use the next IP address in the list until the preferred node becomes available again.

Procedure 

1. Log into the KeyControl webGUI on any node in the cluster 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 part of 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 hostname or IP address to which this node should be mapped. This name or address should be accessible to the VMs that will be connected to KeyControl using this mapping.
   Port	The port number for the specified Hostname or IP address. The default is 443.
   Node drop-down	Select the appropriate node in the drop-down list. You can only have one entry for each node.
   Enabled/Disabled	Select Enabled if the node is available to the VMs associated with this KeyControl Mapping. If you want to use this 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. The VMs will attempt to contact the first node in the list. If the first is unavailable they will try to contact the second node, then the third, then the fourth and so on. 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 KeyControl, see Linux Policy Agent Installation or Windows Policy Agent Installation.

13. To associate the KeyControl Mapping with one or more Policy Agents, log into each server you want to associate with the KeyControl Mapping and enter the command hcl updatekc –a [-u username [-p password]], where:

    • -u is a KeyControl user account with Cloud Admin privileges. If you do not enter a user account name you will be prompted for one.
    • -p is the password for the KeyControl user account. If you do not enter a password you will be prompted for one.

    The Policy Agent then queries KeyControl for the list of available KeyControl Mappings. Type the number corresponding to the Mapping you want to use and press Enter.

    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