Chef로 Datadog 에이전트 설치와 구성

원문 보기 위키 갱신 2026.10.05

Datadog Chef cookbook을 사용해 지원되는 Linux와 Windows 플랫폼에서 Datadog 에이전트의 설치와 구성을 자동화해요.

출처: 문서

본문

Datadog Chef cookbook은 지원되는 Linux와 Windows 플랫폼에서 Datadog 에이전트의 설치와 구성을 자동화해요. 이 cookbook은 chef-client >= 12.7과 호환되며 Windows와 Linux 플랫폼을 지원해요. 전체 속성 참조, 레시피, 사용 예제, 통합 구성 패턴은 아래 고급 구성 섹션을 참고하세요.

Datadog Chef 레시피는 Datadog의 구성 요소와 구성을 자동으로 배포하는 데 사용돼요. cookbook은 다음을 지원해요.

Datadog 에이전트 v7.x(기본)
Datadog 에이전트 v6.x
Datadog 에이전트 v5.x

참고: 이 페이지는 선택한 버전에서 사용할 수 없는 기능을 다룰 수도 있어요. 해당 버전의 문서는 git 태그 또는 gem 버전의 README를 확인하세요.

사전 요구사항

Datadog Chef cookbook은 chef-client >= 12.7과 호환돼요. Chef < 12.7 지원이 필요하면 cookbook 2.x 릴리스를 사용하세요. 자세한 내용은 CHANGELOG를 참고하세요.

플랫폼

다음 플랫폼이 지원돼요.

AlmaLinux(Chef 16 >= 16.10.8 또는 Chef >= 17.0.69 필요)
Amazon Linux
CentOS
Debian
RedHat(RHEL 8은 Chef >= 15 필요)
Rocky(Chef 16 >= 16.17.4 또는 Chef >= 17.1.35 필요)
Scientific Linux
Ubuntu
Windows
SUSE(Chef >= 13.3 필요)

Cookbook

다음 Opscode cookbook은 의존성으로 필요해요.

apt
chef_handler
yum

참고: Debian 9+에 에이전트를 설치하려면 apt cookbook v7.1+가 필요해요.

Chef

Chef 13 사용자: Chef 13과 chef_handler 1.x를 사용하면 dd-handler 레시피에 문제가 있을 수 있어요. 알려진 해결 방법은 의존성을 chef_handler >= 2.1로 업데이트하는 거예요.

셋업

설치

Chef로 Datadog 에이전트를 설치하려면 Fleet Automation의 인앱 흐름의 Berkshelf 또는 Knife용 셋업 가이드를 따라 하세요. 이 셋업 가이드에서 관찰 기능을 선택할 수 있고 환경에 필요한 속성과 명령을 생성해 줘요.

다음은 셋업 단계를 나열한 거예요.

    # Berksfile
    cookbook 'datadog', '~> 4.0'
    ```
    ```shell
    # Knife
    knife cookbook site install datadog
    ```
2. 역할(role), 환경(environment), 또는 다른 레시피에서 [Datadog 전용 속성](#datadog-attributes)을 설정하세요.
    ```text
    node.default['datadog']['api_key'] = "<YOUR_DD_API_KEY>"
    node.default['datadog']['application_key'] = "<YOUR_DD_APP_KEY>"
    ```
3. 업데이트된 cookbook을 Chef 서버에 업로드하세요.
    ```shell
    berks upload
    # or
    knife cookbook upload datadog
    ```
4. 업로드 후 cookbook을 노드의 `run_list` 또는 `role`에 추가하세요.
    ```text
    "run_list": [
      "recipe[datadog::dd-agent]"
    ]
    ```
5. 다음 예약된 `chef-client` 실행을 기다리거나 직접 트리거하세요.

Datadog 속성

[Datadog API 및 애플리케이션 키][4]를 추가하는 데 사용 가능한 방법은 다음과 같아요.

environment 또는 role이 있는 노드 속성으로.
다른 cookbook에서 더 높은 우선순위 수준으로 키를 선언해 노드 속성으로.
run_list에서 Datadog 레시피보다 앞서는 다른 cookbook에서 node.run_state['datadog']['api_key']를 설정해 노드 run_state로. 이 방식은 Chef 서버에 자격 증명을 평문으로 저장하지 않아요.

참고: API 및 애플리케이션 키를 저장할 때 run state를 사용한다면 run_list의 datadog::dd-handler 전 compile time에 설정하세요.

고급 구성

cookbook의 속성으로 직접 제공되지 않는 요소를 에이전트 구성 파일(보통 datadog.yaml)에 추가하려면 node['datadog']['extra_config'] 속성을 사용하세요. 이 속성은 구성 파일에 그에 맞게 마샬링되는 해시 속성이에요.

예제

다음 코드는 구성 파일 datadog.yaml에서 secret_backend_command 필드를 설정해요.

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

secret_backend_command는 다음으로도 설정할 수 있어요.

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

중첩 속성에는 객체 구문을 사용하세요. 다음 코드는 구성 파일 datadog.yaml에서 logs_config 필드를 설정해요.

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

AWS OpsWorks Chef 배포

AWS OpsWorks에서 Chef로 Datadog 에이전트를 배포하려면 아래 단계를 따르세요.

Chef 커스텀 JSON을 추가하세요.

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

install-lifecycle 레시피에 레시피를 포함하세요.

include_recipe '::dd-agent'

통합

역할의 run-list와 속성에 레시피와 구성 세부 정보를 포함해 에이전트 통합을 활성화하세요. 참고: 레시피 없이 에이전트 통합을 활성화하려면 datadog_monitor 리소스를 사용할 수 있어요.

레시피를 원하는 roles와 연결하세요. 예를 들어 role:chef-client는 datadog::dd-handler를 포함해야 하고 role:base는 datadog::dd-agent로 에이전트를 시작해야 해요. 아래는 dd-handler, dd-agent, 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]
)

참고: 애플리케이션 키 하나와 함께 여러 API 키가 있을 가능성이 낮으므로 이 레시피에서는 data_bags를 사용하지 않아요.

버전

기본적으로 이 cookbook의 현재 메이저 버전은 에이전트 v7을 설치해요. 설치되는 에이전트 버전을 제어하는 데 다음 속성을 사용할 수 있어요.

파라미터	설명
`agent_major_version`	에이전트 메이저 버전을 5, 6, 7(기본)로 고정해요.
`agent_version`	특정 에이전트 버전을 고정해요(권장).
`agent_package_action`	(Linux 전용) 기본은 `'install'`(권장), 자동 에이전트 업데이트를 원하면 `'upgrade'`(권장하지 않음, 기본을 사용하고 고정된 `agent_version`을 변경해 업그레이드).
`agent_flavor`	(Linux 전용) 기본은 `'datadog-agent'`로 datadog-agent 설치, IOT 에이전트를 설치하려면 `'datadog-iot-agent'`로 설정할 수 있어요.

cookbook 버전의 사용 가능한 모든 속성은 샘플 attributes/default.rb를 참고하세요.

업그레이드

cookbook 3.x에서 4.x로 일부 속성 이름이 변경됐어요. 이 참조 표를 사용해 구성을 업데이트하세요.

작업	Cookbook 3.x	Cookbook 4.x
에이전트 7.x 설치	지원 안 함	`'agent_major_version' => 7`
에이전트 6.x 설치	`'agent6' => true`	`'agent_major_version' => 6`
에이전트 5.x 설치	`'agent6' => false`	`'agent_major_version' => 5`
에이전트 버전 고정	`'agent_version'` 또는 `'agent6_version'`	모든 버전에 `'agent_version'`
package_action 변경	`'agent_package_action'` 또는 `'agent6_package_action'`	모든 버전에 `'agent_package_action'`
APT repo URL 변경	`'aptrepo'` 또는 `'agent6_aptrepo'`	모든 버전에 `'aptrepo'`
APT repo 배포 변경	`'aptrepo_dist'` 또는 `'agent6_aptrepo_dist'`	모든 버전에 `'aptrepo_dist'`
YUM repo 변경	`'yumrepo'` 또는 `'agent6_yumrepo'`	모든 버전에 `'yumrepo'`
SUSE repo 변경	`'yumrepo_suse'` 또는 `'agent6_yumrepo_suse'`	모든 버전에 `'yumrepo_suse'`

에이전트 v6에서 v7로 업그레이드하는 방법은 두 가지예요.

agent_major_version을 7로, agent_package_action을 install로 설정하고 특정 v7 버전을 agent_version으로 고정(권장).
agent_major_version을 7로, agent_package_action을 upgrade로 설정.

다음 예제는 에이전트 v6에서 v7로 업그레이드해요. v5에서 v6으로 업그레이드할 때도 동일하게 적용돼요.

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

다운그레이드

에이전트 버전을 다운그레이드하려면 'agent_major_version', 'agent_version', 'agent_allow_downgrade'를 설정하세요.

다음 예제는 에이전트 v6로 다운그레이드해요. v5로 다운그레이드할 때도 동일하게 적용돼요.

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

제거

에이전트를 제거하려면 dd-agent 레시피를 제거하고 속성이 없는 remove-dd-agent 레시피를 추가하세요.

커스텀 에이전트 저장소

커스텀 저장소의 에이전트를 사용하려면 aptrepo 옵션을 설정할 수 있어요.

기본적으로 이 옵션은 [signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] apt.datadoghq.com과 같아요. 커스텀 값을 설정하면 다른 signed-by 키링도 [signed-by=custom-repo-keyring-path] custom-repo로 설정할 수 있어요.

아래 예제는 스테이징 저장소를 사용해요.

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

레시피

GitHub의 Datadog Chef 레시피에 접근하세요.

기본

기본 레시피는 자리 표시자예요.

에이전트

dd-agent 레시피는 대상 시스템에 Datadog 에이전트를 설치하고 Datadog API 키를 설정하며 로컬 시스템 메트릭을 보고하기 위해 서비스를 시작해요.

참고: 에이전트를 버전 <= 5.10.1에서 >= 5.12.0으로 업그레이드하는 Windows 사용자는 windows_agent_use_exe 속성을 true로 설정하세요. 자세한 내용은 dd-agent 위키를 참고하세요.

핸들러

dd-handler 레시피는 chef-handler-datadog gem을 설치하고 Chef 실행이 끝날 때 핸들러를 호출해 세부 정보를 뉴스 피드에 보고해요.

DogStatsD

DogStatsD와 상호작용하는 언어별 라이브러리를 설치하려면:

Ruby: dogstatsd-ruby 레시피
Python: 커스텀/래퍼 cookbook에 poise-python cookbook 의존성을 추가하고 아래 리소스를 사용하세요. 자세한 내용은 poise-python 저장소를 참고하세요.
```
python_package 'dogstatsd-python' # assumes python and pip are installed
```

트레이싱

애플리케이션 트레이싱(APM)용 언어별 라이브러리를 설치하려면:

Ruby: ddtrace-ruby 레시피
Python: 커스텀/래퍼 cookbook에 poise-python cookbook 의존성을 추가하고 아래 리소스를 사용하세요. 자세한 내용은 poise-python 저장소를 참고하세요.
```
python_package 'ddtrace' # assumes python and pip are installed
```

통합

에이전트 통합 구성 파일과 의존성을 배포하는 데 도움이 되는 많은 레시피가 있어요.

시스템 프로브

system-probe 레시피는 기본적으로 자동 포함돼요. 이 레시피는 system-probe.yaml 파일을 작성해요. 이 동작은 node['datadog']['system_probe']['manage_config']를 false로 설정해 비활성화할 수 있어요.

system-probe.yaml에서 네트워크 성능 모니터링(NPM)을 활성화하려면 node['datadog']['system_probe']['network_enabled']을 true로 설정하세요.

system-probe.yaml에서 유니버설 서비스 모니터링(USM)을 활성화하려면 node['datadog']['system_probe']['service_monitoring_enabled']을 true로 설정하세요.

Windows 사용자 참고: NPM은 에이전트 v6.27+ 및 v7.27+에서 Windows를 지원해요. NPM은 에이전트 설치 또는 업그레이드 시 node['datadog']['system_probe']['network_enabled']이 true로 설정된 경우에만 설치되는 선택적 구성 요소로 제공돼요. 따라서 기존 설치에서는 에이전트를 동시에 업그레이드하지 않는 한 NPM 구성 요소를 설치하기 위해 에이전트를 한 번 제거·재설치해야 할 수 있어요.

리소스

레시피 없는 통합

레시피 없이 에이전트 통합을 활성화하려면 datadog_monitor 리소스를 사용하세요.

작업

:add:(기본) 구성 파일을 설정하고 파일에 올바른 권한을 추가하며 에이전트를 재시작해 통합을 활성화해요.
:remove: 통합을 비활성화해요.

구문

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

속성

속성	설명
`'name'`	구성하고 활성화할 에이전트 통합의 이름이에요.
`instances`	통합 구성 파일의 `instances` 섹션 아래 값을 채우는 데 사용되는 필드예요.
`init_config`	통합 구성 파일의 `init_config` 섹션 아래 값을 채우는 데 사용되는 필드예요.
`logs`	통합 구성 파일의 `logs` 섹션 아래 값을 채우는 데 사용되는 필드예요.
`use_integration_template`	기본 템플릿을 사용하려면 `true`(권장)로 설정해요. 이 템플릿은 `instances`, `init_config`, `logs` 값을 YAML의 각 키 아래에 작성해요. 하위 호환을 위해 기본값은 `false`이지만, 미래의 cookbook 메이저 버전에서는 `true`가 기본이 될 수 있어요.
`config_name`	통합 구성 파일 생성 시 사용되는 파일 이름이에요. 이 속성을 덮어쓰면 단일 통합에 대해 여러 구성 파일을 만들 수 있어요. 기본값은 `conf`로, `conf.yaml`이라는 구성 파일을 만들어요.

예제

이 예제는 datadog_monitor 리소스를 사용해 ElasticSearch 통합을 활성화해요. 인스턴스 구성(여기서는 ElasticSearch에 연결할 URL)을 제공하고 기본 구성 템플릿을 사용하도록 use_integration_template 플래그를 설정해요. 또한 service[datadog-agent] 리소스에 에이전트를 재시작하라고 알려요.

참고: 에이전트 설치는 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

추가 예제는 Datadog 통합 Chef 레시피를 참고하세요.

통합 버전

Datadog 통합의 특정 버전을 설치하려면 datadog_integration 리소스를 사용하세요.

작업

:install:(기본) 지정된 버전으로 통합을 설치해요.
:remove: 통합을 제거해요.

구문

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

속성

'name': 설치할 에이전트 통합의 이름. 예: datadog-apache.
version: 설치할 통합의 버전(:install 작업에서만 필요).
third_party: Datadog 통합을 설치하면 false, 그 외에는 true. Datadog 에이전트 버전 6.21/7.21 이상에서만 사용할 수 있어요.

예제

이 예제는 datadog_integration 리소스를 사용해 ElasticSearch 통합 버전 1.11.0을 설치해요.

참고: 에이전트 설치는 run list에서 이 레시피보다 위에 있어야 해요.

include_recipe '::dd-agent'

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

사용 가능한 통합 버전을 얻으려면 integrations-core 저장소에서 통합별 CHANGELOG.md를 참고하세요.

참고: Chef Windows 사용자의 경우, 이 리소스가 노드에서 사용 가능한 datadog-agent 바이너리를 사용할 때 chef-client가 datadog.yaml 파일에 대한 읽기 권한이 있어야 해요.

개발

Dockerized 환경

kitchen 테스트를 실행할 Docker 환경을 빌드하려면 docker_test_env 아래 파일을 사용하세요.

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

컨테이너를 실행하려면 다음을 사용하세요.

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

그런 다음 컨테이너에 콘솔을 연결하거나 VS Code 원격 컨테이너 기능을 사용해 컨테이너 내부에서 개발하세요.

컨테이너 내부에서 kitchen-docker 테스트를 실행하려면:

# 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

더 알아보기 (Learn more)

추가로 도움이 되는 문서, 링크, 아티클: