---
title: "How to automate Ansible reporting + deployment of the Datadog Agent"
description: "This step-by-step guide shows you how to deploy Datadog with Ansible, and get real-time Ansible reporting in Datadog."
author: "Boyan Syarov"
date: 2018-01-22
tags: ["infrastructure monitoring", "datadog agent", "ansible", "configuration management", "monitoring as code"]
blog_type_id: the-monitor
locale: en
---

Ansible is an infrastructure automation solution that enables users to provision, deploy, and manage their infrastructure and applications. Ansible roles, which are similar to Puppet modules and Chef cookbooks, are shippable modules that users can download from the open source [Ansible Galaxy](https://galaxy.ansible.com/explore#) in order to quickly accomplish important tasks, such as installing a database and configuring its service.

Datadog's Ansible role and integration enable you to go a step beyond infrastructure as code to implementing *monitoring* as code. The [Datadog Ansible role](https://galaxy.ansible.com/Datadog/datadog/) allows you to deploy the Datadog Agent and enable other Datadog integrations, while the [callback plugin](https://github.com/DataDog/ansible-datadog-callback) provides Ansible reporting and visibility into key metrics and events, including failed tasks, in an out-of-the-box dashboard like the one shown below.

![Datadog Ansible default dashboard](https://web-assets.dd-static.net/42588/1776299019-deploy-datadog-ansible-reporting-ansible-reporting-screenboard-overview.png)

In this guide, we will show you how to use this [Ansible role](https://galaxy.ansible.com/Datadog/datadog/) and [callback plugin](https://github.com/DataDog/ansible-datadog-callback) to quickly deploy the Datadog Agent on a node, and track Ansible performance metrics and events in Datadog. To follow along, you'll need a Datadog account. (If you’re not yet a Datadog user, sign up for a free trial <!-- Sign-up trigger (here) omitted -->.)

## Installing Ansible

Unlike many other configuration management solutions, Ansible follows the push method, so you only need to install Ansible on a control machine (the system you're going to push from)—you won't need to install it on any of the nodes that you intend to manage. Installing Ansible is as easy as running:

```text
pip install ansible
```

You also have the option to [install it via your distribution's package manager](http://docs.ansible.com/ansible/latest/intro_installation.html). Next, you'll need to clone [the example repository](https://github.com/DataDog/dd_ansible_example.git) on your control machine:

```text
git clone https://github.com/DataDog/dd_ansible_example.git
```

Then navigate into the repo and install its dependencies:

```text
pip install -r requirements.txt
```

Typically, you would install an Ansible role with the `ansible-galaxy` command, but in this case, we can skip that step because the `dd_ansible_example` repository already includes a copy of the Datadog role. This repository also includes a callback plugin that will send Ansible events to Datadog. (Normally, you would install that on your server by following the steps outlined [here](https://github.com/DataDog/ansible-datadog-callback).)

Note: In this guide, all file paths and commands will be listed relative to the location of the local `dd_ansible_example` repository on your control machine.

## Using the Datadog Ansible role + integration

1. In order to start using Datadog's Ansible role and integration, we'll need to source the `setenv` file to tell Ansible a few things about our environment (where the `hosts` file lives, where to access the Ansible configuration file, etc.).

```text
source setenv
```

1. Next, we need to tell Ansible the [fully qualified domain names](http://docs.ansible.com/ansible/latest/playbooks_lookups.html#the-dns-lookup-dig) (FQDNs) or IPs of the nodes we want to manage. In this example, we are managing a single node (an Ubuntu 14 instance), so we only need to add that Ubuntu instance's FQDN to the `./hosts` file:

```text
echo "yourinstance.fqdn.name" >> ./hosts
```

1. Add a valid API key (accessible in your Datadog account [here](https://app.datadoghq.com/account/settings#api)) to the playbook (`./playbooks/dd_agent.yml`). You'll also need to add it to the callback plugin, (`./playbooks/callback_plugins/datadog_callback.yml`) where indicated. This will allow the plugin to report the results of playbook runs to the Datadog event stream. Alternatively, you can also choose to set your Datadog API key in the callback by using an environment variable or [hostvars](http://docs.ansible.com/ansible/latest/playbooks_variables.html), as explained [in the callback documentation](https://github.com/DataDog/ansible-datadog-callback).
1. Ansible uses SSH to push changes from the control machine (wherever you installed Ansible and the example repository) to the remote system it needs to manage. Before you can execute your first Ansible command, you'll need to set up SSH access, as outlined [in the Ansible documentation](http://docs.ansible.com/ansible/latest/intro_getting_started.html#remote-connection-information). Once you've set up SSH access between your control machine and your remote node, go ahead and test it out by running:

```text
ansible -m ping -i hosts mynodes
```

You should see something similar to the following output:

```text
yourinstance.fqdn.name | SUCCESS => {
    "changed": false,
    "ping": "pong"
}
```

This indicates that Ansible was able to successfully contact your remote node.

1. Now we're ready to actually run our Ansible playbook, which will call the Datadog role and install the Datadog Agent on your node. Switch into the `playbooks` directory and run the playbook:

```text
ansible-playbook dd_agent.yml
```

The output of this command will give you details of the individual tasks being performed. It will also generate two events and send them to Datadog: one that marks the start of a playbook run, and another that marks its completion. If any errors occur during the run of the playbook, they will also be displayed in the event description. Navigate to your [Datadog event stream](https://app.datadoghq.com/event/stream) to see the results of your Ansible playbook run, which should look something like this:

![Datadog Ansible](https://web-assets.dd-static.net/42588/1776299023-deploy-datadog-ansible-reporting-ansible-reporting-datadog-event-stream2.png)

This tells us that Ansible successfully deployed the Datadog Agent on the node listed in our `hosts` file.

## Breaking down the rules of the playbook

Let's take a closer look behind the scenes to understand how Ansible followed our playbook (`./playbooks/dd_agent.yml`) to execute the Agent push.

```text
- hosts: mynodes
  remote_user: ubuntu
  become: yes
  roles:
      - role: Datadog.datadog
  vars:
    datadog_api_key: <YOUR API KEY>
    datadog_agent_version: 1:5.20.2-1
```

The `hosts` section defines the [group of hosts](http://docs.ansible.com/ansible/latest/intro_inventory.html#hosts-and-groups) we're pushing to—in this case, the group name `mynodes` that was predefined in our `hosts` file. In a [previous step](#using-the-datadog-ansible-role--integration), we used `echo` to add the FQDN of our server to the `mynodes` group of the `hosts` file.

`remote_user: ubuntu` refers to the SSH username that Ansible should use in order to execute this push on the remote host, and `become: yes` allows the specified user to [elevate to `sudo` privileges](http://docs.ansible.com/ansible/latest/become.html) if necessary (required for package installs and service reboots).

Over the next few lines, we call the Datadog role and pass two variables to it: our API key and the version of the Agent we want to push. Specifying a version number is optional, but highly recommended. For example, to deploy version 5.20.2 of the Agent, you would specify `1:5.20.2-1` on apt-based distributions, or `5.20.2-1` on yum-based distributions.

In less than 10 lines, we set up Ansible to deploy the Datadog Agent on a remote server. We easily could have pushed the Agent to many more systems simply by adding them to the `mynodes` section of our Ansible `hosts` file.

## Real-time Ansible reporting in Datadog

One key benefit of using [Datadog's Ansible integration](https://www.datadoghq.com/blog/ansible-datadog-monitor-your-automation-automate-your-monitoring.md) is that you'll automatically get access to an [out-of-the-box dashboard](https://app.datadoghq.com/screen/integration/84/Ansible) that provides a high-level overview of Ansible performance and activity. You'll also be able to view dashboards for any of the integrations that you enable using the Datadog Ansible role.

You can use this dashboard to track key information about Ansible performance, including the average time it takes to execute playbooks and the percentage of changes resulting from those pushes. You can also clone and modify this dashboard to get deeper insights into changes as they are deployed across your infrastructure and applications.

### Correlate Ansible events with metrics

Because [Datadog's callback plugin](https://github.com/DataDog/ansible-datadog-callback) provides real-time Ansible reporting, you can overlay playbook executions and failures over any timeseries graph to help troubleshoot and investigate issues across your infrastructure and applications. Below, we searched for Ansible events and overlaid them on a dashboard that tracks the performance of one of our applications.

![Track Ansible events in Datadog event stream](https://web-assets.dd-static.net/42588/1776299027-deploy-datadog-ansible-reporting-ansible-reporting-datadog-event-overlay2.png)

Each vertical red band represents an Ansible push event. In this case, we are hovering over two events (shown in purple on each timeseries graph), which are highlighted in the stream on the left, to investigate if a rise in application latency is correlated with the execution of an Ansible playbook. This functionality greatly reduces time to resolution when investigating an incident.

## Configuring Ansible playbooks  

The playbook in our [example repo](https://github.com/DataDog/dd_ansible_example.git) is just a starting point—you can also create an Ansible playbook that not only installs the Agent but also enables specific Datadog integrations for the applications running on those nodes. Our example repository includes a sample playbook (`./playbooks/dd_agent_nginx.yml`) that you can modify to enable Datadog's NGINX integration. To set it up, edit the playbook to match your `/nginx_status` configuration. (Consult our [NGINX documentation](https://docs.datadoghq.com/integrations/nginx.md#connect-the-agent) for more details.) Then you're all set to execute the playbook:

```text
ansible-playbook dd_agent_nginx.yml
```

This will install and configure the Datadog Agent to collect and report NGINX metrics so that you can monitor them in Datadog.

Note that you can call multiple roles from a single Ansible playbook: for example, one role that installs and configures a database on a set of servers, and another that deploys the Datadog Agent on those nodes. You can even create a playbook that uses Datadog's Ansible role to enable more than one Datadog integration at a time (including for that database you just deployed) by updating the `datadog_checks` variable with the configuration for each Agent check you want to set up. To see an example, [here's a playbook](https://github.com/DataDog/ansible-datadog#example-playbooks) that sets up three Datadog Agent checks. As with any other infrastructure-wide change, make sure to test each playbook extensively before deploying it in a production environment.

## Track Ansible performance + more with Datadog

In this guide, we walked through a basic example of using the Datadog Ansible role and [callback plugin](https://github.com/DataDog/ansible-datadog-callback) to deploy the Datadog Agent on a node and to get Ansible reporting in Datadog. The [example repo](https://github.com/DataDog/dd_ansible_example.git) is only designed to demonstrate how Datadog's Ansible role and callback plugin work in a testing capacity. In order to run it on a larger scale, we recommend installing the [Datadog role from the Ansible Galaxy](https://github.com/DataDog/ansible-datadog) and reading through the documentation. To collect Ansible performance metrics and events, and send them to Datadog, you will also need to install the [callback plugin as described here](https://github.com/DataDog/ansible-datadog-callback).

If you're already using Datadog and Ansible, check out our Ansible [role](https://github.com/DataDog/ansible-datadog) and our [callback plugin](https://github.com/DataDog/ansible-datadog-callback) documentation to learn how you can use Ansible and Datadog together to automate your configuration management *and* your monitoring. If you're new to Datadog, get started with a <!-- Sign-up trigger (14-day free trial) omitted -->.