Deploying the Agent with Chef

NOTICE:アクセスいただきありがとうございます。こちらのページは現在英語のみのご用意となっております。引き続き日本語化の範囲を広げてまいりますので、皆様のご理解のほどよろしくお願いいたします。

Overview

In this guide, we will explore how to leverage Chef to automate installation of the Datadog Agent

Deploying Datadog with Chef is meant to be very simple, and provide you with a method of getting the value of monitoring across all of your infrastructure as simply as possible.

We also provide a Chef Execution and Report Handler that can capture chef-client failures as well as metrics related to the Chef run, such as timing and resources updated.

Deploying the Agent

We created a cookbook to assist with Agent deployment.

Install the latest released version of the Datadog Chef cookbook from the Community Site via knife, and upload to your Chef Server:

knife cookbook site install datadog
knife cookbook upload datadog

You may also be using another tool to manage your cookbook workflow, such as Berkshelf or Librarian Chef, in which case you will need to add a line like this to your Berksfile/Cheffile:

cookbook 'datadog'

And follow the instructions for your tool to upload the cookbook to your Chef Server.

Before adding the cookbook’s recipe to your node’s run_list, you need to add account-specific details to be provided to the Agent configuration file.

This is commonly done via role or environment files, or another cookbook declaring the attributes.

Here is an example of a base.rb role file, typically applied to every host in an organization.

# Make sure you replace the API and/or APP key below
# with the ones for your account

name 'base'
description 'base role, runs on every node'
run_list(
  'ntp',
  'datadog::dd-agent',
  'some_other_base_cookbook::recipe'
)
default_attributes(
  'datadog' => {
    'api_key' => "PUT_YOUR_API_KEY_HERE",
    'application_key' => "PUT_YOUR_APPLICATION_KEY_HERE"
  }
)

Note that there are two keys needed. Your API Key can be found in Datadog, under the Integrations => API menu item, or click this link to log in and go there directly.

Then, on the same page, you must create an Application Key for use with Chef. You may name the key whatever you wish, we recommend something like ‘chef_appkey’ or something of that nature.

Provide both values in the attributes as shown above.

Then upload your role file to Chef Server like so:

knife role from file roles/base.rb

The next time Chef runs, it should install the Agent and set the configuration file with the API and application keys.

NOTE: If you are using another cookbook to define these attributes, use a higher attribute precedence level than default.

Deploying the Handler

In order to further raise the visibility of your Chef runs, you may use the Datadog Chef Handler to monitor your Chef execution.

This has the added value of bringing the output of a Chef run back to Datadog’s Event stream, so failures can be highlighted quickly, discussed amongst the team, and resolved.

Successes typically will be found in the “Low” priority, whereas failures are of “Normal” priority, and when the same node passes the Chef run, then it is put pack into “Low” priority.

Adding the handler is very simple, as you can see in this role snippet:

# Make sure you replace the API and/or APP key below
# with the ones for your account

name 'base'
description 'base role, runs on every node'
run_list(
  'datadog::dd-handler',
  'ntp',
  'datadog::dd-agent',
  'some_other_base_cookbook::recipe'
)
default_attributes(
  'datadog' => {
    'api_key' => "PUT_YOUR_API_KEY_HERE",
    'application_key' => "PUT_YOUR_APPLICATION_KEY_HERE"
  }
)

All we’ve done is add the datadog::dd-handler recipe to the beginning of the node’s run list. Adding it to the beginning allows the handler to capture details about everything in it observes after being invoked, so if you added it to the end of the run_list and something failed prior to it being executed, you may not receive the full output.

Once set, upload the role to your Chef Server, and wait. After Chef has run on a few hosts, a new automatic Dashboard will be created, with the relevant Chef Metrics. You can find it in your Dashboards List, on the right-hand side.

Customizations

The Datadog Chef Cookbook provides more integration-specific recipes.

Including one of these recipes in your run list will install any monitoring dependencies, such as any Python modules that are required to monitor that service, as well as write out the correct configuration file.

Here’s an example of how we’ve extended a webserver.rb role file to automatically monitor Apache via Datadog:

name 'webserver'
description 'Webserver role, runs apache'
run_list(
  'apache2',
  'datadog::apache',
)
default_attributes(
  'apache' => {
    'ext_status' => true,
  }
  'datadog' => {
    'apache' => {
      'instances' => [
        { 'status_url' => 'http://localhost:8080/server-status/',
          'tags' => ['extra_tag', 'env:example'] }
      ]
    }
  }
)

As you can see, we’ve added the datadog::apache recipe to the run list, and provided some attributes to control what instances of Apache should be monitored by Datadog.

Read each recipe file for the exact details of the integration values to pass into the instances part of the attributes.