ELIAS

ELIAS est le service Elasticsearch du CC-IN2P3. Il vous permettra d’optimiser vos recherches textuelles via Elasticsearch et de les visualiser sous la forme de graphiques organisés en tableaux de bord grâce aux outils Kibana et Grafana. De plus une API REST est disponible.

alternate text

Selon l’utilisation de la plateforme, nous proposons différents types d’hébergement :

  • un cluster générique partagé ;

  • un cluster dédié en cas de spécificités particulières.

Pour demander un accès, merci de contacter le support utilisateurs. En cas de besoin particulier, précisez-le dans votre demande (contexte, raison et demande de ressources) comme pour les demandes de base de données.

Un espace sur ELIAS (namespace) vous sera alors attitré avec la possibilité d’y associer un ou plusieurs comptes d’accès (humain ou robot).

Note

L’URL d’accès à votre cluster ELIAS sera sous la forme :

elias-${CLUSTERNAME}.cc.in2p3.fr

La variable $CLUSTERNAME dépend du cluster sur lequel est hébergé l’utilisateur. La valeur de cette variable sera indiquée à l’utilisateur avec ses identifiants.

Accéder à la plateforme

Tous les services inclus dans ELIAS s’appuient sur un système d’authentification centralisé et supportent plusieurs méthodes selon le type de comptes.

Types de comptes

Un compte (utilisateur ou robot) est associé à une ou plusieurs méthodes d’authentification et dispose d’un ensemble de privilèges.

Les comptes utilisateur seront identifiés par:

  • Kerberos ;

  • Keycloack ;

  • login / mot de passe.

Methodes d’accès

Cette méthode est à privilégier pour l’utilisation interactive, par exemple :

Pour bénéficier d’une authentification par Kerberos, il vous suffit de disposer d’un compte calcul, et de l’avoir correctement configuré.

Après une requête simple (par exemple un curl) :

% curl --negotiate -u: https://elias-elias-${CLUSTERNAME}.cc.in2p3.fr.cc.in2p3.fr:9200/

la liste des tickets Kerberos devrait ressembler à :

% klist
Ticket cache: FILE:/tmp/krb5cc_1234_RrLMgX8bak
Default principal: username@CC.IN2P3.FR

Valid starting       Expires              Service principal
05/12/2020 10:49:33  05/15/2020 09:07:56  krbtgt/CC.IN2P3.FR@CC.IN2P3.FR
05/12/2020 10:50:30  05/15/2020 09:07:56  HTTP/ccosvmse0007.in2p3.fr@
05/12/2020 10:50:30  05/15/2020 09:07:56  HTTP/ccosvmse0007.in2p3.fr@CC.IN2P3.FR

La machine apparaissant comme service principal HTTP/... correspond au point d’entrée au service ELIAS.

Les services inclus dans ELIAS

L’API REST est une interface qui permet les échanges de données entre services web. En tant que client de l’API, vous utiliserez les appels HTTP (GET, POST, PUT, …). Pour accéder à l’API REST, vous devrez vous authentifier par l’une des méthodes suivantes :

Pour plus d’informations, consultez les paragraphes suivantes :

Ingéstion des données

L’ingestion de vos données dans ELIAS est possible uniquement au travers de l’API REST.

L’API REST peut être exploitée par des librairies haut-niveau, dont certaines sont maintenues par elastic.co, ou via les commandes curl, wget, httpie, …

Pour stocker vos données, trois approches sont possibles :

  • commandes en ligne (curl) (pratique pour une première prise en main) ;

  • agent dédié (Fluentbit, logstash, syslog-ng, …) ;

  • votre propre script utilisant des librairies haut-niveau.

Vous pouvez utiliser les options suivantes pour indiquer la méthode d’authentification :

% kinit

% curl -u: --negotiate --cacert /path/to/elias.ca -H 'Content-Type: application/json' ...

Elasticsearch enregistre les données dans un index comparable à une table dans les bases de données relationnelle. La commande suivante se connecte via un certficat et crée un index nommé mynamespace-myindexname.

% curl -XPUT 'https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200/mynamespace-myindexname?pretty' --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert /path/to/elias.ca -H 'Content-Type: application/json'

Attention

Le nom des indices doit respecter la syntaxe suivante : <namespace>-<index>. Vous pouvez créer autant d’indices que vous le souhaitez sous votre espace ELIAS.

Le nom du namespace est imposé par les administrateurs et vous est communiqué lors de la création de votre compte.

Un index Elasticsearch manipule uniquement des documents JSON. Un document est une collection de tuples clé/valeur et c’est l’unité la plus petite que manipule Elasticsearch. Il est possible de stocker des documents avec des structures de données complètement hétérogènes (sous certaines conditions).

Elasticsearch construit le schéma au fur et à mesure que les documents arrivent. Toutefois, il est possible d’imposer une structure de données explicite en configurant le mapping.

L’exemple ci-dessous associe une structure minimale que les documents de l’index mynamespace-myindexname doivent respecter.

% curl -XPUT --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert  /path/to/elias.ca -H 'Content-type: application/json' -XPUT 'http://localhost:9200/test3/_mapping' -d
'{
      "dynamic_templates": [
        {
          "template_stdField": {
            "path_match": "*",
            "mapping": {
              "ignore_malformed": true,
              "type": "keyword"
            }
          }
        }
      ],
      "properties": {
        "user_name": {
          "type": "text"
        }
      }
  }'

La commande suivante définit un mapping explicite pour l’indexe mynamespace-myindexname.

% curl -XPUT --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert  /path/to/elias.ca -H 'Content-Type: application/json' 'https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200/mynamespace-myindexname/_mapping' -d @"my_mapping.json"
Contenu du fichier my_mapping.json
{
    "dynamic_templates": [
      { -
        "template_stdField": {
          "path_match": "*",
          "mapping": {
            "ignore_malformed": true,
            "type": "keyword"
          }
        }
      }
    ],
    "properties": {
      "user_name": {
        "type": "text"
      }
    }
}

Attention

Le mapping explicite peut rejeter les documents non-conformes avec l’option ignore-malformed.

Note

Pour plus d’informations sur le mapping veuillez vous référer à la documentation officielle.

La commande suivante se connecte à ELIAS par certificat et crée un premier document dans l’index kafka-testoal :

% curl -XPOST 'https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200/kafka-testoal/_doc/1/_create' --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert /path/to/elias.ca -H 'Content-Type: application/json' -d '{ "user_name" : "John Doe" }'

Pour consulter une partie des documents d’un index, on pourra utiliser la commande suivante :

% curl -XGET 'https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200/kafka-testoal//_search?pretty' --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert /path/to/elias.ca -H 'Content-Type: application/json'

Note

Dans le cas d’une recherche avancée, veuillez vous référer au paragraphe Consulter les donnnées.

Consulter vos données

Pour consulter vos données, ELIAS propose différentes interfaces selon vos besoins :

Avec Elasticsearch vous avez la possibilité d’effectuer des recherches exactes par l’intermédiaire de filtres ou des recherches dites floues dans le sens où les critères peuvent être complètement ou partiellement respectés.

Exemples :

recherche les documents contenant obligatoirement les mots application et contains.

% curl -GET --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert /path/to/elias.ca -H 'Content-Type: application/json' 'https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200/mynamespace-myindexname/_search' -d @"filter_query.json"
Contenu du fichier filter_query.json
{
  "query": {
    "bool": {
      "must": [
          { "match": { "message": "application" }},
          { "match": { "message": "contains" }}
      ]
    }
  }
}

Elasticsearch implémente un langage de requête connu sous le nom de Elasticsearch DSL (Domain Specific Language). Ce langage permet d’exprimer des requêtes avec des conditions complexes en utilisant des opérateurs logiques, de comparaison et ensembliste.

Note

L’algorithme de découpage et de filtrage dans Elasticsearch est personnalisable pour chaque clé. Il suffit pour cela de définir le mapping convenablement.

Superviser votre machine

Pour superviser vos machines, vous pouvez collecter différents métriques et des logs en utilisant respectivement :

  • Collectd, un outil permettant de collecter diverses métriques ;

  • Fluentbit, un outil léger de gestion des logs.

Les données peuvent ensuite être envoyées par FluentBit vers Elasticsearch afin de pouvoir les consulter comme le montre le schéma ci-dessous :

../../../_images/fluentbit.png

Attention

Vous êtes responsable des données que vous insérer dans Elasticsearch. Merci de vous assurer d’avoir défini le cycle de vie de vos données au préalable.

Il est également conseillé de créer plusieurs index. Par exemple dans le cas d’utilisation défini dans cette documentation il est nécessaire de créer des index Collectd et FluentBit.

Installation

La procédure d’installation dépend de votre système d’exploitation, aussi il faudra consulter la documentation d’installation de Collectd et choisir la méthode adapté.

Configuration

Pour notre exemple nous allons utiliser des plugins collectd installés par défaut au moment de l’installation.

Afin de déployer un plugin collectd, il faut crééer un fichier de configuration comme ceci dans /etc/collectd/plugins.

Pour utiliser le plugin memory par exemple, nous allons créer le fichier /etc/collectd/plugins/memory.conf avec le contenu suivant :

<Plugin "memory">
ValuesAbsolute true
ValuesPercentage true
</Plugin>

et le fichier de configuration pour le fichier network /etc/collectd/plugin/network.conf avec le contenu suivant :

<Plugin "network">
Server "127.0.0.1" "25826"
</Plugin>

Nous allons rediriger la sortie du plugin memory vers l’adresse localhost sur le port par défaut qui est le 25826.

Il faut ensuite vérifier que les lignes LoadPlugin memory et LoadPlugin network sont présentent dans le fichier /etc/collectd/collectd.conf.

Nous démarrons ensuite le service :

% sudo systemctl restart collectd.service

Pour vérifier que tous s’est bien passé nous pouvons consulter les logs avec la commande :

% journalctl -xe

Enfin pour tester que les données sont bien exposées sur le port choisi nous pouvons lancer la commande suivante :

% nc -ul 25826

Pour tester vos fichiers de configuration vous pouvez utiliser l’outil de visualisation Calyptia.

Exemple de configuration avec l’input tail qui fonctionne comme la commande tail -f pour lire la fin d’un fichier et un input qui va récupérer les données générées par collectd :

# Le champ service défini différents paramètres de FluentBit
[SERVICE]
    flush           1
    daemon          Off
    log_level       debug
    log_file        /var/log/fluent-bit.log
    parsers_file    parsers.conf
    plugins_file    plugins.conf
    http_server     Off
    http_listen     0.0.0.0
    http_port       2020
    storage.metrics on

# Le champ input défini les données en entré de FluentBit
[INPUT]
    Name        tail
    Tag         zeppelin.log
    Path        /path/to/my/logfile/zeppelin.log
    Parser       zeppelin

# Le champ filter permet de filtrer des données en utilisant divers modules comme ici modify qui permet d'ajouter le nom du service aux données
[FILTER]
    Name modify
    Match zeppelin.log
    Add service zeppelin

# Le champ output défini la destination des données
[OUTPUT]
    Name   stdout
    Match  *

[OUTPUT]
    Name  es
    Match *.log
    Host  elias-beta.cc.in2p3.fr
    Port  9200
    Index indexname
    tls On
    tls.verify Off
    tls.ca_file      /path/to/ca.crt
    tls.crt_file     /path/to/client.crt
    tls.key_file     /path/to/client.key

# La commande @INCLUDE permet d'inclure le contenu d'un fichier de configuration
@INCLUDE /etc/fluent-bit/collectd.conf