Puppet으로 Datadog 에이전트 설치와 구성

원문 보기 위키 갱신 2026.10.05

Puppet 모듈을 사용해 Datadog 에이전트를 설치하고 Puppet 리포트를 Datadog로 보내요.

출처: 문서

본문

이 모듈은 Datadog 에이전트를 설치하고 Puppet 리포트를 Datadog로 보내요.

사전 요구사항

Datadog Puppet 모듈은 Linux와 Windows를 지원하며 Puppet >= 7.34.x 또는 Puppet Enterprise 버전 >= 2021.7.x와 호환돼요. 호환성에 대한 자세한 내용은 Puppet Forge의 모듈 페이지를 참고하세요.

설치

Fleet Automation의 인앱 설치 가이드를 따라 필요한 기능을 선택하고, 생성된 매니페스트 스니펫을 복사해 Puppet 매니페스트에 추가하고, 표준 Puppet 배포를 적용해 에이전트를 배포하세요. 에이전트 업그레이드 관리, 에이전트 통합 활성화, Puppet 실행 보고 설정을 포함한 추가 구성은 Datadog 에이전트 모듈 또는 고급 구성 섹션을 참고하세요.

에이전트 업그레이드

[!IMPORTANT] Datadog Puppet 모듈 v4.x는 Puppet <= 6과 Datadog 에이전트 v5 지원을 중단해요. Puppet <= 6에서 Datadog 에이전트 v5+를 업그레이드하거나 설치하려면 모듈 v3.x를 사용하세요.

기본적으로 Datadog 에이전트 v7.x가 설치돼요. 에이전트 버전 6을 사용하려면 agent_major_version 설정을 변경하세요.
에이전트 v5 전용 레거시 옵션은 제거됐어요. 자세한 내용은 CHANGELOG.md를 참고하고, 사용 가능한 모든 옵션은 datadog_agent 클래스 주석을 참고하세요.

[!IMPORTANT] 아래 에이전트 통합에 업데이트와 호환성 깨짐 변경이 있었어요.

ActiveMQ_XML
- suppress_errors 구성이 supress_errors 대신 사용되어야 해요(하위 호환).
ElasticSearch [호환성 깨짐 변경]
- ssl_verify는 Boolean 값만 허용해요.
- tls_verify 옵션이 추가됐어요.
Disk Check [호환성 깨짐 변경]
- use_mount, all_partitions, tag_by_filesystem는 Boolean 값만 허용해요.
TCP Check
- skip_event 옵션이 Datadog 에이전트 v6.4+ 이후 제거됐어요.

구성

puppetserver/puppetmaster(또는 masterless 호스트)에 datadog_agent 모듈을 설치한 후 다음 구성 단계를 따르세요.

Datadog API 키를 얻으세요.
노드 매니페스트에 Datadog 클래스를 추가하세요(예: /etc/puppetlabs/code/environments/production/manifests/site.pp).
```
class { 'datadog_agent':
    api_key => "<YOUR_DD_API_KEY>",
}
```

기본 'datadoghq.com'이 아닌 다른 Datadog 사이트를 사용한다면 여기에서도 설정하세요.

class { 'datadog_agent':
    api_key => "<YOUR_DD_API_KEY>",
    datadog_site => "datadoghq.eu",
}

CentOS/RHEL 버전 <7.0과 Ubuntu < 15.04의 경우 서비스 제공자를 upstart로 지정하세요.

class { 'datadog_agent':
    api_key => "<YOUR_DD_API_KEY>",
    service_provider => 'upstart'
}

여기서 사용할 수 있는 인수 목록은 구성 변수 섹션을 참고하세요.

(선택) 에이전트와 함께 사용하려는 통합을 포함하세요. 다음 예제는 mongo 통합을 설치해요.
```
class { 'datadog_agent::integrations::mongo':
    # integration arguments go here
}
```

주어진 통합에 사용 가능한 모든 인수는 코드의 주석을 참고하세요.

통합에 전용 클래스가 있는 매니페스트가 없다면 여전히 해당 통합에 대한 구성을 추가할 수 있어요. 아래는 ntp 체크 예시예요.

class { 'datadog_agent':
    api_key      => "<YOUR_DD_API_KEY>",
    integrations => {
        "ntp" => {
            init_config => {},
            instances => [{
                offset_threshold => 30,
            }],
        },
    },
}

(선택) Puppet 자체에 대한 메트릭과 이벤트를 수집하려면 Reporting에 관한 섹션을 참고하세요.

고급 구성

통합 업그레이드

특정 통합 버전을 설치하고 고정하려면 datadog_agent::install_integration을 사용하세요. 이 명령은 datadog-agent integration 명령을 호출해 특정 통합이 설치되거나 제거되었는지 확인해요.

datadog_agent::install_integration { "mongo-1.9":
    ensure => present,
    integration_name => 'datadog-mongo',
    version => '1.9.0',
    third_party => false,
}

ensure 인수는 두 값을 가질 수 있어요.

present(기본)
absent(이전에 고정된 통합 버전 제거)

서드파티 통합(예: 마켓플레이스)을 설치하려면 third_party 인수를 true로 설정하세요.

에이전트에 번들로 포함된 버전보다 오래된 버전으로 통합을 다운그레이드할 수 없다는 점에 유의하세요.

보고

Puppet 실행을 Datadog 타임라인에 보고하려면 Puppet 마스터에서 리포트 프로세서를 활성화하고 클라이언트에 대해 보고를 활성화하세요. 클라이언트는 각 체크인 후 실행 리포트를 마스터로 보내요.

마스터의 노드 구성 매니페스트에서 puppet_run_reports 옵션을 true로 설정하세요.

class { 'datadog-agent':
  api_key            => '<YOUR_DD_API_KEY>',
  puppet_run_reports => true
  # ...
}

dogapi gem은 자동으로 설치돼요. 설치를 커스터마이즈하려면 manage_dogapi_gem을 false로 설정하세요.

Puppet 마스터 구성에 다음 구성 옵션을 추가하세요(예: /etc/puppetlabs/puppet/puppet.conf).

[main]
# No modification needed to this section
# ...

[master]
# Enable reporting to Datadog
reports=datadog_reports
# If you use other reports, add datadog_reports to the end,
# for example: reports=store,log,datadog_reports
# ...

[agent]
# ...
report=true

ini_setting 모듈 사용:

  ini_setting { 'puppet_conf_master_report_datadog_puppetdb':
    ensure  => present,
    path    => '/etc/puppetlabs/puppet/puppet.conf',
    section => 'master',
    setting => 'reports',
    value   => 'datadog_reports,puppetdb',
    notify  => [
      Service['puppet'],
      Service['puppetserver'],
    ],
  }

모든 Puppet 클라이언트 노드의 같은 위치에 다음을 추가하세요.

[agent]
# ...
report=true

ini_setting 모듈 사용:

  ini_setting { 'puppet_conf_agent_report_true':
    ensure  => present,
    path    => '/etc/puppetlabs/puppet/puppet.conf',
    section => 'agent',
    setting => 'report',
    value   => 'true',
    notify  => [
      Service['puppet'],
    ],
  }

(선택) 팩트로 리포트 태깅 활성화:

Datadog로 이벤트로 전송되는 리포트에 태그를 추가할 수 있어요. 이 태그는 해당 리포트가 관련된 노드의 Puppet 팩트에서 가져올 수 있어요. 가독성을 위해 1:1이어야 하고 구조적 팩트(해시, 배열 등)를 포함하지 않아야 해요. 일반 팩트 태깅을 활성화하려면 datadog_agent::reports::report_fact_tags 파라미터를 팩트의 배열 값으로 설정하세요(예: ["virtual","operatingsystem"]). 신뢰 팩트 태깅을 활성화하려면 datadog_agent::reports::report_trusted_fact_tags 파라미터를 팩트의 배열 값으로 설정하세요(예: ["certname","extensions.pp_role","hostname"]).

참고: 이 설정을 변경하려면 pe-puppetserver(또는 puppetserver)를 재시작해 리포트 프로세서를 다시 읽어야 해요. 서비스를 재시작하기 전에 변경 사항이 배포되었는지 확인하세요.

팁:

점 인덱스를 사용해 대상 팩트를 지정하세요. 그렇지 않으면 전체 팩트 데이터 세트가 문자열로 값이 돼요(그다지 유용하지 않음).
hostname, uptime, memory 같은 모니터링의 일반 데이터를 중복하지 마세요.
role, owner, template, datacenter 같은 핵심 팩트를 메트릭의 같은 태그와 의미 있는 상관관계를 만들도록 조정하세요.

Event Stream에서 sources:puppet을 검색해 Puppet 데이터가 Datadog에 있는지 확인하세요.

NPM 셋업

Datadog 에이전트 네트워크 성능 모니터링(NPM) 기능을 활성화하려면 다음 단계를 따르세요.

(Windows 전용) 에이전트가 이미 설치되어 있다면 메인 클래스에 win_ensure => absent를 전달해 제거하고 다른 클래스 정의를 제거하세요.
(Windows 전용) datadog::datadog_agent 클래스에 값 true로 windows_npm_install 옵션을 전달하세요. 이전 단계에서 추가했다면 win_ensure를 제거하세요.
datadog_agent::system_probe 클래스를 사용해 구성 파일을 올바르게 만드세요.

class { 'datadog_agent::system_probe':
    network_enabled => true,
}

USM 셋업

Datadog 에이전트 유니버설 서비스 모니터링(USM)을 활성화하려면 datadog_agent::system_probe 클래스를 사용해 구성 파일을 올바르게 만드세요.

class { 'datadog_agent::system_probe':
    service_monitoring_enabled => true,
}

트러블슈팅

출력에서 오류를 확인하려면 Puppet 에이전트를 수동으로 실행할 수 있어요.

```shell
sudo systemctl restart puppetserver
sudo puppet agent --onetime --no-daemonize --no-splay --verbose
```

예제 응답:

info: Retrieving plugin
info: Caching catalog for alq-linux.dev.datadoghq.com
info: Applying configuration version '1333470114'
notice: Finished catalog run in 0.81 seconds

다음 오류가 보이면 reports=datadog_reports가 [main]이 아니라 [master]에 정의되어 있는지 확인하세요.

```text
err: Could not send report:
Error 400 on SERVER: Could not autoload datadog_reports:
Class Datadog_reports is already defined in Puppet::Reports
```

들어오는 리포트가 없으면 Puppet 서버 로그를 확인하세요.

Masterless Puppet

Datadog 모듈과 그 의존성은 masterless로 실행되는 모든 노드에 설치되어야 해요.

각 노드의 site.pp 파일에 다음을 추가하세요.

class { "datadog_agent":
    api_key            => "<YOUR_DD_API_KEY>",
    puppet_run_reports => true
}

masterless 구성에서 puppet을 실행하세요.

puppet apply --modulepath <path_to_modules> <path_to_site.pp>

클라이언트 노드 태깅

Datadog 에이전트 구성 파일은 매 Puppet 실행마다 템플릿에서 다시 생성돼요. 노드를 태그해야 한다면 Hiera에 배열 항목을 추가하세요.

datadog_agent::tags:
- 'keyname:value'
- 'anotherkey:%{factname}'

커스텀 팩트로 태그를 생성하려면 Puppet Enterprise 콘솔이나 Hiera를 통해 facts_to_tags 파라미터에 Puppet 팩트를 배열로 분류하세요. 예시는 다음과 같아요.

class { "datadog_agent":
  api_key            => "<YOUR_DD_API_KEY>",
  facts_to_tags      => ["os.family","networking.domain","my_custom_fact"],
}

팁:

구조적 팩트는 특정 팩트 값으로 인덱싱하세요. 그렇지 않으면 전체 배열이 문자열로 전달되어 결국 사용하기 어려워져요.
CPU 사용량, Uptime 등 실행마다 바뀔 것으로 예상되는 동적 팩트는 태깅에 적합하지 않아요. 노드 수명 동안 유지될 것으로 예상되는 정적 팩트가 태깅에 가장 좋은 후보예요.

구성 변수

이 변수들은 datadog_agent 클래스에서 설정해 에이전트 설정을 제어할 수 있어요. 지원되는 인수의 전체 목록은 코드의 주석을 참고하세요.

변수 이름	설명
`agent_major_version`	설치할 에이전트 버전: 6 또는 7(기본: 7).
`agent_version`	설치할 에이전트 특정 마이너 버전을 고정할 수 있어요. 예: `1:7.16.0-1`. 최신 버전을 설치하려면 비워 두세요.
`collect_ec2_tags`	`true`를 사용해 인스턴스의 커스텀 EC2 태그를 에이전트 태그로 수집해요.
`collect_instance_metadata`	`true`를 사용해 인스턴스의 EC2 메타데이터를 에이전트 태그로 수집해요.
`datadog_site`	보고할 Datadog 사이트. 기본값은 `datadoghq.com`이며 예: `datadoghq.eu` 또는 `us3.datadoghq.com`.
`dd_url`	Datadog 수집 서버 URL. 변경할 필요가 없을 거예요. `datadog_site`를 덮어써요.
`host`	노드의 호스트 이름을 덮어써요.
`local_tags`	노드에 대한 태그로 설정되는 `<KEY:VALUE>` 문자열 배열.
`non_local_traffic`	다른 노드가 이 노드를 통해 DogstatsD 트래픽을 중계할 수 있게 허용해요.
`apm_enabled`	APM 에이전트를 활성화하는 부울(기본값 false).
`process_enabled`	프로세스 에이전트를 활성화하는 부울(기본값 false).
`scrub_args`	프로세스 cmdline 스크러빙을 활성화하는 부울(기본값 true).
`custom_sensitive_words`	스크러빙 기능이 기본으로 사용하는 단어 외에 더 많은 단어를 추가하는 배열(기본값 `[]`).
`logs_enabled`	로그 에이전트를 활성화하는 부울(기본값 false).
`windows_npm_install`	Windows NPM 드라이버 설치를 활성화하는 부울(기본값 false).
`win_ensure`	Windows에서 Datadog 에이전트의 존재/부재를 보장하는 enum(present/absent)(기본값 present).
`container_collect_all`	모든 컨테이너의 로그 수집을 활성화하는 부울.
`agent_extra_options`1	추가 구성 옵션을 제공하는 해시(에이전트 v6과 v7 전용).
`hostname_extraction_regex`2	Puppet 노드 이름 대신 Datadog에서 실행을 보고하기 위해 호스트 이름 캡처 그룹을 추출하는 데 사용되는 정규식. 예: `'^(?<hostname>.\.datadoghq\.com)(\.i-\w{8}\..)?$'`

(1) agent_extra_options는 추가 에이전트 v6/v7 구성 옵션을 세밀하게 제어하는 데 사용돼요. datadog_agent 클래스 파라미터에서 제공된 옵션을 덮어쓸 수 있는 딥 병합이 수행돼요. 예:

class { "datadog_agent":
    < your other arguments to the class >,
    agent_extra_options => {
        use_http => true,
        use_compression => true,
        compression_level => 6,
    },
}

(2) hostname_extraction_regex는 Puppet 모듈과 Datadog 에이전트가 인프라 목록에서 같은 호스트에 대해 다른 호스트 이름을 보고할 때 유용해요.