<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/snmp/npm-catalog/integrations/vsphere_topology.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/go/plugin/go.d/collector/snmp/npm-catalog/metadata.yaml"
sidebar_label: "vSphere Topology"
learn_status: "Published"
learn_rel_path: "Network Performance Monitoring/Topologies/Integrations"
keywords: ['vsphere', 'vmware', 'vcenter', 'virtualization', 'topology', 'npm']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE NPM CATALOG metadata.yaml FILE"
endmeta-->

<!-- markdownlint-disable-file -->

# vSphere Topology


<img src="https://netdata.cloud/img/vmware.svg" width="150"/>


Plugin: go.d.plugin
Module: vsphere

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## Overview

Map VMware vSphere infrastructure. The vSphere collector renders clusters, hosts, VMs, and datastores with placement links and datastore-utilization overlays; enabling `collect_network_topology` adds the network and port-group attachments.

The vSphere collector reads the vCenter inventory and renders it as a `netdata.topology.v1` graph.

This integration is supported on all platforms.

This integration supports multiple instances configured side-by-side.


### Default Behavior

#### Auto-Detection

Built from the configured vCenter inventory.

#### Limits

The default configuration for this integration does not impose any limits.

#### Performance Impact

The default configuration for this integration is not expected to impose a significant performance impact on the system.

## Setup


You can configure the **vsphere** collector in two ways:

| Method                | Best for                                                                                 | How to                                                                                                                                 |
|-----------------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
| [**UI**](#via-ui)     | Fast setup without editing files                                                         | Go to **Nodes → Configure this node → Collectors → Jobs**, search for **vsphere**, then click **+** to add a job. |
| [**File**](#via-file) | If you prefer configuring via file, or need to automate deployments (e.g., with Ansible) | Edit `go.d/vsphere.conf` and add a job.                                                                        |

:::important

UI configuration requires paid Netdata Cloud plan.

:::


### Prerequisites

#### vCenter access

A vCenter Server reachable from the Netdata Agent, and a read-only account with permission to browse the inventory.


### Configuration

#### Options

Configure the vSphere collector with the vCenter URL and credentials. See the [vSphere collector](https://github.com/netdata/netdata/blob/master/src/go/plugin/go.d/collector/vsphere/integrations/vmware_vcenter_server.md) page for all options, including `collect_network_topology`, which is off by default and is what adds the network and port-group actors to the map.


#### via UI

Configure the **vsphere** collector from the Netdata web interface:

1. Go to **Nodes**.
2. Select the node **where you want the vsphere data-collection job to run** and click the :gear: (**Configure this node**). That node will run the data collection.
3. The **Collectors → Jobs** view opens by default.
4. In the Search box, type _vsphere_ (or scroll the list) to locate the **vsphere** collector.
5. Click the **+** next to the **vsphere** collector to add a new job.
6. Fill in the job fields, then click **Test** to verify the configuration and **Submit** to save.
    - **Test** runs the job with the provided settings and shows whether data can be collected.
    - If it fails, an error message appears with details (for example, connection refused, timeout, or command execution errors), so you can adjust and retest.


#### via File

The configuration file name for this integration is `go.d/vsphere.conf`.

The file format is YAML. Generally, the structure is:

```yaml
update_every: 1
autodetection_retry: 0
jobs:
  - name: some_name1
  - name: some_name2
```
You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config go.d/vsphere.conf
```

##### Examples

###### Minimal job with topology enabled

The three required fields plus `collect_network_topology`, which is off by default and is what adds the network and port-group actors to the map.

```yaml
jobs:
  - name: vcenter
    url: https://vcenter.example.com
    username: netdata@vsphere.local
    password: SECRET
    collect_network_topology: yes

```


## Alerts

There are no alerts configured by default for this integration.



## Metrics
