Elasticsearch

Installer & Configurer votre instance Flower

    Le connecteur Elasticsearch s’appuie sur la stack Elastic 5.2.1


    Cette documentation s’appuie sur la propriété ${F_HOME} définissant le répertoire dans lequel est stocké la configuration de FlowerDocs.

    Ce répertoire doit être défini par serveur d’application (au niveau de la JVM) grâce à la propriété flower.docs.config.dir. Il doit contenir le fichier de configuration flowerdocs.properties

    flowerdocs.properties

    L’ensemble des propriétés permettant de configurer les applications WEB doivent être ajoutées dans un fichier flowerdocs.properties situé dans le répertoire ${F_HOME}.
    Ce fichier est chargé au démarrage de la JVM, les modifications ne sont donc prises en compte qu’après redémarrage du serveur d’application.

    ws.url=http://<flower host>:<flower port>/<flower context path>/services
    file.dir=C:\\Flower\\Files\\	
    

    Installation Elasticsearch


    Se reporter à la documentation officielle pour des environnements de production.

    Cette partie décrit comment installer Elasticsearch afin de l’utiliser comme backend Flower.


    Afin d’installer Elasticsearch, il est nécessaire de :

    • Télécharger Elasticsearch à partir du site officiel

    • Extraire l’archive elasticsearch-5.2.1.zip dans un répertoire ${ES_HOME}


    Ensuite, pour configurer Elasticsearch, éditer le fichier ${ES_HOME}/config/elasticsearch.yml tel que :

    • Pour définir le nom du cluster Elasticsearch, dé-commenter la propriété cluster.name et modifier sa valeur par flower-es-dev
    • Dans le cas d’un cluster Elasticsearch, dé-commenter la propriété node.name et modifier sa valeur par celle de votre choix (ex: node-1)
    • Si plusieurs noeud Elasticsearch sont déployés sur la même machine, il est nécessaire de modifier la valeur de la propriété http.port
    • Ajouter la propriété action.auto_create_index: false
    • Pour accéder à Elasticsearch depuis un serveur distant, il est nécessaire de décommenter la propriété network.host et de définir une des valeurs suivantes :
      • 0.0.0.0
      • nom DNS
      • adresse IP


    Pour terminer, démarrer Elasticsearch en allant dans le dossier ${ES_HOME}/bin puis en exécutant le script elasticsearch ou elasticsearch.bat (selon le système d’exploitation)



    Pour vérifier son bon fonctionnement, aller sur la page http://localhost:9200/

    Installation Kibana


    Se reporter à la documentation officielle pour des environnements de production.

    Cette partie décrit comment installer Kibana afin de faire du reporting dans Flower.


    Afin d’installer Kibana, il est nécessaire de :

    • Télécharger Kibana à partir du site officiel

    • Extraire l’archive dans un répertoire ${KIBANA_HOME}


    Ensuite, pour configurer Kibana, éditer le fichier ${KIBANA_HOME}/config/kibana.yml tel que :

    • Dans le cas d’un Kibana sur un serveur différent d’Elasticsearch, dé-commenter la propriété elasticsearch.url et renseigner pour valeur l’url d’accès à Elasticsearch (par défaut http://localhost:9200)
    • Dé-commenter la propriété server.basePath et modifier sa valeur par /flower-docs-gui/plugins/reporting.


    Pour terminer, démarrer Kibana en allant dans le dossier ${KIBANA_HOME}/bin puis en exécutant le script kibana ou kibana.bat (selon le système d’exploitation)



    Pour vérifier son bon fonctionnement, aller sur la page http://localhost:5601/

    Configuration

    Afin de configurer l’accès de Flower à Elasticsearch et Kibana, modifier le fichier flowerdocs.properties en fonction des paramètres renseignés lors de l’installation :

    Propriété Valeur par défaut Description
    es.nodes localhost:9300 Adresses des différents noeuds Elasticsearch séparées par une ,
    es.cluster flower-es-dev Le nom du cluster Elasticsearch
    es.username Le nom de l’utilisateur (optionnel)
    es.password Le mot de passe de l’utilisateur (optionnel)
    es.conflict.version true Utilise la notion de version pour gérer les modifications concurrentes
    es.aggregation.max.size 100 Nombre de buckets maximum remontées par aggrégation
    kibana.url http://localhost:5601 URL d’accès à Kibana à partir du Core

    Téléchargement

    Télécharger les applications suivantes :

    Flower GUI
    Interface graphique (Version : 2.4.2.5)

    Flower Core
    Coeur de l'application exposant des web services (Version : 2.4.2.5)

    ARender HMI
    Interface graphique de la visionneuse (Version : 2.4.2.5)

    Notes de version
    Version : 2.4.2.5

    Déploiement

    Renommer les applications selon les nom suivants :

    • GUI : flower-docs-gui-webapp-2.4.2.5.war → gui.war
    • Core : flower-docs-core-webapp-2.4.2.5.war → core.war
    • ARender : flower-docs-arender-hmi-2.4.2.5.war → flower-docs-arender.war

    Copier les trois applications WEB renommées dans le répertoire ${TOMCAT_HOME}/webapps



    Pour configurer les applications déployées, il est nécessaire de suivre la procédure en fonction du connecteur concerné.

    Le connecteur Elasticsearch fournit deux types de stockage pour les contenus (ou fichiers) de document.

    Système de fichier

    Ce connecteur permet le stockage des fichiers sur un système de fichier vu comme local par la JVM (local, NFS…). Le répertoire utilisé peut être configuré :

    • Windows :

      file.dir=C:\\Flower\\Files\\
      
    • Linux :

      file.dir=/opt/Flower/Files/
      

    Amazon S3

    Avec le connecteur Amazon S3, les contenus de document sont stockés dans un bucket S3. Pour utiliser le connecteur Amazon S3 la configuration suivante est nécessaire :

    core.services.file.dao=s3
    s3.region=<region AWS>
    

    Paramétrage du client Amazon S3

    Paramètre Description Valeur par défaut
    s3.max.connections Le nombre maximum de connexions HTTP ouvertes 100
    s3.max.error.retry Le nombre maximum d’essai sur pour des requêtes pouvant être rejouées (erreur 5xx) 2
    s3.socket.timeout Le temps d’attente (en ms) pour que les données soient transférées 100000

    Par défaut, le fichier contenant la paire de clés d’accès et secrète doit se trouver dans le dossier $USER_HOME/.aws/credentials et le profil utilisé est default.

    L’utilisation d’un autre fichier de clés ou d’un autre profile est possible grâce aux paramètres suivants :

    s3.profile=<nom du profile>
    s3.configFilePath=<chemin du répertoire>/<fichier contenant les clés>
    

    L’utilisation des rôles de l’instance AWS est possible en ajoutant la propriété :

    s3.instanceProfile=true
    

    Un bucket unique peut être utilisé pour tous les scopes Flower avec la configuration suivante :

    s3.bucket.scoped=false
    s3.bucketName=<nom du bucket>
    

    La procédure de Backup & Restore décrite ci-dessous se base sur le mécanisme de snapshot d’Elasticsearch.

    Répertoire de sortie

    Pour définir le répertoire où les snapshots sont sauvegardés, ajouter dans le fichier ${ES_HOME}/config/elasticsearch.yml dans la partie “Paths” : path.repo: ["${HOME}/mount/backups", "${HOME}/mount/longterm_backups"]

    Puis redémarrer tous les noeuds d’Elasticsearch.

    Exécuter ensuite la commande :

    $ curl -XPUT 'http://localhost:9200/_snapshot/my_backup' -d '{
    	"type": "fs",
    	"settings": {
    		"location": "${HOME}/mount/backups/my_backup",
    		"compress": true
    	}
    }'
    

    Ou exécuter la commande :

    PUT /_snapshot/my_backup
    {
    	"type": "fs",
    	"settings": {
    		"location": "${HOME}/mount/backups/my_backup"
    	}
    }
    

    Pour visualiser les informations du répertoire créé, exécuter la commande :

    GET /_snapshot
    

    Enfin pour vérifier que le répertoire créé est fonctionnel, exécuter la commande :

    POST /_snapshot/my_backup/_verify
    

    Cette commande permet de lister tous les noeuds où la vérification a été un succès.


    Génération d’un snapshot

    Un répertoire peut contenir plusieurs snapshots pour un même cluster. Un snapshot est identifié par un nom unique dans un cluster. La commande suivante permet de créer un snapshot dans le répertoire créé précédemment :

    PUT /_snapshot/my_backup/nom_du_snapshot?wait_for_completion=true 
    

    Le paramètre wait_for_completion spécifie si oui ou non la demande doit retourner immédiatement après l’initialisation du snapshot (par défaut) ou attendre l’achèvement du snapshot. Pendant l’initialisation du snapshot, des informations sur tous les snapshots précédents sont chargés dans la mémoire, ce qui signifie que pour les grands répertoires cela peut prendre plusieurs secondes (voire quelques minutes).

    Par défaut, un snapshot de tous les index ouverts et démarrés est créé. Il est cependant possible de spécifier seulement les index à inclure dans le snapshot grâce à la commande suivante :

    PUT /_snapshot/my_backup/nom_du_snapshot
    {
    	"indices": "index_1,index_2",
    	"ignore_unavailable": "true",
    	"include_global_state": false
    }
    

    Pour voir les informations relatives à un snapshot, la commande à saisir est la suivante :

    GET /_snapshot/my_backup/nom_du_snapshot
    

    Enfin, il est possible de supprimer un snapshot avec la commande :

    DELETE /_snapshot/my_backup/nom_du_snapshot
    

    Restauration

    Un snapshot peut être restauré grâce à la commande suivante :

    POST /_snapshot/my_backup/nom_du_snapshot/_restore
    

    Cette commande permet de restaurer tous les index du snapshot. Cependant il est possible de restaurer uniquement certains index, avec la commande suivante :

    POST /_snapshot/my_backup/nom_du_snapshot/_restore
    {
    	"indices": "index_1,index_2",
    	"ignore_unavailable": "true",
    	"include_global_state": false,
    	"rename_pattern": "index_(.+)",
    	"rename_replacement": "restored_index_$1"
    }
    

    Un index peut être restauré seulement s’il est fermé. Si l’index n’existe pas dans le cluster, il est créé lors de la restauration du snapshot.

    Changer les paramètres de l’index pendant la restauration

    Pendant la restauration, il est possible de modifier certains paramètres de l’index. Dans l’exemple ci-dessous, l’index index_1 restauré avec 3 répliques et avec un intervalle de rafraichissement par défaut de 1s :

    POST /_snapshot/my_backup/nom_du_snapshot/_restore
    {
    	"indices": "index_1",
    	"index_settings": {
    		"index.number_of_replicas": 3
    	},
    	"ignore_index_settings": [
    		"index.refresh_interval"
    	]
    }
    

    Restauration vers un cluster différent

    Un snapshot n’est pas spécifique à un cluster. Un snapshot d’un cluster A peut être restauré sur un autre cluster B.

    Enregistrer le répertoire contenant le snapshot dans le cluster B et lancer le processus de restauration.

    Attention, cependant à la capacité du cluster. Le nombre d’index disponible sur le cluster doit être égal ou supérieur au nombre d’index du snapshot. Si le cluster a une plus petite taille, il est possible de changer les paramètres de l’index durant la restauration en réduisant par exemple le nombre de répliques.

    Gestion du snapshot

    Statut du snapshot

    • La liste des snapshots en cours d’exécution peut être visible grâce à la commande :

      GET /_snapshot/_status
      
    • Il est possible d’affiner la recherche à un répertoire :

      GET /_snapshot/my_backup/_status
      
    • Il est également possible de voir le statut d’un snapshot précis :

      GET /_snapshot/my_backup/nom_du_snapshot/_status
      

    Progression

    GET /_snapshot/my_backup/nom_du_snapshot/_status, cette commande permet de visualiser les informations du snapshot avant que celui-ci ne soit arrêté. Ainsi, avec cette commande il est possible d’avoir les informations du snapshot lorsqu’il est en cours d’exécution. Ce qui n’est pas le cas pour la commande GET /_snapshot/my_backup/nom_du_snapshot qui va attendre la fin de l’exécution pour donner les informations.

    Arrêt

    Si un snapshot a été exécuté par erreur, ou si l’exécution est anormalement longue, il est possible de l’arrêter en utilisant une opération de suppression du snapshot. L’opération va alors arrêter le snapshot avant de le supprimer.

    Pour annuler une restauration, les indices en cours de restauration doivent être supprimés. Toutes les données des indices effacés seront également supprimées du cluster.

    Pour effectuer la montée de version d’Elasticsearch, il est nécessaire d’installer un nouveau cluster Elasticsearch dans la version cible. Ensuite, la procédure suivante décrit comment pousser les données d’un cluster Elasticsearch à un autre après avoir créer votre scope à partir du CLM.

    Lancement de la ré-indexation

    Dans cette section, nous allons demander à Elasticsearch la population d’un index à partir d’un autre index distant.

    Elasticsearch va tout d’abord vérifier la demande puis retourner l’identifiant d’une tâche asynchrone. Pour cela, exécuter la requête suivante sur le cluster cible en adaptant aux environnements :

    POST /_reindex?wait_for_completion=false
    {
      "source": {
        "remote": {
          "host": "http://localhost:9200",
          "username": "user",
          "password": "password"
        },
        "index": "<scope>-flower-docs",
        "type": "document",
        "size": 100
      },
      "dest": {
        "index": "<scope>-flower-docs"
      }
    }
    

    Nota : Dans cette requête, <scope> est l’identifiant du scope Flower en minuscule.

    La réponse retournée par Elasticsearch est du type :

    {
        "task": "<nodeId>:<taskId>"
    } 
    

    Etat de la ré-indexation

    La tâche de ré-indexation étant asynchrone, il est possible de connaître son état :

    GET /_tasks/<nodeId>:<taskId>
    

    Selon la réponse retournée, il est donc possible de déterminer si la ré-indexation a été exécutée avec succès ou si elle est encore en cours d’exécution.

    • Un flag completed indique si la ré-indexation est terminée ou non
    • La tâche récupérée mentionne un objet response ou error indiquant si la tâche a pu être terminée avec succès

    L’ensemble des tâches de ré-indexation peuvent être également consultées avec :

    GET /_tasks?detailed=true&actions=*reindex
    
Intialisation d'un scope