Datadog
DataDog Agent Plugin Details
Getting Started
The DataDog Agent is deployed to VNS3 as a plugin.
Please be familiar with the VNS3 Plugins Guide.
An overview video of the plugin and deployment/configuration can be found on our YouTube channel: https://youtu.be/DLcEDx1mVaA
What does it do?
The DataDog Agent Container collects information from the VNS3 API, SNMP, system logs, and/or netflow, and sends reports to DataDog.
These data can be displayed as graphs or binary status checks, with certain conditions triggering alerts.
The goal is to collect auditable logs and system health information and to prevent outages through monitoring and alerting.
What does it need?
The DataDog Agent setup script inside the container requires the following information at minimum:
- An API token for the VNS3 API
- A DataDog API key associated with your account
- The DataDog “site” where your account resides
Other commonly changed values which come with sane defaults include:
- A unique hostname to identify the Agent (default: container name)
- A hostname/address and port at which the host VNS3 controller can be reached (default: plugin bridge gateway, port 8000)
- A decision regarding whether to report the state of overlay clients which are not “Checked Out” (default: false)
- A decision regarding how often data will be gathered from VNS3 and reported to DataDog (default: 60s)
These may be configured at launch time through environment variables, or later through Plugin Manager. Additional configuration options are available through Plugin Manager once deployed.
Deploying
Installing the VNS3 Integration
You will need to install the VNS3 Integration in your DataDog account.
Search for “VNS3” in the Integrations Marketplace and click Install. There is no further Integration configuration required.
Getting the Plugin
The Linux-based DataDog Agent Plugin Image is accessible through the Plugin catalog in VNS3.
It can also be imported manually or via the API with this URL: https://cohesive-networks.s3.amazonaws.com/plugins/vns3-container-datadog-20240916-2.1.tar.gz and this startup command: /opt/cohesive/container_startup.sh.
Starting the Plugin
Navigate to the Plugins -> Dashboard page. When the image has finished importing, it will say Ready in the Status Column.
To launch a plugin from the image, choose Start Instance from the Action menu and provide a name. You may optionally specify a particular plugin network address.
Initial configuration can optionally be provided through environment variables under the Advanced dropdown:
dd_api_key: Your DataDog account API key
dd_site: Your DataDog account “site”
vns3_api_token: A refreshing API token from VNS3
hostname: The hostname used by dd-agent which will appear in the DataDog console
vns3_api_host: The IP/hostname:port where the VNS3 API can be reached
vns3_api_interval: How often, in seconds, to poll the VNS3 API for state
report_all_clients: Whether to report connection state of all overlay clients or only those which are “checked out”
All options may be configured after launching the plugin.
Take note of the IP address assigned to the plugin for the next step.
Required VNS3 Firewall Rules
The DataDog Agent Container requires the following firewall rules be added to the VNS3 controller.
Anywhere it appears, replace <plugin_ip> with the address of your new plugin.
# Allow DataDog plugin to reach internet
FORWARD -s <plugin_ip> -o eth0 -j ACCEPT
# Allow replies back to DataDog plugin (not needed if you have a global stateful rule)
FORWARD -m conntrack --ctstate RELATED,ESTABLISHED -i eth0 -d <plugin_ip> -j ACCEPT
# SNAT for dd-agent to reach datadog for reporting
POSTROUTING -o eth0 -s <plugin_ip> -j MASQUERADE-ONCE
# Accept incoming API connections from dd-vns3 poller
INPUT -p tcp --dport 8000 -s <plugin_ip> -j ACCEPT
# Accept incoming SNMP from DataDog container (if applicable)
INPUT -p udp -s <plugin_ip> --dport snmp -j ACCEPT
# Allow returning API responses to dd-vns3 poller
OUTPUT -p tcp --sport 8000 -d <plugin_ip> -j ACCEPT
# Allow returning SNMP traffic (if applicable)
OUTPUT -p udp -d <plugin_ip> --sport snmp -j ACCEPT
# Allow netflow packets to dd plugin (if applicable; change port if other than 2055)
OUTPUT -p udp -d <plugin_ip> --dport 2055 -j ACCEPT
Configure the Plugin
After creating the plugin instance and applying the necessary firewall rules to VNS3, navigate to the Instances tab on the Plugins -> Dashboard page, then click on the name of your new plugin to access the plugin manager page.
Configuration should be placed into the appropriate files tabbed on the righthand frame. The What does it need? section details the information required. Additional dd-agent configuration can be provided according to DataDog’s documentation.
API Tokens can be generated on the Access Management page in VNS3. This plugin requires a refreshing token; we recommend a life of 7 days.
A DataDog account API key can be created or retrieved from the Organization Settings > API Keys page in the DataDog console. Your DataDog account “site” can be found by correlating your console URL with the table found on this page.
If you enable logging or SNMP, you must also define specific configuration in those services' respective config files. If you will be collecting netflow, you can also start VNS3 sending netflow reports to this plugin using that executable.
Once all configuration has been saved, run “Initialize” from the executables dropdown in the lefthand frame.
Future configuration changes can be read in using the initialize executable, by restarting the plugin, or by restarting the appropriate processes.
Create Status checks on a Dashboard
Custom Metrics
The integration reports six custom status checks; their names are vns3.overlay.clients, vns3.peering, vns3.overlay.links, vns3.ipsec, vns3.interfaces, and vns3.sys_admin.remote_support.
To create a status check widget, open a DataDog Dashboard and select Edit Board.
Drag a new Check Status widget from the widget bar onto your dashboard.
Select the appropriate status check from the dropdown, select Statuses for: A Cluster of Checks, select Reported by: host:[agent hostname], and then Group by: the appropriate tag:
- For vns3.overlay.clients, choose “ip”.
- For vns3.peering, choose “peerid”.
- For vns3.ipsec, choose “tunnel”. (If you wish to create a widget for a specific Endpoint, choose that endpoint in the “Statuses for:” box.)
- For vns3.overlay.links, choose “name”.
- For vns3.interfaces, choose “name”.
- vns3.sys_admin.remote_support has no grouping, as it is a global option on each controller.
An example dashboard in importable JSON format is available here: VNS3ExampleDashboard-20240923.json
Standard Data
SNMP, Netflow, and Logging functionality are handled according to DataDog’s documentation and recommendations.
Final Notes
It may take 10-15 minutes for the agent to appear in your DataDog account, metrics to populate, and logs to begin appearing. This delay is inherent to the DataDog platform.
VNS3 will include your plugin configuration in its system snapshots. We recommend saving these regularly. VNS3 Management System provides options for automatic scheduled snapshotting. Upon recovery with a snapshot file, VNS3 will attempt to download all plugin images from their original URLs and reinstall their saved configuration.
Please reach out to support@cohesive.net with any issues or questions.