Collecte des journaux Kubernetes et Red Hat OpenShift

Vous pouvez déployer OTEL Collector à l'aide du tableau « Helm » ou de l'opérateur; les deux sont configurés pour utiliser le paquet open OTEL Collector Contrib source développé par la communauté, qui comprend les fonctionnalités nécessaires à la collecte et à l'envoi des journaux vers Instana.

Si vous souhaitez communiquer avec l'agent Instana à l'aide de méthodes cryptées par TLS, suivez les étapes pour configurer le cryptage TLS pour le point de terminaison de l'agent.

Ce document suppose l'utilisation d'une version minimale du graphique « Helm » ( v0.71.1 ) et de l'opérateur «Operator» ( v0.110.0 ), qui utilisent tous deux OTEL Collector ( v0.110.0 ). Les anciennes versions peuvent encore fonctionner, mais nécessitent des configurations différentes et peuvent présenter des bogues qui ont été corrigés dans les versions plus récentes.

Dans les deux cas, commencez par installer l'agent Instana et configurez le collecteur OTEL pour qu'il achemine les données via cet agent. Lors de l'installation de l'agent, vous devez également activer le plug-in « OpenTelemetry » en indiquant la configuration suivante dans le fichier d' YAML s d'installation qui contient les options « OpenTelemetry ». Voir l'exemple suivant :

    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

Lorsque vous installez le collecteur OTEL en utilisant la méthode d'installation de la carteHelm, tenez compte des considérations suivantes :

Le fichier " opentelemetry-collector/templates/_config.tpl de la carte Helm contient des définitions de préréglages pour le récepteur " filelog et le processeur " k8sattributes Vous pouvez activer ces définitions en utilisant les options de présélection " logsCollection et " kubernetesAttributes qui sont documentées dans le fichier " opentelemetry-collector/values.yaml. Pour modifier le comportement du récepteur " filelog ou du processeur " k8sattributes dans la carte Helm, mettez à jour le fichier " opentelemetry-collector/templates/_config.tpl au lieu d'ajouter votre propre configuration dans le fichier " opentelemetry-collector/values.yaml, car vous risquez d'écraser partiellement la configuration et de provoquer un comportement inattendu.

Le récepteur préconfiguré filelog est capable d'analyser les journaux des conteneurs afin d'en extraire les métadonnées d' Kubernetes s ( k8s ).

Vous pouvez améliorer la configuration du récepteur fournie filelog dans le opentelemetry-collector/templates/_config.tpl fichier en y ajoutant l'exemple suivant de configuration de l'opérateur Recombine afin de gérer les journaux multilignes. Vous pouvez également vous appuyer sur les algorithmes de journalisation multiligne intégrés à l' Instana pour gérer la fusion.

Toutefois, pour les formats de journalisation multilignes personnalisés qui nécessitent une logique d'assemblage spécifique, vous pouvez mettre en œuvre cette logique personnalisée. Voir l'exemple suivant où " recombine operator est ajouté après l'opérateur " container-parser qui extrait les journaux sur la base d'un formatage prédéterminé des journaux de conteneurs :

  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.

Pour activer les composants préconfigurés " filelog du récepteur et " k8sattributes du processeur, modifiez le fichier " opentelemetry-collector/values.yaml et réglez " enabled sur " true " pour " logsCollection et " kubernetesAttributes. Voir l'exemple suivant :

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

Pour filelog le récepteur, réglez le mode du collecteur OTEL sur daemonset. Ajoutez le paramètre suivant au début du opentelemetry-collector/values.yaml fichier :

mode: "daemonset"

Pour vous assurer que le collecteur OTEL puisse accéder aux fichiers journaux du pod générés par Kubernetes, accordez les privilèges de sécurité nécessaires au pod du collecteur OTEL. Dans le fichier " opentelemetry-collector/values.yaml, ajoutez les privilèges de sécurité suivants au champ " securityContext:

securityContext: { privileged: true }

Lorsque les drapeaux 'presets.logsCollection.enabled et 'presets.kubernetesAttributes.enabled sont tous deux réglés sur 'true, le collecteur OTEL charge le récepteur 'filelog et le processeur 'k8sattributes préconfigurés. Cependant, vous devez ajouter quelques configurations supplémentaires au fichier " opentelemetry-collector/values.yaml. Plus précisément, remplacez la configuration actuelle du collecteur OTEL sous la config clé par la configuration suivante :

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]

Avant d'installer le collecteur OTEL à l'aide de l'opérateur, vous devez d'abord installer le " cert-manager.

Pour installer le " cert-manager, exécutez la commande suivante :

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

Ensuite, créez un nouveau projet pour héberger OTEL Collector :

oc new-project otel-collector

Exécutez le collecteur OTEL en tant que conteneur privilégié sous Red Hat OpenShift pour accéder aux fichiers journaux dans '/var/log/pods sur le nœud sous-jacent. Définissez un contexte de sécurité pour le collecteur OTEL afin de définir les autorisations d'accès à la sécurité requises.

Définissez les autorisations d'accès à la sécurité dont le collecteur OTEL a besoin en créant un fichier Security Context Constraint (SCC) avec le contenu suivant.

Dans cet exemple, nommez le fichier " 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

Exécutez la commande oc apply -f scc.yaml pour configurer le contexte de sécurité.

Une fois le contexte de sécurité installé, procédez à l'installation operator en exécutant le dernier manifeste d'installation pour Kubernetes. Exécutez la commande suivante :

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

Après avoir installé le 'operator, procédez à la configuration du collecteur OTEL. Contrairement à la méthode d'installation « Chart » d' Helm, l'opérateur ne fournit pas de préréglages pour la configuration du filelog récepteur et k8sattributes du processeur. Vous devez donc les configurer manuellement. Utilisez l'un des exemples de configuration manuelle d'OTEL Collector ci-dessous, copiez-le dans un fichier « YAML » (par exemple otel-collector-config.yaml), puis appliquez-le à votre cluster « Kubernetes » en exécutant la commande suivante :

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

Le premier exemple est une configuration de base, qui ne contient que les paramètres minimaux nécessaires pour démarrer OTEL Collector et surveiller les journaux de tous les pods détectés dans l'environnement d' Red Hat OpenShift. Cette configuration n'effectue aucun traitement particulier des données; elle les transmet simplement à l'agent sans les modifier. Cette configuration constitue un bon point de départ pour tester le fonctionnement du collecteur. Vous pourrez ajouter les personnalisations nécessaires ultérieurement.

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]

La configuration suivante comprend plusieurs champs facultatifs permettant de présenter certaines fonctionnalités supplémentaires offertes par OTEL Collector. Ces champs sont signalés par [OPTIONAL] dans un commentaire précédant le champ. Cette configuration ne contient pas une liste exhaustive de toutes les possibilités offertes par OTEL Collector; elle ne fournit qu'une sélection d'exemples d'options couramment utilisées.

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]

En général, vous pouvez gérer votre cluster Red Hat OpenShift à distance à l'aide de l'interface de ligne de commande Red Hat OpenShift . Même si vous pouvez suivre les étapes suivantes décrites dans ce document en vous connectant au nœud INF (Infrastructure), utilisez l'interface de ligne de commande (CLI) d' Red Hat OpenShift pour gérer votre cluster.

Installez le CLI Red Hat OpenShift 'oc sur votre poste de travail. Pour plus d'informations, consultez la section « Premiers pas avec l'interface CLI d' Red Hat OpenShift ».

Configurez l'interface de ligne de commande Red Hat OpenShift pour vous connecter à votre cluster Red Hat OpenShift à l'aide de la commande suivante pour vous connecter à distance au cluster:

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

A présent, toutes les commandes oc que vous exécutez sur votre poste de travail sont redirigées vers votre cluster Red Hat OpenShift .