本文へスキップ

EC2インスタンス状態転送の設定

AWS EC2インスタンスが終了しても、サーバープロジェクトには該当サーバーが登録されたまま残る場合があります。OpenAgentのEC2インスタンス状態転送機能を有効にすると、EC2 State Exporterが照会したインスタンスの状態をサーバープロジェクトに送信し、収集サーバーが終了したインスタンスのサーバー登録を自動的に解除します。オートスケーリングなどでEC2インスタンスが頻繁に作成・終了される環境で、OpenAgentとサーバーモニタリングを併せて運用する管理者を対象としています。

動作方式​

AWS EC2の状態照会
  → EC2 State Exporter: /metrics
  → OpenAgent: 登録したサーバープロジェクトごとに状態を転送
  → 収集サーバー: 該当プロジェクトのサーバーを識別して登録解除

  • EC2 State Exporterは、CPU・ネットワーク指標を収集するCloudWatch Exporterとは別のプログラムです。CloudWatch Exporterのみをインストールしている場合は、EC2 State Exporterを追加でインストールする必要があります。

  • 1つのExporterが、認証されたAWSアカウントの1つのリージョンにあるEC2インスタンス全体の状態を照会します。すべてのEC2インスタンスにインストールする必要はありません。複数のアカウント・リージョンを自動的に探索することはありません。

  • OpenAgentは、登録したサーバープロジェクトごとに観測した状態を転送します。プロジェクトコードやインスタンスIDとエージェントのマッピングを別途入力する必要はありません。

  • インスタンスの状態がshutting-down(32)またはterminated(48)の場合、該当プロジェクトでinstance-idが同じサーバーをすべて登録解除します。同じEC2インスタンスにエージェントを再インストールして以前のサーバーと新しいサーバーが両方残っている場合も、すべて解除の対象です。

  • この機能はWhaTapのサーバー登録のみを整理します。AWSのEC2インスタンスを停止または削除することはありません。

事前準備​

次のバージョンが必要です。

ComponentVersion
OpenAgent1.8.11以上
EC2 State Exporter0.1.0以上
収集サーバー3.1.10以上
注意

OpenAgent 1.8.10以下では、この文書の設定だけでは動作しません。対象の収集サーバーがこの機能をサポートしているかを確認するまでは、ec2_state_forwarding_enabledをfalseのままにしてください。旧バージョンの収集サーバーは転送された状態を無視するため、OpenAgentにエラーがないことだけではサポート有無を判断できません。

EC2 State Exporterが実行されるEC2インスタンスのIAMロールに、次の読み取り権限を追加してください。すでに許可されている場合は追加不要です。

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ec2:DescribeInstances",
      "Resource": "*"
    }
  ]
}

ExporterはAWS SDKのデフォルトの認証経路を使用します。EC2ロールを使用する環境では、Access KeyとSecret Keyを別途入力せず、whatap.confにもAWSキーを記載しません。リージョンはSDKの環境変数とプロファイル設定を優先して使用し、ない場合はEC2メタデータ(IMDS)から確認します。

EC2 State Exporterの実行​

次のコマンドでバイナリをダウンロードして実行してください。arm64ホストの場合は、パスのamd64をarm64に変更します。

mkdir -p bin
curl -fLo bin/ec2_state_exporter https://repo.whatap.io/exporter/ec2_state_exporter/0.1.0/amd64/ec2_state_exporter
chmod +x bin/ec2_state_exporter
./bin/ec2_state_exporter --version
./bin/ec2_state_exporter

デフォルトの待ち受けアドレスはhttp://127.0.0.1:9107/metricsです。リージョンを自動的に確認できない場合や、別のリージョンを照会する場合は、--region引数を指定してください。

./bin/ec2_state_exporter --region=ap-northeast-2

上記のコマンドでは、サービス登録や再起動時の自動起動は設定されません。運用環境では、使用しているサービス管理方式でプロセスを維持してください。

別のターミナルで次のコマンドを実行し、出力を確認してください。

curl --fail --show-error --max-time 15 http://127.0.0.1:9107/metrics

出力形式は次のとおりです。インスタンスIDは例です。

# HELP aws_ec2_instance_state EC2 lifecycle state code reported by DescribeInstances.
# TYPE aws_ec2_instance_state gauge
aws_ec2_instance_state{instance_id="i-0123456789abcdef0",region="ap-northeast-2",state_name="running"} 16

メトリクスの値はAWSのインスタンス状態コードです。

CodeState
0pending
16running
32shutting-down
48terminated
64stopping
80stopped

収集対象の登録​

scrape_config.yamlの既存のfeatures.openAgent.targetsリストにec2-state項目を追加してください。既存のファイルを以下の例で上書きしたり、features・openAgentキーを重複して作成したりせず、既存のYAML構造に項目をマージします。

scrape_config.yaml
features:
  openAgent:
    enabled: true
    targets:
      - targetName: ec2-state
        type: StaticEndpoints
        enabled: true
        endpoints:
          - address: "127.0.0.1:9107"
            path: "/metrics"
            scheme: "http"
            interval: "60s"
            timeout: "15s"

  • intervalの推奨値は60sです。

  • ExporterはAWS全体の照会を10秒に制限しているため、timeoutはそれより長い15sに指定します。

  • 既存のCloudWatch Exporterの収集対象はそのまま維持します。

  • OpenAgentとExporterが別のホストやコンテナで実行される場合は、Exporterを--web.listen-address引数でOpenAgentがアクセスできるプライベートアドレスで実行し、addressをそのアドレスに変更してください。ExporterにはTLSとHTTP認証がないため、ファイアウォールやセキュリティグループでOpenAgentからのアクセスのみを許可します。

管理ライセンスの登録​

whatap.confに次の2つのオプションを追加してください。最初は機能を無効にした状態で登録します。

whatap.conf
ec2_state_forwarding_enabled=false
ec2_state_licenses=<SERVER_LICENSE_A>,<SERVER_LICENSE_B>

ec2_state_licensesには、登録解除を管理するサーバープロジェクトのライセンスを入力します。OpenAgent自身のプロジェクトライセンス(license)の代わりとなる値ではありません。

  • プロジェクトが複数ある場合は、カンマで区切って1行に入力します。末尾にカンマを付けたり、空の項目を入れたりしないでください。

  • ライセンスからプロジェクトコードを自動的に解釈するため、プロジェクトコードを別途入力する必要はありません。

  • 登録したプロジェクトは、OpenAgentが接続した収集サーバーにデータを送信できる必要があります。プロジェクトごとに異なる収集サーバーのアドレスを指定することはできません。

収集サーバーのサポート有無を確認したら、ec2_state_forwarding_enabledの値をtrueに変更してください。この設定は実際のサーバー登録解除につながるため、管理するプロジェクトが正しいかを事前に確認します。

whatap.conf
ec2_state_forwarding_enabled=true
ec2_state_licenses=<SERVER_LICENSE_A>,<SERVER_LICENSE_B>

通常のホストで実行するOpenAgentはwhatap.confの変更を検知して再読み込みし、次の収集から変更された設定を使用します。

設定オプション​

EC2 State Exporterをデフォルト値で接続する場合は、ec2_state_forwarding_enabledとec2_state_licenses以外は設定する必要はありません。

OptionTypeDefaultDescription
ec2_state_forwarding_enabledbooleanfalseEC2インスタンス状態転送の有効化有無
ec2_state_licensesstring-登録解除を管理するサーバープロジェクトのライセンス。カンマ区切りで最大64個
ec2_state_metric_namestringaws_ec2_instance_stateインスタンス状態のメトリクス名
ec2_state_instance_id_labelstringinstance_idインスタンスIDのラベル名
ec2_state_state_name_labelstringstate_name状態名のラベル名
ec2_state_state_code_sourcestringvalue状態コードを読み取る場所。valueはメトリクスの値を状態コードとして使用
ec2_state_state_code_labelstringstateCode状態コードのラベル名。label方式でのみ使用
ec2_state_exporter_urlsstring-状態を処理する収集対象URLの許可リスト。未設定の場合は収集したソース全体で状態メトリクスを処理
ec2_state_param_idinteger1002収集サーバーに転送するコマンドID
ec2_state_resend_intervalstring5m同じ状態を再転送する周期。5m、30sのような単位付きの期間形式。300のように単位がない値や、0・負数・解釈できない値は転送エラーが発生

ec2_state_metric_nameをデフォルト値以外の名前に変更すると、ラベルのデフォルト値はinstanceId・stateName・stateCodeに、コード位置のデフォルト値はlabelに変わります。

  • ec2_state_*オプションは、同じ名前の環境変数でも指定できます。whatap.confに空でない値がある場合はファイルの値が優先され、環境変数の変更はプロセスを再起動しないと反映されません。

  • ec2_state_exporter_urlsは、すでに登録した収集対象のうち処理を許可するURLのリストです。このオプションを設定するだけでは新しい収集ジョブは作成されず、実際の収集URLのscheme・アドレス・ポート・パスと完全に一致する必要があります。

ノート

OpenAgent 1.8.11から、ec2_state_param_idのデフォルト値が56から1002に変更されました。既存の設定にec2_state_param_id=56がある場合は、その行を削除するか1002に変更してください。明示した値を自動的に修正したり、以前のIDに置き換えて転送したりすることはありません。以前の例のメトリクス名やラベル設定が残っていると自動のデフォルト値を使用できないため、別のExporterを意図的に運用している場合を除き、不要なec2_state_*設定は削除してください。

Kubernetes Operator環境の設定​

WhaTap OperatorでOpenAgentをインストールした場合は、Pod内のwhatap.confや、Operatorが作成したConfigMap・Deploymentを直接修正しないでください。Operatorが手動の変更を元に戻します。WhatapAgent CRのspec.features.openAgentに設定します。

ItemCR field
EC2 State Exporterの収集対象targets
機能の有効化、管理するサーバープロジェクトのライセンスenvs
OpenAgentのイメージバージョンimageVersion。現在のバージョンが1.8.11未満の場合のみ指定

  1. EC2 State Exporterをクラスターにデプロイしてください。他のPodのOpenAgentがアクセスできるように--web.listen-address=0.0.0.0:9107引数で実行し、PodではEC2メタデータの照会がブロックされている場合があるため、--regionで照会するリージョンを指定します。Exporterには認証がないため、NetworkPolicyなどでOpenAgent Podからのアクセスのみを許可してください。Exporterの公式コンテナイメージは提供していないため、バイナリを含むイメージを独自に用意する必要があります。

    IMDSへのアクセスがブロックされたPodでは、ノードのIAMロールの認証情報も取得できません。EKSでは、IRSAまたはEKS Pod Identityでec2:DescribeInstances権限を付与してください。

  2. 次のコマンドでCRをバックアップしてから編集してください。

    umask 077
    kubectl get whatapagent whatap -o yaml > "whatapagent-backup-$(date +%Y%m%d%H%M%S).yaml"
    kubectl edit whatapagent whatap

  3. spec.features.openAgentに次の項目を追加してください。既存のenvs・targets項目は削除せず、リストに続けて追加します。kubectl patch --type mergeはリスト全体を置き換えるため、既存の項目がある場合は使用しないでください。

    spec:
      features:
        openAgent:
          enabled: true
          envs:
            - name: ec2_state_forwarding_enabled
              value: "false"
            - name: ec2_state_licenses
              value: "<SERVER_LICENSE_A>,<SERVER_LICENSE_B>"
          targets:
            - targetName: ec2-state
              type: StaticEndpoints
              enabled: true
              endpoints:
                - address: "ec2-state-exporter.whatap-monitoring.svc:9107"
                  path: "/metrics"
                  scheme: "http"
                  interval: "60s"

    • 環境変数の値は文字列のため、"false"、"true"のように引用符を付けます。

    • ライセンスをCRにそのまま記載しない場合は、Secretを作成し、valueの代わりにvalueFrom.secretKeyRefで参照してください。

    • 収集サーバーのサポートを確認した後にec2_state_forwarding_enabledの値を"true"に変更すると、OperatorがDeploymentを更新してPodを再起動します。Secretの値のみを変更した場合はPodが自動的に再起動されないため、OpenAgent Podを削除して再作成する必要があります。

  4. 次のコマンドで反映結果を確認してください。

    kubectl -n whatap-monitoring rollout status deploy/whatap-open-agent
    kubectl -n whatap-monitoring logs deploy/whatap-open-agent --since=10m | grep -E 'EC2_STATE_'

例のネームスペースwhatap-monitoringとCR名whatapは、Operatorのデフォルト値です。インストール環境に合わせて変更してください。

動作確認​

  1. EC2 State Exporterの/metricsがHTTP 200とaws_ec2_instance_stateサンプルを返すかを確認してください。該当アカウント・リージョンにインスタンスがない場合は、HTTP 200でもサンプルがないことがあります。

  2. OpenAgentのログにEC2_STATE_CONFIG、EC2_STATE_INPUT、EC2_STATE_SENDエラーがないかを確認してください。

  3. 状態を送信キューに入れると、INFOログEC2_STATE_FORWARD ... locally queued=<件数> from <収集アドレス>を出力します。この件数はOpenAgentのローカルキューが受け付けた件数であり、収集サーバーの受信件数や登録解除の成功件数ではありません。

  4. 実際に登録解除されたかどうかは、対象サーバープロジェクトのエージェントリストを再度照会して確認してください。

OpenAgentは次のタイミングで状態を転送します。

SituationBehavior
初めて観測した状態該当の収集で転送
状態コード・名前の変更変更を確認した収集で転送
同じ状態の繰り返し最後の転送後、ec2_state_resend_interval(デフォルト5分)の間は転送しない
同じ状態のまま再転送周期が経過次の収集で再度転送
照会失敗、リストから消失以前の状態を再送したり、terminatedとみなしたりしない

状態の変更はAWSイベントを即時に受け取る方式ではなく、次の収集で変更を検出したときに転送します。AWSの照会結果からすでに消えた終了インスタンスは転送できません。

トラブルシューティング​

SymptomCheck
9107ポートへの接続拒否Exporterのプロセス、待ち受けアドレス・ポート、コンテナネットワークを確認
EC2_STATE_EXPORTER: AWS region is unavailableAWS環境・プロファイルのリージョンまたはIMDSへのアクセスを確認。必要に応じて--regionを指定
HTTP 503、EC2_STATE_EXPORTER: collection failedAWSの認証情報、ec2:DescribeInstances権限、リージョン・ネットワークを確認
HTTP 503、EC2_STATE_EXPORTER: scrape already in progress同じExporterに重複した収集対象や同時収集がないかを確認
EC2_STATE_CONFIGログライセンスの欠落・誤記・空の項目、誤った選択オプションを確認
EC2_STATE_INPUTログメトリクスの形式、必須ラベル、コードと状態名の一致有無を確認
EC2_STATE_SENDログローカル送信キューによる拒否。収集サーバーとの接続とキューの状態を確認。次の収集で再試行
収集はされるが転送されないOpenAgentのバージョン(1.8.11以上)、実際に読み込んでいるwhatap.conf、機能の有効化有無、以前の設定が残っていないかを確認
locally queuedログがあるのにサーバーが残っている収集サーバーのバージョン、対象プロジェクトのライセンス、サーバーのinstance-idの一致有無を確認。running・stopped状態は解除の対象外

機能の無効化​

whatap.confを次のように変更してください。Operator環境では、CRのenvsの値を"false"に変更します。

whatap.conf
ec2_state_forwarding_enabled=false

設定を再読み込みした後、次の収集から状態の転送を停止します。通常のメトリクス収集は継続され、すでに送信キューに入ったデータは取り消されません。AWSの照会も停止するには、scrape_config.yamlでec2-state収集対象を無効にし、Exporterのプロセスを停止してください。

最終修正：