Kubernetes と Red Hat OpenShift のログの収集

OTEL Collectorは、「 Helm 」 チャートまたはOperatorのいずれかを使用してデプロイできます。どちらも、ログを収集して Instana に送信するために必要な機能が含まれた、コミュニティ主導の OTEL Collector Contrib オープンソースパッケージを使用するように設定されています。

TLS で暗号化されたメソッドを使用して Instana エージェントと通信する場合は、以下の手順に従って、 エージェントエンドポイントの TLS 暗号化を設定してください。

本書では、 Helm チャート （ v0.71.1 ） およびOperator （ v0.110.0 ）の最低バージョンを前提としています。これらはいずれもOTEL Collector（ v0.110.0 ）を使用しています。 古いバージョンでも動作しますが、異なる設定が必要で、新しいリリースで修正されたバグがあるかもしれません。

いずれの場合も、まず Instana エージェントをインストールし、OTELコレクターがエージェントを経由してデータを転送するように設定してください。 エージェントをインストールする際は、 OpenTelemetry オプションを含むインストール用 YAML ファイルに以下の設定を指定し、 OpenTelemetry プラグインを有効にする必要があります。 以下の例を参照してください。

    configuration_yaml: |
      # You can leave this empty, or use this to configure your instana agent.
      # See https://docs.instana.io/setup_and_manage/host_agent/on/kubernetes/
      com.instana.plugin.opentelemetry:
        enabled: true
        http:
          enabled: true
        grpc:
          enabled: true

HelmChart を使用して OTEL Collector をインストールするときは、以下の点に 注意してください：

Helmチャートの'opentelemetry-collector/templates/_config.tplファイルには、'filelogレシーバーと'k8sattributesプロセッサーのプリセット定義が含まれています。 これらの定義を有効にするには、'opentelemetry-collector/values.yamlファイルに記述されている'logsCollectionと'kubernetesAttributesプリセットオプションを使用する。 Helmチャート内の'filelogレシーバーまたは'k8sattributesプロセッサーの動作を変更するには、'opentelemetry-collector/values.yamlファイルに独自の設定を追加するのではなく、'opentelemetry-collector/templates/_config.tplファイルを更新する。

この事前設定 filelog 済みのレシーバーは、コンテナのログを解析して、 Kubernetes （ k8s ）のメタデータを抽出することができます。

ファイル opentelemetry-collector/templates/_config.tpl 内の既定 filelog のレシーバー設定を、複数行のログを処理するための以下の 「Recombine」オペレーター設定の例を追加することで、さらに充実させることができます。 あるいは、 Instana の内部マルチラインログアルゴリズムを利用して、マージ処理を行うこともできます。

ただし、独自の結合ロジックを必要とするカスタムな複数行のログ形式については、そのカスタムロジックを実装することができます。 次の例を参照。「recombine operator」は、「container-parser演算子の後に追加され、所定のコンテナログフォーマットに基づいてログを抽出する：

  receivers:

    ## [REQUIRED] The filelog receiver will collect logs written to file by Kubernetes.
    filelog:
    [...]

      ## [REQUIRED] Provides file location information optional operators below (i.e. recombine operator) and to Instana.
      include_file_name: true

      operators:
          ## [REQUIRED] Container log parser. Collects necessary information for correlation by k8sattributes processor.
        - type: container
          id: container-parser

        ## [OPTIONAL] Example recombine operator config to handle multi-line log messages for stack-traces. Requires `include_file_path: true` above.
        - type: recombine
          combine_field: body
          is_first_entry: body matches "^[^\\s]"
          source_identifier: attributes["log.file.path"]

    k8sattributes:
      extract:
        metadata:
          - "k8s.node.name"
          - "k8s.namespace.name"
          - "k8s.deployment.name"
          ## Here add any additional metadata you want to extract from the k8s environment. ## For the full list of supported attributes: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/k8sattributesprocessor/README.md 
          - "service.name" ## Allows logs to be correlated to specific services by Instana.
          - "k8s.pod.uid"   ## Allows logs to be correlated to specific k8s pods by Instana.
          - "container.id"  ## Allows logs to be correlated to specific containers by Instana.

事前設定済みの filelog 受信機および k8sattributes プロセッサコンポーネントを有効にするには、ファイルを opentelemetry-collector/values.yaml 編集し、および logsCollection について true をに enabledkubernetesAttributes 設定します。 以下の例を参照してください。

presets:
  ## [REQUIRED] Automatically adds a pre-configured `filelog` receiver to all logs pipelines and configures container runtime specific message parsers.
  logsCollection:
    enabled: true
  ## [REQUIRED] Automatically adds a pre-configured `k8sattributes` processor to all logs pipelines to provide `k8s.pod.uid` metrics.
  kubernetesAttributes:
    enabled: true

受信 filelog 側については、OTELコレクタのモードを に設定してください daemonset。 ファイル opentelemetry-collector/values.yaml の先頭に以下の設定を追加してください：

mode: "daemonset"

OTEL Collectorが Kubernetes によって生成されるPodのログファイルにアクセスできるようにするには、OTEL CollectorのPodに必要なセキュリティ権限を付与してください。 opentelemetry-collector/values.yamlファイルの'securityContextフィールドに以下のセキュリティ権限を追加する：

securityContext: { privileged: true }

presets.logsCollection.enabledと 'presets.kubernetesAttributes.enabledフラグの両方を 'true に設定すると、OTEL コレクタは設定済みの 'filelogレシーバと 'k8sattributesプロセッサをロードします。 ただし、'opentelemetry-collector/values.yamlファイルにいくつかの設定を追加する必要がある。 具体的には、` config key` 配下の既存の OTEL Collector 設定を、以下の設定に置き換えてください：

config:
  ## [REQUIRED] Unless you require additional log receivers, no need to specify the `filelog` receiver since the `logCollection.enabled: true` preset automatically configures the receiver.
  ## Note: If no additional receivers are to be configured, setting the value to `{}` prevents a `null value` error from occurring in the OTEL Collector.
  receivers: {}

  processors:
    ## [REQUIRED] Resource processor can be manually added to set the `container.runtime` field. Adding this field helps Instana correlate logs to the correct type of Container technology.
    ## Permitted values:
    ## - containerd
    ## - crio
    ## - docker
    ## - garden
    ## Note: In this example, the K8s cluster is running Containerd containers, so the appropriate `container.runtime` attribute is added.
    resource/container_runtime:
      attributes:
        - key: container.runtime
          value: containerd
          action: insert

    ## [OPTIONAL] This is an example log severity parser that sets the **severity_text** field in the log payload, each runs in-order such that the highest matching severity is set.
    ## Note: If the OpenTelemetry Collector does not set log severity, the severity is set by Instana when analyzing the log message.
    transform/set_log_severity:
      log_statements:
        - context: log
        statements:
          - set(severity_text, "Info") where IsMatch(body.string, ".*INFO.*")
          - set(severity_text, "Warn") where IsMatch(body.string, ".*WARN.*")
          - set(severity_text, "Error") where IsMatch(body.string, ".*ERROR.*")
          - set(severity_text, "Fatal") where IsMatch(body.string, ".*FATAL.*")

    ## [REQUIRED] Logs must be sent in batches for performance reasons.
    ## Note: No additional `batch` processor configuration is provided since configuration depends on the user scenario.
    batch: {}
    ## See the page on best practices for Instana OpenTelemetry logging for more information.

  exporters:
    ## [REQUIRED] The Instana Agent supports GRPC payloads
    otlp/instanaAgent:
      ## Note: This configuration assumes the Instana Agent is also deployed in the same cluster.
      ## Note: The GRPC port will be 4317 (unless port-forwarding is used to change this).
      endpoint: instana-agent.instana-agent:4317
      ## TLS encryption is disabled in this example.
      tls:
        insecure: true

  service:
    pipelines:
      ## [REQUIRED] Sample logs pipeline using the above configurations.
      logs:
        receivers: [filelog]
        processors: [resource/container_runtime, k8sattributes, transform/set_log_severity, batch]
        exporters: [otlp/instanaAgent]

オペレータを使用して OTEL Collector をインストールする前に、まず 'cert-manager をインストールする必要があります。

cert-managerインストールするには、以下のコマンドを実行する：

• kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.16.1/cert-manager.yaml

次に、OTEL Collector を格納する新しいプロジェクトを作成します：

oc new-project otel-collector

Red Hat OpenShiftの特権コンテナとして OTEL Collector を実行し、基盤となるノードの '/var/log/podsにあるログファイルにアクセスします。 必要なセキュリティアクセス許可を設定するために、OTEL Collector のセキュリティコンテキストを定義します。

以下の内容の Security Context Constraint (SCC) ファイルを作成して、OTEL Collector が必要とするセキュリティアクセス許可を定義します。

この例では、ファイル名を「scc.yamlする。

apiVersion: security.openshift.io/v1

kind: SecurityContextConstraints

metadata:
  name: otel-scc

allowPrivilegedContainer: true
allowHostDirVolumePlugin: true
allowHostPorts: true

runAsUser:
  type: RunAsAny

seLinuxContext:
  type: RunAsAny

fsGroup:
  type: RunAsAny

users:
## [REQUIRE] The format of the next line is
##  `system:serviceaccount:<namespace>:<otel-pod-name>`
## The provided example matches the defaults used in this documentation.
## If you did not use the default values, then you should change this
## line to reflect that.
- system:serviceaccount:otel-collector:simple-otelcol-collector

セキュリティコンテキストを設定するには、次の oc apply -f scc.yaml コマンドを実行してください。

セキュリティコンテキストをインストールした後、最新の 「 Kubernetes インストールマニフェスト 」 operator を実行してインストールを行ってください。 以下のコマンドを実行します。

• kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

operatorインストールしたら、OTEL Collector の設定に進みます。 Helm Chartのインストール方法とは異なり、本製品にはレシーバーおよび k8sattributes プロセッサー filelog の設定用プリセットは用意されていません。 したがって、手動で設定する必要があります。 以下のOTEL Collectorの手動設定例のうちいずれかを使用し、それを YAML ファイル（例 otel-collector-config.yaml：）にコピーして、次のコマンドを実行することで、 Kubernetes クラスタに適用してください：

• kubectl apply -f otel-collector-config.yaml

最初の例は基本的な構成であり、OTEL Collector を起動し、 Red Hat OpenShift 環境で検出されたすべてのポッドのログを監視するために必要な最小限の設定のみが含まれています。 この設定では、データに対して特別な処理は行わず、変更を加えることなくエージェントにデータを転送します。 この設定は、コレクターの動作を確認するための良い出発点となります。 必要なカスタマイズは後で追加できます。

apiVersion: opentelemetry.io/v1beta1

kind: OpenTelemetryCollector

metadata:
  ## Users should set this name as needed
  name: simple-otelcol

spec:
  ## [REQUIRED] Grants the OTEL Collector necessary privileges to access kubernetes log files.
  securityContext: { privileged: true }

  ## [REQUIRED] Best configuration for the `filelog` receiver.
  mode: daemonset

  ## [REQUIRED] We assume minimum OTEL Collector Contrib release v0.110.0 in this documentation.
  image: otel/opentelemetry-collector-contrib:0.110.0
  imagePullPolicy: IfNotPresent

  ## [REQUIRED] It is necessary to specify the mounts that provide the OTEL Collector with access to the pod log files.
  volumeMounts:
    - name: varlogpods
      mountPath: /var/log/pods
      readOnly: true
  volumes:
    - name: varlogpods
      hostPath:
        path: /var/log/pods

  config:
    receivers:
      ## [REQUIRED] The filelog receiver will collect logs written to file by Kubernetes.
      filelog:
        ## [REQUIRED] Standard location for cluster pod log files. Update if different.
        include: [ /var/log/pods/*/*/*.log ]

        ## [REQUIRED] Whether to include the file path in the logs.
        include_file_path: true

        operators:
          ## [REQUIRED] Container log parser. Collects necessary information for correlation by k8sattributes processor.
          - type: container
            id: container-parser

    processors:
      ## [REQUIRED] The k8sattributes processor provides UIDs needed to correlate container/pod logs to their corresponding entities.
      ## Note: The following configures collection of the `container.id` and `k8s.pod.uid` fields in the `k8sattributes` processor for correlation.
      ## Note: In some cases, the `container.id` field cannot be provided by the OpenTelemetry SDK, which means Instana will fallback on the `k8s.pod.uid`.
      k8sattributes:
        passthrough: false
        pod_association:
        - sources:
          - from: resource_attribute
            name: container.id
        - sources:
          - from: resource_attribute
            name: k8s.pod.ip
        - sources:
          - from: resource_attribute
            name: k8s.pod.uid
        - sources:
          - from: connection
        extract:
          ## [REQUIRED] At minimum we need the following metadata fields extracted by the `k8sattributes` processor.
          metadata:
            - "k8s.node.name" 
            - "k8s.namespace.name" 
            - "k8s.deployment.name" 
            ## Here add any additional metadata you want to extract from the k8s environment. 
            ## For the full list of supported attributes: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/k8sattributesprocessor/README.md 
            - "service.name" ## Allows logs to be correlated to specific services by Instana.
            - "k8s.pod.uid"   ## If container.id is unavailable, logs are correlated to a specific Kubernetes pod.
            - "container.id"  ## If this field is available, logs are correlated to specific containers in a Kubernetes pod.

      ## [REQUIRED] Resource processor can be manually added to set the `container.runtime` field. Adding this field helps Instana correlate logs to the correct type of Container technology.
      ## Note: In this example, the K8s cluster is running Containerd containers, so the appropriate `container.runtime` attribute is added.
      resource/container_runtime:
        attributes:
        - key: container.runtime
          value: containerd
          action: insert

      ## Logs must be sent in batches for performance reasons.
      ## Note: No additional `batch` processor configuration is provided since configuration depends on the user scenario.
      batch: {}
      ## See the page on best practices for Instana OpenTelemetry logging for more information.

    exporters:
      ## [REQUIRED] The Instana Agent supports GRPC payloads
      otlp/instanaAgent:
        ## Note: This configuration assumes the Instana Agent is also deployed in the same cluster.
        ## Note: The GRPC port will be 4317 (unless port-forwarding is used to change this).
        endpoint: 'http://instana-agent.instana-agent:4317'
        ## TLS encryption is disabled in this example.
        tls:
          insecure: true

    service:
      pipelines:
        ## [REQUIRED] Sample logs pipeline using the above configurations.
        logs:
          receivers: [filelog]
          processors: [resource/container_runtime, k8sattributes, batch]
          exporters: [otlp/instanaAgent]

次の設定には、OTEL Collector で利用可能な追加機能を示すためのオプションのフィールドがいくつか含まれています。 これらのフィールドは、フィールド名の前のコメント内で [OPTIONAL] でマークされています。 この設定には、OTEL Collectorで可能なすべての機能の網羅的なリストが含まれているわけではなく、あくまで一般的に使用されるオプションの例をいくつか示しているに過ぎません。

apiVersion: opentelemetry.io/v1beta1

kind: OpenTelemetryCollector

metadata:
  ## Users should set this name as needed
  name: simple-otelcol

spec:
  ## [REQUIRED] Grants the OTEL Collector necessary privileges to access kubernetes log files.
  securityContext: { privileged: true }

  ## [REQUIRED] Best configuration for the `filelog` receiver.
  mode: daemonset

  ## [REQUIRED] We assume minimum OTEL Collector Contrib release v0.110.0 in this documentation.
  image: otel/opentelemetry-collector-contrib:0.110.0
  imagePullPolicy: IfNotPresent

  ## [REQUIRED] It is necessary to specify the mounts that provide the OTEL Collector with access to the pod log files.
  volumeMounts:
    - name: varlogpods
      mountPath: /var/log/pods
      readOnly: true
  volumes:
    - name: varlogpods
      hostPath:
        path: /var/log/pods

  config:
    receivers:
      ## [REQUIRED] The filelog receiver will collect logs written to file by Kubernetes.
      filelog:
        ## [REQUIRED] Standard location for cluster pod log files. Update if different.
        include: [ /var/log/pods/*/*/*.log ]

        ## [OPTIONAL] Path (or regex) to the log files that must be ignored.
        ## Note: This could be the OTEL Collector pod log located at:
        ##      /var/log/pods/{"opentelemetry collector namespace"}_{"opentelemetry collector fullname"}*_*/{"opentelemetry collector lowercase_chartname"}/*.log
        exclude: [ "/path/to/log/files/to/ignore" ]

        ## [REQUIRED] Whether to include the file path in the logs
        include_file_path: true

        ## [OPTIONAL] Whether to include the file name in the logs
        include_file_name: true

        ## [OPTIONAL] Preserve the leading white spaces so that the example 'recombine' operator works as expected.
        preserve_leading_whitespaces: true

        operators:
          ## [REQUIRED] Container log parser. Collects necessary information for correlation by k8sattributes processor.
          - type: container
            id: container-parser

          ## [OPTIONAL] Example recombine operator config to handle multi-line log messages for stack-traces. Requires `include_file_path: true` above.
          - type: recombine
            combine_field: body
            is_first_entry: body matches "^[^\\s]"
            source_identifier: attributes["log.file.path"]

    processors:
      ## [REQUIRED] The k8sattributes processor provides UIDs needed to correlate container/pod logs to their corresponding entities.
      ## Note: The following configures collection of the `container.id` and `k8s.pod.uid` fields in the `k8sattributes` processor for correlation.
      ## Note: In some cases, the `container.id` field cannot be provided by the OpenTelemetry SDK, which means Instana will fallback on the `k8s.pod.uid`.
      k8sattributes:
        passthrough: false
        pod_association:
        - sources:
          - from: resource_attribute
            name: container.id
        - sources:
          - from: resource_attribute
            name: k8s.pod.ip
        - sources:
          - from: resource_attribute
            name: k8s.pod.uid
        - sources:
          - from: connection
        extract:
          ## [REQUIRED] At minimum we need the following metadata fields extracted by the `k8sattributes` processor.
          metadata:
            - "k8s.node.name" 
            - "k8s.namespace.name" 
            - "k8s.deployment.name" 
            ## Here add any additional metadata you want to extract from the k8s environment. 
            ## For the full list of supported attributes: https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/k8sattributesprocessor/README.md 
            - "service.name" ## Allows logs to be correlated to specific services by Instana.
            - "k8s.pod.uid"   ## If container.id is unavailable, logs are correlated to a specific Kubernetes pod.
            - "container.id"  ## If this field is available, logs are correlated to specific containers in a Kubernetes pod.
          ## [OPTIONAL] Useful if you want to collect pod labels and send them to Instana as "custom-tags". See the "transform/copy-from-resourcelog" processor below.
          labels:
            - tag_name: $$1
              key_regex: (.*)
              from: pod
          ## [OPTIONAL] Useful if you want to collect pod annotations and send them to Instana as "custom-tags". See the "transform/copy-from-resourcelog" processor below.
          annotations:
            - tag_name: $$1
              key_regex: (.*)
              from: pod

      ## [OPTIONAL] Example OTEL Processor for extracting resource-log attributes collected from pod labels/annotations to be processed as "custom-tags" by Instana
      transform/copy-from-resourcelog:
        log_statements:
          - context: log
            statements:
              ## Example where a pod's start time is collected by the k8sattributes processor.
              - set(attributes["Pod Start Timestamp"], resource.attributes["k8s.pod.start_time"])
              ## Example where a specific field, in this case some `x-forwarder-ip` value is extracted from log messages, using a regex.
              ## Note: Due to the usage of the regex, the entire `set(...)` command is surrounded by single-quotes to avoid YAML parse errors.
              - 'set(attributes["x-forwarder-ip"], ExtractPatterns(body, "x-forwarder-ip: (?P<value>[0-9\\.]+)"))'

      ## [REQUIRED] Resource processor can be manually added to set the `container.runtime` field. Adding this field helps Instana correlate logs to the correct type of Container technology.
      ## Note: In this example, the K8s cluster is running Containerd containers, so the appropriate `container.runtime` attribute is added.
      resource/container_runtime:
        attributes:
        - key: container.runtime
          value: containerd
          action: insert

      ## [OPTIONAL] This is an example log severity parser that sets the **severity_text** field in the log payload, each runs in-order such that the highest matching severity is set.
      ## Note: If the OpenTelemetry Collector does not set log severity, then the severity is set by Instana when analyzing the log message.
      transform/set_log_severity:
        log_statements:
        - context: log
          statements:
          - set(severity_text, "Info") where IsMatch(body.string, ".*INFO.*")
          - set(severity_text, "Warn") where IsMatch(body.string, ".*WARN.*")
          - set(severity_text, "Error") where IsMatch(body.string, ".*ERROR.*")
          - set(severity_text, "Fatal") where IsMatch(body.string, ".*FATAL.*")

      ## Logs must be sent in batches for performance reasons.
      ## Note: No additional `batch` processor configuration is provided since configuration depends on the user scenario.
      batch: {}
      ## See the page on best practices for Instana OpenTelemetry logging for more information.

    exporters:
      ## [REQUIRED] The Instana Agent supports GRPC payloads
      otlp/instanaAgent:
        ## Note: This configuration assumes the Instana Agent is also deployed in the same cluster.
        ## Note: The GRPC port will be 4317 (unless port-forwarding is used to change this).
        endpoint: instana-agent.instana-agent:4317
        ## TLS encryption is disabled in this example.
        tls:
          insecure: true

    service:
      pipelines:
        ## [REQUIRED] Sample logs pipeline using the above configurations.
        logs:
          receivers: [filelog]
          processors: [resource/container_runtime, k8sattributes, transform/set_log_severity, batch]
          exporters: [otlp/instanaAgent]

一般に、 Red Hat OpenShift コマンド・ライン・インターフェース (CLI) を使用して、 Red Hat OpenShift クラスターをリモート側で管理できます。 このドキュメントの残りの手順は、INF（インフラストラクチャ）ノードにログインして実行することもできますが、クラスタの管理には Red Hat OpenShift のCLIを使用してください。

ワークステーションにRed Hat OpenShiftCLI 'ocをインストールします。 詳細については、 「 Red Hat OpenShift CLI のはじめ方」を参照してください。

以下のコマンドを使用してリモート側でクラスターにログインし、 Red Hat OpenShift クラスターに接続するように Red Hat OpenShift CLI を構成します。

$ oc login --web --server=https://<infrastructure node's hostname>:6443

これで、ワークステーションで実行するすべての oc コマンドが Red Hat OpenShift クラスターにリダイレクトされます。