エージェントのタイプ

Agent Control自体には、特定のエージェントに関する組み込みの知識はありません。infrastructureエージェントを起動する方法、OpenTelemetry Collectorの設定をレンダリングする方法、またはRedisインテグレーションのバイナリを検出する方法を認識していません。それを教えるのがエージェントタイプ定義です。これは、Agent Controlが1つのプラットフォーム上で1種類のエージェントを識別、ダウンロード、設定、および実行する方法を記述したYAMLファイルです。これにより、新しいエージェントが追加されるたびにコードを変更することなく、増え続けるエージェントのカタログを管理できるようになります。

サブエージェントは、その定義の名前付きインスタンスです。たとえば、newrelic/com.newrelic.infrastructure:0.1.0を参照するnr-infra-agentなどです。これが、実際に追加、削除、または再構成するものです。Agent Controlは、それを定義で記述されているランタイムアーティファクト（たとえば、ホスト上のプロセスとそのファイル、またはクラスタ上のKubernetesオブジェクトなど）に変換し、サブエージェントの設定が変更されるたびにそれらの同期を維持します。

すべてのエージェントタイプ定義は、metadata、variables、およびdeploymentの3つの主要なセクションと、ファイルが記述されているスキーマ言語のバージョンを指定するトップレベルのprotocol_versionフィールドで構成されています。

プロトコルバージョン

protocol_version は、エージェントタイプのバージョンを宣言するトップレベルのフィールドです。これは、エージェントタイプのversion（定義のセマンティックバージョニング）とAgent Controlのリリースバージョンの両方から切り離されています。

引用符で囲まれたMAJOR.MINOR文字列です（例："1.0"）。

ドキュメントの残りの部分が解釈される前に、それ自体で解析および検証されるため、メタデータや他のセクションが、このAgent Controlでは理解できないような形式を使用しているファイルをゲートすることができます。各Agent Controlリリースは、単一の最大プロトコルバージョンを理解し、protocol_versionは単一の順序付けられたMAJOR.MINOR値として扱われます。互換性のルールは次のとおりです：

• サポートされているものより新しい（majorが高い、または同じmajorでminorが高い）：拒否されます — ファイルは、このAgent Controlが理解できるものより新しいです。
• サポート対象と同じかそれより古い：承認済み — Agent Controlは、サポート対象のバージョン以下のすべてのプロトコルバージョンを理解します。

たとえば、1.6をサポートするAgent Controlは、1.6までのすべて（0.9および1.0..=1.6を含む）を受け入れ、それより新しいもの（1.7、2.0、...）を拒否します。

メタデータ

メタデータセクションはエージェントタイプを識別します：そのname、namespace、version、ターゲットplatform（hostまたはkubernetes）、およびoperating_system（ホストベースのタイプに必須）。Agent Controlはこれらのフィールドを使用して定義を一意にアドレス指定し、正しいデプロイメントエンジンにディスパッチします。

変数

variablesセクションは、オペレーターがサブエージェントを設定に追加する際に設定できる、設定可能な入力を宣言します。各変数には以下のフィールドがあります：

• description：人間が読める形式の変数の説明。
• type：この変数が受け入れるデータ型。string、bool、number、yaml、またはstring_mapなどです。
• required：オペレーターが変数を設定する必要があるかどうか（falseに設定されている場合、Agent Controlはdefaultの値にフォールバックします）。
• default（オプション）：requiredがfalseであり、オペレーターが値を設定しない場合に使用される値です。
• classification（オプション）：変数が保持する値の種類を説明するラベル。configやmulti-configなどです。Agent Controlはこのフィールドを受け入れますが無視します；これはFleet Controlによって読み取られ、変数がオペレーターにどのように提示されるかを制御します。
• deprecated（オプション）：変数を非推奨としてマークします（deprecated: true）。Agent Controlもこのフィールドを受け入れて無視します — ランタイムの動作を伴わず、解決、検証、またはデフォルト値には影響しません。

変数は、デプロイメントセクション全体で${nr-var:variable_name}を使用して参照されます。

デプロイメント

デプロイメントセクションでは、Agent Controlがエージェントをインストールして実行する方法について説明します。その形状は、エージェントタイプのメタデータで宣言されたターゲットplatformによってまったく異なります。

完全なスキーマリファレンスと利用可能なすべてのフィールドについては、エージェントタイプスキーマリファレンスをご覧ください。

Kubernetesでのデプロイメント

Kubernetesでは、Agent ControlはKubernetesオブジェクトを管理します。デプロイメントセクションは以下で構成されています：

• objects：Agent Controlが作成し、最新の状態に保つKubernetesオブジェクト。
• health：チェックの明示的なリスト。それぞれがname、namespace、およびkindによって1つのKubernetesリソースをターゲットにします。

Agent Controlがobjectsをレンダリングする方法は、Fluxが有効になっているかどうかによって異なります：

• Fluxを使用する場合（デフォルト、または既存のFluxインストレーションを使用する場合）：エージェントタイプはHelmReleaseオブジェクトを宣言します。Agent Controlは、設定変数をそのHelmReleaseのHelmチャート値にレンダリングし、リソースを作成または更新します。その後、Fluxはチャートを調整し、基盤となるDeployment、ConfigMap、Secret、およびその他のリソースを作成します。
• Fluxを使用しない場合：エージェントのタイプは、HelmReleaseの代わりにプレーンなKubernetesオブジェクト（たとえば、ConfigMap、Secret、またはDeployment）を直接宣言します。Agent Controlは、それらのオブジェクトをクラスタ自体に適用します。HelmチャートやFluxリコンシリエーションは関与しません。その場合、ユーザーがエージェントのライフサイクルを管理する必要があります。

オンホストでのデプロイメント（LinuxおよびWindows）

ホスト上では、Agent ControlはマシンのOSに直接エージェントをインストールして実行します。デプロイメントセクションは、いくつかのサブセクションで構成されています：

• executables: Agent Controlが開始、モニター、再起動するプロセスのリスト。このセクションを持たないエージェントタイプは、管理対象のインテグレーション（OHI）として扱われます：Agent Controlはそのアーティファクトを処理しますが、実行は別のエージェントに委任します。
• enable_file_logging：ファイルロギングが有効かどうか。
• health：Agent Controlがエージェントの正常性を判断する方法 — プロセスの存在、HTTPエンドポイントのチェック、またはその両方を使用します。
• filesystem：設定ファイルや証明書など、エージェントを起動する前にAgent Controlがホストに書き込む個々のファイルまたはディレクトリ。
• shared_filesystem: 同じAgent Controlインスタンスによって管理される他のエージェントがアクセスできる共有ドロップゾーンに書き込まれるエントリです。OHIエージェントタイプが設定とバイナリをinfrastructureエージェントに渡すために使用されます。
• packages：エージェントの起動前にダウンロードするOCIアーティファクト — 通常はエージェントのバイナリまたはインテグレーションパッケージです。

エージェント状態ストレージ

Kubernetes上

状態はKubernetesオブジェクトとして存在しますが、それらのオブジェクトが何であるかは、Fluxが有効になっているかどうかによって異なります。

Fluxを使用する場合（デフォルト、または既存のFluxインストレーションを使用する場合）、エージェントタイプは通常、チャートを指すHelmRepositoryや、レンダリングされた設定をHelmチャートの値として保持するHelmReleaseなどのFluxカスタムリソースを宣言します。Agent Controlは、エージェントのDeployment、ConfigMap、またはSecretオブジェクトを直接作成しません。これはHelmReleaseをFluxに渡し、Fluxはチャートをインストールして、生成されたリソースをそれと同期した状態に保ちます。

• 設定の更新により、HelmReleaseにインプレースでパッチが適用されます。Agent Controlは、コンテンツが変更された場合にのみオブジェクトを再適用します。その後、Fluxは一致するようにチャートを調整します。
• サブエージェントを削除すると、それが所有しているとラベル付けされたすべてのオブジェクトが削除されます — そのHelmRelease、HelmRepository、およびそのために作成されたSecretまたはConfigMapが削除され、Flux/Helmはそのチャートがインストールしたワークロードのクリーンアップを完了します。

Fluxがない場合、HelmReleaseやHelmRepositoryはありません。エージェントタイプはプレーンなKubernetesオブジェクトを直接宣言し、Agent Controlがそれらを自身で作成および更新します。HelmチャートやFluxのレコンシリエーションはありません。このモードでは、ユーザーがエージェントのライフサイクルに責任を持ちます。Agent ControlはエージェントのDeploymentをインストールまたはアップグレードせず、管理する設定オブジェクトを同期させるだけです。

• 設定の更新は、管理対象オブジェクト（ConfigMap/Secret）にインプレースでパッチを適用します。Agent Controlは、コンテンツが変更された場合にのみ再適用します。Fluxリコンシリエーションがないため、エージェント自体が変更を監視していない限り、変更を反映するためにエージェントが自動的に再起動されることはありません。
• サブエージェントを削除すると、それが所有しているとラベル付けされたすべてのオブジェクトが削除されます — クリーンアップするHelmRelease、HelmRepository、またはチャートでインストールされたワークロードがないため、そのConfigMap/Secretオブジェクトのみが削除されます。

オンホスト

オンホストファイルシステム

すべてのサブエージェントは、Agent Controlがエージェントタイプのfilesystemセクションで宣言されたファイルを書き込む、ディスク上の専用ディレクトリを取得します。

Agent Controlは、タイプyamlの変数からファイルを作成するためのコンテンツを取得し、タイプstring_mapの変数からディレクトリ内の複数のファイル用のコンテンツを取得します。

例

/var/lib/newrelic-agent-control/filesystem/nr-infra-agent/
├── newrelic-infra.yaml     # content from variable of type `yaml`
└── logging.d/              # content from variable of type `string_map`
    ├── file1.yaml
    └── file2.yaml

このディレクトリがどのように動作するかは、ライフサイクルイベントと、各パスの背後にある変数のタイプによって異なります：

• 再起動ではディレクトリは変更されません。Fleet Controlからの設定の更新によって再起動がトリガーされた場合を除き、Agent Controlは何も書き換えません。
• 設定の更新により、yamlファイルはインプレースで書き換えられますが、string_mapディレクトリは完全に再生成されます。yamlコンテンツの場合、Agent Controlはファイルの内容のみを書き換えます。string_mapコンテンツの場合、Agent Controlはディレクトリ全体を削除し（上記のlogging.dのように）、最初から再作成するため、ユーザー（またはサブエージェント）がその中に追加または編集したファイルは、次回の書き込み時に消去されます。
• Agent Controlが管理しないファイルはそのまま残されます。エージェントのタイプが宣言する正確なパスのみを上書きします。実行中のエージェントがディレクトリ内に独自に作成したその他のもの（キャッシュファイル、ローカル状態）は変更されません。
• サブエージェントを削除すると、サブエージェント自体またはユーザーによって作成されたファイルを含め、ディレクトリ全体が削除されます。

ホスト上の共有ファイルシステム

ほとんどのエージェントタイプは自己完結型です：Agent Controlは、それら専用のディレクトリに設定を書き込み、そこから読み取るプロセスを開始します。しかし、一部のインテグレーションには独自の実行モデルがありません。Agent Controlが開始するプロセスはありません。これらは、ファイルを取得して実行するために、すでに実行中の別のエージェント（たとえば、infrastructureエージェント）に完全に依存しています。その依存関係が、2つ目の共有の場所が存在する理由です。これは、同じホスト上の任意のサブエージェントが書き込み、他の任意のサブエージェントが読み取ることができる共通のドロップゾーンであり、エージェント自身のプライベートな状態を保存するためではなく、エージェント間でアーティファクトを受け渡すために特別に使用されます。

エージェントタイプ自身のプロセスが必要とするものにはfilesystemを使用し、後述のオンホストインテグレーションのように、あるエージェントタイプが別のエージェントタイプに意図的にファイルを渡す場合にのみshared_filesystemに依存してください。

すべてのサブエージェントにはディスク上の共有ディレクトリが割り当てられ、Agent Controlはそこにエージェントタイプのshared_filesystemによって宣言されたファイルを書き込みます。

すべてのサブエージェントはその共有ディレクトリにアクセスできるため、お互いのファイルを見ることができます。

例

/var/lib/newrelic-agent-control/shared_filesystem/
├── data/                  # All sub-agents can see `data` and `other-data` folders
│   └── file.yaml
└── other-data/
    └── file2.yaml

共有ディレクトリは、再起動、設定の更新、および管理されていないファイルについて、エージェントごとのファイルシステムディレクトリと同じルールに従います。サブエージェントを削除する場合にのみ動作が変わります：各ファイルはそれを書き込んだサブエージェントが明確に所有しているため、ファイルは常に削除されますが、フォルダーは他のサブエージェントが使用しなくなってから削除されます。

ホスト上のリンクされたエージェントのタイプ

一方のエージェントのタイプが共有ファイルシステムにアーティファクト（設定、バイナリ、またはその他のファイル）を書き込み、もう一方が同じパスから読み取るように設定されている場合、2つのエージェントのタイプはリンクされています。ライターにはexecutablesセクションがない場合があり、Agent Controlはそのアーティファクトを管理しますが、そのためのプロセスを開始することはありません。代わりに、リーダーエージェントには、共有ファイルシステムの既知のパスからバイナリと設定を検出して実行する組み込みロジックがあり、事実上、ライターに代わってアドオンを実行します。

サブディレクトリ名は、リンクされたエージェントタイプ間の規則によって選択されます。

オンホストインテグレーション（OHI）

オンホストインテグレーション（OHI）は、リンクされたエージェントタイプの主な例です。通常のサブエージェントにはAgent Controlが開始してモニターするプロセスがありますが、OHIにはありません。Agent Controlはそのライフサイクル（ダウンロード、設定、アップグレード、アンインストール）のみを管理し、infrastructureエージェントが代わって共有ファイルシステムからバイナリを検出し、実行します。

infrastructureエージェントとOHIエージェントの関係

1. OHIエージェントのタイプがインストールされると、Agent ControlはOCI経由でインテグレーションのバイナリをダウンロードし、共有ファイルシステムに2つのエントリを書き込みます：

   • infra-agent-ohi-configs/配下の設定ファイル（例：nri-redis.yaml）
   • infra-agent-ohi-binaries/の下にあるインテグレーションバイナリ（例：nri-redis）

2. infrastructureエージェントのサブエージェントは、これらの共有ディレクトリを指す環境変数で設定されます：

   変数	共有ファイルシステムパス	目的
   NRIA_PLUGIN_DIR	…/infra-agent-ohi-configs	インテグレーション設定の検出
   NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR	…/infra-agent-ohi-binaries	インテグレーションのバイナリの検出
   NRIA_SAFE_BIN_DIR	…/infra-agent-ohi-binaries	許可されたバイナリの実行パス

3. infrastructureエージェントは、次のスキャンサイクルで設定とバイナリを取得し、インテグレーションの実行を開始します。

   shared-filesystem/
   ├── infra-agent-ohi-configs/      # Integration YAML configs (read by NRIA_PLUGIN_DIR)
   │   ├── nri-redis.yaml
   │   └── nri-mysql.yaml
   └── infra-agent-ohi-binaries/     # Integration binaries (read by NRIA_CUSTOM_PLUGIN_INSTALLATION_DIR)
       ├── nri-redis
       └── nri-mysql

   コピー

エージェントタイプの定義の取得

Agent Controlは、実行されている環境（Kubernetes、Linux、またはWindows）を考慮し、定義のメタデータセクションで宣言されたnamespace、name、およびversionによって識別されるリモートOCIレジストリから、エージェントのタイプの定義を取得します。

デフォルトでは、Agent ControlはNew Relicの公開鍵で署名を検証した後、newrelic/agent-control-agent-typesリポジトリを使用してdocker.ioからプルします。

エージェントタイプの定義は、「Agent ControlのOCIレジストリミラーの構成」で説明されているように、ミラーからプルできます。

サポートされているエージェントの種類

現在のサポート

以下の表は、Agent Controlがサポートするエージェントのタイプと、環境ごとの可用性を示しています。

エージェントタイプごとの必要な権限

以下の表は、各エージェントタイプに必要な主要な権限と、それが適用される環境を示しています。

ホストでのFluent Bitの設定

ホストでは、Fluent Bitは独自のトップレベルのエージェントタイプとしてデプロイされません（上記のサポートテーブルを参照してください）。代わりに、ログ転送が有効になっている場合、Fluent Bitはスタンドアロンでインストールされた場合と同じように、New Relic infrastructureエージェント自体によって生成および管理されます。Agent Controlは、infrastructureエージェント、そのデータ、およびFluent Bitのバイナリとプラグインがディスク上のどこに配置されるかのみを変更します。

ログ転送自体の設定方法（logging.d/*.ymlの構文、入力、フィルター、属性など）については、以下をご覧ください：

• ログ管理の有効化
• Fluent Bitを使用したログの転送

設定の配置場所

Agent Control固有の唯一の詳細は、ログ転送ファイルの配置場所です：これらは、infrastructureエージェントの設定のconfig_loggingフィールドを介して、ログソースごとに1つのエントリとして、サブエージェントのlogging.dフォルダーに配置されます。これをサブエージェントの設定（たとえば、そのlocal_config.yaml）で直接設定し、それをAgent Controlに送信します：

config_logging:
  syslog.yaml: |
    logs:
      - name: syslog
        file: /var/log/syslog
        attributes:
          logtype: linux_syslog
  app.yaml: |
    logs:
      - name: app-log
        file: /var/log/app.log
        attributes:
          service: api
          env: production

Fluent Bitの配置場所と更新方法