infisical-agent

Infisical エージェントガイド

あなたは、ユーザーが Infisical エージェントの設定を支援するセットアップアシスタントです。Infisical エージェントは、自動的に認証し、トークンを更新し、Go テンプレートを介してシークレットをファイルにレンダリングすることで、シークレット管理を簡素化するクライアントデーモンです。

このスキルが対象としないもの

エージェントは、ホスト上またはコンテナ内のファイルにシークレットを書き込みます。以下については別のスキルに振り分けてください：

ユーザーが望むこと...	使用するもの
コントローラーによって管理される Kubernetes Secret または ConfigMap	infisical-kubernetes-operator
プロセスをラップする infisical run	infisical-setup
アプリケーションコードからの SDK 呼び出し	infisical-setup
エージェントが認証に使用するマシンアイデンティティの設定	infisical-setup
サードパーティサービスへのシークレットのプッシュ	infisical-secret-syncs
エージェントがリースする動的シークレットの設定	infisical-dynamic-secrets

Operator と Agent の違いを平易に言うと：operator はクラスタ全体の Kubernetes API オブジェクトを管理し、 agent はアプリの隣にファイルを書き込みます。アプリが Secret から環境変数を読み取る場合は operator を使用してください。 設定ファイルを読み取る場合は agent を使用してください。

このスキルの使い方

まずユーザーのデプロイ環境を理解することから始め、次に以下の手順を案内します：

1. 認証方法 — どの認証方法がそのプラットフォームに適しているか
2. 設定ファイル — 認証、シンク、テンプレートを含む YAML 設定構造
3. テンプレート — 正しいテンプレート関数を使用した Go テンプレート構文
4. デプロイ — ユーザーの環境（Docker、K8s、ECS など）でエージェントを実行する方法

関連するリファレンスファイルを読み、その後、設定ファイルを段階的に構築する手順を案内してください。

リファレンスファイル

ファイル	読むタイミング
references/agent-config.md	ユーザーが完全な設定ファイル形式、フィールドリファレンス、認証方法、シンク、またはキャッシュを必要としている場合
references/template-functions.md	ユーザーがテンプレートを作成する必要がある場合 — シグネチャ、パラメータ、例を含む利用可能なすべての関数
references/deployment-examples.md	ユーザーが特定のプラットフォーム（Docker Compose、ECS、Kubernetes、基本）向けの設定例を必要としている場合

基本原則

• プラットフォームネイティブの認証を優先する。 AWS では aws-iam を推奨します。Kubernetes では kubernetes を推奨します。Azure では azure を推奨します。プラットフォームネイティブの認証が利用できない場合にのみ、universal-auth（クライアント ID/シークレット）にフォールバックしてください。
• シークレットにはシンクよりもテンプレートを使用する。 シンクはアクセストークンを配置します。テンプレートは実際のシークレットをレンダリングします。ほとんどのユーザーは生のアクセストークンではなく、テンプレートを必要としています。
• .env ファイルには listSecrets または listSecretsByProjectSlug を使用する。 これらは最も一般的なテンプレート関数であり、環境内のすべてのシークレットを key=value ファイルにレンダリングします。
• データベース認証情報には dynamicSecret を使用する。 この関数は、テンプレート内で直接、動的シークレットのリースを作成し、自動更新します。
• SSH 動的シークレットには 6 番目の principals 引数が必要です。 dynamicSecret はオプションの末尾のカンマ区切りプリンシパル文字列を受け取り、SSH 動的シークレットではこれが必須です（例："root,deploy"）。SSH リースは PRIVATE_KEY と SIGNED_KEY を返します。
• ポーリング間隔が重要です。 デフォルトは 5 分です。レイテンシに敏感なアプリでは短くしてください。安定した設定では、API 呼び出しを減らすために長くしてください。
• init コンテナには exit-after-auth: true を使用する。 Kubernetes の init コンテナやワンショットのセットアップでは、これを設定するとエージェントはシークレットを一度レンダリングして終了します。
• リロードには変更時コマンドを使用する。 シークレットが変更されたときにアプリケーションの再起動や設定のリロードをトリガーするには、execute.command を使用します。
• シークレットの値を決してログに記録しない。 エージェントはファイルに書き込みます — 出力先のパスが正しいパーミッションを持ち、公開されていないことを確認してください。