Docs » Splunk Distribution of the OpenTelemetry Collector の利用開始 » Collector コンポーネント » Collectorコンポーネント: プロセッサー » Kubernetes属性プロセッサー

Kubernetes属性プロセッサー 🔗

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

注意

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

はじめに 🔗

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

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 アクセス許可を要求します。

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

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 のデプロイモード を参照してください。

エージェント設定 🔗

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

Collectorをホスト監視（エージェント）モードで実行する場合は、検出フィルターを適用して、Collectorが実行されているのと同じホストからの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

ゲートウェイ設定 🔗

データ転送（ゲートウェイ）モードで実行している場合、プロセッサーがテレメトリデータを出力するポッドの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

注意

Kubernetes ナビゲーター、関連コンテンツ、正確なサブスクリプションの使用など、Splunk Observability Cloud の機能に必要なため、k8s.pod.name などのデフォルト属性が常に抽出されていることを確認してください。

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

  • コンテナ仕様の属性：リソース属性として 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 ステートメ ントのペアで構成されます。 from ステートメントには 2つのタイプを定義できます：

  • 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のラベルとポッドと名前空間のアノテーションからリソース属性を設定することもできます。これは extract 内の annotations と labels リストから設定できます。

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

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

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

  • from: 値の抽出に使用される Kubernetes オブジェクト。指定可能な値は pod と namespace の2つ。デフォルト値は 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 に送信されません。

既知の制限 🔗

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

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

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

サイドカー 🔗

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

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

Splunk Observability Cloudをご利用のお客様で、Splunk Observability Cloudでデータを確認できない場合は、以下の方法でサポートを受けることができます。

Splunk Observability Cloudをご利用のお客様

見込み客および無料トライアルユーザー様

  • Splunk Answers のコミュニティサポートで質問し、回答を得る

  • Splunk #observability ユーザーグループの Slack チャンネルに参加して、世界中の顧客、パートナー、Splunk 社員とのコミュニケーションを図る。参加するには、Get Started with Splunk Community マニュアルの チャットグループ を参照してください。

This page was last updated on 2024年05月29日.