E-mail
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.
CONTENTS | RELATED RESOURCES |
WAS THIS PAGE HELPFUL? |
1.0 Adding a New Connection
To access Cloud Hub, log in to GroundWork Monitor as an Administrator and select (1) GroundWork Administration > GroundWork Cloud Hub.
The initial Cloud Hub screen is used to (2) Add new, or Start, Stop, Modify, obtain Status for, or Delete configured connectors.
The Start option enables a configured connector to begin the discovery and data collection process. If you decide you do not want to monitor a particular region, simply select Stop for the corresponding connector, the connectors configuration will be maintained for a subsequent start. Modify opens the Configuration page with a link to the Metrics screen. Status provides connection status information including error details. If a configured connector fails to connect, a connector-specific service will be updated to a Warning state, or Critical if you run out of retries (hosts will still become Unreachable and services Unknown if retries are exhausted). To stop and completely Delete a connection, see How to delete hosts. To keep a Cloud Hub connector configuration and temporarily suspend its monitoring, see Black List.
To (3) add a new connection click +Add corresponding to the Docker connector icon. You will need to create a new connection in this way for each region to be monitored.
Figure: Adding a connection
Next, in the configuration page (shown below) 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 information is pulled from the API on a periodic basis based on the check interval that is set.
The (1) Groundwork Server is where Cloud Hub will store Docker metrics. Often, this is the same server as where Cloud Hub is running. However, Cloud Hub can also be run in a distributed environment, on its own node in a GroundWork cluster. Here we enter the GroundWork server parameters, each described in the first table below.
Next enter values for the remote (2) Docker Connector including a configuration authentication file, shown below and described in the second table.
Validate both server configurations by selecting the (3) Test buttons which will check if the connections are 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. When a successful connection is made, the Connection Status buttons will change to green.
And after the remote server parameters have been entered and verified, click (4) Save in the upper right corner to save and write the entries to an XML file in the GroundWork server /usr/local/groundwork/config/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. After the credentials have been validated select the Metrics link (top navigation) to start customizing metrics for the connection.
Figure: Docker connector
Table: GroundWork server values
| Version | Indicates the minimum GroundWork Monitor version needed. In other words, a version below the indicated value is incompatible. |
| Hostname | The host name or IP address where a Groundwork server is running. A port number should not be entered here. If Groundwork is running on the same server, you can enter localhost. |
| Username | The provisioned Username granted API access on the GroundWork server. |
| Token | The corresponding API Token (password) for the given Username on the GroundWork server, see GroundWork Administration > GroundWork License > Webservices API Account Info Token (encrypted). |
| SSL | Check the SSL checkbox if your GroundWork server is provisioned with a secure HTTPS transport. |
| Merge Hosts | 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). |
| Monitor | Enables connection to be monitored. |
Table: Docker server values
| Display Name | This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page. |
| Docker Host:Port | 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-). |
| Cloud Hub Interval (min) | This is the metric gathering interval for collecting monitoring data from Docker and sending it to the GroundWork server. The value is in minutes. |
| Infinite Retries | Check this box if you want Cloud Hub to infinitely retry connection to Docker when the connection fails. When this box is checked, the Retry Limit field is disabled. When this box is unchecked, the Retry Limit field is enabled. |
| Retry Limit | This entry is the number of retries for the connection and sets a limit on how many attempts are made after a failure. The number set indicates how many connections are attempted before the connection is left in an inactive state. At this point, the connection is suspended and you will need to manually restart it. When a retry limit is exhausted, all hosts managed by this connection are set to the monitor status Unreachable and all services for the matched hosts are set to the status of Unknown. |
2.0 Navigating
From the Configuration page, navigations are on displayed in the top navigation bar:
From here, you can navigate to:
- Home - Cloud Hub home page
- Metrics - Metrics configuration page associated with this Cloud Hub connection
- Configuration - Cloud Hub configuration page
When creating a new Docker configuration, the Metrics link is not visible until you successfully save the configuration parameters. Once you are satisfied with your configuration settings, click Save, then click the Metrics link in the navigation bar to start customizing your metrics for this connection. Also, the Save button is not enabled until all required fields are validated. If you make changes on the configuration page, and forget to save, you will be prompted.
3.0 Determining Metrics To Be Monitored
The Docker metrics page is where you customize the lists of metrics being gathered for a connection. Out of the box, a complete list of metrics is provided for clusters, hosts, and Docker services. You can customize these metric lists by adding metrics to the list, deleting metrics, as well as creating calculated metric fields called Synthetic metrics.
The Metrics page is displayed in groups of metrics grouped by Cluster, Host, and Docker Service collections. The counts of metrics are displayed in the Group bar, and summarized by:
- # metrics per group
- # active metrics per group
- # synthetic metrics per group
A metric is considered inactive if it is not monitored.
Figure: Docker metrics
You can configure the metrics for any group by clicking on the (1) group bar. Each row in the grid represents a metric. Metrics can be added, edited or deleted. You can directly edit metrics in the grid or use the advanced metric dialog by clicking the (2) Edit button and then configuring all properties of a metric in the dialog. When editing metrics in the grid directly, you will need to click the (3) Save button in the top navigation to commit your changes to Cloud Hub. To add new metrics use (4) Add Normal Metric or Add Synthetic Metric.
For example, if we click on the Docker Engine (3 metrics, 2 active, 1 synthetic) group bar, the display automatically expands to show all metrics for the Docker Engine group.
Figure: Metrics page expanded
The grid displays the following fields:
| Monitor? | Check this if you want to enable monitoring of this metric. |
| Graph? | Check this if you want to graph the values of this metric in time series |
| Metric Name | The exact Docker metric name or a Docker metric expression. This field is read-only. Click the Edit button to modify it. |
| Display Name | Overrides the metric name and stores the metric in GroundWork as a service with this name. |
| Warning Threshold | Metric value that will trigger a GroundWork Warning alert. |
| Critical Threshold | Metric value that will trigger a GroundWork Critical alert. |