Repository files navigation

The Datadog Chef recipes are used to deploy Datadog's components and configuration automatically. The cookbook includes support for:

• Datadog Agent v7.x (default)
• Datadog Agent v6.x
• Datadog Agent v5.x

Note: This page may discuss features that are not available for your selected version. Check the README of thegit tag or gem version for your version's documentation.

The Datadog Chef cookbook is compatible withchef-client >= 12.7. If you need support for Chef < 12.7, use arelease 2.x of the cookbook. See theCHANGELOG for more info.

The following platforms are supported:

• AlmaLinux (requires Chef 16 >= 16.10.8 or Chef >= 17.0.69)
• Amazon Linux
• CentOS
• Debian
• RedHat (RHEL 8 requires Chef >= 15)
• Rocky (requires Chef 16 >= 16.17.4 or Chef >= 17.1.35)
• Scientific Linux
• Ubuntu
• Windows
• SUSE (requires Chef >= 13.3)

The following Opscode cookbooks are dependencies:

• apt
• chef_handler
• yum

Note:apt cookbook v7.1+ is needed to install the Agent on Debian 9+.

Chef 13 users: With Chef 13 andchef_handler 1.x, you may have trouble using thedd-handler recipe. The known workaround is to update your dependency tochef_handler >= 2.1.

1. Add the cookbook to your Chef server withBerkshelf orKnife:

   # Berksfilecookbook 'datadog', '~> 4.0'

   # Knifeknife cookbook site install datadog

2. Set theDatadog-specific attributes in a role, environment, or another recipe:

   node.default['datadog']['api_key'] = "<YOUR_DD_API_KEY>"node.default['datadog']['application_key'] = "<YOUR_DD_APP_KEY>"

3. Upload the updated cookbook to your Chef server:

   berks upload# orknife cookbook upload datadog

4. After uploading, add the cookbook to your node'srun_list orrole:

   "run_list": [  "recipe[datadog::dd-agent]"]

5. Wait for the next scheduledchef-client run or trigger it manually.

The following methods are available for adding yourDatadog API and application keys:

• As node attributes with anenvironment orrole.
• As node attributes by declaring the keys in another cookbook at a higher precedence level.
• In the noderun_state by settingnode.run_state['datadog']['api_key'] in another cookbook preceding Datadog's recipes in therun_list. This approach does not store the credential in clear text on the Chef Server.

Note: When using the run state to store your API and application keys, set them at compile time beforedatadog::dd-handler in the run list.

To add additional elements to the Agent configuration file (typicallydatadog.yaml) that are not directly available as attributes of the cookbook, use thenode['datadog']['extra_config'] attribute. This is a hash attribute, which is marshaled into the configuration file accordingly.

The following code sets the fieldsecret_backend_command in the configuration filedatadog.yaml:

default_attributes('datadog'=>{'extra_config'=>{'secret_backend_command'=>'/sbin/local-secrets'}})

Thesecret_backend_command can also be set using:

default['datadog']['extra_config']['secret_backend_command'] = '/sbin/local-secrets'

For nested attributes, use object syntax. The following code sets the fieldlogs_config in the configuration filedatadog.yaml:

default['datadog']['extra_config']['logs_config']={'use_port_443'=>true}

Follow the steps below to deploy the Datadog Agent with Chef on AWS OpsWorks:

1. Add Chef custom JSON:

{"datadog":{"agent_major_version":7,"api_key":"<API_KEY>","application_key":"<APP_KEY>"}}

2. Include the recipe in theinstall-lifecycle recipe:

include_recipe'::dd-agent'

Enable Agent integrations by including therecipe and configuration details in your role’s run-list and attributes.Note: You can use thedatadog_monitor resource for enabling Agent integrations without a recipe.

Associate your recipes with the desiredroles, for examplerole:chef-client should containdatadog::dd-handler androle:base should start the Agent withdatadog::dd-agent. Below is an example role with thedd-handler,dd-agent, andmongo recipes:

name'example'description'Example role using DataDog'default_attributes('datadog'=>{'agent_major_version'=>7,'api_key'=>'<YOUR_DD_API_KEY>','application_key'=>'<YOUR_DD_APP_KEY>','mongo'=>{'instances'=>[{'host'=>'localhost','port'=>'27017'}]}})run_list%w(recipe[datadog::dd-agent]recipe[datadog::dd-handler]recipe[datadog::mongo])

Note:data_bags are not used in this recipe because it is unlikely to have multiple API keys with only one application key.

By default, the current major version of this cookbook installs Agent v7. The following attributes are available to control the Agent version installed:

See the sampleattributes/default.rb for your cookbook version for all available attributes.

Some attribute names have changed from version 3.x to 4.x of the cookbook. Use this reference table to update your configuration:

Use one of the following methods to upgrade from Agent v6 to v7:

• Setagent_major_version to7,agent_package_action toinstall, and pin a specific v7 version asagent_version (recommended).
• Setagent_major_version to7 andagent_package_action toupgrade.

The following example upgrades from Agent v6 to v7. The same applies if you are upgrading from Agent v5 to v6.

default_attributes('datadog'=>{'agent_major_version'=>7,'agent_version'=>'7.25.1','agent_package_action'=>'install',})

To downgrade the Agent version, set the'agent_major_version','agent_version', and'agent_allow_downgrade'.

The following example downgrades to Agent v6. The same applies if you are downgrading to Agent v5.

default_attributes('datadog'=>{'agent_major_version'=>6,'agent_version'=>'6.10.0','agent_allow_downgrade'=>true})

To uninstall the Agent, remove thedd-agent recipe and add theremove-dd-agent recipe with no attributes.

To use an Agent from a custom repository, you can set theaptrepo option.

By default, this option is equal to[signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datadoghq.com. If a custom value is set, anothersigned-by keyring can also be set[signed-by=custom-repo-keyring-path] custom-repo.

The example below uses the staging repository:

default_attributes('datadog'=>{'aptrepo'=>'[signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datad0g.com',}}

Access theDatadog Chef recipes on GitHub.

Thedefault recipe is a placeholder.

Thedd-agent recipe installs the Datadog Agent on the target system, sets yourDatadog API key, and starts the service to report on local system metrics.

Note: Windows users upgrading the Agent from versions <= 5.10.1 to >= 5.12.0, set thewindows_agent_use_exe attribute totrue. For more details, see thedd-agent wiki.

Thedd-handler recipe installs thechef-handler-datadog gem and invokes the handler at the end of a Chef run to report the details to the news feed.

To install a language-specific library that interacts with DogStatsD:

• Ruby:dogstatsd-ruby recipe
• Python: Add a dependency on thepoise-python cookbook to your custom/wrapper cookbook, and use the resource below. For more details, see thepoise-python repository.

  python_package'dogstatsd-python'# assumes python and pip are installed

To install a language-specific library for application tracing (APM):

• Ruby:ddtrace-ruby recipe
• Python: Add a dependency on thepoise-python cookbook to your custom/wrapper cookbook, and use the resource below. For more details, see thepoise-python repository.

  python_package'ddtrace'# assumes python and pip are installed

There are manyrecipes to assist you with deploying Agent integration configuration files and dependencies.

Thesystem-probe recipe is automatically included by default. It writes thesystem-probe.yaml file. This behavior can be disabled by settingnode['datadog']['system_probe']['manage_config'] to false.

To enableNetwork Performance Monitoring (NPM) insystem-probe.yaml, setnode['datadog']['system_probe']['network_enabled'] to true.

To enableUniversal Service Monitoring (USM) insystem-probe.yaml, setnode['datadog']['system_probe']['service_monitoring_enabled'] to true.

Note for Windows users: NPM is supported on Windows with Agent v6.27+ and v7.27+. It ships as an optional component that is only installed ifnode['datadog']['system_probe']['network_enabled'] is set to true when the Agent is installed or upgraded. Because of this, existing installations might need to do an uninstall and reinstall of the Agent once to install the NPM component, unless the Agent is upgraded at the same time.

Use thedatadog_monitor resource for enabling Agent integrations without a recipe.

• :add: (default) Enables the integration by setting up the configuration file, adding the correct permissions to the file, and restarting the Agent.
• :remove: Disables an integration.

datadog_monitor'name'doinit_configHash# default value: {}instancesArray# default value: []logsArray# default value: []use_integration_templatetrue,false# default value: falseconfig_nameString# default value: 'conf'actionSymbol# defaults to :addend

This example enables the ElasticSearch integration by using thedatadog_monitor resource. It provides the instance configuration (in this case: the URL to connect to ElasticSearch) and sets theuse_integration_template flag to use the default configuration template. Also, it notifies theservice[datadog-agent] resource to restart the Agent.

Note: The Agent installation must be above this recipe in the run list.

include_recipe'::dd-agent'datadog_monitor'elastic'doinstances[{'url'=>'http://localhost:9200'}]use_integration_templatetruenotifies:restart,'service[datadog-agent]'ifnode['datadog']['agent_start']end

See theDatadog integration Chef recipes for additional examples.

To install a specific version of a Datadog integration, use thedatadog_integration resource.

• :install: (default) Installs an integration with the specified version.
• :remove: Removes an integration.

datadog_integration'name'doversionString# version to install for :install actionactionSymbol# defaults to :installthird_party[true,false]# defaults to :falseend

• 'name': The name of the Agent integration to install, for example:datadog-apache.
• version: The version of the integration to install (only required with the:install action).
• third_party: Set to false if installing a Datadog integration, true otherwise. Available for Datadog Agents version 6.21/7.21 and higher only.

This example installs version1.11.0 of the ElasticSearch integration by using thedatadog_integration resource.

Note: The Agent installation must be above this recipe in the run list.

include_recipe'::dd-agent'datadog_integration'datadog-elastic'doversion'1.11.0'end

To get the available versions of the integrations, see the integration-specificCHANGELOG.md in theintegrations-core repository.

Note: For Chef Windows users, thechef-client must have read access to thedatadog.yaml file when thedatadog-agent binary available on the node is used by this resource.

To build a Docker environment with which to run kitchen tests, use the files underdocker_test_env:

cd docker_test_envdocker build -t chef-datadog-test-env .

To run the container use:

docker run -d -v /var/run/docker.sock:/var/run/docker.sock chef-datadog-test-env

Then attach a console to the container or use the VS Code remote-container feature to develop inside the container.

To run kitchen-docker tests from within the container:

# Note: Also set KITCHEN_DOCKER_HOSTNAME=host.docker.internal if on MacOS or Windows# Run this under a login shell (otherwise `bundle` won't be found)KITCHEN_LOCAL_YAML=kitchen.docker.yml bundle exec rake circle