Overview

This page reviews how to add and configure a Docker connection using GroundWork Cloud Hub. The connection requires a unique set of parameters (e.g., endpoint, credentials). You will need your GroundWork server and virtual environment connector parameters handy.

1.0 Adding a New Connection

The initial Cloud Hub screen is used to add, start, stop, modify, or delete available connectors. Follow the steps below to add a connection. You will need to create a new connection in this way for each region to be monitored.

1. Log in to GroundWork Monitor as an Administrator.
2. Select GroundWork Administration > GroundWork Cloud Hub.
3. Click +Add corresponding to the Docker connector icon. 
   
   Figure: Adding a connection
   

2.0 Configuring the Connection

In the configuration page you will need to enter both the GroundWork server and remote server parameters.

The data the GroundWork server receives comes from the remote virtualization server. The GroundWork server is where Cloud Hub will store the connectors metrics. The information is pulled from the API on a periodic basis based on the check interval that is set.

2.1 GroundWork Server Parameters

1. Here we enter the GroundWork server parameters, each described in the table below.
   
   Figure: GroundWork server values
   
   
   Table: GroundWork server values

   GroundWork Server Version	The GroundWork server version number which is set to the latest release installed. Cloud Hub can be configured to talk to versions from GroundWork Monitor version 7.0.
   Display Name	This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page.
   GroundWork Server Name	The host name or IP address of the GroundWork server that will integrate the Cloud Hub messages. A port number should not be entered here. If Cloud Hub is running on the same server as the portal the name can be localhost, or as preferred the server name. Often the GroundWork server is the same server where Cloud Hub is running however, Cloud Hub can also run in a distributed environment on its own node in a GroundWork cluster.
   Is SSL enabled on GroundWork Server?	Check this box if the GroundWork server is provisioned with a secure HTTPS transport.
   GroundWork Web Services Username	This is the provisioned user name granted API access on the GroundWork server. This value defaults to RESTAPIACCESS, and can be located by opening a tab to the GroundWork Administration > GroundWork License page. The value is under Webservices API Account Info in the Access field. For all systems, make sure the Web Services Username and Password match with the entries in the ws_client.properties file.
   GroundWork Web Services Password	This is the corresponding API Token (password) for the given user name on the GroundWork server. This is obtained by opening a tab to the GroundWork Administration > GroundWork License page. The value is under Webservices API Account Info in the Token (encrypted) field. For all systems, make sure the Web Services Username and Password match with the entries in the ws_client.properties file.
   Merge hosts on GroundWork Server?	If checked, this option combines all metrics of same named hosts under one host. For example, if there is a Nagios configured host named demo1 and a Cloud Hub discovered host named demo1, the services for both configured and discovered hosts will be combined under the hostname demo1 (case-sensitive).

2.2 Remote Server Parameters

1. Here we enter the remote server parameters, each described in the table below.
   
   Figure: Remote server values
   
   
   Table: Docker server values

   Docker Server URL	This is the URL for the Docker virtualization server (e.g., docker-host.yourdomain.com:port.
   Host Prefix	This is the prefix of the host (e.g., qa- or docker1-).
   Check Interval (in mins)	This is the polling interval for collecting monitoring data from the virtual instance and sending it to the GroundWork server. The value is in minutes.
   Connection Retries (-1 infinite)	This entry is the number of retries for the connection and sets a limit on how many attempts are made after a failure. If you set this to -1, the retrying goes on forever. The number set indicates how many connections are attempted before the connection is left inactive (until you restart it).

2. After the remote server parameters have been entered, click SAVE which saves and writes the entries to an XML file in the GroundWork server /usr/local/groundwork/conifg/cloudhub directory. The Cloud Hub connector is assigned an agent ID and that in turn becomes a record locator in Foundation when you begin monitoring.
3. Next, validate the configuration by selecting TEST CONNECTION which will check if the connection is accessible with the given credentials. A dialog will be displayed with either a success message or, if the server cannot be contacted, an error message will be displayed with information describing why the connection failed.
4. After the credentials have been validated, select NEXT to display an associated connection metrics screen where you can determine the metrics to be monitored.

3.0 Determining Metrics To Be Monitored

Each management system provides metrics for specific checks that can be defined for the instance or the container. The property name and the thresholds are defined in a monitoring profile in an XML format.

In the UI the metrics are separated into categories, e.g., Docker Engine Thresholds and Docker Container Thresholds, where you can define if a metric should be monitored, graphed, and also set the values for Warning and Critical thresholds at which to trigger alerts. By default some of these thresholds are set to -1 which turns them off so you can get an idea by watching the data coming in and then setting a value appropriate for the environment. The Service Name field enables overriding of the automatically generated service name. 

The selections made are applied to every instance discovered in the region. The set of selections is saved on the GroundWork server in the /usr/local/groundwork/config/cloudhub/profiles directory as a profile in an XML file. The selections become effective both against new instances that may be discovered as well as already monitored instances.

1. Here we adjust any profile selections, each described in the table below.
   
   Figure: Docker profile metrics
   
   
   Table: Docker profile attribute options

   Attribute	The name of the service attribute (the metric name reported by the virtualization server).
   Monitored	When on (checked) the service will be monitored.
   Graphed	When on (checked) the service will be graphed.
   Warning and Critical Thresholds	These values control the triggering of alerts. A Warning number larger than the Critical value will cause Cloud Hub to detect the metric as a trigger. Choosing a -1 in a threshold box will disable triggering on that alert.
   Service Name	Cloud Hub automatically creates service names based on the metric name gathered from a virtualization server. The Service Name option adds the ability to report the polled metrics under a unique name that is set by the Administrator. Leaving the Service Name field blank defaults to the metric name reported by the virtualization server. All Cloud Hub connectors now support the editable Service Name feature.
   Description	A description of the service attribute.

2. When you are satisfied with the profile selections click SAVE to write out the profile.
3. Click HOME to return to the main Cloud Hub panel.
4. Click START for the specific connector to begin the discovery and data collection process.

   At anytime, if you decide you do not want to monitor a particular region, simply navigate back to this point (GroundWork Administration > GroundWork Cloud Hub) and select STOP for the corresponding connector, the connectors configuration will be maintained for a subsequent START. To stop and completely delete a connection see How to delete GroundWork Hub hosts.