This article reviews how to add and configure a VMware connection using GroundWork Cloud Hub. The connection requires a unique set of parameters. If you are connecting to a remote GroundWork server to send results, you will need your remote GroundWork server RESTACCESSAPI token.

Adding a new connection

To access Cloud Hub configuration, log in to GroundWork Monitor as a member of the Admin role (e.g., user admin), and select Configuration > Cloud Hub. To add a new connection click the +Add button next to the VMware connector icon. You will need to create a new connection in this way for each VMware project to be monitored.

Connection 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. In the configuration page you will need to enter both the GroundWork Server and VMware Connector parameters, and select the Views (resources to be monitored). The  fas fa-info-circle  link located at the top right side provides information and versioning for the selected Cloud Hub connector.

GroundWork server

1. The GroundWork Server can simply be the same as the one you are running the Cloud Hub connector on, or it can be a remote server.
   
   • If it's the same as the one you are running on, leave the directive Use Local Connection checked. 
   • Otherwise, uncheck this box and fill in the hostname of the remote GroundWork server in the Hostname field, leave RESTAPIACCESS in the Username field, and paste in the the encrypted Token. The token can be obtained on the remote GroundWork server, for users within the Admin role, by going to Administration > Security under Webservices API Account: RESTAPIACCESS, Encrypted Token. Just copy the key from the remote server into the Token field on the Cloud Hub server.
     
     

2. Once you have the GroundWork Server side of the form filled out, click Test. If you have the credentials correct and you have access to the API, you will see a Success message. Otherwise an error will give you a hint as to what is wrong and let you try again. 

   Using a remote server will populate the remote server with the VMware monitoring data, and this will not show in the local GroundWork server.

   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 for the given Username on the GroundWork server, see Administration > Security under Webservices API Account: RESTAPI Encrypted Token.
   SSL	Check this box if the 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	If checked, enables connection to be monitored.
   Use Local Connection	This directive refers to where the Cloud Hub results are sent. If this field is checked, results will be posted to the same server as where Cloud Hub is running. Or, with this field unchecked, you can forward results to any accessible GroundWork server you define with the name and API key.
   Ownership	Ownership is the owner of a connectors hosts and the ownership can be switched. When a Cloud Hub connector is instantiated the following options are available for ownership: Always take ownership: The connector will assume ownership of all hosts it instantiates, even merged hosts. This will remain true even if another app merges the host.  Leave ownership if already owned: The connector host will remain with the existing owner until or unless the owner deletes the host. Always defer ownership (default): This option leaves ownership unchanged on merged hosts, and allows other apps to take ownership. Note that multiple apps can report on a single service, but only one can own the host. See Ownership options.
   Connection Status	Click Test to verify a connection using the GroundWork server entries.

VMware server

Next you will need to fill in the VMware Connector parameters and test the connection.

1. Enter a Display Name.
2. Enter the VMware Server Name.
3. Enter the Server URI.
4. Enter a Username.
5. Enter a Password.
6. Optionally set the Interval, FQDN, and Retry directives.
7. Validate the connection by clicking Test. A dialog will be displayed with either a Success message or, if the project cannot be contacted, an error message will be displayed with a hint as to why the connection failed. When a successful connection is made, the Connection Status buttons will change to green.
8. Click Save in the upper right corner to save your correct connection parameters. 
9. Next, you need to select the resources to monitor. On the right side of the screen are Views which are optional features of VMware. These features are the core components, or services that are managed by VMware. Services include storageView, networkView, and resourcePoolView. Each of these services has their own rich set of metrics. If checked, service will be monitored. If you were collecting metrics for a service, and then unchecked that VMware service, the existing hosts and metrics stored in the GroundWork server will be deleted.
   
   • Click Save when finished.

10. After the credentials have been validated and the resources indicated, select the Metrics link (top navigation) to start customizing metrics for the connection. 

    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.

    Please refer to the article How to determine Cloud Hub metrics to be monitored.
    

    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. 

    Table: VMware server values

    Display Name	This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page.
    VMware Server Name	This is the name of the VMware server and the domain name, (e.g., vmware-server.yourdomain.com).
    Server URI	A Universal Resource Identifier (URI)is a locator, a name, or both. This is the server URI, (e.g., sdk)
    Username	The provisioned Username granted API access on the VMware server.
    Password	The corresponding Password for the given Username on the VMware server.
    Interval (in min)	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.
    FQDN	Check to specify the host name as a Fully Qualified Domain Name.
    Infinite Retries	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).
    Retry Limit	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.
    Connection Status	Click Test to verify a connection using the VMware connector entries.

Related articles

• Page:
  Cloud Hub (Documentation)
• Page:
  How to determine Cloud Hub metrics to be monitored (Knowledge Base)
• Page:
  Cloud Hub troubleshooting (Knowledge Base)
• Page:
  Ownership options (Documentation)
• Page:
  Transit Connection Generator (TCG) (Documentation)