{"id":19054640,"url":"https://github.com/datadog/chef-datadog","last_synced_at":"2025-04-05T01:06:17.054Z","repository":{"id":1870870,"uuid":"2796081","full_name":"DataDog/chef-datadog","owner":"DataDog","description":"Chef cookbook for Datadog Agent \u0026 Integrations","archived":false,"fork":false,"pushed_at":"2024-04-11T13:58:15.000Z","size":2236,"stargazers_count":96,"open_issues_count":59,"forks_count":263,"subscribers_count":85,"default_branch":"main","last_synced_at":"2024-04-14T03:36:59.562Z","etag":null,"topics":["chef","datadog"],"latest_commit_sha":null,"homepage":"https://www.datadoghq.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"viralpatel/jquery.shorten","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DataDog.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2011-11-17T14:46:52.000Z","updated_at":"2024-04-15T15:05:47.147Z","dependencies_parsed_at":"2023-02-17T04:02:46.042Z","dependency_job_id":"fa5c9431-e805-4bb4-9b24-5ea74086ca27","html_url":"https://github.com/DataDog/chef-datadog","commit_stats":null,"previous_names":[],"tags_count":90,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fchef-datadog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fchef-datadog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fchef-datadog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DataDog%2Fchef-datadog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DataDog","download_url":"https://codeload.github.com/DataDog/chef-datadog/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271528,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chef","datadog"],"created_at":"2024-11-08T23:39:10.175Z","updated_at":"2025-04-05T01:06:17.032Z","avatar_url":"https://github.com/DataDog.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Datadog Chef Cookbook\n\nThe Datadog Chef recipes are used to deploy Datadog's components and configuration automatically. The cookbook includes support for:\n\n* Datadog Agent v7.x (default)\n* Datadog Agent v6.x\n* Datadog Agent v5.x\n\n**Note**: This page may discuss features that are not available for your selected version. Check the README of the\ngit tag or gem version for your version's documentation.\n\n## Setup\n\n### Requirements\n\nThe Datadog Chef cookbook is compatible with `chef-client` \u003e= 12.7. If you need support for Chef \u003c 12.7, use a [release 2.x of the cookbook][2]. See the [CHANGELOG][3] for more info.\n\n#### Platforms\n\nThe following platforms are supported:\n\n* AlmaLinux (requires Chef 16 \u003e= 16.10.8 or Chef \u003e= 17.0.69)\n* Amazon Linux\n* CentOS\n* Debian\n* RedHat (RHEL 8 requires Chef \u003e= 15)\n* Rocky (requires Chef 16 \u003e= 16.17.4 or Chef \u003e= 17.1.35)\n* Scientific Linux\n* Ubuntu\n* Windows\n* SUSE (requires Chef \u003e= 13.3)\n\n#### Cookbooks\n\nThe following Opscode cookbooks are dependencies:\n\n* `apt`\n* `chef_handler`\n* `yum`\n\n**Note**: `apt` cookbook v7.1+ is needed to install the Agent on Debian 9+.\n\n#### Chef\n\n**Chef 13 users**: With Chef 13 and `chef_handler` 1.x, you may have trouble using the `dd-handler` recipe. The known workaround is to update your dependency to `chef_handler` \u003e= 2.1.\n\n### Installation\n\n1. Add the cookbook to your Chef server with [Berkshelf][5] or [Knife][6]:\n    ```text\n    # Berksfile\n    cookbook 'datadog', '~\u003e 4.0'\n    ```\n\n    ```shell\n    # Knife\n    knife cookbook site install datadog\n    ```\n\n2. Set the [Datadog-specific attributes](#datadog-attributes) in a role, environment, or another recipe:\n    ```text\n    node.default['datadog']['api_key'] = \"\u003cYOUR_DD_API_KEY\u003e\"\n\n    node.default['datadog']['application_key'] = \"\u003cYOUR_DD_APP_KEY\u003e\"\n    ```\n\n3. Upload the updated cookbook to your Chef server:\n    ```shell\n    berks upload\n    # or\n    knife cookbook upload datadog\n    ```\n\n4. After uploading, add the cookbook to your node's `run_list` or `role`:\n    ```text\n    \"run_list\": [\n      \"recipe[datadog::dd-agent]\"\n    ]\n    ```\n\n5. Wait for the next scheduled `chef-client` run or trigger it manually.\n\n#### Datadog attributes\n\nThe following methods are available for adding your [Datadog API and application keys][4]:\n\n* As node attributes with an `environment` or `role`.\n* As node attributes by declaring the keys in another cookbook at a higher precedence level.\n* In the node `run_state` by setting `node.run_state['datadog']['api_key']` in another cookbook preceding Datadog's recipes in the `run_list`. This approach does not store the credential in clear text on the Chef Server.\n\n**Note**: When using the run state to store your API and application keys, set them at compile time before `datadog::dd-handler` in the run list.\n\n#### Extra configuration\n\nTo add additional elements to the Agent configuration file (typically `datadog.yaml`) that are not directly available as attributes of the cookbook, use the `node['datadog']['extra_config']` attribute. This is a hash attribute, which is marshaled into the configuration file accordingly.\n\n##### Examples\n\nThe following code sets the field `secret_backend_command` in the configuration file `datadog.yaml`:\n\n```ruby\n default_attributes(\n   'datadog' =\u003e {\n     'extra_config' =\u003e {\n       'secret_backend_command' =\u003e '/sbin/local-secrets'\n     }\n   }\n )\n```\n\nThe `secret_backend_command` can also be set using:\n\n```text\ndefault['datadog']['extra_config']['secret_backend_command'] = '/sbin/local-secrets'\n```\n\nFor nested attributes, use object syntax. The following code sets the field `logs_config` in the configuration file `datadog.yaml`:\n\n```ruby\ndefault['datadog']['extra_config']['logs_config'] = { 'use_port_443' =\u003e true }\n```\n\n#### AWS OpsWorks Chef deployment\n\nFollow the steps below to deploy the Datadog Agent with Chef on AWS OpsWorks:\n\n1. Add Chef custom JSON:\n  ```json\n  {\"datadog\":{\"agent_major_version\": 7, \"api_key\": \"\u003cAPI_KEY\u003e\", \"application_key\": \"\u003cAPP_KEY\u003e\"}}\n  ```\n\n2. Include the recipe in the `install-lifecycle` recipe:\n  ```ruby\n  include_recipe '::dd-agent'\n  ```\n\n### Integrations\n\nEnable Agent integrations by including the [recipe](#recipes) and configuration details in your role’s run-list and attributes.\n**Note**: You can use the `datadog_monitor` resource for enabling Agent integrations without a recipe.\n\nAssociate your recipes with the desired `roles`, for example `role:chef-client` should contain `datadog::dd-handler` and `role:base` should start the Agent with `datadog::dd-agent`. Below is an example role with the `dd-handler`, `dd-agent`, and `mongo` recipes:\n\n```ruby\nname 'example'\ndescription 'Example role using DataDog'\n\ndefault_attributes(\n  'datadog' =\u003e {\n    'agent_major_version' =\u003e 7,\n    'api_key' =\u003e '\u003cYOUR_DD_API_KEY\u003e',\n    'application_key' =\u003e '\u003cYOUR_DD_APP_KEY\u003e',\n    'mongo' =\u003e {\n      'instances' =\u003e [\n        {'host' =\u003e 'localhost', 'port' =\u003e '27017'}\n      ]\n    }\n  }\n)\n\nrun_list %w(\n  recipe[datadog::dd-agent]\n  recipe[datadog::dd-handler]\n  recipe[datadog::mongo]\n)\n```\n\n**Note**: `data_bags` are not used in this recipe because it is unlikely to have multiple API keys with only one application key.\n\n## Versions\n\nBy default, the current major version of this cookbook installs Agent v7. The following attributes are available to control the Agent version installed:\n\n| Parameter              | Description                                                                                                                                                                         |\n|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `agent_major_version`  | Pin the major version of the Agent to 5, 6, or 7 (default).                                                                                                                         |\n| `agent_version`        | Pin a specific Agent version (recommended).                                                                                                                                         |\n| `agent_package_action` | (Linux only) Defaults to `'install'` (recommended), `'upgrade'` to get automatic Agent updates (not recommended, use the default and change the pinned `agent_version` to upgrade). |\n| `agent_flavor` | (Linux only) Defaults to `'datadog-agent'` to install the datadog-agent, can be set to `'datadog-iot-agent'` to install the IOT agent. |\n\nSee the sample [attributes/default.rb][1] for your cookbook version for all available attributes.\n\n### Upgrade\n\nSome attribute names have changed from version 3.x to 4.x of the cookbook. Use this reference table to update your configuration:\n\n| Action                | Cookbook 3.x                                          | Cookbook 4.x                              |\n|-----------------------|-------------------------------------------------------|-------------------------------------------|\n| Install Agent 7.x     | Not supported                                         | `'agent_major_version' =\u003e 7`              |\n| Install Agent 6.x     | `'agent6' =\u003e true`                                    | `'agent_major_version' =\u003e 6`              |\n| Install Agent 5.x     | `'agent6' =\u003e false`                                   | `'agent_major_version' =\u003e 5`              |\n| Pin agent version     | `'agent_version'` or `'agent6_version'`               | `'agent_version'` for all versions        |\n| Change package_action | `'agent_package_action'` or `'agent6_package_action'` | `'agent_package_action'` for all versions |\n| Change APT repo URL   | `'aptrepo'` or `'agent6_aptrepo'`                     | `'aptrepo'` for all versions              |\n| Change APT repo distribution  | `'aptrepo_dist'` or `'agent6_aptrepo_dist'`   | `'aptrepo_dist'` for all versions         |\n| Change YUM repo       | `'yumrepo'` or `'agent6_yumrepo'`                     | `'yumrepo'` for all versions              |\n| Change SUSE repo      | `'yumrepo_suse'` or `'agent6_yumrepo_suse'`           | `'yumrepo_suse'` for all versions         |\n\nUse one of the following methods to upgrade from Agent v6 to v7:\n\n* Set `agent_major_version` to `7`, `agent_package_action` to `install`, and pin a specific v7 version as `agent_version` (recommended).\n* Set `agent_major_version` to `7` and `agent_package_action` to `upgrade`.\n\nThe following example upgrades from Agent v6 to v7. The same applies if you are upgrading from Agent v5 to v6.\n\n```ruby\ndefault_attributes(\n  'datadog' =\u003e {\n    'agent_major_version' =\u003e 7,\n    'agent_version' =\u003e '7.25.1',\n    'agent_package_action' =\u003e 'install',\n  }\n)\n```\n\n### Downgrade\n\nTo downgrade the Agent version, set the `'agent_major_version'`, `'agent_version'`, and `'agent_allow_downgrade'`.\n\nThe following example downgrades to Agent v6. The same applies if you are downgrading to Agent v5.\n\n```ruby\n  default_attributes(\n    'datadog' =\u003e {\n      'agent_major_version' =\u003e 6,\n      'agent_version' =\u003e '6.10.0',\n      'agent_allow_downgrade' =\u003e true\n    }\n  )\n```\n\n### Uninstall\n\nTo uninstall the Agent, remove the `dd-agent` recipe and add the `remove-dd-agent` recipe with no attributes.\n\n### Custom Agent repository\n\nTo use an Agent from a custom repository, you can set the `aptrepo` option. \n\nBy default, this option is equal to `[signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datadoghq.com`. If a custom value is set, another `signed-by` keyring can also be set `[signed-by=custom-repo-keyring-path] custom-repo`.\n\nThe example below uses the staging repository:\n\n```ruby\n  default_attributes(\n    'datadog' =\u003e {\n      'aptrepo' =\u003e '[signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datad0g.com',\n    }\n  }\n```\n\n## Recipes\n\nAccess the [Datadog Chef recipes on GitHub][7].\n\n### Default\n\nThe [default recipe][8] is a placeholder.\n\n### Agent\n\nThe [dd-agent recipe][9] installs the Datadog Agent on the target system, sets your [Datadog API key][4], and starts the service to report on local system metrics.\n\n**Note**: Windows users upgrading the Agent from versions \u003c= 5.10.1 to \u003e= 5.12.0, set the `windows_agent_use_exe` attribute to `true`. For more details, see the [dd-agent wiki][10].\n\n### Handler\n\nThe [dd-handler recipe][11] installs the [chef-handler-datadog][12] gem and invokes the handler at the end of a Chef run to report the details to the news feed.\n\n### DogStatsD\n\nTo install a language-specific library that interacts with DogStatsD:\n\n- Ruby: [dogstatsd-ruby recipe][13]\n- Python: Add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the resource below. For more details, see the [poise-python repository][14].\n    ```ruby\n    python_package 'dogstatsd-python' # assumes python and pip are installed\n    ```\n\n### Tracing\n\nTo install a language-specific library for application tracing (APM):\n\n- Ruby: [ddtrace-ruby recipe][15]\n- Python: Add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the resource below. For more details, see the [poise-python repository][14].\n    ```ruby\n    python_package 'ddtrace' # assumes python and pip are installed\n    ```\n\n### Integrations\n\nThere are many [recipes][7] to assist you with deploying Agent integration configuration files and dependencies.\n\n### System-probe\n\nThe [system-probe recipe][17] is automatically included by default. It writes the `system-probe.yaml` file. This behavior can be disabled by setting `node['datadog']['system_probe']['manage_config']` to false.\n\nTo enable [Network Performance Monitoring][7] (NPM) in `system-probe.yaml`, set `node['datadog']['system_probe']['network_enabled']` to true.\n\nTo enable [Universal Service Monitoring][7] (USM) in `system-probe.yaml`, set `node['datadog']['system_probe']['service_monitoring_enabled']` to true.\n\n**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 if `node['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.\n\n## Resources\n\n### Integrations without recipes\n\nUse the `datadog_monitor` resource for enabling Agent integrations without a recipe.\n\n#### Actions\n\n- `:add`: (default) Enables the integration by setting up the configuration file, adding the correct permissions to the file, and restarting the Agent.\n- `:remove`: Disables an integration.\n\n#### Syntax\n\n```ruby\ndatadog_monitor 'name' do\n  init_config                       Hash # default value: {}\n  instances                         Array # default value: []\n  logs                              Array # default value: []\n  use_integration_template          true, false # default value: false\n  config_name                       String # default value: 'conf'\n  action                            Symbol # defaults to :add\nend\n```\n\n#### Properties\n\n| Property                   | Description                                                                                                                                                                                                                                                                                   |\n|----------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `'name'`                   | The name of the Agent integration to configure and enable.                                                                                                                                                                                                                                    |\n| `instances`                | The fields used to fill values under the `instances` section in the integration configuration file.                                                                                                                                                                                           |\n| `init_config`              | The fields used to fill values under the the `init_config` section in the integration configuration file.                                                                                                                                                                                     |\n| `logs`                     | The fields used to fill values under the the `logs` section in the integration configuration file.                                                                                                                                                                                            |\n| `use_integration_template` | Set to `true` (recommended) to use the default template, which writes the values of `instances`, `init_config`, and `logs` in the YAML under their respective keys. This defaults to `false` for backward compatibility, but may default to `true` in a future major version of the cookbook. |\n| `config_name`              | The filename used when creating an integrations configuration file. Overriding this property allows the creation of multiple configuration files for a single integration.  This defaults to `conf`, which creates a configuration file named `conf.yaml`.                                    |\n\n#### Example\n\nThis example enables the ElasticSearch integration by using the `datadog_monitor` resource. It provides the instance configuration (in this case: the URL to connect to ElasticSearch) and sets the `use_integration_template` flag to use the default configuration template. Also, it notifies the `service[datadog-agent]` resource to restart the Agent.\n\n**Note**: The Agent installation must be above this recipe in the run list.\n\n```ruby\ninclude_recipe '::dd-agent'\n\ndatadog_monitor 'elastic' do\n  instances  [{'url' =\u003e 'http://localhost:9200'}]\n  use_integration_template true\n  notifies :restart, 'service[datadog-agent]' if node['datadog']['agent_start']\nend\n```\n\nSee the [Datadog integration Chef recipes][7] for additional examples.\n\n### Integration versions\n\nTo install a specific version of a Datadog integration, use the `datadog_integration` resource.\n\n#### Actions\n\n- `:install`: (default) Installs an integration with the specified version.\n- `:remove`: Removes an integration.\n\n#### Syntax\n\n```ruby\ndatadog_integration 'name' do\n  version                      String         # version to install for :install action\n  action                       Symbol         # defaults to :install\n  third_party                  [true, false]  # defaults to :false\nend\n```\n\n#### Properties\n\n- `'name'`: The name of the Agent integration to install, for example: `datadog-apache`.\n- `version`: The version of the integration to install (only required with the `:install` action).\n- `third_party`: Set to false if installing a Datadog integration, true otherwise. Available for Datadog Agents version 6.21/7.21 and higher only.\n\n#### Example\n\nThis example installs version `1.11.0` of the ElasticSearch integration by using the `datadog_integration` resource.\n\n**Note**: The Agent installation must be above this recipe in the run list.\n\n```ruby\ninclude_recipe '::dd-agent'\n\ndatadog_integration 'datadog-elastic' do\n  version '1.11.0'\nend\n```\n\nTo get the available versions of the integrations, see the integration-specific `CHANGELOG.md` in the [integrations-core repository][16].\n\n**Note**: For Chef Windows users, the `chef-client` must have read access to the `datadog.yaml` file when the `datadog-agent` binary available on the node is used by this resource.\n\n## Development\n\n### Dockerized environment\n\nTo build a Docker environment with which to run kitchen tests, use the files under `docker_test_env`:\n\n```\ncd docker_test_env\ndocker build -t chef-datadog-test-env .\n```\n\nTo run the container use:\n\n```\ndocker run -d -v /var/run/docker.sock:/var/run/docker.sock chef-datadog-test-env\n```\n\nThen attach a console to the container or use the VS Code remote-container feature to develop inside the container.\n\nTo run kitchen-docker tests from within the container:\n\n```\n# Note: Also set KITCHEN_DOCKER_HOSTNAME=host.docker.internal if on MacOS or Windows\n# Run this under a login shell (otherwise `bundle` won't be found)\nKITCHEN_LOCAL_YAML=kitchen.docker.yml bundle exec rake circle\n```\n\n[1]: https://github.com/DataDog/chef-datadog/blob/master/attributes/default.rb\n[2]: https://github.com/DataDog/chef-datadog/releases/tag/v2.18.0\n[3]: https://github.com/DataDog/chef-datadog/blob/master/CHANGELOG.md\n[4]: https://app.datadoghq.com/organization-settings/api-keys\n[5]: https://docs.chef.io/berkshelf/\n[6]: https://docs.chef.io/knife/\n[7]: https://github.com/DataDog/chef-datadog/tree/master/recipes\n[8]: https://github.com/DataDog/chef-datadog/blob/master/recipes/default.rb\n[9]: https://github.com/DataDog/chef-datadog/blob/master/recipes/dd-agent.rb\n[10]: https://github.com/DataDog/dd-agent/wiki/Windows-Agent-Installation\n[11]: https://github.com/DataDog/chef-datadog/blob/master/recipes/dd-handler.rb\n[12]: https://rubygems.org/gems/chef-handler-datadog\n[13]: https://github.com/DataDog/chef-datadog/blob/master/recipes/dogstatsd-ruby.rb\n[14]: https://github.com/poise/poise-python\n[15]: https://github.com/DataDog/chef-datadog/blob/master/recipes/ddtrace-ruby.rb\n[16]: https://github.com/DataDog/integrations-core\n[17]: https://github.com/DataDog/chef-datadog/blob/master/recipes/system-probe.rb\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fchef-datadog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatadog%2Fchef-datadog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatadog%2Fchef-datadog/lists"}