エージェント設定ファイルを使用したホストエージェントの設定

Instana エージェントは、 HashiCorp ボールト を使用して、エージェント構成ファイル内の機密設定の値を安全に取得します。

エージェント構成ファイルに以下の行を追加して、ホスト・エージェントに Vault 統合構成パラメータを提供する必要があります：

com.instana.configuration.integration.vault:
  connection_url: <vault_server_base_url> # The address (URL) of the Vault server instance(e.g. http://127.0.0.1:8200 or https://exapmle.com:8200)
  prefix: <optional_prefix> # Optional prefix path required if kv_version 2 is used and the /data/ must be injected further down
  token: <vault_access_token> # Vault access token with assigned, at least, `read` access policy to relevant Vault paths, optional if other auth providers are present
  github: # Optional auth method if Vault access token is not provided, has higher priority than approle if present
    github_token: <github_token> # Personal Access Token, must provide at least read:org scope, must be present if github is used as an auth provider
    auth_mount: github # Optional mount path for GitHub Auth, defaults to github
  approle: # Optional auth method if Vault access token or github auth is not provided
    role_id: <roleId> # AppRole RoleId, must be present if approle is used as an auth provider
    secret_id: <secretId> # AppRole SecretId, must be present if approle is used as an auth provider
    auth_mount: approle # Optional mount path for AppRole Auth, defaults to approle
  path_to_pem_file: <path_to_X.509_CA_certificate> # X.509 CA certificate (UTF8 encoded) in unencrypted PEM format, used by the Agent when communicating with Vault over HTTPS
  secret_refresh_rate: 24 # This configuration option allows you to account for rotating credentials, refresh rate in hours, default 24
  kv_version: 2 # The Key/Value secrets engine version, default is 2
 

Vault を MySQL で設定し、シークレットを追加する例については、 Vault の設定例 （ MySQL ）を参照してください。

Vault の初期設定後、エージェント設定ファイルでは、様々なセンサの秘密の取得を指定することができます。

password をエージェント設定ファイルに直接追加する代わりに、 HashiCorp Vault から取得する次の例を参照してください：

com.instana.example:
  user: 'instana'
  password:
    configuration_from:
      type: vault
      secret_key:
        path: <vault_path>
        key: <vault_secret_key>
 

センシティブデータの文字列値を、Vault座標を指定するYAML構造で置き換えることができ、ホストエージェントは自動的に秘密を取得します。

また、パスワード・フィールドのためのシークレット・マネージャーとの統合に制限されることはありません。 secretsマネージャは、エージェント設定ファイル configuration.yaml の値として文字列を持つすべての設定に使用できます。

詳細については、Instana エージェントの統合に関連する以下の Vault の概念を参照してください：

• ボールトサーバー
• ボールトークンの管理
• アクセスポリシーの設定
• ボールトKVシークレットエンジン
• Vault TCPリスナーの設定

IBM Cloud Secrets Manager はオープンソースの HashiCorp Vault をベースにしており、 HashiCorp Vault と 同じ API と同じ設定を提供する。 統合の構成の詳細については、 HashiCorp Vault を参照してください。

Vault コンポーネントのバージョン 1.0.11 から、 IBM Cloud Secrets Manager SDK と IAM Keys が Vault で使用できるようになりました。

エージェント設定ファイルに以下の行を追加して、 IBM Cloud Secrets Manager 統合設定パラメータをホスト・エージェントに提供する必要があります：

com.instana.configuration.integration.vault:
  connection_url: <secrets-manager-address> # The address (URL) of the IBM Cloud Secrets Manager server instance(e.g. https://f022446e-1024-4aa9-a00c-72bf15aa9e7b.us-south.secrets-manager.appdomain.cloud)
  ibm_secrets_manager: <iam_key> # IAM Key that can be used to create access tokens
  secret_refresh_rate: 24 # This configuration option allows you to account for rotating credentials, refresh rate in hours, default 24
 

IBM Cloud Docs - Secrets Manager または IBM Secrets Manager ダッシュボード内にエンドポイントの説明があります。

IAMキーを作成するには、 IBM Cloud - IAMキーを参照してください。

IBM Cloud Secrets Manager をホストエージェントに統合した後、エージェント設定ファイルで、様々なセンサの秘密の取得を指定できます。

エージェント設定ファイルに直接追加する代わりに、 IBM Cloud Secrets Manager から password を取得する次の例を参照してください：

com.instana.example:
  user: 'instana'
  password:
    configuration_from:
      type: vault
      secret_key:
        path: <secret-id> # The id of the Secret within the IBM Secrets Manager, (e.g. cc32688d-89c0-6fa8-c0b4-6cc88c232e66)
        key: <kv-key-entry> # The Key inside the Secret Object of type KV (e.g. login)
      poll_rate: 300 # seconds
 

Kubernetes シークレットからエージェントのセンサー設定に機密情報を取り出すには、以下の2つのコンセプトを組み合わせる：

• シークレットを環境変数またはファイルにマウントするように Kubernetes 構成します。
  • このシークレットは、ワークロード固有の環境変数またはファイルとすることができる。この環境変数またはファイルには、データベースまたはメトリックエンドポイントへのアクセス認証情報など、監視対象のワークロードのみの情報を保持する。
  • このシークレットは、エージェント構成で使用される一般的なシークレットにすることもでき、環境変数またはファイルとしてエージェントポッドにマウントされる。
• マウントされた環境変数またはファイルから設定値を読み込むように、エージェントの configuration.yaml ファイルを適合させる：
  • configuration_from: {type: env} または configuration_from: {type: file} を使って、 ワークロード固有の環境変数またはファイルからシークレットを読み込む。
  • configuration_from: {type: agent_env} または configuration_from: {type: agent_file} を使って、 エージェントの環境変数またはローカルファイルからシークレットを読み込みます。

この2つのプロセスを組み合わせることで、ワークロードは、ポッド固有またはプロセス固有の環境変数やファイルに機密情報を格納することができる。 さらに、エージェントはこれらの環境変数やファイルを取得して機密情報を読み取り、その情報をワークロード固有の設定に適用することができる。

一般的なエージェント設定に適用される秘密については、エージェント環境から機密情報を取得することができます。

エージェントの環境から取得したコンフィギュレーション値については、 configuration.yaml ファイルを以下のように修正する：

com.instana.configuration.integration.vault:
  connection_url: <vault_server_base_url>
  token:
    configuration_from:
      type: agent_env
      env_name: INSTANA_AGENT_VAULT_TOKEN
 

以下の例では、エージェントは自身の環境から HashiCorp Vault 構成のアクセストークンを読み取るため、トークンを configuration.yaml で平文で公開する必要はありません：

com.instana.configuration.integration.vault:
  connection_url: <vault_server_base_url>
  token:
    configuration_from:
      type: agent_env
      env_name: INSTANA_AGENT_VAULT_TOKEN
 

デフォルト値を指定せず、エージェントの環境に環境変数が存在しない場合、 configuration.yaml ファイルは値が入力されていないとみなします。

設定値をファイルから取得する場合は、 configuration.yaml ファイルを以下のように変更してください：

com.instana.plugin.mysql:
  user: 'instana'
  password:
    configuration_from:
      type: agent_file
      file_path: <absolute or relative path to a file containing the configuration value>
      default_value: <set this when the file is not found>
 

プロパティ file_path は、ファイルへの絶対パスを保持するか、エージェントのインストールフォルダからの相対ファイルを指すことができます。 Linux ホストでは、この場所は通常 /opt/instana/agent です。 ファイル /opt/instana/agent/etc/vault_token から読み込む場合、 configuration.yaml ファイルのエントリーは、絶対パス /opt/instana/agent/etc/vault_token または相対パス etc/vault_token のいずれかになります。

ターゲット・プロセス環境から取得したコンフィギュレーション値については、 configuration.yaml ファイルを以下のように修正する：

com.instana.plugin.mysql:
  user: 'instana'
  password:
    configuration_from:
      type: env
      env_name: <environment variable name>
      default_value: <set this when no env var is found on this process>
 

デフォルト値を指定せず、監視対象のプロセスに環境変数が存在しない場合、 configuration.yaml ファイルは値が入力されていないとみなす。

設定値をファイルから取得する場合は、 configuration.yaml ファイルを以下のように変更してください：

com.instana.plugin.mysql:
  user: 'instana'
  password:
    configuration_from:
      type: file
      file_path: <absolute path to a file containing the configuration value>
      default_value: <set this when the file is not found>
      common_value: <set this in addition to the configuration value from file>
 

以下の例では、エージェントは type: file プロパティを持つプロセス・ファイル・システムから /jmx-config-map.yaml ファイルを読み込みます。 default_value プロパティは複雑な YAML 構造を受け入れます。 common_value プロパティーは、後ですべてのプロセス固有の構成とマージされ、すべてのモニター対象プロセスに共通です。

com.instana.plugin.java:
  jmx:
    configuration_from:
      type: file
      file_path: /jmx-config-map.yaml
      default_value:
        - object_name: 'java.lang:type=OperatingSystem'
          metrics:
          - attributes: 'CommittedVirtualMemorySize'
            type: 'absolute'
      common_value:
        - object_name: 'java.lang:type=OperatingSystem'
          metrics:
          - attributes: 'ProcessCpuLoad'
            type: 'delta'
 

以下の例では、 /jmx-config-map.yaml ファイルが Kubernetes ConfigMap からアプリケーション・コンテナにマウントされ、以下のコンテンツを提供している：

- object_name: 'java.lang:type=Compilation'
  metrics:
  - attributes: 'TotalCompilationTime'
    type: 'delta'
- object_name: 'java.lang:type=ClassLoading'
  metrics:
  - attributes: 'LoadedClassCount'
    type: 'absolute'
 

このプロセスの結果、最終的なコンフィギュレーションは以下のようになる。 ProcessCpuLoad の common_value が追加されていることに注意してください。

com.instana.plugin.java:
  jmx:
  - object_name: 'java.lang:type=Compilation'
    metrics:
    - attributes: 'TotalCompilationTime'
      type: 'delta'
  - object_name: 'java.lang:type=ClassLoading'
    metrics:
    - attributes: 'LoadedClassCount'
      type: 'absolute'
  - object_name: 'java.lang:type=OperatingSystem'
    metrics:
    - attributes: 'ProcessCpuLoad'
      type: 'delta'
 

監視対象のプロセスがコンテナ内で実行されている場合、ファイルの絶対パスは、そのコンテナのファイルシステムに対して解決される。

次の表は、トレースの無効化をサポートしているトレーサーの一覧です：

以下のオプションを使用して、トレースをフィルタリングすることができます：

• メソッド名によるフィルタリング：このオプションを使用すると、メソッド名のみに基づいてトレースをフィルタリングできます。 Redis の GET 呼び出しや、 DynamoDB の QUERY 呼び出しなど、特定の操作を無視したい場合に便利である。

• メソッド名とエンドポイントによるフィルタリング：このオプションを使用すると、メソッドと特定のエンドポイントの両方に基づいてトレースを除外することができます。 このオプションは、 Kafka のような、特定のメソッド (たとえば、 consume) のトレースを除外し、特定のトピック (たとえば、 topic1 または topic2) のトレースのみを除外できるテクノロジで特に便利です。

トレースのフィルタリングのルールは以下の通り：

• トレースが無視されると、それ以降のダウンストリームトレースもすべて無視される。
• すべてのエンドポイントやメソッドを無視するには * を使う。
• エンドポイント値（ Kafka トピック名など）は、サービス間で一貫性を保つ。
• メソッド名はプログラミング言語や技術によって異なる場合がある。 サービスの正しいメソッドとエンドポイントを決定するには、Instana UI を参照してください。

次の Instana UI のスクリーンショットは、設定のための正しいメソッドとエンドポイントを識別するための視覚的なリファレンスを提供します：

無視するエンドポイントを設定するには、次の例に示すように、エージェント設定ファイルの com.instana.tracing.ignore-endpoints セクションで、監視から除外する必要があるエンドポイントを指定します：

com.instana.tracing:
  ignore-endpoints:

    # Filtering by Method Name
    redis:
      - 'get'
      - 'type'
    dynamodb:
      - 'query'
    kafka:
      - 'send'

    # Filtering by Method Name and Endpoint for Kafka
    kafka:
      - methods: ["consume"]
        endpoints: ["topic1", "topic2"]  # Exclude consume calls for topic1 and topic2

      - methods: ["consume", "send"]
        endpoints: ["topic3"]  # Exclude both consume and send calls for topic3

      - methods: ["*"]
        endpoints: ["topic4"]  # Exclude all methods for topic4

      - methods: ["consume"]
        endpoints: ["*"]  # Exclude consume method for all topics
 

前述の例では、リストされたフィルタリングオプションに対して、以下のトレースは無視される：

• メソッドによるフィルタリング (Redis, DynamoDB, and Kafka)

  • GET および TYPE のコマンドを使用する。 Redis
  • QUERY コマンドを DynamoDB
  • SEND メソッド（ Kafka ）およびすべての下流トレース

• メソッドとエンドポイントによるフィルタリング (Kafka のみ )

  • CONSUME Kafka およびすべての下流トレースにおける および のメソッド topic1 topic2
  • CONSUME および SEND のメソッド topic3 のメソッド Kafka すべての下流のトレース
  • Kafka の topic4 の全メソッド (*) と全下流トレース
  • CONSUME すべてのトピック (*) とすべてのダウンストリームトレースに対するメソッド

次の表は、エンドポイントの無視をサポートするトレーサーとパッケージの一覧です：