E-mail
Overview
This page covers how to add and configure a Microsoft Azure connector 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 Microsoft Azure 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 Azure 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) Azure 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.
(4) Service Resources are optional features of Azure. These features are the core components, or resource managed by Azure. Services include Microsoft.Compute/virtualMachines, Microsoft.DocumentDb/databaseAccounts, Microsoft.Sql/servers/databases, Microsoft.Web/sites, Microsoft.Sql/servers and others exposed when you choose Discover. Each of these services has their own rich set of metrics. By default, all services are selected. If checked, service will be monitored. Azure also provides Cluster and Host metrics which can be optionally collected. If there are one or more clusters or hosts in the system, they will be automatically detected and collected. If you were collecting metrics for a service, and then unchecked that Azure service, the existing hosts and metrics stored in the GroundWork server will be deleted.
And after the remote server parameters have been entered and verified, click (5) 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: Azure 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: Azure server values
| Display Name | This is the configuration’s name displayed in the list of Cloud Hub connectors on the Cloud Hub home page. |
| Configuration File | This is the required Azure authentication file. Refer to Appendix A: Azure Authentication on this page for a detailed description of this requirement. |
| Interval (min) | This is the metric gathering interval for collecting monitoring data from Azure and sending it to the GroundWork server. The value is in minutes. |
| Timeout (ms) | The connection timeout in milliseconds. Normally the default value 5000 is sufficient. When you have a slow network connection, you may want to increase the default value. |
| Infinite Retries | Check this box if you want Cloud Hub to infinitely retry connection to Azure 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. |
| Enable Resource Groups | If checked Azure resource groups are monitored and displayed in Status. Resource Groups are are logical containers for a collection of resources that can be treated as one logical instance. You can use resource groups to control all of their members collectively. A resource group is simply an identifier that Azure Resource Manager applies to resources to group them together. This resource group ID allows Azure Resource Manager to perform operations on a group of resources that share this ID. |
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 Azure 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 Azure 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 Azure 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 Azure 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: Azure 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 bottom Microsoft.web/sites group bar, the display automatically expands to show all metrics for this selection.
Figure: Microsoft.web/sites metrics
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 Azure metric name or a Azure 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. |
Leaving the threshold fields blank will disable threshold triggers.
Metrics come in two flavors: they can either be Normal or Synthetic metrics.
Appendix A: Azure Authentication
To access Azure, the connector requires an authentication (auth) file.
In order for the CloudHub connector to securely log into an Azure subscription without requiring the user to log in manually, the connector can authenticate with credentials based on the Azure Active Directory service principal functionality. A service principal is analogous to a user account, but it is intended for applications like CloudHub to authenticate themselves without human intervention.
The auth file can be generated with the Azure CLI. The CLI can be installed on any laptop or server. To install, follow the instructions here for Windows, Mac, or Linux:
https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest
Once the CLI is installed, you can easily create a service principal and grant it access privileges for a given subscription through Azure CLI 2.0:
az login \-u (username) az ad sp create-for-rbac \--sdk-auth > cloudhub.azureauth
If you cannot use the Azure command line tool, the interactive process of creating the file via the Azure portal to generate credentials is documented here:
Once the file is generated, upload it into Cloud Hub (e.g., /usr/local/groundwork/config/cloudhub/azure/cloudhub.azureauth), Save, and Test to ensure you have proper access.
Figure: Configuration File entry