Las recetas del Datadog Chef se usan para desplegar los componentes y la configuración de Datadog automáticamente. El cookbook es compatible con:

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

Nota: Es posible que esta página describa funciones que no están disponibles en la versión que has elegido. Consulta el archivo README de la etiqueta git o la versión del GEM de la documentación de tu versión.

Configuración

Requisitos

El cookbook de Datadog Chef es compatible con chef-client >= 12.7. Si necesitas compatibilidad con Chef < 12.7, usa la versión 2.x del cookbook. Consulta CHANGELOG para más información.

Platformas

Se admiten las siguientes plataformas:

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

Cookbooks

Los siguientes cookbooks de Opscode son dependencias:

• apt
• chef_handler
• yum

Nota: Se necesita, como mínimo, la v7.1 del cookbook apt para instalar el Agent en Debian 9 (y posteriores).

Chef

Usuarios de Chef 13: Con Chef 13 y chef_handler 1.x, puede que la receta dd-handler os dé algún problema. La única solución conocida es actualizar la dependencia a chef_handler >= 2.1.

Instalación

1. Añade el cookbook a tu servidor de Chef con Berkshelf o Knife:

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

   # Knife
   knife cookbook site install datadog
   

2. Configura los atributos específicos de Datadog en un rol, entorno u otra receta:

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

3. Carga el cookbook actualizado en tu servidor Chef:

   berks upload
   # or
   knife cookbook upload datadog
   

4. Después de cargar el cookbook, añádelo a los parámetros run_list o role de tu nodo:

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

5. Espera a que se ejecute el próximo chef-client programado o actívalo manualmente.

Atributos de Datadog

Puedes usar los siguientes métodos para añadir tus claves de API y aplicación de Datadog:

• Como atributos de nodo con un environment o role.
• Como atributos de nodo, declarando las claves en otro cookbook con un nivel más alto de prioridad.
• En el nodo run_state, definiendo node.run_state['datadog']['api_key'] en otro cookbook que sea anterior a las recetas de Datadog en la run_list. Esta opción no guarda las credenciales en el servidor de Chef como texto sin cifrar.

Nota: Cuando se usa el estado de ejecución para guardar las claves de API y aplicación, hay que configurarlas en el momento de la compilación y antes que datadog::dd-handler en la lista de ejecuciones.

Configuración extra

Para añadir más elementos al archivo de configuración del Agent (generalmente, datadog.yaml) sin que estén directamente disponibles como atributos del cookbook, usa el atributo node['datadog']['extra_config']. Se trata de un atributo hash que se ordena dentro del archivo de configuración como corresponde.

Ejemplos

El código siguiente define el campo secret_backend_command en el archivo de configuración datadog.yaml:

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

También se puede definir secret_backend_command usando:

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

Usa la sintaxis de objeto para los atributos anidados. El código siguiente define el campo logs_config en el archivo de configuración datadog.yaml:

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

Despliegue de Chef en AWS OpsWorks

Sigue los pasos siguientes para desplegar el Datadog Agent con Chef en AWS OpsWorks:

1. Añade el JSON personalizado de Chef:

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

2. Incluye la receta en la receta install-lifecycle:

include_recipe '::dd-agent'

Integraciones

Incluye la receta y los detalles de la configuración en la lista de ejecuciones y los atributos de tu rol para activar las integraciones del Agent. Nota: Puedes usar el recurso datadog_monitor para activar las integraciones del Agent sin una receta.

Asocia tus recetas con los roles que prefieras. Por ejemplo, role:chef-client debería contener datadog::dd-handler y role:base debería iniciar el Agent con datadog::dd-agent. A continuación, te mostramos un ejemplo de rol con las recetas dd-handler, dd-agent y 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]
)

Nota: No se usa data_bags en esta receta porque es improbable que haya varias claves de API con una sola clave de aplicación.

Versiones

Por defecto, la actual versión principal de este cookbook instala el Agent v7. Los siguientes atributos sirven para controlar la versión del Agent instalada:

Consulta el ejemplo attributes/default.rb correspondiente a tu versión del cookbook para ver todos los atributos disponibles.

Actualizar

Los nombres de algunos atributos han cambiado entre las versiones 3.x y 4.x del cookbook. Usa esta tabla de referencia para actualizar tu configuración:

Usa uno de los siguientes métodos para actualizar el Agent v6 al v7:

• Define agent_major_version como 7 y agent_package_action como install, y ancla una versión específica de v7 como agent_version (recomendado).
• Define agent_major_version como 7 y agent_package_action como upgrade.

El siguiente ejemplo muestra cómo se puede cambiar del Agent v6 al v7. Para pasar del Agent v5 al v6, sigue los mismos pasos.

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

Pasar a una versión anterior

Para cambiar a una versión anterior del Agent, define 'agent_major_version', 'agent_version' y 'agent_allow_downgrade'.

El siguiente ejemplo muestra cómo se puede cambiar del Agent v7 al v6. Para pasar del Agent v6 al v5, sigue los mismos pasos.

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

Desinstalar

Para desinstalar el Agent, elimina la receta dd-agent y añade la receta remove-dd-agent sin atributos.

Repositorio personalizado del Agent

Para utilizar un Agent de un repositorio personalizado, puedes configurar la opción aptrepo.

Por defecto, esta opción es igual a [signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datadoghq.com. Si se establece un valor personalizado, también se puede establecer otro conjunto de claves signed-by [signed-by=custom-repo-keyring-path] custom-repo.

El ejemplo siguiente utiliza el repositorio de preparación:

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

Recetas

Accede a las recetas de Datadog Chef en GitHub.

Predeterminado

La receta predeterminada es un parámetro.

Agent

La receta dd-agent instala el Datadog Agent en el sistema de destino, establece tu clave de API de Datadog e inicia el servicio para enviar métricas de sistemas locales.

Nota: Los usuarios de Windows que actualicen las versiones del Agent <= 5.10.1 a >= 5.12.0 a otras posteriores, deben definir el atributo windows_agent_use_exe como true. Para más información, consulta la wiki de dd-agent.

Handler

La receta dd-handler instala el GEM chef-handler-datadog e invoca el handler al final de una ejecución de Chef para enviar los detalles al muro de noticias.

DogStatsD

Para instalar una biblioteca en un lenguaje concreto para interactuar con DogStatsD:

• Ruby: receta dogstatsd-ruby
• Python: Añade una dependencia del cookbook poise-python en tu cookbook personalizado/contenedor y usa el recurso que te presentamos a continuación. Para más información, consulta el repositorio poise-python.

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

Rastreo

Para instalar una biblioteca en un lenguaje concreto para rastrear aplicaciones (APM):

• Ruby: receta ddtrace-ruby
• Python: Añade una dependencia del cookbook poise-python en tu cookbook personalizado/contenedor y usa el recurso que te presentamos a continuación. Para más información, consulta el repositorio poise-python.

  python_package 'ddtrace' # assumes python and pip are installed
  

Integraciones

Hay muchas recetas que pueden ayudarte a desplegar los archivos de configuración y las dependencias de la integración del Agent.

System-probe

La receta system-probe se incluye automáticamente por defecto y es la encargada de redactar el archivo system-probe.yaml. Se puede modificar este comportamiento si se establece node['datadog']['system_probe']['manage_config'] como false.

Para activar Network Performance Monitoring (NPM) en system-probe.yaml, define node['datadog']['system_probe']['network_enabled'] como true.

Para activar Universal Service Monitoring (USM) en system-probe.yaml, define node['datadog']['system_probe']['service_monitoring_enabled'] como true.

Nota para usuarios de Windows: Windows admite NPM con el Agent v6.27/v7.27 (y posteriores). Esta herramienta se distribuye como un componente opcional que solo se instala si node['datadog']['system_probe']['network_enabled'] está configurado como true en el momento de instalar o actualizar el Agent. Por este motivo, las instalaciones existentes podrían requerir la desinstalación y reinstalación del Agent para instalar el componente NPM, a no ser que se actualice el Agent al mismo tiempo.

Recursos

Integraciones sin recetas

Usa el recurso datadog_monitor para activar integraciones del Agent sin ninguna receta.

Acciones

• :add: (predeterminado) Prepara el archivo de configuración, añade los permisos correctos al archivo y reinicia el Agent para activar la integración.
• :remove: Desactiva una integración.

Sintaxis

datadog_monitor 'name' do
  init_config                       Hash # valor predeterminado: {}
  instances                         Array # valor predeterminado: []
  logs                              Array # valor predeterminado: []
  use_integration_template          true, false # valor predeterminado: false
  config_name                       String # valor predeterminado: 'conf'
  action                            Symbol # con el valor predeterminado :add
end

Propiedades

Ejemplo

Este ejemplo muestra cómo se activa la integración de ElasticSearch usando el recurso datadog_monitor. Esto proporciona la configuración de la instancia (en este caso, la URL para conectar con ElasticSearch) y define el indicador de use_integration_template para usar la plantilla de configuración predeterminada. Además, avisa al recurso service[datadog-agent] para que reinicie el Agent.

Nota: La instalación del Agent debe estar por encima de esta receta en la lista de ejecuciones.

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

Consulta las recetas de Chef para su integración con Datadog si deseas ver más ejemplos.

Versiones de integraciones

Para instalar una versión específica de una integración de Datadog, usa el recurso datadog_integration.

Acciones

• :install: (predeterminado) Instala una integración con la versión especificada.
• :remove: Elimina una integración.

Sintaxis

datadog_integration 'name' do
  version                      String         # version to install for :install action
  action                       Symbol         # defaults to :install
  third_party                  [true, false]  # defaults to :false
end

Propiedades

• 'name': Nombre de la integración del Agent que se va a instalar. Ejemplo: datadog-apache.
• version: Versión de la integración que se va a instalar (solo se necesita con la acción :install).
• third_party: Debe establecerse como false si se va a instalar una integración de Datadog y como true en caso contrario. Solamente disponible para las versiones 6.21/7.21 y posteriores del Datadog Agent.

Ejemplo

Este ejemplo instala la versión 1.11.0 de la integración de ElasticSearch usando el recurso datadog_integration.

Nota: La instalación del Agent debe estar por encima de esta receta en la lista de ejecuciones.

include_recipe '::dd-agent'

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

Para obtener las versiones disponibles de las integraciones, consulta el CHANGELOG.md específico de la integración en el repositorio integrations-core.

Nota: En el caso de los usuarios de Chef con Windows, chef-client debe tener permiso para leer el archivo datadog.yaml cuando este recurso use el binario datadog-agent disponible en el nodo.

Desarrollo

Entorno dockerizado

Para crear un entorno Docker con el cual ejecutar pruebas Kitchen, utiliza los archivos siguientes docker_test_env:

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

Para ejecutar el contenedor, usa:

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

Luego, asocia una consola al contenedor o usa la función de contenedor remoto de VS Code para desarrollar dentro del contenedor.

Para ejecutar pruebas kitchen-docker desde el contenedor:

# Nota: También configura KITCHEN_DOCKER_HOSTNAME=host.docker.internal si estás en MacOS o Windows
# Ejecuta esto bajo un shell de inicio de sesión (de lo contrario, no se encontrará `bundle`)
KITCHEN_LOCAL_YAML=kitchen.docker.yml bundle exec rake circle