Overview

This page reviews how to add and configure a VMware connection using GroundWork Cloud Hub. The connection requires a unique set of parameters (e.g., URI, 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 VMware 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

Regarding an ESX direct connection It is possible to connect to a vSphere server or an ESX server with Cloud Hub. GroundWork recommends connecting to vSphere if possible, as the API is more advanced and has a greater range of metrics. If you do need to connect to an ESX server, be advised that some services you may want to select will show as Unknown, as the metrics you want are not in the API. You can review the /usr/local/groundwork/jboss/framework.log file to see the details of which metric are not available.

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

   Is SSL enabled on VMware Server?	Check this box if the VMware server is configured for secure HTTPS.
   VMware Server Name	This is the name of the VMware server and the domain name, (e.g., vmware-server.yourdomain.com).
   VMware Server URI	A Universal Resource Identifier (URI)is a locator, a name, or both. This is the server URI, (e.g., sdk)
   VMware Server Username	The provisioned Username granted API access on the VMware server.
   VMware Server Password	The corresponding Password for the given Username on the VMware server.
   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).
   Views	The radio buttons specify the views you would like to report upon. The view selections made on this screen determine the metric options on the next profile screen. Hyperviser View -  Storage View -  Network View -  Resource Pool View -

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.

The VMware API defines a set of metrics that apply to hypervisors, hosts, networks and datastores. The metrics gathered by Cloud Hub are of two kinds: native and synthetic. The strings that define the native metrics are exactly those supported by the VMware API, with certain restrictions, namely that the list must be from those metrics that result in values, and not lists of objects. The majority of the metrics are numeric in nature - amounts of "MHz" (megahertz, in VMware parlance), amounts of memory, amounts of disk space. Again, they are taken in their native form, neither normalized nor adjusted.

The native metrics lack a sense of normalization, as an example a host (VM/virtual machine) may have a metric for CPU utilization of 273. The VMware documentation indicates that this value is in MHz. However, in ferreting out system issues, it is often more useful to know what proportion of the total resource in question is in use. In other words, 273 of what?

The synthetic metrics are pairs of native metrics, cast into percentage-of-total form. The numerator (number on top) is a performance metric, and the denominator (divisor on the bottom) is the sum of, or size of a resource. Synthetic metrics can be extremely helpful in deciphering performance and accessibility issues in real-time. The percentages are bounded in the [0..100] range, and they include the "%" character at the end.

The metrics screen allows you to define if a metric should be monitored and graphed, and lets you set the values for Warning and Critical thresholds at which to trigger alerts. It is recommended to use the synthetic metrics (computed percentages) since it helps to define the threshold values in a 0-100% range.

1. Here we adjust any profile selections, each described in the table below.
   
   Figure: VMware profile metrics
   
   
   Table: VMware 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.