Le cookbook Chef Datadog automatise l’installation et la configuration de l’Agent Datadog sur les plateformes Linux et Windows prises en charge. Le cookbook est compatible avec chef-client >= 12.7 et prend en charge les plateformes Windows et Linux. Pour les références complètes d’attributs, les recettes, les exemples d’utilisation et les modèles de configuration d’intégrations, consultez la section Configurations avancées.

Les recettes Chef pour Datadog servent à déployer automatiquement les composants et la configuration de Datadog. Le cookbook prend en charge les versions suivantes de l’Agent :

• Agent Datadog v7.x (par défaut)
• Agent Datadog v6.x
• Agent Datadog v5.x

Remarque : cette page peut mentionner des fonctionnalités qui ne sont pas disponibles avec votre version. Consultez le fichier README du tag git ou de la version gem pour accéder à la documentation de votre version.

Prérequis

Le cookbook Chef pour Datadog est compatible avec chef-client 12.7 ou une version ultérieure. Pour une version antérieure de Chef, utilisez une version 2.x du cookbook. Consultez le CHANGELOG pour en savoir plus.

Plateformes

Les plateformes suivantes sont prises en charge :

• AlmaLinux (Chef 16 ou 16.10.8 ou une version supérieure, ou bien Chef 17.0.69 ou une version supérieure requis)
• Amazon Linux
• CentOS
• Debian
• RedHat (RHEL 8 nécessite Chef 15 ou une version ultérieure)
• Rocky (Chef 16 ou 16.17.4 ou une version supérieure, ou bien Chef 17.1.35 ou une version supérieure requis)
• Scientific Linux
• Ubuntu
• Windows
• SUSE (nécessite Chef 13.3 ou une version ultérieure)

Cookbooks

Les cookbooks Opscode suivants sont des dépendances :

• apt
• chef_handler
• yum

Remarque : un cookbook apt 7.1 ou ultérieur est nécessaire pour installer l’Agent sur Debian 9+.

Chef

Utilisateurs de Chef 13 : avec Chef 13 et chef_handler 1.x, il se peut que vous rencontriez des problèmes avec la recette dd-handler. Pour y remédier, mettez à jour dépendance chef_handler en installant la version 2.1 ou une version ultérieure.

Configuration

Installation

1. Ajoutez le cookbook à votre serveur Chef avec Berkshelf ou Knife :

   # Berksfile
   cookbook 'datadog', '~> 4.0'
   

   # Knife
   knife cookbook site install datadog
   

2. Définissez les attributs spécifiques à Datadog dans un rôle, un environnement ou une autre recette :

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

3. Importez le cookbook mis à jour sur votre serveur Chef :

   berks upload
   # or
   knife cookbook upload datadog
   

4. Une fois l’importation terminée, ajoutez le cookbook au paramètre run_list ou role de votre nœud :

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

5. Patientez jusqu’à la prochaine exécution programmée de chef-client ou déclenchez-le manuellement.

Attributs Datadog

Vous pouvez utiliser les méthodes suivantes pour ajouter vos clés d’API et d’application Datadog :

• En tant qu’attributs de nœud, avec un paramètre environment ou role
• En tant qu’attributs de nœud, en déclarant les clés dans un autre cookbook à un niveau de priorité plus élevé
• Dans le nœud run_state, en définissant node.run_state['datadog']['api_key'] dans un autre cookbook précédant les recettes de Datadog dans la run_list ; cette approche ne stocke pas les identifiants en texte en clair sur le serveur Chef

Remarque : lorsque vous utilisez l’état d’exécution pour stocker vos clés d’API et d’application, définissez-les en fonction de la durée de compilation avant datadog::dd-handler dans la run list.

Configurations avancées

Pour ajouter des éléments supplémentaires qui ne sont pas directement disponibles en tant qu’attributs du cookbook au fichier de configuration de l’Agent (généralement datadog.yaml), utilisez l’attribut node['datadog']['extra_config']. Il s’agit d’un attribut de hachage, qui est marshalé dans le fichier de configuration en conséquence.

Exemples

Le code suivant définit le champ secret_backend_command dans le fichier de configuration datadog.yaml :

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

Le paramètre secret_backend_command peut également être définie en utilisant :

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

Pour les attributs imbriqués, utilisez une syntaxe d’objet. Le code suivant définit le champ logs_config dans le fichier de configuration datadog.yaml :

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

Déploiement Chef sur AWS OpsWorks

Suivez les étapes ci-dessous pour déployer l’Agent Datadog avec Chef sur AWS OpsWorks :

1. Ajoutez le JSON personnalisé suivant pour Chef :

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

2. Incluez la recette dans la recette install-lifecycle :

include_recipe '::dd-agent'

Intégrations

Activez les intégrations de l’Agent en ajoutant la recette et les détails de configuration dans la run list et les attributs de votre rôle. Remarque : vous pouvez utiliser la ressource datadog_monitor pour activer les intégrations de l’Agent sans passer par une recette.

Associez vos recettes aux roles souhaités. Par exemple, role:chef-client doit contenir datadog::dd-handler, et role:base doit démarrer l’Agent avec datadog::dd-agent. Voici un exemple de rôle avec les recettes dd-handler, dd-agent et mongo :

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]
)

Remarque : cette recette n’utilise pas de data_bags, car il est peu probable d’avoir plusieurs clés d’API avec une seule clé d’application.

Versions

Par défaut, la version majeure actuelle de ce cookbook installe l’Agent v7. Les attributs suivants sont disponibles pour contrôler la version de l’Agent installée :

Consultez le fichier d’exemple attributes/default.rb correspondant à la version de votre cookbook pour découvrir tous les attributs disponibles.

Mise à jour

Certains noms d’attributs ont changé entre les versions 3.x et 4.x du cookbook. Référez-vous à ce tableau de référence pour mettre à jour votre configuration :

Utilisez l’une des méthodes suivantes pour passer de la version 6 à la version 7 de l’Agent :

• Définissez agent_major_version sur 7 et agent_package_action sur install, puis imposez une version 7 spécifique pour agent_version (conseillé).
• Définissez agent_major_version sur 7 et agent_package_action sur upgrade.

L’exemple suivant permet de passer de la version 6 à la version 7 de l’Agent. La même logique s’applique pour les versions 5 et 6.

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

Passer à une version antérieure

Pour passer à une version antérieure de l’Agent, définissez les paramètres 'agent_major_version', 'agent_version' et 'agent_allow_downgrade'.

L’exemple suivant permet de passer de la version 7 à la version 6 de l’Agent. La même logique s’applique pour les versions 6 et 5.

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

Désinstallation

Pour désinstaller l’Agent, supprimez la recette dd-agent, puis ajoutez la recette remove-dd-agent sans aucun attribut.

Référentiel d’Agent personnalisé

Pour utiliser un Agent depuis un référentiel personnalisé, vous pouvez définir l’option aptrepo.

Par défaut, cette option est égale à [signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datadoghq.com. Si une valeur personnalisée est définie, un autre trousseau signed-by peut également être défini [signed-by=custom-repo-keyring-path] custom-repo.

L’exemple ci-dessous utilise le référentiel de staging :

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

Recettes

Accédez aux recettes Chef pour Datadog sur GitHub.

Valeur par défaut

La recette par défaut est donnée à titre d’exemple.

Agent

La recette dd-agent permet d’installer l’Agent Datadog sur le système cible, de définir votre clé d’API Datadog et de démarrer le service afin de transmettre des métriques système locales.

Remarque : pour les utilisateurs Windows qui effectuent une mise à niveau de l’Agent à partir d’une version <= 5.10.1 vers une version >= 5.12.0, définissez l’attribut windows_agent_use_exe sur true. Pour en savoir plus, consultez la page Wiki dd-agent.

Gestionnaire

La recette dd-handler permet d’installer le gem chef-handler-datadog et d’appeler le gestionnaire à la fin d’une exécution Chef pour transmettre les détails au flux d’actualités.

DogStatsD

Pour installer une bibliothèque spécifique à un langage qui interagit avec DogStatsD :

• Ruby : recette dogstatsd-ruby
• Python : ajoutez une dépendance sur le cookbook poise-python à votre cookbook wrapper/personnalisé et utilisez la ressource ci-dessous. Pour en savoir plus, consultez le référentiel poise-python.

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

Tracing

Pour installer une bibliothèque spécifique à un langage pour le tracing d’applications (APM) :

• Ruby : recette ddtrace-ruby
• Python : ajoutez une dépendance sur le cookbook poise-python à votre cookbook wrapper/personnalisé et utilisez la ressource ci-dessous. Pour en savoir plus, consultez le référentiel poise-python.

  python_package 'ddtrace' # assumes python and pip are installed
  

Intégrations

De nombreuses recettes peuvent vous aider à déployer des dépendances et des fichiers de configuration pour les intégrations de l’Agent.

System-probe

Par défaut, la recette system-probe est automatiquement incluse. Elle génère le fichier system-probe.yaml. Pour désactiver ce comportement, définissez node['datadog']['system_probe']['manage_config'] sur false.

Pour activer la solution Network Performance Monitoring (NPM) dans system-probe.yaml, définissez node['datadog']['system_probe']['network_enabled'] sur true.

Pour activer Universal Service Monitoring (USM) dans system-probe.yaml, définissez node['datadog']['system_probe']['service_monitoring_enabled'] sur true.

Remarque pour les utilisateurs Windows : la solution NPM fonctionne sous Windows avec les versions 6.27+ et 7.27+ de l’Agent. Elle est fournie en tant que composant facultatif. Celui-ci est uniquement installé lorsque node['datadog']['system_probe']['network_enabled'] est défini sur true durant l’installation ou la mise à niveau de l’Agent. Ainsi, pour installer le composant NPM, vous devrez probablement désinstaller et réinstaller l’Agent, sauf si vous en profitez pour mettre à niveau l’Agent.

Ressources

Intégrations sans recette

Utilisez la ressource datadog_monitor pour activer des intégrations de l’Agent sans passer par une recette.

Actions

• :add (par défaut) : active une intégration en configurant le fichier de configuration, en ajoutant les autorisations appropriées au fichier et en redémarrant l’Agent.
• :remove : désactive une intégration.

Syntaxe

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
  config_name                       String # default value: 'conf'
  action                            Symbol # defaults to :add
end

Propriétés

Exemple

Cet exemple permet d’activer l’intégration ElasticSearch en utilisant la ressource datadog_monitor. Il fournit la configuration d’instance (dans ce cas : l’URL pour se connecter à ElasticSearch) et définit le flag use_integration_template afin d’utiliser le modèle de configuration par défaut. En outre, il indique à la ressource service[datadog-agent] de redémarrer l’Agent.

Remarque : l’installation de l’Agent doit être au-dessus de cette recette dans la run list.

include_recipe '::dd-agent'

datadog_monitor 'elastic' do
  instances  [{'url' => 'http://localhost:9200'}]
  use_integration_template true
  notifies :restart, 'service[datadog-agent]' if node['datadog']['agent_start']
end

Consultez les recettes Chef pour les intégrations Datadog afin de découvrir des exemples supplémentaires.

Versions d’intégration

Pour installer une version spécifique d’une intégration Datadog, utilisez la ressource datadog_integration.

Actions

• :install (par défaut) : installe la version spécifiée d’une intégration.
• :remove : supprime une intégration.

Syntaxe

datadog_integration 'name' do
  version                      String         # version à installer pour l'action :install
  action                       Symbol         # valeur par défaut : :install
  third_party                  [true, false]  # valeur par défaut : false
end

Propriétés

• 'name' : le nom de l’intégration de l’Agent à installer, par exemple : datadog-apache.
• version : la version de l’intégration à installer (obligatoire uniquement pour l’action :install).
• third_party : définissez ce paramètre sur false si vous installez une intégration Datadog. Si ce n’est pas le cas, définissez-le sur true. Disponible à partir des versions 6.21/7.21 de l’Agent Datadog uniquement.

Exemple

Cet exemple permet d’installer la version 1.11.0 de l’intégration ElasticSearch en utilisant la ressource datadog_integration.

Remarque : l’installation de l’Agent doit être au-dessus de cette recette dans la run list.

include_recipe '::dd-agent'

datadog_integration 'datadog-elastic' do
  version '1.11.0'
end

Pour obtenir la liste des versions disponibles d’une intégration, consultez son CHANGELOG.md dans le référentiel integrations-core.

Remarque : pour les utilisateurs de Chef sous Windows, le chef-client doit avoir un accès en lecture au fichier datadog.yaml lorsque le binaire datadog-agent disponible sur le nœud est utilisé par cette ressource.

Développement

Environnement Dockerisé

Pour créer un environnement Docker avec lequel exécuter des tests kitchen, utilisez les fichiers sous docker_test_env :

cd docker_test_env
docker build -t chef-datadog-test-env .

Pour exécuter le conteneur, utilisez :

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

Attachez ensuite une console au conteneur ou utilisez la fonctionnalité remote-container de VS Code pour développer à l’intérieur du conteneur.

Pour exécuter des tests kitchen-docker depuis l’intérieur du conteneur :

# 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