ELIAS

ELIAS est le service « Elasticsearch à la demande » du CC-IN2P3. C’est une plateforme intégrant une base de données orientée document (Elasticsearch) agrémentée d’outils de visualisation. Elasticsearch vous permettra d’optimiser vos recherches textuelles grâce à son moteur d’indexation basé sur Apache Lucene. Les outils de visualisations mis à disposition vous offriront une nouvelle dimension à l’analyse de vos données. Les données ingérées dans ELIAS sont immédiatement exploitables sous la forme de tableaux de bord. ELIAS offre différents moyens pour interagir avec vos données, aussi bien graphique (Kibana/Grafana) que par programmation (API REST).

alternate text
Tous les services inclus dans ELIAS s’appuient sur un système d’authentification centralisé et supportent plusieurs méthodes :

  • Mot de passe

  • Certificat client

  • Kerberos

  • Keycloak

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

  • Un cluster partagé pour les demandes ne déclarant pas de spécifités particulières.

  • Un cluster dédié adapté à votre usage.

Si vous pensez qu’un cluster dédié est plus adapté à votre utilisation, merci de bien vouloir décrire dans votre demande de ressource votre contexte ainsi que la raison pour laquelle un cluster dédié serait plus appropriée. Notez que l’URL d’accès à votre cluster ELIAS sera sous la forme elias-${CLUSTERNAME.cc.in2p3.fr.

Pour utiliser la plateforme ELIAS, vous devrez soumettre une demande au support utilisateurs en précisant les informations demandées.

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

Les services inclus dans ELIAS

API REST

API REST (Representational State Transfer Application Program Interface) est une interface qui principalement facilite les échanges entre applications. Dans le cas de ELIAS, l’API s’appuie sur le protocol HTTP avec un format d’échange en JSON. En tant que client de l’API, vous utiliserez les appels HTTP (GET, POST, PUT, etc.) pour interagir avec vos données. Pour accéder à l’API REST vous devrez vous authentifier par l’une des méthodes suivantes :

Certificat client

L’authentification par certificat est celle que nous recommandons pour l’utilisation automatisée (sans surveillance). Voir Procédure d’accès par certificat.

Kerberos

L’authentification par Kerberos (SPNEGO) est celle que nous recommandons pour l’utilisation interactive (par un humain). Pour accéder à ELIAS par Kerberos, vous devrez au préalable disposer d’un compte calcul.

Login / Mot de passe

L’authentification par login / mot de passe est déconseillée et ne doit être utilisée qu’en cas d’absence de support des autres types d’authentification par le client utilisé.

Pour interagir avec vos données via l’API REST, vous pouvez consulter les sections suivantes :

Kibana

Kibana est une interface graphique bien adaptée à l’analyse de données textuelles (par exemple l’analyse de « logs »). Vous pouvez construire des graphes sur la base d’une recherche textuelle pour constituer votre propre tableau de bord, qui regroupera ainsi un ensemble de graphes autour d’un sujet bien déterminé. Pour accéder à l’outil de visualisation Kibana vous devez disposer d’un compte calcul.

Grafana

Grafana est une interface graphique bien adaptée à l’analyse de données numériques en séries temporelles (« time series »). Au même titre que Kibana Grafana utilise la notion de dashboard pour agencer un ensemble de métriques sur une même page. Pour accéder à l’outil de visualisation Grafana vous devez disposer d’un compte calcul.

Accéder à la plateforme ELIAS

Pour accéder aux différents services ELIAS, vous devrez soumettre une demande au support utilisateurs. Un espace ELIAS vous sera alloué et celui-ci sera accessible par un ou plusieurs comptes utilisateurs. Nous pouvons également créer des comptes « robot » pour vos tâches automatisées. Ceux-si seront identifiés soit par un certificat client, soit (quand nécessaire) par login/mot de passe. Une bonne pratique est d’associer un compte robot par machine cliente quand cela est possible. Un compte (utilisateur ou robot) est associé à une ou plusieurs méthodes d’authentification et dispose d’un ensemble de privilèges. Pour des raisons de sécurité, nous recommandons l’utilisation de comptes specifiques pour toute machine exterieure au CC-IN2P3.

Accéder à ELIAS par certificat client

Les certificats permettent de vous authentifier et de sécuriser les échanges entre le client et le serveur. Cette méthode est à privilégier pour les interactions automatisées (mode robot) avec Elasticsearch telles que :

  • Tâche planifiée (cron)

  • Job dans la ferme de calcul

  • Importation de données (DAQ)

La plateforme ELIAS dispose de sa propre autorité de certification par conséquent il vous faudra télécharger la CA-ELIAS et l’importer dans votre système d’exploitation, votre navigateur ou votre application.

Pour demander votre accès par certificat, merci de suivre la procédure en fonction du système d’exploitation utilisé. La procédure est à appliquer sur la machine cible, c’est à dire la machine qui utilisera le certificat. Elle ne doit pas être appliquée sur une autre machine.

  • Générer une clé privée rsa

    % openssl genrsa -out myelias.key 2048

  • Générer le CSR (Certificate Signing Request) :

    % openssl req -new -key ${ROBOT}.key -out ${ROBOT}.csr

You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:FR
State or Province Name (full name) [Some-State]:RHONE
Locality Name (eg, city) []:Lyon
Organization Name (eg, company) [Internet Widgits Pty Ltd]:CNRS
Organizational Unit Name (eg, section) []:CC-IN2P3
Common Name (e.g. server FQDN or YOUR name) []: ***myELIASACCOUNT***
Email Address []:
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

    Attention

    Pour des raisons d’uniformisation, nous recommandons de respecter les règles suivantes pour la clé Common Name :

    ***myELIASACCOUNT*** = namespace + machine + application name

    Si vous souhaitez utiliser votre certificat pour plusieurs machines utilisez le pattern suivant :

    ***myELIASACCOUNT*** = namespace + application name

    Pour les autres champs Organization, Organizational Unit ceux-ci sont optionnels et peuvent être personnalisées sans contrainte.

  • Envoyez le fichier avec l’extension .req à eliasmaster@cc.in2p3.fr .

    Attention

    N’envoyez en aucun cas la clé ${ROBOT}.key par mail. La clé ne doit jamais transiter par le réseau et rester uniquement sur la machine sur laquelle elle a été générée.

  • Votre certificat signé par la CA vous sera ensuite envoyé par mail.

Accéder à ELIAS par mot de passe

L’accès par login et mot de passe est possible mais il est fortement recommandé d’éviter ce type d’authentification pour des raisons de sécurité. Pour le login, nous vous recommandons de suivre le pattern suivant :

login = namespace + application name

Accéder à ELIAS par Kerberos

Cette méthode est à privilégier pour l’utilisation interactive. Exemples d’utilisation:

Pour bénéficier d’une authentification par Kerberos, il vous suffit de disposer d’un compte calcul. une fois votre compte est disponible, vous pourrez obtenir votre ticket Kerberos de la manière suivante :

% kinit username@CC.IN2P3.FR

Cette étape n’est pas nécessaire si vous avez effectué une connexion au CC-IN2P3.

Pour vérifier que vous avez bien un ticket kerberos:

% 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

La version de curl sur Centos-7 étant à un niveau insuffisant, il faut utiliser la commande suivante:

% ccenv curl

Si vous utilisez une version de curl plus récente, par exemple celle installée sur Rocky-8, l’étape ccenv n’est pas nécessaire.

Puis tentez une requête simple:

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

À présent la liste des tickets 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.

Accéder à ELIAS par Keycloak

Cette méthode est à privilégier pour l’accès aux interfaces de visualisation Kibana / Grafana et repose sur le système d’authentification du CC-IN2P3. Pour bénéficier de cette méthode d’authentification, il vous suffit de disposer d’un compte calcul.

Ingéstion des données dans ELIAS

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 les librairies haut-niveau dont certaines sont maintenues par elastic.co. Elle peut aussi être utilisée via les commandes curl, wget, httpie, etc.

Pour stocker vos données dans ELIAS, 3 approches sont possibles :

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

  • Agent dédié (Fluentbit, logstash, syslog-ng etc.)

  • Votre propre programme utilisant les librairies haut-niveau

Débuter avec la commande curl

Si vous disposez de la commande curl sur votre machine, utilisez les options suivantes pour indiquer la méthode d’authentification :

  • par certificat

    % curl --key /path/to/mycertificate.pkey --cert /path/to/mycertificate.crt --cacert /path/to/elias.ca -H 'Content-Type: application/json' ...

  • par mot de passe

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

  • par kerberos

    % kinit

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

Elasticsearch stocke les données dans un index que l’on peut comparer à une table dans les bases de données relationnelles. La commande suivante se connecte via un certficat à ELIAS 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-indexname. Vous pouvez créer autant d’indices que vous le souhaitez sous votre espace ELIAS : namespace-index1, namespace-index2,…

Le nom du namespace est imposé par les administrateurs ELIAS 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. Elasticsearch, comme la plupart des solutions NoSQL, est sans schéma (« schemaless »). C’est à dire que les documents indexés ne doivent pas nécessairement respecter un schéma donné. Par conséquent, il est possible de stocker des documents avec des structures de données complètements hétérogènes (sous certaines conditions). En d’autres termes, un même index peut contenir simultanément des documents décrivant une personne, une galaxie et des fruits et légumes.

En réalité, Elasticsearch construit le schéma au fur et à mesure que les documents arrivent, c’est ce que l’on appelle le « mapping dynamique ». Toutefois, il est possible d’imposer une structure de données explicite en configurant le mapping

L’exemple ci-dessous associe une structure minimale (create_p4_schema_payload.json) que les documents de l’index namespace-indexname 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.

Pour optimiser les recherches sur vos indices, Elasticsearch peut analyser les valeurs des clés de vos documents en les découpant par mot. C’est le cas pour le mapping de type « text » (contrairement par exemple au mapping « keyword »).

Elasticsearch y parvient en construisant un dictionnaire associant à chaque mot la liste des documents contenant ce mot. (« inverted index »). La stratégie de l”analyseur est configurable et peut inclure des sémantiques relatives à un domaine ou une langue.

Pour insérer des données dans l’index mynamespace-myindexname, l’API REST fournit un ensemble complet de fonctionnalités :

https://www.elastic.co/guide/en/elasticsearch/reference/8.2/docs.html

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'

Dans le cas d’une recherche avançée, veulliez vour référer au paragraphe Consulter les donnnées.

Débuter avec un Agent

Un agent est un programme dont l’objectif est de collecter de l’information à partir de différentes sources d’information et de rediriger le flux d’information vers une destination de votre choix.

La configuration des différentes sources de données et la destination seront à configurer au niveau de l’agent après son installation.

Exemple d’utilisation de l’agent Fluentd :

alternate text

Les agents intègrent nativement un ensemble de fonctionnalités pour le traitement de vos sources de données les plus connues.

Quant à la redirection du flux d’information, il vous suffira de préciser comme destination ELIAS.

Pour les agents, il existe une multitude d’agents propriétaires et opensource. A titre d’information, plusieurs solutions opensource comme Fluentd, Fluentbit, Syslog-ng, collectd, Riemann où propriétaires comme Elasticbeat sont disponibles.

Le support des agents n’est pas fourni par les administrateurs de ELIAS. Sachez cependant que le CC-IN2P3 utilise Riemann et Syslog-ng. Toutefois, pour une mise en place facile et rapide nous vous conseillons de regarder Fluentbit.

Débuter avec un programme

Si vous avez développé votre propre application ou que vous avez des besoins spécifiques qui ne peuvent être comblés avec un agent, vous avez la possibilité de vous interfacer avec ELIAS soit en utilisant une librairie haut-niveau propre à votre langage (recommandé), soit directement via l’API RESTful. Vous pouvez trouver une liste non-exhaustive de librairies à l’adresse suivante

https://www.elastic.co/guide/en/elasticsearch/client/community/current/index.html

L’exemple ci-dessous illustre un programme python qui se connecte à ELIAS par certificat et interagit avec la plateforme. Veillez à utiliser un environnement virtuel afin de sauvegarder le python de votre système.

  • Prérequis

    Configuration de l’environnement python
    % conda create --name elias python=3.9

    % conda activate elias
    Installation de la librairie officielle Elasticsearch
    % pip install elasticsearch==7.10 certifi

  • Utiliser la librairie certifi pour localiser l’emplacement des CA autorisées pour python

    >>> import certifi
>>> certifi.where()
'/Users/xxxxxx/miniconda3/lib/python3.7/site-packages/certifi/cacert.pem'

  • Charger la CA ELIAS dans le fichier cacert.pem

    % cat elias.ca >> /Users/moi/miniconda3/lib/python3.7/site-packages/certifi/cacert.pem

  • Vous pouvez à présent vous authentifier par certificat avec python.

Vous trouverez ci-dessous quelques instructions pour vos débuts avec ELIAS :

#!/usr/bin/env python3
from elasticsearch import Elasticsearch
from datetime import datetime
import certifi

es = Elasticsearch('https://elias-${CLUSTERNAME}.cc.in2p3.fr:9200', timeout=120, use_ssl=True, verify_certs=True, client_cert='/Users/moi/elias/mynamespace-myhost-myuser.crt',ca_certs=certifi.where(),client_key='/Users/moi/elias/mynamespace-myhost-myuser.pkey')

## Permet d'afficher l'état du cluster
es.cluster.health()

## Création d'un index repectant la nomenclature namespace-indexname
es.indices.create(index='mynamespace-myindexname')

## Vérification du mapping de l'index
## L'index dispose d'un mapping dynamique,
## Le moteur d'Elasticsearch décrit la structure des documents au fur et à mesure de leur insertion

current_mapping = es.indices.get_mapping('mynamespace-myindexname')
print(current_mapping)


## Insertion d'un document dans un index

mydoc1 = {
    'message': 'ERROR : This message contains some data about my application ',
    'IP': "192.168.56.152",
    'client': "java"
}

mydoc2 = {
    'message': 'CRITICAL : This message is a warning from my application ',
    'IP': "192.168.56.201",
    'client': "python"
}

myindexeddoc = es.index(index="mynamespace-myindexname",id="2022-08-09 16:39:11.052116",body=mydoc1)
myindexeddoc = es.index(index="mynamespace-myindexname",id="2022-08-10 17:49:11.058455",body=mydoc2)


## Le mapping est automatiquement mis à jour

current_mapping = es.indices.get_mapping('mynamespace-myindexname')
print(current_mapping)

## lister l'ensemble de vos indices dans votre namespace

indices_dict = es.indices.get_alias("mynamespace-*")
for index_name, value in indices_dict.items():
    print ('index: ', index_name)


## Rechercher un document par son identifiant

print(es.get(index="mynamespace-myindexname", id="2022-08-09 16:39:11.052116"))

## Rechercher un document avec des conditions

research = {
  "query": {
    "term": {
      "message": "application"
    }
  }
}

resp = es.search(body=research ,index="mynamespace-myindexname")
print(resp)

## Limiter la projection des données

resp = es.search(body=research ,index="mynamespace-myindexname",filter_path=['hits.hits._id', 'hits.hits._source.message'])


## Supprimer un index

es.indices.delete(index="mynamespace-myindexname")

Consulter vos données

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

  • Une API REST pour une interopérabilité avec vos applications

  • Des interfaces graphiques pour une visualisation graphique de vos données

Consulter les donnnées avec l’API REST

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.

Exemple d’une recherche exacte : recherche les documents contenant obligatoirement le mot 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" }}
      ]
    }
  }
}

Exemple d’une recherche floue : recherche les documents contenant obligatoirement le mot application et contains et potentiellement le mot warning.

% 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" }}
      ],
      "should": [
          { "match": { "message": "warning" }}
      ]
    }
  }
}

Pour effectuer une recherche textuelle, Elasticsearch s’appuie sur un analyseur dont l’objectif est de construire la cartographie des mots pour l’ensemble des documents contenus dans un index. Cela concerne les clés dont le mapping est « text ». Chaque valeur de clé dans vos documents est découpée en mot (tokenizer) et ensuite filtrée éventuellement traitée (analyseur), par exemple pour tenir compte des spécificités de la langue, comme la grammaire. Vos conditions de recherche seront donc appliquées sur le dictionnaire obtenu en sortie de l’analyse. 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. Il est basé notamment sur le langage de requête Apache Lucene. Pour plus de détail sur ce langage consulter la documentation Elasticsearch-dsl.

Pour illustrer des recherches avancées, le site suivant propose des exemples d’application :

https://coralogix.com/blog/42-elasticsearch-query-examples-hands-on-tutorial/

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.

Consulter les données avec Kibana

Kibana est une interface graphique pour l’analyse de données textuelles. Kibana sera très bien adapté pour rechercher dans vos journaux applicatifs les messages contenant un ou plusieurs mots en particulier. Bien qu’il soit possible de construire des visualisations avec des requêtes json complexes, il permet de générer des requêtes graphiques et des filtres.

alternate text

Consulter les données avec Grafana

Grafana est une interface graphique avec une prédisposition pour les données numériques temporelles (timeseries). Grafana est souvent utilisé pour la surveillance des performances applicatives, des systèmes et matérielles. Il dispose d’une capacité limitée mais croissante d’interrogation et d’affichage des logs.

alternate text

Les tableaux de bord

La représentation de vos données sous forme graphique dépend essentiellement des questions auquelles vous souhaitez répondre. Regroupez toutes vos questions dans un tableau de bord thématique.

Grafana vous propose des modèles (template) de dashboards de performance pour la supervision d’applications connues comme nginx, redis et bien d’autres :

https://Grafana.com/Grafana/dashboards/

Pour Kibana, un guide est proposé par la société elastic.co sur la mise en place d’un dashboard :

https://www.elastic.co/guide/en/kibana/current/dashboard.html

Accès à Kibana ou Grafana

Kibana et Grafana sont configurés avec le système d’authentification interne du CC. Pour accéder à ces outils, vous devrez au préalable disposer d’un compte calcul.

L’URL pour l’accès à Kibana :

https://elias-${CLUSTERNAME}.cc.in2p3.fr/

L’URL pour l’accès à Grafana :

https://elias-${CLUSTERNAME}.cc.in2p3.fr:4443/login

C’est à partir de votre compte calcul que vous pourrez consulter vos données dans ELIAS.