Datadog Agent Ansible ロールは、Datadog Agent とインテグレーションをインストールおよび構成します。

Ansible ロールと Ansible コレクション

Datadog Agent Ansible ロールは、2 つの異なるチャンネルで利用できます。

• Datadog コレクションの一部として、Ansible Galaxy 上で datadog.dd の名前で利用可能 (推奨)。
• スタンドアロンロールとして、Ansible Galaxy 上で datadog.datadog の名前で利用可能 (レガシー)。

ロールのバージョン 4 とコレクションのバージョン 5 は、デフォルトで Datadog Agent v7 をインストールします。

セットアップ

このドキュメントのインストール手順は、スタンドアロンの Datadog ロールのインストールを説明しています。Datadog コレクションのインストール手順については、コレクションの README ファイルを参照してください。構成変数は、スタンドアロンのロールとコレクションからアクセスされるロールの両方で同じです。

要件

• Ansible v2.6 以上。

• Debian と RHEL ベースの Linux ディストリビューション、macOS および Windows のほとんどをサポートしていること。

• Ansible 2.10+ で Windows ホストを管理する場合、ansible.windows コレクションをインストールする必要があります。

  ansible-galaxy collection install ansible.windows
  

• Ansible 2.10+ を使用して openSUSE/SLES ホストを管理する場合、community.general コレクションのインストールが必要です。

  ansible-galaxy collection install community.general
  

インストール

Datadog のロールを Ansible サーバー上で、Ansible Galaxy からインストールします。

ansible-galaxy install datadog.datadog

Datadog Agent をホストにデプロイするには、Datadog のロールと API キーをプレイブックに追加します。

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "<DD_API_キー>"

API キーは必須で、存在しない場合はロールが失敗します。Ansible の管理外で別の方法で提供したい場合は、プレースホルダーのキーを指定し、後でキーを置き換えてください。

エアギャップ環境

特定のレジストリとイメージを使用して Datadog をエアギャップ環境にインストールするには、Datadog Ansible コレクションと、datadog_installer_registry、datadog_installer_auth、agent_datadog_config 変数を併用してください。

注: agent_datadog_config は installer_registry_config の設定を上書きします。

例:

name: Datadog Agent Install
  include_role:
    name: datadog.dd.agent
  vars:
    datadog_installer_registry: "my.local.registry"
    datagog_yum_repo: "my.local.repo"
    datadog_api_key: "MY_DATADOG_API_KEY"
    datadog_site: "MY_DATADOG_SITE"

ロールの変数

これらの変数は Datadog Agent のインストール時に追加の設定を行います。vars セクションで指定してください。

インテグレーション

Datadog インテグレーション（チェック）を構成するには、datadog_checks セクションにエントリを追加します。第 1 レベルのキーにチェックの名前を入力し、値にはコンフィギュレーションファイルに記載する YAML ペイロードを入力します。以下にその例を示します。

インテグレーションをインストールまたは削除するには、datadog_integration の該当セクションを参照してください

プロセスチェック

process チェックに 2 つのインスタンスを定義するには、以下のコンフィギュレーションを使用します。これにより、それぞれに対応するコンフィギュレーションファイルが作成されます。

• Agent v6 および v7: /etc/datadog-agent/conf.d/process.d/conf.yaml
• Agent v5: /etc/dd-agent/conf.d/process.yaml

    datadog_checks:
      process:
        init_config:
        instances:
          - name: ssh
            search_string: ['ssh', 'sshd']
          - name: syslog
            search_string: ['rsyslog']
            cpu_check_interval: 0.2
            exact_match: true
            ignore_denied_access: true

カスタムチェック

カスタムチェックを構成するには、以下のコンフィギュレーションを使用します。これにより、それぞれに対応するコンフィギュレーションファイルが作成されます。

• Agent v6 および v7: /etc/datadog-agent/conf.d/my_custom_check.d/conf.yaml
• Agent v5: /etc/dd-agent/conf.d/my_custom_check.yaml

    datadog_checks:
      my_custom_check:
        init_config:
        instances:
          - some_data: true

カスタム Python チェック

Python チェックをプレイブックに渡すには、以下の構成を使用します。

この構成では、Datadog のプレイとロールが、Linux または Windows のための実際のタスクへの相対ファイルパスとして渡される大きなプレイブックの一部であることが要求されます。

これは Agent v6+ 以降でのみ利用可能です。

キーはチェックディレクトリ checks.d/{{ item }}.py に作成されるファイル名である必要があります。

    datadog_checks:
      my_custom_check:
        init_config:
        instances:
          - some_data: true
    datadog_custom_checks:
      my_custom_check: '../../../custom_checks/my_custom_check.py'

オートディスカバリー

オートディスカバリーを使用する場合は、YAML での前処理も後処理も必要ありません。つまり、autodiscovery identifiers を含むすべての YAML セクションが、完成後のコンフィギュレーションファイルに追加されます。

以下は、オートディスカバリーによる PostgreSQL チェックを構成する例です。

    datadog_checks:
      postgres:
        ad_identifiers:
          - db-master
          - db-slave
        init_config:
        instances:
          - host: %%host%%
            port: %%port%%
            username: ユーザー名
            password: パスワード

詳しくは、Datadog のオートディスカバリーに関するドキュメントを参照してください。

トレーシング

Agent v6 または v7 でトレース収集を有効にするには、以下のコンフィギュレーションを使用します。

datadog_config:
  apm_config:
    enabled: true

Agent v5 でトレース収集を有効にするには、以下のコンフィギュレーションを使用します。

datadog_config:
  apm_enabled: "true" # 文字列であることが必要

ライブプロセス

Agent v6 または v7 でライブプロセス収集を有効にするには、以下のコンフィギュレーションを使用します。

datadog_config:
  process_config:
    enabled: "true" # 型: 文字列

enabled の値には "true"、"false"（コンテナ収集のみ）、"disabled"（ライブプロセスを完全に無効化）を指定できます。

変数

ライブプロセスには、以下の変数を使用できます。

• scrub_args: プロセスのコマンドラインで、機密性の高い引数のスクラビングを有効にします（デフォルトでは true）。
• custom_sensitive_words: コマンドラインのスクラビング機能が使用する、機密語のデフォルトリストを拡張します。

システムプローブ

システムプローブは system_probe_config 変数の下で構成されます。その下にネストされる変数はすべて、system_probe_config セクションの system-probe.yaml に書き込まれます。

ネットワークパフォーマンスモニタリング（NPM）は、 network_config 変数の下で構成されます。その下にネストされる変数はすべて、network_config セクションの system-probe.yaml に書き込まれます。

Cloud Workload Security は runtime_security_config 変数の下で構成されます。その下にネストされる変数はすべて、runtime_security_config セクションの system-probe.yaml および security-agent.yaml に書き込まれます。

Universal Service Monitoring (USM) は service_monitoring_config 変数で構成されます。その下にネストされた変数は system-probe.yaml の service_monitoring_config セクションに書き込まれます。

Compliance は compliance_config 変数の下で構成されます。その下にネストされる変数はすべて、compliance_config セクションの security-agent.yaml に書き込まれます。

Windows をご利用の方へのご注意: NPM は Agent v6.27+ と v7.27+ で Windows 上でサポートされています。NPM はオプションコンポーネントとして出荷され、Agent のインストールまたはアップグレード時に network_config.enabled が true に設定された場合にのみインストールされます。このため、Agent を同時にアップグレードしない限り、既存のインストールでは NPM コンポーネントをインストールするために一旦 Agent をアンインストールして再インストールする必要があるかもしれません。

構成サンプル

datadog_config:
  process_config:
    enabled: "true" # type: string
    scrub_args: true
    custom_sensitive_words: ['consul_token','dd_api_key']
system_probe_config:
  sysprobe_socket: /opt/datadog-agent/run/sysprobe.sock
network_config:
  enabled: true
service_monitoring_config:
  enabled: true
runtime_security_config:
  enabled: true

注: このコンフィギュレーションは Agent 6.24.1 以降および 7.24.1 以降で機能します。それ以前のバージョンの Agent については、ネットワークパフォーマンスのモニタリングドキュメントのシステムプローブの有効化方法を参照してください。

Linux の場合、この変更後、インストールした Agent のバージョンが 6.18.0 または 7.18.0 より前の場合は、以下のステップに従います。

1. システムプローブを起動します: sudo service datadog-agent-sysprobe start 注: ご使用のシステムで service ラッパーを使用できない場合は、代わりに次のコマンドを使用してください: sudo initctl start datadog-agent-sysprobe。
2. Agent を再起動します: sudo service datadog-agent restart
3. システムプローブがブートから起動されるようにします: sudo service enable datadog-agent-sysprobe。

手動でセットアップする場合は、NPM のドキュメントを参照してください。

Agent v5

Agent v5 でライブプロセス収集を有効にするには、以下のコンフィギュレーションを使用します。

datadog_config:
  process_agent_enabled: true
datadog_config_ex:
  process.config:
    scrub_args: true
    custom_sensitive_words: "<最初の語>,<次の語>"

バージョン

デフォルトでは、Datadog Ansible ロールの現在のメジャーバージョンは、Agent v7 をインストールします。datadog_agent_version と datadog_agent_major_version の変数を使用すると、インストールされる Agent のバージョンをコントロールできます。

このロールのバージョン v4 以上では、datadog_agent_version を使用して Agent のバージョンを固定すると、ロールはサポート対象の OS のバージョン命名スキームに従って、OS ごとに異なるバージョン名を作成します。たとえば以下のようになります。

• Debian および SUSE ベースの場合は 1:7.16.0-1
• RedHat ベースの場合は 7.16.0-1
• macOS の場合 7.16.0-1
• Windows の場合は 7.16.0

これにより、ホストが複数の OS で稼働している場合に、バージョンを指定することが可能になります。以下に例を示します。

バージョン: バージョンを指定しない場合、ロールはエポックに 1 を、リリース番号に 1 を使用します。

Agent v5（旧バージョン）:

Datadog Ansible ロールは、Linux のみを対象として、Datadog Agent v5 をサポートしています。Agent v5 をインストールする場合は、datadog_agent_major_version: 5 を使用することで、Agent v5 の最新バージョンをインストールできます。あるいは、datadog_agent_version を設定して、Agent v5 の特定のバージョンをインストールすることもできます。注: datadog_agent5 変数は非推奨であり、削除されています。

リポジトリ

Linux

datadog_apt_repo、datadog_yum_repo、datadog_zypper_repo の変数が設定されていない場合、datadog_agent_major_version に設定されたメジャーバージョンの Datadog 公式リポジトリが使用されます。

デフォルトの動作を上書きするには、これらの変数に空の文字列ではなく、何か別の値を設定してください。

以下の Agent v5 変数を過去に使用していた場合は、新に示す変数を使用し、同時に datadog_agent_major_version を 5 に設定するか、またはdatadog_agent_version を使用して Agent v5 のバージョンを指定してください。

バージョン 4.9.0 以降は APT キーが https://keys.datadoghq.com から取得されるようになったため、use_apt_backup_keyserver 変数は削除されました。

Windows

datadog_windows_download_url 変数が設定されていない場合は、datadog_agent_major_version に対応する Windows 公式 MSI パッケージが使用されます。

デフォルトの動作を上書きするには、この変数に空の文字列ではなく、何か別の値を設定してください。

macOS

datadog_macos_download_url 変数が設定されていない場合は、datadog_agent_major_version に対応する macOS 公式 DMG パッケージが使用されます。

デフォルトの動作を上書きするには、この変数に空の文字列ではなく、何か別の値を設定してください。

アップグレード

Agent v6 を v7 にアップグレードするには、datadog_agent_major_version: 7 を使用して最新バージョンをインストールするか、datadog_agent_version を設定して Agent v7 のバージョンを指定します。Agent v5 から v6 へのアップグレードと同じ方法を使用してください。

インテグレーションのインストール

Agent v6.8 以上が対象

Datadog インテグレーションを、バージョンを指定してインストールするには、datadog_integration リソースを使用します。Agent は、コアインテグレーションがすでにインストールされた状態になります。このコマンドは、特定のインテグレーションを、Agent 全体をアップグレードすることなくアップグレードする場合に便利です。詳しくは、インテグレーション管理を参照してください。

インテグレーションを設定したい場合は、datadog_checks の該当セクションを参照してください

実行可能アクション:

• install: 指定したバージョンのインテグレーションをインストールします。
• remove: インテグレーションを削除します。

サードパーティとのインテグレーション

Datadog コミュニティと Datadog Marketplace インテグレーションは datadog_integration リソースでインストールできます。注: これらのインテグレーションは「サードパーティ」とみなされるため、third_party: true を設定する必要があります。次の例を参照してください。

構文

  datadog_integration:
    <INTEGRATION_NAME>:
      action: <アクション>
      version: <インストールするバージョン>

サードパーティインテグレーションをインストールするには、third_party を true に設定します。

  datadog_integration:
    <INTEGRATION_NAME>:
      action: <ACTION>
      version: <VERSION_TO_INSTALL>
      third_party: true

例

以下の例は、バージョン 1.11.0 の ElasticSearch インテグレーションをインストールし、postgres インテグレーションを削除します。

 datadog_integration:
   datadog-elastic:
     action: install
     version: 1.11.0
   datadog-postgres:
     action: remove

使用可能な Datadog インテグレーションのバージョンを確認するには、integrations-core リポジトリにある CHANGELOG.md ファイルを参照してください。

ダウングレード

Agent を以前のバージョンにダウングレードするには、

1. datadog_agent_version に、たとえば 5.32.5 などのバージョンを指定します。
2. datadog_agent_allow_downgrade に yes を設定します。

注:

• ダウングレードは、Windows プラットフォームではサポートされません。

プレイブック

以降では、Datadog Ansible ロールを使用する際の参考になるプレイブックのサンプルをいくつか紹介します。

以下の例では、データを Datadog US（デフォルト）に送信し、ログや NPM を有効にし、いくつかのチェックを構成します。

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "<YOUR_DD_API_KEY>"
    datadog_agent_version: "7.16.0"
    datadog_config:
      tags:
        - "<KEY>:<VALUE>"
        - "<KEY>:<VALUE>"
      log_level: INFO
      apm_config:
        enabled: true
      logs_enabled: true  # Agent v6 および v7 で可能
    datadog_checks:
      process:
        init_config:
        instances:
          - name: ssh
            search_string: ['ssh', 'sshd' ]
          - name: syslog
            search_string: ['rsyslog' ]
            cpu_check_interval: 0.2
            exact_match: true
            ignore_denied_access: true
      ssh_check:
        init_config:
        instances:
          - host: localhost
            port: 22
            username: root
            password: <YOUR_PASSWORD>
            sftp_check: True
            private_key_file:
            add_missing_keys: True
      nginx:
        init_config:
        instances:
          - nginx_status_url: http://example.com/nginx_status/
            tags:
              - "source:nginx"
              - "instance:foo"
          - nginx_status_url: http://example2.com:1234/nginx_status/
            tags:
              - "source:nginx"
              - "<KEY>:<VALUE>"

        #ログ収集は Agent 6 および 7 で可能
        logs:
          - type: file
            path: /var/log/access.log
            service: myapp
            source: nginx
            sourcecategory: http_web_access
          - type: file
            path: /var/log/error.log
            service: nginx
            source: nginx
            sourcecategory: http_web_access
    # datadog_integration is available on Agent 6.8+
    datadog_integration:
      datadog-elastic:
        action: install
        version: 1.11.0
      datadog-postgres:
        action: remove
    network_config:
      enabled: true

Agent v6

以下の例は、最新の Agent v6 をインストールします。

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_agent_major_version: 6
    datadog_api_key: "<DD_API_キー>"

サイトの設定

デフォルトの datadoghq.com 以外のサイトを利用している場合は、datadog_site var を適切な URL (例: datadoghq.eu, us3.datadoghq.com) に設定してください。

以下の例は、データを EU サイトに送信します。

- hosts: servers
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_site: "datadoghq.eu"
    datadog_api_key: "<DD_API_キー>"

Windows

Windows では become: yes オプションを削除して、ロールの失敗を回避します。以下に、サンプルのプレイブックを Windows ホストで動作させるための方法を 2 つ説明します。

インベントリファイル

インベントリファイルを使用する方法が推奨されています。インベントリファイル内で、Windows の各ホストに対し、ansible_become オプションを no に設定してください。

[servers]
linux1 ansible_host=127.0.0.1
linux2 ansible_host=127.0.0.2
windows1 ansible_host=127.0.0.3 ansible_become=no
windows2 ansible_host=127.0.0.4 ansible_become=no

すべての Windows ホストに同じコンフィギュレーションを繰り返したくない場合は、ホストをグループ化し、グループレベルで変数を設定してください。

[linux]
linux1 ansible_host=127.0.0.1
linux2 ansible_host=127.0.0.2

[windows]
windows1 ansible_host=127.0.0.3
windows2 ansible_host=127.0.0.4

[windows:vars]
ansible_become=no

プレイブックファイル

あるいは、プレイブックをWindows ホストのみで実行する場合は、プレイブックファイル内で以下を使用してください。

- hosts: servers
  roles:
    - { role: datadog.datadog }
  vars:
    ...

注: このコンフィギュレーションは、Linux ホストではエラーになります。プレイブックを Windows ホストでのみ実行する場合に使用するか、そうでない場合は、インベントリファイルの方法を使用してください。

アンインストール

Windows では、Ansible のロール内で以下のコードを使用することで、Agent をアンインストールすることが可能です。

- name: Datadog Agent がインストールされているか確認
  win_shell: |
    (@(Get-ChildItem -Path "HKLM:SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall" -Recurse) | Where {$_.GetValue("DisplayName") -like "Datadog Agent" }).PSChildName    
  register: agent_installed_result
- name: Datadog Agent のインストール状況を設定
  set_fact:
    agent_installed: "{{ agent_installed_result.stdout | trim }}"
- name: Datadog Agent をアンインストール
  win_package:
    product_id: "{{ agent_installed }}"
    state: absent
  when: agent_installed != ""

トラブルシューティング

Debian stretch

注: この情報はバージョン 4.9.0 以前のロールに適用されます。4.9.0 以降、apt_key モジュールはロールで使用されなくなりました。

Debian Stretch では、ロールが apt_key モジュールを使用する際にシステム依存性を追加しなければ、正しく動作できません。モジュールはその依存性（dirmngr）を提供していないため、現在のロールを使用するために、以下のコンフィギュレーションをプレイブックに追加してください。

---
- hosts: all
  pre_tasks:
    - name: Debian Stretch requires the dirmngr package to use apt_key
      become: yes
      apt:
        name: dirmngr
        state: present
  roles:
    - { role: datadog.datadog, become: yes }
  vars:
    datadog_api_key: "<YOUR_DD_API_KEY>"

CentOS 6/7 と Python 3 インタプリター、Ansible 2.10.x またはそれ以下

CentOS ベースのホストに Agent をインストールするためにこのロールで使用される yum Python モジュールは、Ansible 2.10.x 以下を使用する場合のみ Python 2 で利用可能です。そのような場合は、代わりに dnf パッケージマネージャーを使用する必要があります。

ただし、CentOS 8 以前の CentOS ベースのホストでは、dnf および dnf Python モジュールはデフォルトではインストールされません。このため、Python 3 インタプリターを使用する場合、Agent をインストールすることができません。

このロールは、CentOS / RHEL < 8 に Agent をインストールする際に、Ansible 2.11+ または Python 2 インタプリターが必要であることを示すために、この状況が検出されると早期に失敗します。

この早期の障害検出を回避するには（たとえば、dnf と python3-dnf パッケージがホストで利用可能な場合）、datadog_ignore_old_centos_python3_error 変数を true に設定します。

Windows

Agent バージョン 6.14.0 と 6.14.1 には、Windows における重大なバグが存在するため、これらのバージョンのインストールはブロックされています（このロールのバージョン 3.3.0 以降）。

注: Windows で datadog_agent_version を 6.14.0 または 6.14.1 に設定すると、Ansible がエラーになります。6.14.2 以降を使用してください。

Windows で 6.14.0 または 6.14.1 からアップグレードするには、以下の手順に従ってください。

1. 現在の datadog.datadog Ansible ロールを最新バージョンにアップグレードします（3.3.0 以降）。
2. datadog_agent_version を 6.14.2 以降に設定します（デフォルトでは最新バージョン）。

詳しくは、Windows における Datadog Agent 6.14.0 および 6.14.1 のアンインストーラに含まれる重大なバグを参照してください。

Ubuntu 20.04 が service_facts で壊れる

Ubuntu 20.04 で service_facts モジュールを実行すると、以下のエラーが発生します。

localhost | FAILED! => {
    "changed": false,
    "msg": "Malformed output discovered from systemd list-unit-files: accounts-daemon.service                    enabled         enabled      "
}

この問題を解決するには、Ansible を v2.9.8 以上にアップデートしてください。

API キーがありません

ロール 4.21 以降では、API キーがないとロールを続行できません。

Ansible を用いて Agent をインストールしつつ、API キーを指定したくない場合 (コンテナや VM イメージに組み込みたいなど) は、以下のいずれかを行ってください。

• ダミーの API キーを指定し、後で置き換える
• managed_config (datadog_manage_config: false) を無効にする