CloudWatch Agentの設定ファイルについて

CloudWatch Agentの設定ファイルについて、どのファイルが読み込まれているのか、理解があやふやだったので整理してみました。
設定ファイルの文法などには触れていません。どこに作ってどう反映されるのかを理解できれば幸いです。

設定ファイルの構成
Agent起動時の設定ファイルの読み込み
設定ファイルの反映
まとめ

設定ファイルの構成

CloudWatch Agentの設定ファイルは通常、/opt/aws/amazon-cloudwatch-agent/etc/ に配置されます。
大体は以下のようになっているでしょう。

/opt/aws/amazon-cloudwatch-agent/etc/
┣ amazon-cloudwatch-agent.d
┣ amazon-cloudwatch-agent.json
┣ amazon-cloudwatch-agent.toml
┣ amazon-cloudwatch-agent.yaml
┣ common-config.toml
┣ env-config.json
┗ log-config.json

amazon-cloudwatch-agent.json は導入直後は存在しません。ユーザが作成する設定ファイルですが、この名前で作成することは推奨されています。この中でユーザが作成する設定ファイルは、

amazon-cloudwatch-agent.d 配下の設定ファイル
amazon-cloudwatch-agent.json

の2つです。Agentは両方を参照しています。また、片方が無くても動作しますが、両方無いとアウトです。
あまりやってる人はいないと思いますが、設定ファイルは複数に分けて持つことができます。

Agent起動時の設定ファイルの読み込み

CloudWatch Agentの起動時は、上記の設定ファイルは以下のように使用されているようです。

設定ファイルをマージしてamazon-cloudwatch-agent.toml ファイルを生成し、Agent は.toml を参照して動作しています。
このマージ動作はAgent起動のたびに実行されています。

Agentの起動コマンドは以下です。systemctl startでも起動しますが、こちらで起動するのが正式です。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a start

設定ファイルの反映

設定ファイルの作成について、前述のamazon-cloudwatch-agent.json として作成する場合は話すことはありません。手動あるいはwizard で指定の名前としてファイルを作成すればいいです。(この場合は後続のfetch/append/remove コマンドは関係ありません。)

一方、amazon-cloudwatch-agent.d に設定ファイルを作成する場合は、ファイルを直接作成することは推奨されていないようで、作法があります。以下、3通りのコマンドがあるので使い分けます。

fetch-config

任意の場所に作成された設定ファイルを読み込み、amazon-cloudwatch-agent.d にコピーしてtoml ファイルを生成します。
尚、既存の設定は削除されます。破棄される内容は

amazon-cloudwatch-agent.d 配下の設定ファイル
amazon-cloudwatch-agent.json

なので注意しましょう。図で書くとこうです。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a fetch-config -m ec2 -c file:/path/to/json/sample.json

指定されたファイルは頭に”file_”がついた状態でamazon-cloudwatch-agent.d/ にコピーされ、.tomlに変換されます。

append-config

任意の場所に作成された設定ファイルを読み込み、amazon-cloudwatch-agent.d にコピーしてtoml ファイルを生成します。
尚、既存の設定は維持されます。このため、設定内容を追加する場合で、既存の設定ファイルを触りたくない場合に使用します。

fetchと同様に、指定されたファイルは頭にfile_がついた名前でコピーされます。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a append-config -m ec2 -c file:/path/to/json/sample.json

remove-config

指定した設定ファイルをamazon-cloudwatch-agent.d/ から削除した上で、.toml ファイルを生成します。
こちらも既存の設定は維持されます。

amazon-cloudwatch-agent.json(あれば)と、amazon-cloudwatch-agent.d/ 内の指定されたファイル以外で.toml が生成されます。

sudo /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl -a remove-config -m ec2 -c file:sample.json

コマンドに指定のfileについては、file_ を除いたファイル名のみを指定します。
手動削除もよいのでしょうが、その場合は.tomlファイルへの変換が行われません。
(しかしAgent起動時にはやはり.tomlへの変換が行われているようであり、結果として問題にはなりませんが。。)

まとめ

CloudWatch Agentの設定ファイルについて、結局どのファイルが使用されるのかがぼんやりしていたため、実験してひも解いてみました。あまり設定が変わらない場合については直接 amazon-cloudwatch-agent.json として作成してAgentの再起動で反映するのが簡単です。
複雑な設定ファイルや更新が頻繁になる場合には、用途ごとに設定ファイルをappendして使用することも考慮に入ってくるのかと思います。

この記事が参考になる人が一人でもいたら幸いです。