Elasticsearch

Installer & Configurer votre instance FlowerDocs
Elasticsearch

    Le connecteur Elasticsearch s’appuie sur la stack Elastic 5.2.1


    Cette documentation s’appuie sur le dossier ${FD_HOME} contenant les fichiers de configuration des applications.

    FlowerDocs Core

    L’ensemble des propriétés permettant de configurer FlowerDocs Core doivent être ajoutées dans un fichier core.properties situé dans le répertoire ${FD_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.

    file.dir=C:\\FlowerDocs\\Files\\	

    FlowerDocs GUI

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

    ws.url=http://<flower host>:<flower port>/<flower context path>/services
    arender.rendition.nodes=http(s)://rendition-host:8761

    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 FlowerDocs.


    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, éditez le fichier ${ES_HOME}/config/elasticsearch.yml tel que :

    • Pour définir le nom du cluster Elasticsearch, dé-commentez la propriété cluster.name et modifiez sa valeur par flower-es-dev
    • Dans le cas d’un cluster Elasticsearch, dé-commentez la propriété node.name et modifiez sa valeur par celle de votre choix (ex: node-1)
    • Si plusieurs noeuds Elasticsearch sont déployés sur la même machine, il est nécessaire de modifier la valeur de la propriété http.port
    • Ajoutez 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émarrez 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, allez 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 FlowerDocs.


    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, éditez le fichier ${KIBANA_HOME}/config/kibana.yml tel que :

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


    Pour terminer, démarrez 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, allez sur la page http://localhost:5601/

    Configuration

    Afin de configurer l’accès de FlowerDocs à Elasticsearch et Kibana, modifiez le fichier gui.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é par agrégation
    kibana.url http://localhost:5601 URL d’accès à Kibana à partir du FlowerDocs Core

    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é :

    
    file.dir=C:\\FlowerDocs\\Files\\
    
    
    file.dir=/opt/FlowerDocs/Files/
    

    Amazon S3

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

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

    Paramétrage du client Amazon S3

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

    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 profil est possible grâce aux paramètres suivants :

    s3.profile=<nom du profil>
    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 FlowerDocs 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 seront sauvegardés, ajoutez dans le fichier ${ES_HOME}/config/elasticsearch.yml dans la partie “Paths” : path.repo: ["${HOME}/mount/backups", "${HOME}/mount/longterm_backups"]

    Puis redémarrez tous les noeuds d’Elasticsearch.

    Exécutez ensuite la commande :

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

    Afin de visualiser les informations du répertoire créé, exécutez la commande :

    GET /_snapshot

    Enfin pour vérifier que le répertoire créé est fonctionnel, exécutez 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 une réponse 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ées 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 est 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

    La commande GET /_snapshot/my_backup/nom_du_snapshot/_status permet de visualiser les informations du snapshot avant que celui-ci ne soit arrêté. Ainsi, il est possible d’avoir les informations du snapshot lorsqu’il est en cours d’exécution contrairement à 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éé 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écutez 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"
      }
    }

    Note : Dans cette requête, <scope> est l’identifiant du scope FlowerDocs 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