Install and configure Datadog Agent & checks. The version 4 of this role installs the Datadog Agent version 7 by default.

Supports most Debian and RHEL-based Linux distributions, and Windows.

• Installation
• Role Variables
• Role upgrade from v3 to v4
• datadog_agent_version variable
• Agent v5 (older version)
• Agent version downgrades
• Dependencies
• Configuring a check
  • Process Check
  • Custom Check
  • Autodiscovery Check
• Upgrading an integration
  • Example
• Example Playbooks
• APM
• Process Agent
  • Variables
  • System Probe
  • Example of configuration
  • Agent 5
• Additional tasks
• Known Issues and Workarounds
  • dirmngr
  • Datadog Agent 6.14 for Windows
• Development
• License
• Author Information

ansible-galaxy install datadog.datadog

The datadog_agent_major_version variable has been introduced, to tell the module which major version of the Agent will be installed, 7 by default. To install Agent v5, set it to 5. To install Agent v6, set it to 6.

The datadog_agent5 variable is thus obsolete and has been removed.

To behavior of the datadog_apt_repo, datadog_yum_repo, and datadog_zypper_repo variables has been modified. When they are not set, the official Datadog repositories for the major version set in datadog_agent_major_version are used:

To override the default behavior, set the datadog_apt_repo, datadog_yum_repo, or datadog_zypper_repo variables to something else than an empty string.

If you were previously using the Agent v5 variables datadog_agent5_apt_repo, datadog_agent5_yum_repo, or datadog_agent5_zypper_repo to set custom Agent v5 repositories, use datadog_apt_repo, datadog_yum_repo, or datadog_zypper_repo(with datadog_agent_major_version set to 5 or datadog_agent_version pinned to a specific Agent v5 version) instead.

To install Agent v5 with the v4 role, follow the instructions in the Agent v5 section. To downgrade an Agent installation with the v4 role, follow the instructions in the Agent downgrade section.

To behavior of the datadog_windows_download_url variable has been modified. When not set, the official Windows msi package corresponding to the datadog_agent_major_version is used:

To override the default behavior, set the datadog_windows_download_url variable to something else than an empty string.

Starting with version 3 of this role, when the datadog_agent_version variable is used to pin a specific Agent version, the role will derive per-OS version names to comply with the version naming schemes of the operating systems we support (eg. 1:7.16.0-1 for Debian- and SUSE- based, 7.16.0-1 for Redhat-based and 7.16.0 for Windows).

This makes it possible to target hosts running different operating systems in the same Ansible run.

For instance, you can now provide:

datadog_agent_version: 7.16.0

and the role will install 1:7.16.0-1 on Debian- and SUSE-based systems, 7.16.0-1 on Redhat-based systems, and 7.16.0 on Windows (if not provided, the role uses 1 as the epoch, and 1 as the release number).

Alternatively, you can provide:

datadog_agent_version: 1:7.16.0-1

and the role will install 1:7.16.0-1 on Debian- and SUSE-based systems, 7.16.0-1 on Redhat-based systems, and 7.16.0 on Windows.

This role includes support for Datadog Agent version 5 for Linux only.

To install Agent v5, either set datadog_agent_major_version to 5 to install the latest version of Agent v5 or set datadog_agent_version to an existing Agent v5.

To downgrade to a prior version of the Agent, you need to (on centos this will only work with ansible 2.4 and up):

1. Set datadog_agent_version to a specific version to downgrade to (ex: 5.32.5),
2. Set datadog_agent_allow_downgrade to yes.

Note: downgrades are not supported on Windows platforms.

None

To configure a check you need to add an entry to the datadog_checks section. The first level key is the name of the check and the value is the yaml payload to write the configuration file.

Example:

To define 2 instances for the process check use the configuration below:

    datadog_checks:
      process:
        init_config:
        instances:
          - name: ssh
            search_string: ['ssh', 'sshd' ]
          - name: syslog
            search_string: ['rsyslog' ]
            cpu_check_interval: 0.2
            exact_match: true
            ignore_denied_access: true

This creates the corresponding configuration files:

• For Agent v6: /etc/datadog-agent/conf.d/process.d/conf.yaml
• For Agent v5: /etc/dd-agent/conf.d/process.yaml

To configure a custom check use the configuration below:

    datadog_checks:
      my_custom_check:
        init_config:
        instances:
          - some_data: true

This creates the corresponding configuration files:

• For Agent v6: /etc/datadog-agent/conf.d/my_custom_check.d/conf.yaml
• For Agent v5: /etc/dd-agent/conf.d/my_custom_check.yaml

There is no pre-processing nor post-processing on the YAML. This means every YAML sections is added to the final configuration file, including autodiscovery identifiers.

The example below configures the PostgeSQL check through autodiscovery:

    datadog_checks:
      postgres:
        ad_identifiers:
          - db-master
          - db-slave
        init_config:
        instances:
          - host: %%host%%
            port: %%port%%
            username: username
            password: password

Learn more about Autodiscovery in the Datadog documentation.

Available for Agent v6.8+

The datadog_integration resource helps you to install specific version of a Datadog integration. Keep in mind the Agent comes with all the integrations already installed. So this command is here to allow you to upgrade a specific integration without upgrading the whole Agent. For more usage information consult the Agent documentation.

Available actions:

• install: Installs a specific version of the integration.
• remove: Removes an integration.

Syntax:

  datadog_integration:
    <INTEGRATION_NAME>:
      action: <ACTION>
      version: <VERSION_TO_INSTALL>

This example installs version 1.11.0 of the ElasticSearch integration and removes the postgres integration.

 datadog_integration:
   datadog-elastic:
     action: install
     version: 1.11.0
   datadog-postgres:
     action: remove

In order to get the available versions of the integrations, please refer to their CHANGELOG.md file in the integrations-core repository.

Sending data to Datadog US (default) and configuring a few checks.

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "123456"
    datadog_agent_version: "7.16.0"
    datadog_config:
      tags:
        - "env:dev"
        - "datacenter:local"
      log_level: INFO
      apm_config:
        enabled: true
        max_traces_per_second: 10
      logs_enabled: true  # log collection is available on Agent 6 and 7
    datadog_checks:
      process:
        init_config:
        instances:
          - name: ssh
            search_string: ['ssh', 'sshd' ]
          - name: syslog
            search_string: ['rsyslog' ]
            cpu_check_interval: 0.2
            exact_match: true
            ignore_denied_access: true
      ssh_check:
        init_config:
        instances:
          - host: localhost
            port: 22
            username: root
            password: changeme
            sftp_check: True
            private_key_file:
            add_missing_keys: True
      nginx:
        init_config:
        instances:
          - nginx_status_url: http://example.com/nginx_status/
            tags:
              - "source:nginx"
              - "instance:foo"
          - nginx_status_url: http://example2.com:1234/nginx_status/
            tags:
              - "source:nginx"
              - "instance:bar"

        #Log collection is available on Agent 6 and 7
        logs:
          - type: file
            path: /var/log/access.log
            service: myapp
            source: nginx
            sourcecategory: http_web_access
          - type: file
            path: /var/log/error.log
            service: nginx
            source: nginx
            sourcecategory: http_web_access
    # datadog_integration is available on Agent 6.8+
    datadog_integration:
      datadog-elastic:
        action: install
        version: 1.11.0
      datadog-postgres:
        action: remove
    system_probe_config:
      enabled: true

Example for installing the latest Agent 6:

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_agent_major_version: 6
    datadog_api_key: "123456"

Example for sending data to EU site:

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

On Windows, the become: yes option is not needed (and will make the role fail, as ansible won't be able to use it).

Below are two methods to make the above playbook work with Windows hosts:

Set the ansible_become option to no in the inventory file for each Windows host:

[servers]
linux1 ansible_host=127.0.0.1
linux2 ansible_host=127.0.0.2
windows1 ansible_host=127.0.0.3 ansible_become=no
windows2 ansible_host=127.0.0.4 ansible_become=no

To avoid repeating the same configuration for all Windows hosts, you can also group them and set the variable at the group level:

[linux]
linux1 ansible_host=127.0.0.1
linux2 ansible_host=127.0.0.2

[windows]
windows1 ansible_host=127.0.0.3
windows2 ansible_host=127.0.0.4

[windows:vars]
ansible_become=no

Alternatively, if your playbook only runs on Windows hosts, you can do the following in the playbook file:

- hosts: servers
  roles:
    - { role: datadog.datadog }
  vars:
    ...

Warning: this configuration will fail on Linux hosts (as it's not setting become: yes for them). Only use it if the playbook is specific to Windows hosts. Otherwise use the inventory file method.

To enable APM with Agent v6 use the following configuration:

datadog_config:
    apm_config:
        enabled: true

To enable APM with agent v5 use the following configuration:

datadog_config:
    apm_enabled: "true" # has to be a string

To control the behavior of the Process Agent, use the enabled variable under the datadog_config field. It has to be set as a string and the possible values are: true, false (for only container collection) or disabled (to disable the Process Agent entirely)

The following variables are available for the Process Agent:

• scrub_args: Enables the scrubbing of sensitive arguments from a process command line. Default value is true.
• custom_sensitive_words: Expands the default list of sensitive words used by the cmdline scrubber.

The network performance monitoring system probe is configured under the system_probe_config variable. Any variables nested underneath will be written to the system-probe.yaml.

Currently, the system probe only works on Linux with the Agent 6 version and beyond.

datadog_config:
  process_config:
    enabled: "true" # has to be set as a string
    scrub_args: true
    custom_sensitive_words: ['consul_token','dd_api_key']
system_probe_config:
  enabled: true
  sysprobe_socket: /opt/datadog-agent/run/sysprobe.sock

To enable/disable the Process Agent on Agent 5, you need to set on datadog_config the process_agent_enabled parameter to true/false.

Set the available variables inside process.config under the datadog_config_ex field to control the Process Agent's features.

datadog_config:
  process_agent_enabled: true
datadog_config_ex:
  process.config:
    scrub_args: true
    custom_sensitive_words: "consul_token,dd_api_key"

pre_tasks and post_tasks folders allow to run user defined tasks. pre_tasks for tasks to be executed before executing any tasks from the Datadog role and post_tasks for those to be executed after.

On Debian Stretch, the apt_key module that the role uses requires an additional system dependency to work correctly. Unfortunately that dependency (dirmngr) is not provided by the module. To work around this, you can add the following configuration to the playbooks that make use of the present role:

---
- hosts: all
  pre_tasks:
    - name: Debian Stretch requires dirmngr package to be installed in order to use apt_key
      become: yes  # On Ansible < 1.9, use `sudo: yes` instead of `become: yes`
      apt:
        name: dirmngr
        state: present

  roles:
    - { role: datadog.datadog, become: yes, datadog_api_key: "mykey" }  # On Ansible < 1.9, use `sudo: yes` instead of `become: yes`

Due to a critical bug in Agent versions 6.14.0 and 6.14.1 on Windows, these versions have been blacklisted (starting with the version 3.3.0 of this role).

PLEASE NOTE: ansible will fail on Windows if datadog_agent_version is set to 6.14.0 or 6.14.1. Please use 6.14.2 or above instead.

If you are updating from 6.14.0 or 6.14.1 on Windows, we strongly recommend following these steps:

1. Upgrade the present datadog.datadog ansible role to the latest version (>=3.3.0)
2. Set the datadog_agent_version to 6.14.2 or above (by default the role install latest).

To learn more about this bug, please read here.

To contribute, you will have to follow the contribution guide in CONTRIBUTING.md.

To test the roles provided by this project, you can follow the instructions in the manual tests readme.md.

This project uses kitchen as its integration tests engine. To really verify integration tests, you should have vagrant installed on your machine as it is used as driver-engine.

Kitchen allows you to test specific recipes described in kitchen.yml. For now, there is only a basic one on ubuntu but that should be enough to develop others or to add features in TDD.

To list available targets, you can use the list command:

bundle exec kitchen list

To test a specific target, you can run:

bundle exec kitchen test <target>

So for example, if you want to test the agent installation, you can run:

bundle exec kitchen test default-ubuntu-1810

More information about kitchen on its Getting Started.

To develop some fixes or some features, the easiest way is to work on the platform and version of your choice, setting the machine up with the create command and applying the recipe with the converge command. If you want to explore the machine and try different things, you can also login into the machine with the login command.

# Create the relevant vagrant virtual machine
bundle exec kitchen create default-ubuntu-1810

# Converge to test your recipe
bundle exec kitchen converge default-ubuntu-1810

# Login to your machine to check stuff
bundle exec kitchen login default-ubuntu-1810

# Verify the integration tests for your machine
bundle exec kitchen verify default-ubuntu-1810

# Clean your machine
bundle exec kitchen destroy default-ubuntu-1810

It is advised that you work in TDD and that you write tests before making changes so that developing your feature or fix is just making tests pass.

Apache2

brian@akins.org

dustinjamesbrown@gmail.com --Forked from brian@akins.org

Datadog info@datadoghq.com --Forked from dustinjamesbrown@gmail.com