Kubernetes属性プロセッサー

リソース属性の更新、追加、削除には Kubernetes 属性プロセッサを使用します。コンポーネントの設定方法については、続きをお読みください。

Kubernetes 属性プロセッサは、Kubernetes メタデータを使用してリソース属性を管理する OpenTelemetry Collector コンポーネントです。プロセッサはリソースを自動的に検出し、それらからメタデータを抽出し、メタデータを関連するスパン、メトリクス、ログにリソース属性として追加します。サポートされるパイプラインタイプは、traces、metrics、logs です。詳細については「パイプラインでデータを処理する」を参照してください。

注意: 設定から Kubernetes 属性プロセッサを削除しないでください。Kubernetes ナビゲーター、関連コンテンツ、正確なサブスクリプションの使用など、Splunk Observability Cloud の機能には、k8s.pod.name など、プロセッサによって抽出されたデフォルトの属性が必要です。

はじめに

Splunk Distribution of OpenTelemetry Collector の Helm チャートにはすでに Kubernetes 属性プロセッサが含まれており、すべてのデプロイモードで、デフォルトで有効になっています。「Helm を使用して Collector for Kubernetes をインストールする」を参照してください。

Kubernetes属性プロセッサーを手動で設定するには、以下の手順に従います：

  1. 役割ベースのアクセス制御を設定する

  2. ディスカバリー・フィルター

  3. メタデータの抽出

  4. 関連付けリスト

  5. Kubernetesのラベルとアノテーション

サンプル構成

Splunk Distribution of OpenTelemetry Collector for Kubernetes では、デフォルトの設定で k8sattributes プロセッサーが追加されます：

processors:
  k8sattributes:

設定ファイルの service セクションのすべてのパイプラインにプロセッサーを含めることができます：

service:
  pipelines:
    metrics:
      processors: [k8sattributes/demo]
    logs:
      processors: [k8sattributes/demo]
    traces:
      processors: [k8sattributes/demo]

設定例

次の例には、抽出されたメタデータ、Kubernetesのアノテーションとラベル、および関連付けのリストが含まれています：

k8sattributes/demo:
  auth_type: "serviceAccount"
  passthrough: false
  filter:
    node_from_env_var: <KUBE_NODE_NAME>
  extract:
    metadata:
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.deployment.name
      - k8s.namespace.name
      - k8s.node.name
      - k8s.pod.start_time
  annotations:
    - key_regex: opentel.* # extracts Keys & values of annotations matching regex `opentel.*`
      from: pod
  labels:
    - key_regex: opentel.* # extracts Keys & values of labels matching regex `opentel.*`
      from: pod
  pod_association:
    - sources:
       - from: resource_attribute
         name: k8s.pod.ip
    - sources:
       - from: resource_attribute
         name: k8s.pod.uid
    - sources:
       - from: connection

高度なユースケース

役割ベースのアクセス制御を設定する

Kubernetes属性プロセッサーは、設定されたフィルターに含まれるすべての名前空間とポッドについて、pods と namespacesの両方のリソースに get 、watch 、list 権限を要求します。

次の例は、クラスター内のすべての Pod と名前空間に対して必要なアクセス許可を ServiceAccount に与える方法を示しています。Collector をデプロイした名前空間に <col_namespace> を置き換えます。

apiVersion: v1
kind: ServiceAccount
metadata:
   name: collector
   namespace: <col_namespace>

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
   name: otel-collector
rules:
   - apiGroups: [""]
   resources: ["pods", "namespaces"]
   verbs: ["get", "watch", "list"]

---

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
   name: otel-collector
subjects:
- kind: ServiceAccount
  name: collector
  namespace: <col_namespace>
roleRef:
   kind: ClusterRole
   name: otel-collector
   apiGroup: rbac.authorization.k8s.io

ディスカバリー・フィルター

Kubernetes 属性プロセッサは、エージェントまたはゲートウェイとしてデプロイした Collector で使用できます。それぞれ DaemonSets または Deployments を使用してデプロイします。詳細については、「Collector deployment modes」を参照してください。

エージェント設定

ホスト監視（エージェント）モードでは、プロセッサーは、スパン、メトリクス、またはログをエージェントに送信するポッドのIPアドレスを検出し、この情報を使用してポッドからメタデータを抽出します。

Collector をホスト監視（エージェント）モードで実行する場合は、検出フィルターを適用して、Collector が実行されているのと同じホストからの Pod のみが検出されるようにします。検出フィルターを使用すると、大規模クラスターでのリソース消費も最適化されます。

プロセッサが実行されているノードによって Pod を自動的にフィルターするには、Downward API を設定して、ノード名を環境変数として注入します。例：

spec:
  containers:
  - env:
    - name: KUBE_NODE_NAME
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: spec.nodeName

次に、filter.node_from_env_var フィールドに、ノードの名前を含む環境変数の名前を設定します。例：

k8sattributes:
  filter:
    node_from_env_var: KUBE_NODE_NAME

ゲートウェイ設定

データ転送（ゲートウェイ）モードで実行している場合、プロセッサはテレメトリデータを出力する Pod の IP アドレスを解決できません。Collector ゲートウェイで正しい IP アドレスを受信するには、アドレスを転送するようにエージェントを設定します。

IP アドレスをゲートウェイに転送するには、ホストモニタリング（エージェント）モードで Collector を設定して、パススルーモードで実行するようにします。これにより、エージェントが IP アドレスを検出し、すべてのテレメトリリソースに接続されている属性として渡すことができます。

k8sattributes:
  passthrough: true

その後、通常通り Collector ゲートウェイを設定します。プロセッサは、エージェントまたは他のソースから送信されたスパン、ログ、メトリクスの IP アドレスを自動的に検出し、Kubernetes API を呼び出してメタデータを抽出します。

メタデータの抽出

metadata オプションを使って、追加したいリソース属性を定義します。pod_association.resource_attribute で定義されている既存のメタデータの属性名しか使用できません。プロセッサは、空の値や存在しない値を無視します。

デフォルトでは以下の属性が追加されます：

  • k8s.namespace.name

  • k8s.pod.name

  • k8s.pod.uid

  • k8s.pod.start_time

  • k8s.deployment.name

  • k8s.node.name

このリストは、metadata セクションを追加することで変更できます。例：

k8sattributes:
  auth_type: "serviceAccount"
  passthrough: false
  filter:
    node_from_env_var: KUBE_NODE_NAME
  extract:
    metadata:
      - k8s.pod.name
      - k8s.pod.uid
      - k8s.deployment.name
      - k8s.namespace.name
      - k8s.node.name
      - k8s.pod.start_time
注意: k8s.pod.name などのデフォルト属性は、Kubernetes ナビゲーター、関連コンテンツ、正確なサブスクリプションの使用など、Splunk Observability Cloud の機能に必要なため、常に抽出されていることを確認してください。

以下のコンテナ・レベル属性は、ポッド内のコンテナを識別するために追加の属性を必要とします：

  • コンテナ仕様の属性：リソース属性として k8s.container.name が利用可能な場合のみ設定します。

    • container.image.name

    • container.image.tag

  • コンテナ属性：リソース属性として k8s.container.name が利用可能な場合のみ設定します。

    • container.id:メタデータで利用可能でなければなりません。

注: k8s.container.restart_count リソース属性を設定して、特定のコンテナインスタンスとの関連付けを取得します。k8s.container.restart_count が設定されていない場合は、最後のコンテナインスタンスが使用されます。

関連付けリスト

pod_association フィールドを使用して、プロセッサーを通過するデータとポッドのメタデータを関連付けるルールを定義します。このフィールドは、最初に一致するまで、指定された順序で実行される関連付けのリストを表します。

各関連付けは、送信元のリストです。送信元にはルールが含まれます。プロセッサはすべてのルールを実行し、その結果メタデータのキャッシュキーを生成します。例：

pod_association:
 # List of associations
  - sources:
      # List of sources. Each cointains rules
      - from: resource_attribute
        name: k8s.pod.name
      - from: resource_attribute
        name: k8s.namespace.name

関連付けを適用するには、各ソースがログ、トレース、またはメトリクスから正常に取得されている必要があります。関連付けルールを設定しない場合、プロセッサは接続のアドレスを使用してリソースを関連付けます。

各ソースのルールは、それぞれルールタイプと属性名を表す from ステートメントと name ステートメントのペアで構成されます。ステートメントには次の 2 つのタイプの from ステートメントを定義できます。

  • from: connection: 接続コンテキストからIPアドレス属性を抽出します(利用可能な場合)。

  • from: resource_attribute: 属性リストから検索する属性名を指定します。

次の例では、ポッド関連付けルールの2種類の from ソース文を示します：

pod_association:
  - sources:
    - from: resource_attribute
      name: ip
  - sources:
    - from: resource_attribute
      name: k8s.pod.ip
  - sources:
    - from: resource_attribute
      name: host.name
  - sources:
    - from: connection
      name: ip

Kubernetesのラベルとアノテーション

Kubernetes 属性プロセッサは、Kubernetes のラベルおよび Pod と名前空間のアノテーションからリソース属性を設定することもできます。これは、extract 内の annotations リストと labels リストを使用して設定できます。

プロセッサは、Pod と名前空間から注釈とラベルを抽出し、スパン、メトリクス、ログに追加します。次のパラメータを使用して各項目を指定できます。

  • tag_name:テレメトリのタグ付けに使用される名前。

  • key: 値を抽出するためのキー。

  • from：値を抽出するために使用される Kubernetes オブジェクト。使用可能な 2 つの値は pod と namespace です。デフォルト値は namespace です。

例：

annotations:
# Extracts value of annotation from pods with key `annotation-one`
# and inserts it as a tag with key `a1`
  - tag_name: a1
    key: annotation-one
    from: pod
# Extracts value of annotation from namespaces with key `annotation-two`
# with regular expressions and inserts it as a tag with key `a2`
  - tag_name: a2
    key: annotation-two
    regex: field=(?P<value>.+)
    from: namespace

labels:
# Extracts value of label from namespaces with key `label1`
# and inserts it as a tag with key `l1`
  - tag_name: l1
    key: label1
    from: namespace
# Extracts value of label from pods with key `label2` with
#  regular expressions and inserts it as a tag with key `l2`
  - tag_name: l2
    key: label2
    regex: field=(?P<value>.+)
    from: pod

設定

次の表は、Kubernetes属性プロセッサーの設定オプションを示します：

メトリクス

以下のメトリクス、リソース属性、および属性が使用できます。

特定のメトリクスをアクティブまたは非アクティブにする

各メトリクスの metrics セクションの enabled フィールドを設定することで、特定のメトリクスをアクティブまたは非アクティブにできます。例：

receivers:
  samplereceiver:
    metrics:
      metric-one:
        enabled: true
      metric-two:
        enabled: false

以下は、アクティブ化されたメトリクスを持つホスト・メトリクス・レシーバーの構成例です：

receivers:
  hostmetrics:
    scrapers:
      process:
        metrics:
          process.cpu.utilization:
            enabled: true
注: 非アクティブ化されたメトリックは Splunk Observability Cloud に送信されません。
請求

  • MTS ベースのサブスクリプションの場合、すべてのメトリックがメトリックの使用にカウントされます。

  • ホストベースのプランを使用している場合、このドキュメントでアクティブ（アクティブ：はい）としてリストされているメトリックはデフォルトと見なされ、無料で含まれています。

詳細については、「Infrastructure Monitoringのサブスクリプション使用状況（ホストとメトリクスのプラン）」を参照してください。

既知の制限

Kubernetes 属性プロセッサは、次のようなケースではうまく動作しません。

ホストネットワーキングモード

プロセッサは、ホストネットワークモードで実行されている Pod を識別できません。そのような Pod によって生成されたテレメトリデータを強化することは、関連付けルールが IP アドレス属性に基づいていない場合にのみ機能します。

サイドカー

サイドカーとして実行している場合、プロセッサは同じ Pod からコンテナを検出できません。代わりに、Kubernetes Downward API を使用して環境変数を Pod に注入し、その値をタグとして使用します。

トラブルシューティング

__ ___ ___ _ ______ _____________ _____ ________ ___ ___ ___ ____ __ ___ ____ ____ __ ______ _____________ ______ ___ ___ ___ ____ __ ___ _________ _____

_________ __ ______ _____________ _____ _________

_________ __ ___________ _________ ___ ____ _____ _____

  • ___ _ ________ ___ ___ _______ _______ _________ _______ __ ______ ________

  • ____ ___ ______ ______________ ____ _____ _____ _______ __ ___________ ____ __________ _________ ___ ______ _________ __________ __ _____ ___ ____ _______