Migrer des agents depuis Elastic

Migrer des agents depuis Elastic

​

Migration des agents depuis Elastic

Elastic Stack propose plusieurs agents de collecte de données d’observabilité. Plus précisément :

• La famille Beats — notamment Filebeat, Metricbeat et Packetbeat — repose entièrement sur la bibliothèque libbeat. Ces Beats prennent en charge l’envoi de données vers Elasticsearch, Kafka, Redis ou Logstash via le protocole Lumberjack.
• L’Elastic Agent est un agent unifié capable de collecter des logs, des métriques et des traces. Cet agent peut être géré de façon centralisée via Elastic Fleet Server et prend en charge l’envoi vers Elasticsearch, Logstash, Kafka ou Redis.
• Elastic propose également une distribution de l’OpenTelemetry Collector - EDOT. Bien qu’elle ne puisse pas encore être orchestrée par Fleet Server, elle offre une voie plus souple et plus ouverte si vous migrez vers ClickStack.

Le meilleur parcours de migration dépend des agents actuellement utilisés. Dans les sections qui suivent, nous présentons les options de migration pour chaque grand type d’agent. Notre objectif est de limiter au maximum les frictions et, lorsque c’est possible, de vous permettre de continuer à utiliser vos agents existants pendant la transition.

​

Parcours de migration recommandé

Dans la mesure du possible, nous recommandons de migrer vers l’OpenTelemetry (OTel) Collector pour toute la collecte des logs, métriques et traces, en déployant le collecteur en périphérie dans un rôle d’agent. C’est le moyen le plus efficace d’envoyer des données, tout en évitant la complexité architecturale et les transformations de données.

Pourquoi OpenTelemetry Collector ?

L’OpenTelemetry Collector offre une solution durable et indépendante des fournisseurs pour l’ingestion des données d’observabilité. Nous savons que certaines organisations exploitent des flottes de milliers, voire de dizaines de milliers, d’agents Elastic. Pour ces utilisateurs, il peut être essentiel de préserver la compatibilité avec l’infrastructure d’agents existante. Cette documentation est conçue pour répondre à ce besoin, tout en aidant les équipes à passer progressivement à une collecte basée sur OpenTelemetry.

​

Point de terminaison OpenTelemetry de ClickHouse

Toutes les données sont ingérées dans ClickStack via une instance de collecteur OpenTelemetry (OTel), qui sert de point d’entrée principal pour les logs, les métriques, les traces et les données de session. Nous recommandons d’utiliser pour cette instance la distribution ClickStack officielle du collecteur, si elle n’est pas déjà incluse dans votre déploiement ClickStack.

Les utilisateurs envoient les données à ce collecteur depuis des language SDKs ou via des agents de collecte qui récupèrent les métriques d’infrastructure et les logs (comme des OTel collecteurs jouant un rôle d’agent, ou d’autres technologies, par ex. Fluentd ou Vector). Pour les équipes qui souhaitent un pipeline OpenTelemetry géré, Bindplane propose une solution native OpenTelemetry avec une destination ClickStack native, ce qui simplifie la collecte, le traitement et le routage de la télémétrie.

Nous partons du principe que ce collecteur est disponible pour toutes les étapes de migration des agents.

​

Migration depuis Beats

Les utilisateurs disposant de déploiements Beats importants peuvent souhaiter les conserver lors de leur migration vers ClickStack.

À ce jour, cette option n’a été testée qu’avec Filebeat et ne convient donc qu’aux logs.

Les agents Beats utilisent le Elastic Common Schema (ECS), actuellement en cours d’intégration dans la spécification OpenTelemetry utilisée par ClickStack. Cependant, ces schémas diffèrent encore de manière significative, et les utilisateurs doivent pour l’instant transformer les événements au format ECS en format OpenTelemetry avant leur ingestion dans ClickStack.

Nous recommandons d’effectuer cette transformation à l’aide de Vector, un pipeline de données d’observabilité léger et très performant, qui prend en charge un puissant langage de transformation appelé Vector Remap Language (VRL).

Si vos agents Filebeat sont configurés pour envoyer des données à Kafka — une sortie prise en charge par Beats — Vector peut consommer ces événements depuis Kafka, appliquer des transformations de schéma avec VRL, puis les transmettre via OTLP à l’OpenTelemetry Collector distribué avec ClickStack.

Vector prend également en charge la réception d’événements via le protocole Lumberjack utilisé par Logstash. Les agents Beats peuvent ainsi envoyer directement les données à Vector, où le même processus de transformation peut être appliqué avant leur transfert vers le ClickStack OpenTelemetry collecteur via OTLP.

Nous illustrons ces deux architectures ci-dessous.

Dans l’exemple suivant, nous présentons les premières étapes de configuration de Vector pour recevoir des événements de logs depuis Filebeat via le protocole Lumberjack. Nous fournissons du VRL pour faire correspondre les événements ECS entrants à la spécification OTel, avant de les envoyer au ClickStack OpenTelemetry collecteur via OTLP. Les utilisateurs qui consomment des événements depuis Kafka peuvent remplacer la source Logstash de Vector par la source Kafka — toutes les autres étapes restent identiques.

1. ​

   Installer Vector

   Installez Vector à l’aide du guide d’installation officiel.

   Vous pouvez l’installer sur la même instance que votre OTel collector Elastic Stack.

   Vous pouvez suivre les bonnes pratiques en matière d’architecture et de sécurité lors du passage de Vector en production.

2. ​

   Configurer vector

   Vector doit être configuré pour recevoir des événements via le protocole Lumberjack, en imitant une instance Logstash. Pour ce faire, configurez une source logstash pour Vector :

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Set to true if you're using TLS
         # The files below are generated from the steps at https://www.elastic.co/docs/reference/fleet/secure-logstash-connections#generate-logstash-certs
         # crt_file: logstash.crt
         # key_file: logstash.key
         # ca_file: ca.crt
         # verify_certificate: true
   

   Configuration TLS

   Si le TLS mutuel est requis, générez des certificats et des clés à l’aide du guide Elastic “Configurer SSL/TLS pour la sortie Logstash”. Vous pouvez ensuite les indiquer dans la configuration, comme illustré ci-dessus.

   Les événements seront reçus au format ECS. Ils peuvent être convertis vers le schéma OpenTelemetry à l’aide d’un transformateur Vector Remap Language (VRL). La configuration de ce transformateur est simple — le script étant conservé dans un fichier séparé :

   transforms:
     remap_filebeat:
       inputs: ["beats"]
       type: "remap"
       file: 'beat_to_otel.vrl'
   

   Notez qu’il reçoit des événements de la source beats ci-dessus. Notre script de remappage est présenté ci-dessous. Ce script a été testé uniquement avec des événements de logs, mais peut servir de base pour d’autres formats.

   VRL - d’ECS vers OTel

   # Define keys to ignore at root level
   ignored_keys = ["@metadata"]
   
   # Define resource key prefixes
   resource_keys = ["host", "cloud", "agent", "service"]
   
   # Create separate objects for resource and log record fields
   resource_obj = {}
   log_record_obj = {}
   
   # Copy all non-ignored root keys to appropriate objects
   root_keys = keys(.)
   for_each(root_keys) -> |_index, key| {
       if !includes(ignored_keys, key) {
           val, err = get(., [key])
           if err == null {
               # Check if this is a resource field
               is_resource = false
               if includes(resource_keys, key) {
                   is_resource = true
               }
   
               # Add to appropriate object
               if is_resource {
                   resource_obj = set(resource_obj, [key], val) ?? resource_obj
               } else {
                   log_record_obj = set(log_record_obj, [key], val) ?? log_record_obj
               }
           }
       }
   }
   
   # Flatten both objects separately
   flattened_resources = flatten(resource_obj, separator: ".")
   flattened_logs = flatten(log_record_obj, separator: ".")
   
   # Process resource attributes
   resource_attributes = []
   resource_keys_list = keys(flattened_resources)
   for_each(resource_keys_list) -> |_index, field_key| {
       field_value, err = get(flattened_resources, [field_key])
       if err == null && field_value != null {
           attribute, err = {
               "key": field_key,
               "value": {
                   "stringValue": to_string(field_value)
               }
           }
           if (err == null) {
               resource_attributes = push(resource_attributes, attribute)
           }
       }
   }
   
   # Process log record attributes
   log_attributes = []
   log_keys_list = keys(flattened_logs)
   for_each(log_keys_list) -> |_index, field_key| {
       field_value, err = get(flattened_logs, [field_key])
       if err == null && field_value != null {
           attribute, err = {
               "key": field_key,
               "value": {
                   "stringValue": to_string(field_value)
               }
           }
           if (err == null) {
               log_attributes = push(log_attributes, attribute)
           }
       }
   }
   
   # Get timestamp for timeUnixNano (convert to nanoseconds)
   timestamp_nano = if exists(.@timestamp) {
       to_unix_timestamp!(parse_timestamp!(.@timestamp, format: "%Y-%m-%dT%H:%M:%S%.3fZ"), unit: "nanoseconds")
   } else {
       to_unix_timestamp(now(), unit: "nanoseconds")
   }
   
   # Get message/body field
   body_value = if exists(.message) {
       to_string!(.message)
   } else if exists(.body) {
       to_string!(.body)
   } else {
       ""
   }
   
   # Create the OpenTelemetry structure
   . = {
       "resourceLogs": [
           {
               "resource": {
                   "attributes": resource_attributes
               },
               "scopeLogs": [
                   {
                       "scope": {},
                       "logRecords": [
                           {
                               "timeUnixNano": to_string(timestamp_nano),
                               "severityNumber": 9,
                               "severityText": "info",
                               "body": {
                                   "stringValue": body_value
                               },
                               "attributes": log_attributes
                           }
                       ]
                   }
               ]
           }
       ]
   }
   

   Enfin, les événements transformés peuvent être envoyés à ClickStack via l’OpenTelemetry Collector en utilisant OTLP. Pour cela, il est nécessaire de configurer un sink OTLP dans Vector, qui prend en entrée les événements issus de la transformation remap_filebeat :

   sinks:
     otlp:
       type: opentelemetry
       inputs: [remap_filebeat] # receives events from a remap transform - see below
       protocol:
         type: http  # Use "grpc" for port 4317
         uri: http://localhost:4318/v1/logs # logs endpoint for the OTel collector 
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
           authorization: ${YOUR_INGESTION_API_KEY}
   

   La YOUR_INGESTION_API_KEY est générée par ClickStack. Vous pouvez retrouver la clé dans l’interface ClickStack (HyperDX) sous Team Settings → API Keys.

   La configuration complète finale est présentée ci-dessous :

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: false  # Set to true if you're using TLS
           #crt_file: /data/elasticsearch-9.0.1/logstash/logstash.crt
           #key_file: /data/elasticsearch-9.0.1/logstash/logstash.key
           #ca_file: /data/elasticsearch-9.0.1/ca/ca.crt
           #verify_certificate: true
   
   transforms:
     remap_filebeat:
       inputs: ["beats"]
       type: "remap"
       file: 'beat_to_otel.vrl'
   
   sinks:
     otlp:
       type: opentelemetry
       inputs: [remap_filebeat]
       protocol:
         type: http  # Use "grpc" for port 4317
         uri: http://localhost:4318/v1/logs
         method: post
         encoding:
           codec: json
         framing:
           method: newline_delimited
         headers:
           content-type: application/json
   
3. ​

   Configurer Filebeat

   Il suffit de modifier les installations Filebeat existantes pour qu’elles envoient leurs événements à Vector. Cela nécessite de configurer une sortie Logstash — là encore, TLS peut aussi être configuré de façon facultative :

   # ------------------------------ Logstash Output -------------------------------
   output.logstash:
     # The Logstash hosts
     hosts: ["localhost:5044"]
   
     # Optional SSL. By default is off.
     # List of root certificates for HTTPS server verifications
     #ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
   
     # Certificate for SSL client authentication
     #ssl.certificate: "/etc/pki/client/cert.pem"
   
     # Client Certificate Key
     #ssl.key: "/etc/pki/client/cert.key"
   

​

Migrer depuis Elastic Agent

Elastic Agent regroupe les différents Elastic Beats dans un seul paquet. Cet agent s’intègre à Elastic Fleet, ce qui permet de l’orchestrer et de le configurer de façon centralisée.

Les utilisateurs ayant déployé des Elastic Agents disposent de plusieurs options de migration :

• Configurez l’agent pour envoyer les données vers un endpoint Vector via le protocole Lumberjack. À ce jour, cette option n’a été testée que pour les utilisateurs qui collectent uniquement des logs avec Elastic Agent. Cela peut être configuré de manière centralisée via l’interface Fleet dans Kibana.
• Exécutez l’agent comme Elastic OpenTelemetry Collector (EDOT). Elastic Agent inclut un collecteur EDOT intégré qui vous permet d’instrumenter vos applications et votre infrastructure une seule fois, puis d’envoyer les données à plusieurs fournisseurs et backends. Dans cette configuration, vous pouvez simplement configurer le collecteur EDOT pour transférer les événements vers le ClickStack OTel collecteur via OTLP. Cette approche prend en charge tous les types d’événements.

Nous présentons ces deux options ci-dessous.

​

Envoi de données via Vector

1. ​

   Installer et configurer Vector

   Installez et configurez Vector en suivant les mêmes étapes que celles décrites pour la migration depuis Filebeat.

2. ​

   Configurer Elastic Agent

   Elastic Agent doit être configuré pour envoyer les données via le protocole Lumberjack de Logstash. Il s’agit d’un modèle de déploiement pris en charge, qui peut être configuré de manière centralisée ou via le fichier de configuration de l’agent elastic-agent.yaml si vous effectuez le déploiement sans Fleet.

   La configuration centralisée via Kibana peut se faire en ajoutant un Output à Fleet.

   Cet output peut ensuite être utilisé dans une stratégie d’agent. Ainsi, tous les agents qui utilisent cette stratégie enverront automatiquement leurs données à Vector.

   Comme cela nécessite de configurer une communication sécurisée via TLS, nous recommandons le guide “Configurer SSL/TLS pour la sortie Logstash”, que vous pouvez suivre en considérant que votre instance Vector joue le rôle de Logstash.

   Notez que cela impose également de configurer la source Logstash dans Vector avec le TLS mutuel. Utilisez les clés et certificats générés dans le guide pour configurer correctement l’entrée.

   sources:
     beats:
       type: logstash
       address: 0.0.0.0:5044
       tls:
         enabled: true  # Définissez sur true si vous utilisez TLS. 
         # Les fichiers ci-dessous sont générés à partir des étapes sur https://www.elastic.co/docs/reference/fleet/secure-logstash-connections#generate-logstash-certs
         crt_file: logstash.crt
         key_file: logstash.key
         ca_file: ca.crt
         verify_certificate: true
   

​

Exécuter Elastic Agent comme collecteur OpenTelemetry

Elastic Agent inclut un EDOT Collector intégré qui vous permet d’instrumenter vos applications et votre infrastructure une seule fois, puis d’envoyer les données à plusieurs fournisseurs et backends.

Intégrations et orchestration de l’agent

Les utilisateurs qui exécutent le collecteur EDOT distribué avec Elastic Agent ne pourront pas tirer parti des intégrations existantes proposées par l’agent. De plus, le collecteur ne peut pas être géré de manière centralisée par Fleet, ce qui oblige l’utilisateur à exécuter l’agent en mode standalone et à gérer lui-même la configuration.

Pour exécuter Elastic Agent avec le collecteur EDOT, consultez le guide officiel d’Elastic. Au lieu de configurer l’endpoint Elastic, comme indiqué dans le guide, supprimez les exporters existants et configurez la sortie OTLP pour envoyer les données au ClickStack OpenTelemetry collecteur. Par exemple, la configuration des exporters devient :

exporters:
  # Exporter to send logs and metrics to Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: true

Managed ClickStack

Par défaut, une clé d’ingestion API n’est pas requise si vous exécutez un OpenTelemetry Collector en mode standalone pour Managed ClickStack. L’ingestion peut toutefois être sécurisée en spécifiant un jeton d’authentification OTLP. Voir “Sécuriser le collecteur”.

La clé YOUR_INGESTION_API_KEY indiquée ici est générée par ClickStack. Vous pouvez la trouver dans la ClickStack UI, sous Team Settings → API Keys.

Si Vector a été configuré pour utiliser le TLS mutuel, avec le certificat et les clés générés en suivant les étapes du guide “Configurer SSL/TLS pour la sortie Logstash”, l’exporter otlp devra être configuré en conséquence, par exemple.

exporters:
  # Exporter to send logs and metrics to Elasticsearch Managed OTLP Input
  otlp:
    endpoint: localhost:4317
    headers:
      authorization: ${YOUR_INGESTION_API_KEY}
    tls:
      insecure: false
      ca_file: /path/to/ca.crt
      cert_file: /path/to/client.crt
      key_file: /path/to/client.key

​

Migrer depuis le collecteur OpenTelemetry Elastic

Les utilisateurs qui exécutent déjà l’Elastic OpenTelemetry Collector (EDOT) peuvent simplement reconfigurer leurs agents pour envoyer leurs données au ClickStack OpenTelemetry collecteur via OTLP. Les étapes à suivre sont identiques à celles décrites ci-dessus pour exécuter l’Elastic Agent comme collecteur OpenTelemetry. Cette approche peut être utilisée pour tous les types de données.