Datadog Agent Ansible Role

The Datadog Agent Ansible role helps you install and set up the Datadog Agent along with its integrations.

Ansible Role vs. Ansible Collection

You can access the Datadog Agent Ansible role in two ways:

• As part of the Datadog collection on Ansible Galaxy, known as datadog.dd (recommended).
• As an independent role, available at datadog.datadog on Ansible Galaxy (legacy).

By default, both version 4 of the role and version 5 of the collection install Datadog Agent v7.

Setup

This document provides instructions for installing the standalone Datadog role. For details on the Datadog collection, check the collection README file. The setup variables are the same for both versions.

Requirements

• Ansible v2.6 or later is required.

• It supports most Debian and RHEL-based Linux, macOS, and Windows.

• From Ansible 2.10 onward, to manage Windows hosts, you need to install the ansible.windows collection:

  ansible-galaxy collection install ansible.windows
  

• For managing openSUSE/SLES with Ansible 2.10+, install the community.general collection:

  ansible-galaxy collection install community.general
  

Installation

Install the Datadog role on your Ansible server:

ansible-galaxy install datadog.datadog

To deploy the Datadog Agent on hosts, add the Datadog role and your API key to your playbook:

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "<YOUR_DD_API_KEY>"

You must provide the API key; if not, the role will fail. If you prefer to add it later, you can use a placeholder key.

Role Variables

These variables allow you to configure the Datadog Agent during installation, and should be specified in the vars section of your playbook.

Variable	Description
datadog_api_key	Your mandatory Datadog API key.
datadog_site	The Datadog site (defaults to datadoghq.com). Set to datadoghq.eu for the EU site (Agent version >= 6.6.0).
datadog_agent_flavor	Specify the package for IoT installations on Raspberry Pi (default is "datadog-agent"; use "datadog-iot-agent" for Raspberry Pi).
datadog_agent_version	Optional pinned version of the Agent to install (e.g., 7.16.0).
datadog_checks	YAML configuration for Agent checks.
datadog_disable_untracked_checks	Set to true to remove all untracked checks.
datadog_additional_checks	List of additional checks that are not removed if datadog_disable_untracked_checks is set to true.
datadog_disable_default_checks	Set to true to remove all default checks.
datadog_config	Configuration settings for the Datadog Agent. For a full list of options, check datadog.yaml.
datadog_enabled	Set to false to stop the datadog-agent service from starting (defaults to true).
datadog_agent_allow_downgrade	Set to yes to allow Agent downgrades (not supported on Windows).

Integrations

To configure a Datadog integration (check), add an entry to the datadog_checks section in your playbook, where the first-level key is the check name, and the value is its YAML configuration.

Tracing and Live Processes

To enable tracing and live process collection with Agent v6 or v7, use the configurations provided above. The possible values for live process enablement include "true", "false", or "disabled".

Example Playbooks

Here are a few example playbooks to help you get started:

Install Datadog and Enable Checks

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "<YOUR_DD_API_KEY>"
    datadog_checks:
      process:
        init_config:
        instances:
          - name: ssh
            search_string: ['ssh', 'sshd']

Configuring the Datadog Site

If you want to send data elsewhere (like datadoghq.eu), you can specify it in your playbook:

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_site: "datadoghq.eu"
    datadog_api_key: "<YOUR_DD_API_KEY>"

Uninstallation

To uninstall the Datadog Agent on Windows, you can use the following commands in your Ansible role:

- name: Check If Datadog Agent is installed
  win_shell: |
    (@(Get-ChildItem -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" -Recurse) | Where {$_.GetValue("DisplayName") -like "Datadog Agent" }).PSChildName
  register: agent_installed_result
- name: Uninstall the Datadog Agent
  win_package:
    product_id: "{{ agent_installed_result.stdout | trim }}"
    state: absent
  when: agent_installed_result.stdout != ""

Troubleshooting

If you encounter issues, here are a few tips:

• Ensure you are using a supported version of Ansible and your OS.
• If the Agent version is not being installed correctly, check your playbook variables.
• On Windows, avoid setting become: yes to prevent permission issues.

This summary covers the foundational aspects of the Datadog Agent Ansible role, making it easy to set up, configure, or troubleshoot.