Updated README to include upgrade instructions
MODIFY
README.md
README.md
@@ -18,16 +18,18 @@ Chef recipes to deploy Datadog's components and configuration automatically.
This cookbook includes support for:
+* Datadog Agent version 7.x (default)
* Datadog Agent version 6.x
* Datadog Agent version 5.x
-**Log collection is available with Agent v6, please refer to the [inline docs](https://github.com/DataDog/chef-datadog/blob/v3.0.0/attributes/default.rb#L401-L406) to enable it.**
+Log collection is available with Agent v6/v7, please refer to the [inline docs](https://github.com/DataDog/chef-datadog/blob/v3.0.0/attributes/default.rb#L401-L406) to enable it.
*Note: This README may refer to features that are not released yet. Please check the README of the
git tag/the gem version you're using for your version's documentation*
Requirements
============
+
- chef-client >= 12.7
If you need support for Chef < 12.7, please consider using a [release 2.x of the cookbook](https://github.com/DataDog/chef-datadog/releases/tag/v2.18.0).
@@ -69,196 +71,50 @@ dd-handler recipe. The known workaround is to update your dependency to `chef_ha
the `chef_handler` cookbook which is now shipped as a resource in Chef 14.
Unfortunately, it will display a deprecation message to Chef 14 and 15 users.
-Recipes
-=======
-
-default
--------
-Just a placeholder for now, when we have more shared components they will probably live there.
-
-dd-agent
---------
-Installs the Datadog agent on the target system, sets the API key, and start the service to report on the local system metrics
-
-**Notes for Windows**:
-
-* Because of changes in the Windows Agent packaging and install in version 5.12.0, when upgrading the Agent from versions <= 5.10.1 to versions >= 5.12.0,
- please set the `windows_agent_use_exe` attribute to `true`.
-
- Once the upgrade is complete, you can leave the attribute to its default value (`false`).
-
- For more information on these Windows packaging changes, see the related [docs on the dd-agent wiki](https://github.com/DataDog/dd-agent/wiki/Windows-Agent-Installation).
-
-dd-handler
-----------
-Installs the [chef-handler-datadog](https://rubygems.org/gems/chef-handler-datadog) gem and invokes the handler at the end of a Chef run to report the details back to the newsfeed.
+Upgrading to version 4.x of the cookbook
+========================================
-dogstatsd-ruby
------------------------
-Installs the language-specific libraries to interact with `dogstatsd`.
+Some attributes have changed their names from version 3.x to 4.x of this cookbook. Use this reference table to update your configuration:
-For ruby, please use the `datadog::dogstatsd-ruby` recipe.
+| Action | Cookbook 3.x | Cookbook 4.x |
+|---|---|---|
+| Install Agent 7.x | Not supported | `'agent_major_version' => 7` |
+| Install Agent 6.x | `'agent6' => true` | `'agent_major_version' => 6` |
+| Install Agent 5.x | `'agent6' => false` | `'agent_major_version' => 5` |
+| Pin agent version | `'agent_version'` or `'agent6_version'` | `'agent_version'` for all versions |
+| Change package_action | `'agent_package_action'` or `'agent6_package_action'` | `'agent_package_action'` for all versions |
+| Change APT repo | `'aptrepo'` or `'agent6_aptrepo'` | `'aptrepo'` for all versions |
+| Change APT dist | `'aptrepo_dist'` or `'agent6_aptrepo_dist'` | `'aptrepo_dist'` for all versions |
+| Change YUM repo | `'yumrepo'` or `'agent6_yumrepo'` | `'yumrepo'` for all versions |
+| Change SUSE repo | `'yumrepo_suse'` or `'agent6_yumrepo_suse'` | `'yumrepo_suse'` for all versions |
-For Python, please add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the following resource:
- ```ruby
- python_package 'dogstatsd-python' # assumes that python and pip are installed
- ```
- For more advanced usage, please refer to the [`poise-python` cookbook documentation](https://github.com/poise/poise-python)
-
-ddtrace-ruby
----------------------
-Installs the language-specific libraries for application Traces (APM).
+## Example
-For ruby, please use the `datadog::ddtrace-ruby` recipe.
+If you had an Agent 6 installation, the same configuration will now look like this:
-For Python, please add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the following resource:
```ruby
- python_package 'ddtrace' # assumes that python and pip are installed
- ```
- For more advanced usage, please refer to the [`poise-python` cookbook documentation](https://github.com/poise/poise-python)
-
-other
------
-There are many other integration-specific recipes, that are meant to assist in deploying the correct agent configuration files and dependencies for a given integration.
-
-Resources
-=========
-
-datadog_monitor
----------------
-
-The `datadog_monitor` resource will help you to enable Agent integrations.
-
-The default action `:add` enables the integration by filling a configuration file for the integration with the values provided to the resource, setting the correct permissions on that file, and restarting the Agent.
-
-The `:remove` action disables an integration.
-
-### Syntax
-
-```ruby
-datadog_monitor 'name' do
- init_config Hash # default value: {}
- instances Array # default value: []
- logs Array # default value: []
- use_integration_template true, false # default value: false
- action Symbol # defaults to :add if not specified
-end
-```
-
-#### Actions
-
-* `:add` Default. Enable the integration.
-* `:remove` Use this action to disable the integration.
-
-#### Properties
-
-* `'name'` is the name of the Agent integration to configure and enable
-* `instances` are the fields used to fill values under the `instances` section in the integration configuration file.
-* `init_config` are the fields used to fill values under the the `init_config` section in the integration configuration file.
-* `logs` are the fields used to fill values under the the `logs` section in the integration configuration file.
-* `use_integration_template`: set to `true` (recommended) to use a default template that simply writes the values of `instances`, `init_config`and `logs` in YAML under their respective YAML keys. (defaults to `false` for backward compatibility, will default to `true` in a future major version of the cookbook)
-
-### Example
-
-This 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 in order to restart the Agent.
-
-Note that the Agent installation needs to be earlier in the run list.
-
-```ruby
-include_recipe 'datadog::dd-agent'
-
-datadog_monitor 'elastic'
- instances [{'url' => 'http://localhost:9200'}]
- use_integration_template true
- notifies :restart, 'service[datadog-agent]' if node['datadog']['agent_start']
-end
-```
-
-See `recipes/` for many examples using the `datadog_monitor` resource.
-
-datadog_integration
----------------
-
-The `datadog_integration` resource will help you to install specific versions
-of Datadog integrations.
-
-The default action `:install` installs the integration on the node using the
-`agent integration install` command.
-
-The `:remove` action removes an integration from the node using the `agent
-integration remove` command.
-
-### Syntax
-
-```ruby
-datadog_integration 'name' do
- version String # version to install for :install action.
- action Symbol # defaults to :install if not specified
-end
-```
-
-#### Actions
-
-* `:install` Default. Installs an integration in the given version.
-* `:remove` Removes an integration.
-
-#### Properties
-
-* `'name'` is the name of the Agent integration to install, e.g. `datadog-apache`
-* `version` is the version of the integration that you want to install. Only needed
-with the `:install` action.
-
-### Example
-
-This example installs version `1.11.0` of the ElasticSearch integration by
-using the `datadog_integration` resource.
-
-Note that the Agent installation needs to be earlier in the run list.
-
-```ruby
-include_recipe 'datadog::dd-agent'
-
-datadog_integration 'datadog-elastic'
- version '1.11.0'
-end
+default_attributes(
+ 'datadog' => {
+ 'agent_major_version' => 6, # was 'agent6' => true,
+ 'agent_version' => '1:6.10.0-1', # was 'agent6_version' => '1:6.10.0-1',
+ 'agent_package_action' => 'install', # was 'agent6_package_action' => 'install',
+ }
+)
```
-
-In order to get the available versions of the integrations, please refer to
-their `CHANGELOG.md` file in the [integrations-core repository](https://github.com/DataDog/integrations-core).
-
-**Note for Chef Windows users**: as the datadog-agent binary available on the
-node is used by this resource, the chef-client must have read access to the
-`datadog.yaml` file.
-
Usage
=====
-### Agent v6
-
-By default, this cookbook installs Agent v6, if you want to install Agent v5, please refer to the Agent v5 section below.
+By default, the current major version (4.x) of this cookbook installs Agent v7.
-Attributes are available to have finer control over how you install Agent v6:
+Attributes are available to have finer control over which version of the Agent you install:
- * `agent_major_version`: allows you to pin the major release of the agent (recommended)
+ * `agent_major_version`: allows you to pin the major version of the agent to 5, 6 or 7 (default).
* `agent_version`: allows you to pin a specific agent version (recommended).
- * `agent_package_action`: defaults to `'install'`, may be set to `'upgrade'` to automatically upgrade to latest (not recommended, we recommend pinning to a version with `agent_version` and change that version to upgrade).
- * `aptrepo`: desired APT repo for the agent. Defaults to `http://apt.datadoghq.com`
- * `aptrepo_dist`: desired distribution for the APT repo. Defaults to `stable`
- * `yumrepo`: desired YUM repo for the agent. Defaults to `https://yum.datadoghq.com/stable/`
- * `yumrepo_suse`: desired YUM repo for the agent in SUSE. Defaults to `https://yum.datadoghq.com/suse/stable/`
+ * `agent_package_action` (Linux only): Defaults to `'install'`, can be set `'upgrade'` to get automatic agent updates (we recommend you keep the default here and instead change the pinned `agent_version` to upgrade).
-Please review the [attributes/default.rb](https://github.com/DataDog/chef-datadog/blob/master/attributes/default.rb) file (at the version of the cookbook you use) for the list and usage of the attributes used by the cookbook.
+Please review the [attributes/default.rb](https://github.com/DataDog/chef-datadog/blob/master/attributes/default.rb) file (at the version of the cookbook you use) for the full list and usage of the attributes used by the cookbook.
-For general information on the Datadog Agent v6, please refer to the [datadog-agent](https://github.com/DataDog/datadog-agent/) repo.
-
-#### Windows Agent v6 installation
-
-Starting with version `>= 6.11`, the Windows Agent v6 must be installed with datadog
-cookbook version `>= 2.18.0`.
-
-This is due to the Agent v6 running with an unprivileged user on Windows
-since 6.11. However, prior to 2.18.0, the datadog cookbook was enforcing
-Administrators privileges to the Datadog Agent directories and files.
+For general information on the Datadog Agent, please refer to the [datadog-agent](https://github.com/DataDog/datadog-agent/) repo.
#### Extra configuration
@@ -297,50 +153,56 @@ default['datadog']['extra_config']['logs_config'] = { 'use_port_443' => true }`
This example will set the field `logs_config` in the configuration file `datadog.yaml`.
-### Agent v5
+### Using Agent v6 o v5
-Since `3.0.0`, the cookbook defaults installing Agent v6. You can still setup the Agent v5 by setting `node['datadog']['agent_major_version']` to 5.
+You can still setup the Agent v6 by setting `node['datadog']['agent_major_version']` to 6.
```ruby
default_attributes(
'datadog' => {
- 'agent_major_version' => 5
+ 'agent_major_version' => 6
}
)
```
+The same works for version 5.
+
### Agent v5 transitions
-#### Upgrade from Agent v5 to Agent v6
+#### Upgrade from Agent v6 to Agent v7
-To upgrade from an already installed Agent v5 to Agent v6, you'll have to set the `agent_package_action` to `install` and we recommend to pin to a specific version:
+To upgrade from an already installed Agent v6 to Agent v7, you'll have to set the `agent_package_action` to `install` and we recommend to pin to a specific version:
```ruby
default_attributes(
'datadog' => {
- 'agent_major_version' => 6,
- 'agent_version' => '1:6.10.0-1', # optional but recommended
+ 'agent_major_version' => 7,
+ 'agent_version' => '1:7.15.0-1', # optional but recommended
'agent_package_action' => 'install',
}
)
```
+The same applies if upgrading from 5 to 6.
+
Note that there are Agent v6 counterparts to several well known Agent v5 attributes (code [here](https://github.com/DataDog/chef-datadog/blob/master/attributes/default.rb#L31-L75))
-#### Downgrade from an installed Agent v6 to an Agent v5
+#### Downgrade from an installed Agent v7 to an Agent v6
-You will need to indicate that you want to setup an Agent v5 instead of v6, pin the Agent v5 version that you want to install and allow downgrade:
+You will need to indicate that you want to setup an Agent v6 instead of v7, pin the Agent v6 version that you want to install and allow downgrade:
```ruby
default_attributes(
'datadog' => {
- 'agent_major_version' => 5,
- 'agent_version' => '1:5.32.0-1',
+ 'agent_major_version' => 6,
+ 'agent_version' => '1:6.10.0-1',
'agent_allow_downgrade' => true
}
)
```
+The same works for version 5.
+
### Instructions
1. Add this cookbook to your Chef Server, either by installing with knife or by adding it to your Berksfile:
@@ -419,3 +281,164 @@ AWS OpsWorks Chef Deployment
include_recipe 'datadog::dd-agent'
```
+
+Recipes
+=======
+
+default
+-------
+Just a placeholder for now, when we have more shared components they will probably live there.
+
+dd-agent
+--------
+Installs the Datadog agent on the target system, sets the API key, and start the service to report on the local system metrics
+
+**Notes for Windows**:
+
+* Because of changes in the Windows Agent packaging and install in version 5.12.0, when upgrading the Agent from versions <= 5.10.1 to versions >= 5.12.0,
+ please set the `windows_agent_use_exe` attribute to `true`.
+
+ Once the upgrade is complete, you can leave the attribute to its default value (`false`).
+
+ For more information on these Windows packaging changes, see the related [docs on the dd-agent wiki](https://github.com/DataDog/dd-agent/wiki/Windows-Agent-Installation).
+
+dd-handler
+----------
+Installs the [chef-handler-datadog](https://rubygems.org/gems/chef-handler-datadog) gem and invokes the handler at the end of a Chef run to report the details back to the newsfeed.
+
+dogstatsd-ruby
+-----------------------
+Installs the language-specific libraries to interact with `dogstatsd`.
+
+For ruby, please use the `datadog::dogstatsd-ruby` recipe.
+
+For Python, please add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the following resource:
+ ```ruby
+ python_package 'dogstatsd-python' # assumes that python and pip are installed
+ ```
+ For more advanced usage, please refer to the [`poise-python` cookbook documentation](https://github.com/poise/poise-python)
+
+ddtrace-ruby
+---------------------
+Installs the language-specific libraries for application Traces (APM).
+
+For ruby, please use the `datadog::ddtrace-ruby` recipe.
+
+For Python, please add a dependency on the `poise-python` cookbook to your custom/wrapper cookbook, and use the following resource:
+ ```ruby
+ python_package 'ddtrace' # assumes that python and pip are installed
+ ```
+ For more advanced usage, please refer to the [`poise-python` cookbook documentation](https://github.com/poise/poise-python)
+
+other
+-----
+There are many other integration-specific recipes, that are meant to assist in deploying the correct agent configuration files and dependencies for a given integration.
+
+Resources
+=========
+
+datadog_monitor
+---------------
+
+The `datadog_monitor` resource will help you to enable Agent integrations.
+
+The default action `:add` enables the integration by filling a configuration file for the integration with the values provided to the resource, setting the correct permissions on that file, and restarting the Agent.
+
+The `:remove` action disables an integration.
+
+### Syntax
+
+```ruby
+datadog_monitor 'name' do
+ init_config Hash # default value: {}
+ instances Array # default value: []
+ logs Array # default value: []
+ use_integration_template true, false # default value: false
+ action Symbol # defaults to :add if not specified
+end
+```
+
+#### Actions
+
+* `:add` Default. Enable the integration.
+* `:remove` Use this action to disable the integration.
+
+#### Properties
+
+* `'name'` is the name of the Agent integration to configure and enable
+* `instances` are the fields used to fill values under the `instances` section in the integration configuration file.
+* `init_config` are the fields used to fill values under the the `init_config` section in the integration configuration file.
+* `logs` are the fields used to fill values under the the `logs` section in the integration configuration file.
+* `use_integration_template`: set to `true` (recommended) to use a default template that simply writes the values of `instances`, `init_config`and `logs` in YAML under their respective YAML keys. (defaults to `false` for backward compatibility, will default to `true` in a future major version of the cookbook)
+
+### Example
+
+This 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 in order to restart the Agent.
+
+Note that the Agent installation needs to be earlier in the run list.
+
+```ruby
+include_recipe 'datadog::dd-agent'
+
+datadog_monitor 'elastic'
+ instances [{'url' => 'http://localhost:9200'}]
+ use_integration_template true
+ notifies :restart, 'service[datadog-agent]' if node['datadog']['agent_start']
+end
+```
+
+See `recipes/` for many examples using the `datadog_monitor` resource.
+
+datadog_integration
+---------------
+
+The `datadog_integration` resource will help you to install specific versions
+of Datadog integrations.
+
+The default action `:install` installs the integration on the node using the
+`agent integration install` command.
+
+The `:remove` action removes an integration from the node using the `agent
+integration remove` command.
+
+### Syntax
+
+```ruby
+datadog_integration 'name' do
+ version String # version to install for :install action.
+ action Symbol # defaults to :install if not specified
+end
+```
+
+#### Actions
+
+* `:install` Default. Installs an integration in the given version.
+* `:remove` Removes an integration.
+
+#### Properties
+
+* `'name'` is the name of the Agent integration to install, e.g. `datadog-apache`
+* `version` is the version of the integration that you want to install. Only needed
+with the `:install` action.
+
+### Example
+
+This example installs version `1.11.0` of the ElasticSearch integration by
+using the `datadog_integration` resource.
+
+Note that the Agent installation needs to be earlier in the run list.
+
+```ruby
+include_recipe 'datadog::dd-agent'
+
+datadog_integration 'datadog-elastic'
+ version '1.11.0'
+end
+```
+
+In order to get the available versions of the integrations, please refer to
+their `CHANGELOG.md` file in the [integrations-core repository](https://github.com/DataDog/integrations-core).
+
+**Note for Chef Windows users**: as the datadog-agent binary available on the
+node is used by this resource, the chef-client must have read access to the
+`datadog.yaml` file.

Updated README to include upgrade instructions