# VMWare vSphere ## Overview The VMWare vSphere StackPack is used to create a near real-time synchronization with VMWare vSphere. This StackPack provides functionality that allows monitoring of the following resources: * Hosts * VirtualMachines * ComputeResources * ClusterComputeResources * DataStores * DataCenters VMWare vSphere is a [StackState core integration](https://archivedocs.stackstate.com/5.1/stackpacks/about_integrations#stackstate-core-integrations). ![Data flow](https://2702698828-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Ft9xRpVRApnyVQrX3f8HH%2Fuploads%2Fgit-blob-235099ade63f684f470e539c4c297f0192e6ee6e%2Fstackpack-vmware.svg?alt=media) The VMware StackPack collects all topology data for the components and relations between them as well as telemetry and events. * StackState Agent V3 connects to the configured VMWare vSphere instance: * Topology data and tags are retrieved for the configured resources. * Metrics data is retrieved for the configured resources. * The Agent watches the vCenter Event Manager for events related to the configured resources. * StackState Agent V3 pushes retrieved data and events to StackState: * [Topology data](#topology) is translated into components and relations. * [Tags](#tags) defined in VMWare vSphere are added to components and relations in StackState. Any defined StackState tags are used by StackState when the topology is retrieved. * [Metrics data](#metrics) is automatically mapped to associated components and relations in StackState. * [Events](#events) are available as a telemetry stream in StackState. ## Setup ### Prerequisites To set up the StackState VMWare vSphere integration, you need to have: * [StackState ](https://archivedocs.stackstate.com/5.1/setup/agent/about-stackstate-agent)installed on a single machine with HTTPS connection to both vSphere vCenter and StackState. * A running vSphere vCenter instance. ### Install The VMWare vSphere StackPack can be installed from the StackState UI **StackPacks** > **Integrations** screen. You will need to enter the following details: * **VSphere Host Name** - The VMWare vSphere host name from which data will be collected. ### Configure To enable the VMWare vSphere check and begin collecting data from your vSphere vCenter instance: 1. Edit the Agent integration configuration file `/etc/stackstate-agent/conf.d/vsphere.d/conf.yaml` to include details of your vSphere vCenter instance: * **name** - aA unique key representing your vCenter instance. * **host** - The same as the `VSphere Host Name` used when the StackPack was installed. * **username** - The username to use when connecting to VMWare vSphere. * **password** - Use [secrets management](https://archivedocs.stackstate.com/5.1/configure/security/secrets_management) to store passwords outside of the configuration file. ``` # Section used for global vsphere check config init_config: instances: - name: # for example main-vcenter host: # for example vcenter.domain.com username: password: ``` 2. If required, you can customise the integration using the [advanced configuration options](#advanced-configuration). 3. [Restart StackState ](https://archivedocs.stackstate.com/5.1/setup/agent/about-stackstate-agent#deployment)to publish the configuration changes. 4. Once the Agent has restarted, wait for the Agent to collect the data and send it to StackState. #### Advanced configuration The advanced configuration items described below can optionally be added to the VMWare vSphere check configuration file. Further details can be found in the [example configuration file (github.com)](https://github.com/StackVista/sts-agent-integrations-core/blob/master/vsphere/conf.yaml.example). | Options | Required? | Description | | ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `all_metrics` | No | Default `false`. Set to `true` to collect *every* metric. This will collect a LOT of metrics that you probably don't need. When set to `false` (default), a selected set of metrics that are interesting to monitor will be collected. Note that when using both `all_metrics` and `collection_level` setting `all_metrics` will be ignored. | | `collection_level` | No | Specify the metrics to retrieve using a [data collection level (docs.vmware.com)](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.monitoring.doc/GUID-25800DE4-68E5-41CC-82D9-8811E27924BC.html) (a number between 1 and 4). Note that when using both `all_metrics` and `collection_level` setting `all_metrics` will be ignored. | | `ssl_verify` | No | Set to `false` to disable SSL verification when connecting to vCenter. | | `ssl_capath` | No | The absolute file path of a directory containing CA certificates in PEM format. | | `host_include_only_regex` | No | Use a regex pattern to only fetch metrics for these ESXi hosts and the VMs running on them. | | `vm_include_only_regex` | No | Use a regex to include only VMs that match the specified pattern. | | `include_only_marked` | No | Set to `true`, if you would like to only collect metrics on vSphere VMs that are marked by a custom field with the value `StackStateMonitored`. To set this custom field with PowerCLI, use the command: \`Get-VM | | `collect_vcenter_alarms` | No | set to `true` to send vCenter alarms as events. | ### Status To check the status of the VMWare vSphere integration, run the status subcommand and look for vSphere under `Running Checks`: ``` sudo stackstate-agent status ``` ## Integration details ### Data retrieved The VMWare vSphere integration retrieves the following data: * [Events](#events) * [Metrics](#metrics) * [Tags](#tags) * [Topology](#topology) #### Events VMWare vSphere events are sent to StackState in a telemetry stream. These can be mapped to components and relations in the StackState topology, however, they won't be visible in the StackState Events Perspective. The VMWare vSphere check watches the vCenter Event Manager for the events listed below and makes these available in StackState in the generic events topic telemetry stream: * AlarmStatusChangedEvent:Gray * VmBeingHotMigratedEvent * VmReconfiguredEvent * VmPoweredOnEvent * VmMigratedEvent * TaskEvent:Initialize powering On * TaskEvent:Power Off virtual machine * TaskEvent:Power On virtual machine * TaskEvent:Reconfigure virtual machine * TaskEvent:Relocate virtual machine * TaskEvent:Suspend virtual machine * TaskEvent:Migrate virtual machine * VmMessageEvent * VmSuspendedEvent * VmPoweredOffEvent #### Metrics The metrics retrieved from VMWare vSphere can be configured in the Agent check configuration file using the configuration items **collection\_level** and **all\_metrics**. For details see the section [advanced configuration of the VMWare vSphere check](#advanced-configuration) (above) and the vmware docs on [Data Collection Levels (docs.vmware.com)](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.monitoring.doc/GUID-25800DE4-68E5-41CC-82D9-8811E27924BC.html). #### Tags All tags defined in VMWare vSphere will be retrieved and added to the associated components and relations in StackState. The VMWare vSphere integration also understands StackState [common tags](https://archivedocs.stackstate.com/5.1/configure/topology/tagging#common-tags). These StackState tags can be assigned to elements in VMWare vSphere to influence the way that the resulting topology is built in StackState. For example, by placing a component in a specific layer or domain. #### Topology The VMWare vSphere integration retrieves the following topology data: * Components * Relations {% hint style="info" %} The VMWare vSphere integration understands StackState [common tags](https://archivedocs.stackstate.com/5.1/configure/topology/tagging#common-tags). These StackState tags can be assigned to elements in VMWare vSphere to influence the way that the resulting topology is built in StackState. For example, by placing a component in a specific layer or domain. {% endhint %} #### Traces The VMWare vSphere integration doesn't retrieve any traces data. ### REST API endpoints The VMWare vSphere integration connects to VMWare vSphere using the VMWare vSphere client library and Python modules `pyvim` and `pyVmomi`. No API endpoints are used. ### Open source The code for the StackState VMware vSphere check is open source and available on GitHub at: ## Troubleshooting Troubleshooting steps for any known issues can be found in the [StackState support Knowledge base](https://support.stackstate.com/hc/en-us/search?category=360002777619\&filter_by=knowledge_base\&query=vSphere). ## Uninstall To uninstall the VMWare vSphere StackPack and disable the VMWare vSphere check: 1. Go to the StackState UI **StackPacks** > **Integrations** > **VMWare vSphere** screen and click UNINSTALL. * All VMWare vSphere specific configuration will be removed from StackState. 2. Remove or rename the Agent integration configuration file, for example: ``` mv vsphere.d/conf.yaml vsphere.d/conf.yaml.bak ``` 3. [Restart StackState ](https://archivedocs.stackstate.com/5.1/setup/agent/about-stackstate-agent#deployment)to apply the configuration changes. ## Release notes **VMWare vSphere StackPack v2.3.3 (2022-06-03)** * Improvement: Updated documentation **VMWare vSphere StackPack v2.3.2 (2022-04-20)** * Improvement: Added collection level setting info. **VMWare vSphere StackPack v2.3.1 (2021-04-12)** * Improvement: Common bumped from 2.5.0 to 2.5.1 ## See also * [StackState](https://archivedocs.stackstate.com/5.1/setup/agent/about-stackstate-agent) * [Secrets management](https://archivedocs.stackstate.com/5.1/configure/security/secrets_management) * [StackState Agent integrations - VMWare vSphere (github.com)](https://github.com/StackVista/stackstate-agent-integrations/tree/master/vsphere) * [Example VMWare vSphere check configuration file (github.com)](https://github.com/StackVista/sts-agent-integrations-core/blob/master/vsphere/conf.yaml.example) * [Data Collection Levels (docs.vmware.com)](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.monitoring.doc/GUID-25800DE4-68E5-41CC-82D9-8811E27924BC.html)