Aller au contenu principal

Development Guides

Accès à l'API S-EdS​

Ce document explique comment une application déployée par SAp peut utiliser l'API REST du Service EdS.

Pré-requis​

Client keycloak​

Après le premier déploiement de l'application, un administrateur KeyCloak doit modifier le client public associé à l'application (l'identifiant du client est le nom de l'application) comme suit:

  • ajouter un mapper au Client Scope Dedicated (Client details/ Client scopes/ nom du client-dedicated/ Add mapper/ By configuration)
  • choisir User Client Role
  • donner un nom unique, par exemple: eds-mapper
  • choisir le client id: eds
  • dans Token Claim name saisir resource_access.${client_id}.roles
  • Sauvegarder

Ceci permet au jeton JWT associé au client public de l'application de contenir les rôles EdS associés à l'utilisateur.

Utilisateur connecté​

L'utilisateur doit avoir les rôles fins EdS nécessaires aux opérations qu'il souhaite utiliser.

L'utilisateur doit avoir accès aux EdS sur lesquels il souhaite faire des opérations.

Principe​

L'application utilise le jeton JWT qui lui est fourni pour s'authentifier (voir la documentation sur l'Exposition de l'application), comme le montrent les exemples ci-dessous.

A fins de tests il est également possible de se connecter à KeyCloak pour obtenir un jeton JWT en procédant comme suit:

  • préparer un fichier au format application/x-www-form-urlencoded contenant les informations de connexion:
grant_type=password&client_id=client&username=user&password=password

où client est le client public associé à l'application, et user/password les login et mot de passe de l'utilisateur connecté.

  • exécuter une requête vers Keycloak :
curl -d@kcdata http://keycloak-cluster-service.kosmos-iam.svc.cluster.local/realms/realm/protocol/openid-connect/token

kcdata étant le nom du fichier préparé à l'étape précédente, et realm le nom du royaume KeyCloak.

  • la réponse à cette requête est une structure JSON, le token est dans le champ access_token de cette structure.

L'URL de l'API S-EdS est fournie par une KosmosInterface de type EdS, via la propriété endpoint. L'application aura donc dans son fichier kosmos.yaml un pré-requis de type EdS.

L'application pourra effectuer des requêtes HTTP vers le Service EdS conformément au swagger du service (voir ci-après).

Documentation de l'API​

Sur une plateforme de type KDL le swagger de l'API S-EdS est accessible en effectuant un port-forward du service de l'API avec la commande suivante :

kubectl -n kosmos-system-restricted port-forward svc/eds-back-kosmos-eds-api-server 3080:3080

Le swagger est alors accessible depuis un navigateur à l'URL suivante: http://localhost:3080/swagger/v1

Exemples​

Dans les commandes qui suivent:

  • eds-endpoint désigne l'URL de l'API EdS obtenue de la KosmosInterface EdS.
  • le token JWT est dans la variable d'environnement TOKEN,
  • on s'intéresse à un EdS appelé edstest,
  • on considère une sauvegarde nommée testsv.

La requête suivante permet d'effectuer une sauvegarde :

curl -H "Authorization: Bearer $TOKEN" -d'{"name":"testsv"}' -v eds-endpoint/v1/storages/edstest/backup

La requête suivante permet d'obtenir l'état de la sauvegarde :

curl -H "Authorization: Bearer $TOKEN" -v eds-endpoint/v1/backups/testsv

La requête suivante permet d'effectuer une restauration :

curl -H "Authorization: Bearer $TOKEN" -d'{"name":"testsv"}' -v eds-endpoint/v1/storages/edstest/restore

Créer un EdS manuellement​

attention

Ce n'est pas la méthode à privilégier, nous conseillons plutôt d'utiliser l'IHM prévue à cet effet.

Pour créer un EdS la commande kubectl suffit : kubectl apply -f path/to/file.yaml fonctionne (avec file.yaml le manifeste descriptif de la KosmosStorage à créer).

Le fichier à fournir par type de moyen de stockage​

Kafka​

Le KosmosStorageType kafka-v1 et donc toutes les KosmosStorages de type kafka-v1 référencent un préfixe de topic Kafka.

Exemple de Kosmos Storage kafka-v1

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: kafka-EdS
  namespace: kosmos-system-restricted
spec:
  type: kafka-v1

  displayName: "Instance kafka-EdS"
  description: "Topic Kafka"
  createdBy: "EdSuser@athea.tech"
  environment: PROD
  mode: Enabled

  tags:
  - name: datastore
    value: global.athea.samples.kafka-EdS

  createParameters:
    partitions: 2
    replications: 2
    configs:
    - key: max.message.bytes
      value: "128000"
    - key: flush.messages
      value: "1"
    group: mon-groupe
    source: true

La partie spécifique a le format suivant :

createParameters:
    partitions: <nb partitions>
    replications: <nb replicas>
    configs:
    - key: <propriete>
      value: <valeur>
    - ...
    group: <groupe>
    source: <true|false>

partitions: facutatif - nombre de partitions du topic (valeur par défaut configurée dans kosmos-mds-kafka)

replications: facutatif - nombre de replicas du topic (valeur par défaut configurée dans kosmos-mds-kafka)

configs: facultatif - éléments de configuration Kafka supplémentaires

group: facutatif - nom du groupe de consumers Kafka qui accédera au topic (valeur par défaut: nom de la KS-group)

source: facultatif - permet d'indiquer si l'EdS sera accédé par l'application IDU (Import de Données Utilisateur) (valeur par défaut: false)

OpenSearch​
Préfixe d'index​

Le KosmosStorageType opensearch-indexprefix-v1 et donc toutes les KosmosStorages de type opensearch-indexprefix-v1 référencent un préfixe d'index OpenSearch.

Convention de nommage des KS de préfixe d'index OpenSearch: Comme on crée un préfixe d'index si la KosmosStorage est supprimée, tous les index portant ce préfixe sont supprimés. Par exemple, si dans OpenSearch on a les index ksName-1, ksNameMyIndex et otherIndex, supprimer la KosmosStorage de nom ksName supprimera les index ksName-1 et ksNameMyIndex, mais ne supprimera pas otherIndex (les comptes associés à ce préfixe d'index seront supprimés aussi). Ce fonctionnement pourrait engendrer des suppressions non souhaitées si une KosmosStorage est le préfixe d'une autre. Pour éviter ce problème, lorsqu'une KosmosStorage est créée, le contrôleur kosmos-mds-opensearch vérifie qu'il n'existe pas déjà une autre KosmosStorage, qui référence le même cluster OpenSearch, qui soit le préfixe ou un suffixe de la KosmosStorage que l'on cherche a créer. Par exemple, s'il existe une KS ksName1 et que l'on souhaite créer ksName, alors la création sera refusée, car ksName est un préfixe de ksName1. De la même manière, si il existe une KS ksN et que l'on souhaite créer ksName, alors la création sera aussi refusée, car ksName est un suffixe de ksN. Il est donc recommandé de ne pas utiliser un nom trop court pour une KosmosStorage OpenSearch afin d'éviter les risques de vouloir créer à l'avenir une KS qui serait un suffixe d'une KS existante.

Exemple :

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: opensearch-index-EdS
  namespace: kosmos-system-restricted
spec:

  ## Partie spécifique au type
  createParameters:
    indices:
    - filepath: opensearch/index.json
      revision: develop
      suffix: -index1
      url: ssh://git@gitlab.technique.artemis:2222/infostructure/socle/service-applicatif/gitops-lab/EdS/EdS-files.git
    - suffix: -index2
    instance: es00

  ## Champs communs aux KosmosStorage de tous types
  createdBy: "EdSuser@athea.tech"
  description: Index OpenSearch
  displayName: Instance opensearch-index-EdS
  environment: PROD
  mode: Enabled
  tags:
  - name: classification
    value: DR
  - name: datastore
    value: global.athea.samples.opensearch-index-EdS
  type: opensearch-indexprefix-v1

La partie spécifique a le format suivant :

createParameters:
    indices:
        - filepath: <path/to/file.json>
        revision: <branch or tag>
        suffix: -index1
        url: <git repository>
        - suffix: -index2
    [...]
    instance: es00

instance : facultatif - c'est le cluster (es00) OpenSearch dans lequel doit être créé l'EdS. Ce champ n'est pas obligatoire car une valeur par défaut est configurée dans l'outil S-EdS. Si ce champ référence un cluster inconnu dans la configuration de l'outil S-EdS, une erreur est retournée.

indices : facultatif - une liste d'index à créer lors de l'activation de l'EdS. La liste peut être vide, auquel cas lors de l'activation de l'EdS seuls les comptes d'accès au préfixe d'index sont créés dans OpenSearch et aucune autre action n'est effectuée dans le moyen de stockage. Chaque élément de la liste est un dictionnaire avec les paramètres suivants :

  • suffix : obligatoire - le suffixe à ajouter au nom de la KS pour créer le nom de l'index. Par exemple pour une KS de nom ksName, si on a suffix: -val1, alors l'index créé dans OpenSearch sera ksName-val1.
  • url: facultatif - si on souhaite que l'index soit créé avec des paramètres spécifiques, il faut fournir un fichier json descriptif. Cette url est le dépôt git dans lequel ce ficher est présent.
  • revision : obligatoire si url est renseigné - la branche ou le tag sur lequel on peut trouver le fichier de configuration
  • filepath : obligatoire si url est renseigné - le chemin complet dans le dépôt vers le fichier de configuration.

Le format de fichier (un fichier json) de configuration attendu est conforme au standard opensearch, en voilà un exemple :

{
  "settings": {
    // Paramètres de l'index
    "index": {
      "number_of_shards": 2,
      "number_of_replicas": 1
    }
  },
  "mappings": {
    // Mapping de l'index
    "properties": {
      "age": {
        "type": "integer"
      }
    }
  },
  "aliases": {
    // Alias de l'index
    "sample-alias1": {}
  }
}

Remarque: un fichier de configuration n'a pas besoin d'avoir tous ces paramètres, si on souhaite ne configurer que le mapping par exemple, on peut fournir un fichier comme celui-ci :

{
  "mappings": {
    "properties": {
      "age": {
        "type": "integer"
      }
    }
  }
}
Script​

Lorsque qu'une KS de type opensearch-script-v1 est créée (ou activée), le script correspondant est créé dans le cluster OpenSearch. L'outil S-EdS s'assure néanmoins au préalable qu'il n'existe pas un script (une KS) de même nom qui référence le même cluster OpenSearch pour ne pas remplacer un script existant.

Exemple :

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: opensearch-script-EdS
  namespace: kosmos-system-restricted
spec:

  ## Partie spécifique au type
  createParameters:
    filepath: opensearch/script.json
    instance: es00
    revision: develop
    url: ssh://git@gitlab.technique.artemis:2222/infostructure/socle/service-applicatif/gitops-lab/EdS/EdS-files.git

  ## Champs communs aux KosmosStorage de tous types
  createdBy: "EdSuser@athea.tech"
  description: Script OpenSearch
  displayName: Instance opensearch-script-EdS
  environment: PROD
  mode: Enabled
  tags:
  - name: classification
    value: DR
  - name: datastore
    value: global.athea.samples.opensearch-script-EdS
  type: opensearch-script-v1

La partie spécifique a le format suivant :

createParameters:
    instance: es00
    filepath: <path/to/file.json>
    revision: <branch or tag>
    url: <git repository>

instance : facultatif - c'est le cluster (es00, es01, ou es80) OpenSearch dans laquelle doit être créé l'EdS. Ce champ n'est pas obligatoire comme une valeur par défaut est configurée dans l'outil S-EdS. Si ce champ référence un cluster inconnu dans la configuration de l'outil S-EdS, une erreur est retournée.

url : obligatoire - pour importer un script, il faut fournir le fichier du script (un fichier json). Ce champ correspond à l'url du dépôt git contenant le fichier en question.

revision : obligatoire - le branche ou le tag du dépôt git contenant le script à importer.

filepath : obligatoire - le chemin complet dans le dépôt vers le script.

Exemple de fichier (json) de script qui peut être importé :

{
    "script": {
        "lang": "painless",
        "source": "\n          int total = 0;\n          for (int i = 0; i < doc['ratings'].length; ++i) {\n            total += doc['ratings'][i];\n          }\n          return total;\n        "
    }
  }

Cet exemple est issu de la documentation officielle OpenSearch.

Compléments de configuration​

Après la création d'un EdS opensearch par l'IHM EdS, il est possible de compléter sa définition via des gestes d'administration, dans le cluster opensearch metier.

####### Création de template

Un template permet d'initialiser un nouvel index avec les mappings et les settings définis dans le template.

Pour créer un template, procéder comme suit:

  1. Se connecter à OpenSearch en suivant la procédure indiquée dans le Manuel d'Administration.
  2. Créer un fichier contenant la définition du template, par exemple :
[opensearch@elasticsearch-0 ~] cat > tmpl
{
  "index_patterns": [
    "tplidx*"
  ],
  "template": {
    "settings": {
      "number_of_shards": 2,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "timestamp": {
          "type": "date",
          "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis"
        },
        "value": {
          "type": "double"
        }
      }
    }
  }
}
  • index_patterns indique les index sur lesquels seront appliqués le template (ici tous les index dont le nom commence par tplidx).
  • template contient la définition de l'index.
  1. Exécuter la requête de création de template, par exemple :
[opensearch@elasticsearch-0 ~] curl -u admin-X PUT -H"Content-type: application/json" -d@tmpl http://localhost:9200/_index_template/tpltest

Avec cet exemple, tous les index dont le nom commence par tplidx auront les mappings et settings définis dans le template.

Consulter la documentation OpenSearch pour d'autres renseignements sur les templates.

####### Création de datastream

Un datastream est un flux composé en interne de plusieurs index sous-jacents. L'écriture se fait sur le dernier index du datastream, la lecture se fait sur tous les index.

Pour créer un datastream, procéder comme suit:

  1. Se connecter à OpenSearch en suivant la procédure indiquée dans le Manuel d'Administration.
  2. Créer un fichier contenant la définition du template qui sera associé au datastream (voir ci-dessus). Le template devra contenir la propriété "data_stream" : {} indiquant qu'il s'agit d'un template associé à un datastream et non à un index, le pattern correspondant au nom du datastream. Les données devront contenir un champ d'horodatage appelé @timestamp par défaut; il est possible de définir le nom de ce champ dans la propriété data_stream, par exemple :
  "data_stream": {
    "timestamp_field": {
      "name": "request_time"
    }
  1. Executer la requête de création de datastream, par exemple :
[opensearch@elasticsearch-0 ~] curl -u admin-X PUT http://localhost:9200/_data_stream/teststream

ou insérer directement des données dans le datastream (procéder comme pour écrire des données dans un index, en utilisant le nom du datastream comme nom d'index). OpenSearch crée le datastream et le premier index sous-jacent.

Consulter la documentation OpenSearch pour d'autres renseignements sur les datastreams.

####### Création de pipeline d'ingestion

Un pipeline permet de spécifier une ou plusieurs tâches à appliquer sur les données avant leur ingestion.

Pour créer un pipeline, procéder comme suit:

  1. Se connecter à OpenSearch en suivant la procédure indiquée dans le Manuel d'Administration.
  2. Créer un fichier contenant la définition du pipeline, comme suit :
{
    "description" : "..."
    "processors" : [...]
}

Le champ processors définit la suite de traitements à effectuer sur les données avant ingestion. Par exemple le processor suivant ajoute un champ nommé un_champ ayant la valeur une_valeur aux données ingérées.

    {
      "set": {
        "field": "un_champ",
        "value": "une_valeur"
      }
    }

Se reférer à la documentation OpenSearch pour la liste des processors possibles.

  1. Exécuter la requête de création de pipeline, par exemple :
[opensearch@elasticsearch-0 ~] curl -u admin-X PUT -H"Content-type: application/json" -d@ppl http://localhost:9200/_ingest/pipeline/testppl

L'utilisation du pipeline se fait en ajoutant le paramètre de requête pipeline=nom_du_pipeline à la requête de création de document.

Consulter la documentation OpenSearch pour d'autres renseignements sur les pipelines.

PostgreSQL​

Le KosmosStorageType pg-v1 et donc toutes les KosmosStorages de type pg-v1 référencent une base de données PostgreSQL.

Exemple de Kosmos Storage pg-v1

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: pg-EdS
  namespace: kosmos-system-restricted
spec:
  type: pg-v1

  displayName: "Instance pg-EdS"
  description: "Bases PG"
  createdBy: "EdSuser@athea.tech"
  environment: PROD
  mode: Enabled

  tags:
  - name: datastore
    value: global.athea.samples.pg-EdS

  createParameters:
    instance: pg-shared
    scripts:
    - url: ssh://git@gitlab.technique.artemis:2222/infostructure/socle/service-applicatif/gitops-lab/EdS/EdS-files.git
      path: postgresql
      revision: develop
      files:
      - /create_table.sql

La partie spécifique a le format suivant:

  createParameters:
    instance: <nom d'instance>
    extensions:
    - <extension>
    scripts:
    - url: <URL SSH du projet GIT>
      path: <chemin dans le projet GIT>
      revision: <version dans le projet GIT>
      files:
      - <chemin relatif du fichier>
      - ...
    - ...

La propriété createParameters permet de choisir l'instance de PostgreSQL, de définir les extensions PostgreSQL à activer (parmi celles supportées par l'instance choisie), et permet de définir une liste (optionnelle) de scripts d'initialisation de la base (DDL).

Si aucun script n'est nécessaire, il faut omettre l'élément scripts dans la propriété createParameters.

Chaque élément de la liste contient les champs suivants:

url : obligatoire - url du dépôt git contenant le(s) script(s).

revision : obligatoire - le branche ou le tag du dépôt git contenant le(s) script(s).

path : obligatoire - le chemin dans le dépôt du répertoire contenant le(s) script(s).

files: obligatoire - liste de scripts. La liste doit contenir au moins un fichier.

S3​

Le KosmosStorageType s3-v1 et donc toutes les KosmosStorages de type s3-v1 référencent un bucket S3.

Exemple de Kosmos Storage S3

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: s3-EdS
  namespace: kosmos-system-restricted
spec:
  type: s3-v1

  displayName: "Instance s3-EdS"
  description: "Bucket S3"
  createdBy: "EdSuser@athea.tech"
  environment: PROD
  mode: Enabled

  tags:
  - name: datastore
    value: global.athea.samples.s3-EdS

  createParameters:
    source: true

La partie spécifique a le format suivant:

  createParameters:
    source: <true | false>

Il faut juste indiquer si l'EdS sera accédé par l'application IDU (Import de Données Utilisateur)

ClickHouse​

Le KosmosStorageType ch-v1 et donc toutes les KosmosStorages de type ch-v1 référencent une base de données ClickHouse.

Exemple de Kosmos Storage ch-v1

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: ch-EdS
  namespace: kosmos-system-restricted
spec:
  type: ch-v1

  displayName: "Instance ch-EdS"
  description: "Bases ClickHouse"
  createdBy: "EdSuser@athea.tech"
  environment: PROD
  mode: Enabled

  tags:
  - name: datastore
    value: global.athea.samples.ch-EdS

  createParameters:
    scripts:
    - url: ssh://git@gitlab.technique.artemis:2222/infostructure/socle/service-applicatif/gitops-lab/EdS/EdS-files.git
      path: ch
      revision: develop
      files:
      - /create_table.sql

La partie spécifique a le format suivant:

  createParameters:
    scripts:
    - url: <URL SSH du projet GIT>
      path: <chemin dans le projet GIT>
      revision: <version dans le projet GIT>
      files:
      - <chemin relatif du fichier>
      - ...
    - ...

La propriété createParameters permet de définir une liste (optionnelle) de scripts d'initialisation de la base (DDL).

Si aucun script n'est nécessaire, il faut positionner un élément createParameters vide: createParameters: {}.

Chaque élément de la liste contient les champs suivants:

url : obligatoire - url du dépôt git contenant le(s) script(s).

revision : obligatoire - le branche ou le tag du dépôt git contenant le(s) script(s).

path : obligatoire - le chemin dans le dépôt du répertoire contenant le(s) script(s).

files: obligatoire - liste de scripts. La liste doit contenir au moins un fichier.

vStore​

Le KosmosStorageType vs-v1 et donc toutes les KosmosStorages de type vs-v1 référencent une base de données vStore.

Exemple de Kosmos Storage vs-v1

apiVersion: EdS.kosmos.tech/v1
kind: KosmosStorage
metadata:
  name: vs-EdS
  namespace: kosmos-system-restricted
spec:
  type: vs-v1

  displayName: "Instance vs-EdS"
  description: "Bases vStore"
  createdBy: "EdSuser@athea.tech"
  environment: PROD
  mode: Enabled

  tags:
  - name: datastore
    value: global.athea.samples.vs-EdS

  createParameters:
    url: ssh://git@gitlab.technique.artemis:2222/infostructure/socle/service-applicatif/gitops-lab/EdS/EdS-files.git
    path: vstore
    revision: develop
    files:
      models:
        path: EdSvs_model.yaml
      policies:
        path: EdSvs_policy.yaml

La partie spécifique a le format suivant:

  createParameters:
    files:
      models:
        path: <fichier contenant le datamodel>
      policies:
        path: <fichier contenant les policies>
    url: <URL SSH du projet GIT>
    path: <chemin dans le projet GIT>
    revision: <version dans le projet GIT>

La propriété createParameters permet de définir les fichiers contenant le datamodel et les policies associés à l'EdS. Ces fichiers doivent être présents dans le dépôt décrit par les paramètres url (url du dépôt git contenant les fichiers de définition), path (path dans le dépôt git contenant les fichiers de définition) et revision (révision du dépôt git à utiliser).