Utiliser Talend/Karaf pour déployer web services et routes

Apache Karaf est un conteneur léger et polyvalent basé sur la plate-forme Java. Il est conçu pour l'exécution d'applications et de services s'appuyant sur des composants modulaires.

Talend Studio exploite Karaf pour la mise en oeuvre des routes et des services. Ceux-ci sont alors déployés en tant que bundle OSGI. Voici quelques éléments utiles pour mieux l'aborder et l'utiliser.

Le fonctionnement est le suivant :

• un web service est développé et testé sur Talend Studio
• il est ensuite exporté vers un livrable
• le livrable est déployé sur une instance du moteur Karaf, pour être opérationnel immédiatement

Installer Karaf en mode standalone

L'installation de Karaf se fait simplement : le logiciel est distribué en un seul livrable compatible Linux et Windows, avec quelques différences dans les scripts de démarrage (batch pour Windows, shell pour Linux). Il nécessite malgré tout de disposer de Java.

Plusieurs solutions existent pour l'obtention d'Apache Karaf :

• Si vous êtes un utilisateur enregistré de Talend, vous pouvez télécharger Talend Runtime depuis votre compte et l'installer sur Linux ou sur Windows.
• Vous pouvez aussi télécharger la dernière version de Talend ESB : Karaf se trouve dans le répertoire <runtime>\Runtime_ESBSE\container\bin
• Enfin, il est possible de télécharger directement depuis le site d'Apache Karaf.

Se connecter à Karaf

• Pour se connecter à un Karaf démarré : allez dans le répertoire <runtime>/bin et lancez client (client.bat ou client.sh selon le système d'exploitation)
• Pour se connecter à un Karaf non démarré : allez dans le répertoire <runtime>/bin et lancez trun (trun.bat ou trun.sh selon le système d'exploitation)
  

Si ne fonctionne pas, assurez-vous que Java est précisé depuis la variable d'environnement JAVA_HOME (faites par exemple SET JAVA_HOME=C:\java\jdk\jdk1.8.0_172 si vous avez le JDK installé à cet emplacement).

Différences entre client et trun

Il y a 2 exécutables, voici leurs différences :

• Les utilisateurs sont différents : c'est l'utilisateur tadmin pour client et l'utilisateur karaf pour trun.
• Le script client doit être utilisé lorsque le service d'exécution est déjà démarré (il cherche à se connecter à une instance déjà ouverte) tandis que trun doit être utilisé lorsque le service d'exécution n'est pas démarré. trun démarrera le service et se connectera à karaf en même temps.
• Les permissions des utilisateur tadmin et karaf peuvent être différentes : elles sont précisées dans le répertoire d'installation de l'exécution sous <runtime>/container/etc.

Ouvrir plusieurs sessions sur Karaf

Par défaut, l'ouverture de plusieurs sessions sur Karaf n'est pas activée. Voici comment faire cela :

• Lancer le fichier client sur 2 shells différents (Linux ou Windows)
• S'il y a une demande de saisie du mot de passe puis l'erreur "No more authentication methods available" :
• Editer le fichier users.properties dans contrainer\etc et ajouter le rôle ssh sur le profil admingroup :
_g_\:admingroup = group,admin,manager,viewer,systembundles,ssh
• Sauvegarder et quitter
• Retenter la connexion à Karaf avec client

Déconnexion de Karaf

Pour se déconnecter de Karaf (ou quitter si trun a été utilisé) :

• En tapant : logout
• Par raccourci clavier : Control+D

Construire un traitement depuis Talend Studio et le déployer sur Karaf

Déployer un web service sur Karaf

• Sur Talend Studio, créez un job de type Web service (contenant un objet tRestRequest).
• Quand il est terminé, faites un clic droit sur le nom du job puis construire un bundle OSGI. Cela crée un fichier JAR.
• Connectez-vous à Karaf puis entrez log:tail pour afficher les logs en temps réel.
• Copier-collez le fichier JAR créé par Talend Studio dans le répertoire deploy de Karaf. Une fois la copie terminée, Karaf le prend en compte immédiatement ; on peut le constater en suivant les logs affichés.
• Testez le web service :
• en l'appelant depuis un logiciel comme SoapUI : http://127.0.0.1:8040/services/mon_web_service
  (ne pas oublier que Karaf ajoute "services", contrairement au Studio)
• en affichant la liste des services déployés sur Karaf : http://127.0.0.1:8040/services

Déployer une route sur Karaf

• Sur Talend Studio, créez votre route.
• Quand elle est terminée, faites un clic droit sur son nom puis construire un "ESB Runtime KAR File". Cela crée un fichier KAR.
• Connectez-vous à Karaf puis entrez log:tail pour afficher les logs en temps réel.
• Copier-collez le fichier JAR créé par Talend Studio dans le répertoire deploy de Karaf. Une fois la copie terminée, Karaf le prend en compte immédiatement ; on peut le constater en suivant les logs affichés.
• Testez votre route.

Les bundles

Karaf fonctionne par le biais de bundles. Quand vous déployez une route ou un web service, elle est empaquetée dans un bundle.

Statut des bundles

Les bundles ont un cycle de vie sur Karaf, avec un statut visible. Entrez bundle:list afin d'afficher tous les bundles et leur statut.

Voici les différents stades de ce statut, dans l'ordre :

Resolved : installé (mais non démarré) Starting : étape temporaire indiquant un démarrage en cours Active : démarré (opérationnel) Stopping : étape temporaire indiquant un arrêt en cours GracePeriod : non démarré pour le moment. Un délai de 5 minutes est accordé pour laisser le bundle démarrer. Failure : échec du démarrage. Le bundle n'a pu démarrer dans le délai imparti ou s'est tout bonnement planté. Pour connaître le problème d'un bundle en échec, faire : bundle:diag <bundle> ou diag <bundle>

Lister les bundles

• Lister tous les bundles :
  list
  ou
  bundle:list
• Lister les bundles en échec :
  list | grep Failure
• Lister les bundles non démarrés :
  list | grep -v Active
• Lister les bundles non démarrés depuis la ligne de commande (en dehors de Karaf) :
  client list | grep -v Active
• Lister les bundles utilisateurs avec un start-level >= 80 (t signifie threshold) :
  bundle:list -t 80

Démarrer un bundle

Un bundle démarre automatiquement lors de son déploiement.

Cependant, si un bundle a été arrêté manuellement (par un bundle:stop), cet état est conservé à l'arrêt de Karaf : le bundle ne sera pas démarré au redémarrage de Karaf.

Pour le démarrer (et faire en sorte que Karaf le démarre automatiquement en cas de redémarrage de Karaf) : bundle:start <bundle>

Désinstaller un bundle

• Arrêtez le bundle : bundle:stop <bundle>
• Désinstallez le bundle : bundle:uninstall <bundle>

Log

Les logs de Karaf sont un endroit clé pour savoir ce que le logiciel est en train de faire. Ils sont accessibles en dehors de Karaf mais aussi quand on est connecté au logiciel.

• Afficher les logs en continu :
  log:tail
• Modifier le niveau de log d'un bundle à WARN :
  log:set WARN <bundle>
  Ce niveau est enregistré dans les fichiers de paramétrage de Karaf et est conservé au redémarrage.
• Afficher le niveau de log d'un bundle :
  log:get <bundle>

Astuces

Modifier la durée d'attente maximum des Web services

Pour une route, si vous appelez un web service au moyen du composant cRest, iI y a 2 valeurs à modifier dans le fichier runtime/etc/org.apache.cxf.http.conduits-common.cfg

• client.ConnectionTimeout = 30000
  Cette durée spécifie la quantité de temps, en millisecondes, pendant laquelle le client tentera d'établir une connexion avant que celle-ci n'expire. 0 spécifie que le client continuera de tenter d'ouvrir une connexion indéfiniment.
  
• client.ReceiveTimeout = 60000
  Cette durée spécifie la quantité de temps, en millisecondes, pendant laquelle le client attendra une réponse avant que celle-ci n'expire. 0 spécifie que le client attendra indéfiniment.
  

Les durées sont exprimées en millisecondes.

Démarrer les bundles en Resolved

Voici un script, à utiliser en dehors de Karaf et sur Linux, pour lister les bundles déployés et non démarrés :

Rechercher les bundles en double

Le script ci-dessous, à utiliser en dehors de Karaf et sur Linux, liste les bundles en doublon :

Installer plusieurs Karaf sur une même machine

Il est possible d'installer plusieurs Karaf sur une même machine, en modifiant les ports utilisés.

Karaf est livré avec 3 scripts permettant de modifier ces ports facilement. Voici quelques étapes d'installation d'un nouveau Karaf :

• Copier le répertoire container (depuis le répertoire du Studio ESB par exemple)
• Supprimer le répertoire data et le répertoire instances
• Démarrer Karaf avec trun
• Lancer le paramétrage de l'instance : configureC0 par défaut, configureC1 ou configureC2.
  
  source scripts/configureC1.sh
• Il faut redémarrer Karaf pour appliquer les modifications
• Vérifier avec : instances:list

Supprimer un lock

En cas de problème de lock sur Karaf, utilisez la commande suivante :

Installer le Web Conteneur (web console)

• Connectez-vous à Karaf puis faites :
  
  feature:install http
• Listez les conteneurs :
  
  http:list
• Installez la web console :
  
  feature:install webconsole
• Une fois cela fait, lancez votre navigateur web et allez sur : http://<machine karaf>:8040/system/console
• Utilisez l' identifiant karaf et le mot de passe karaf
• Vous devriez avoir accès aux informations de Karaf et à tous les bundles déployés

Redémarrer une route contenant une routelet

Les routelets sont déployés sur Karaf comme un bundle à part. C'est à mon avis une erreur car cela crée des dépendances entre routes car Karaf évalue que des routes ont des dépendances entre elles, si cette routelet est utilisée sur plusieurs routes. Suite à ma demande, Talend développe un patch pour modifier cela (ce patch devrait être disponible mi-2023).

En attendant, si vous avez un livrable déployant 2 bundles, voici comment faire :

• Pour démarrer un bundle, il faut démarrer d'abord la routelet :
  
  bundle:start <bundle_routelet>
  bundle:start <bundle>
• Pour arrêter une route, il faut arrêter d'abord sa routelet (sinon le bundle arrive en statut GracePeriod)
  bundle:stop <bundle_routelet>
  bundle:stop <bundle>

Surveiller les bundles

Voici quelques commandes pratiques pour surveiller les statuts des bundles :

• Afficher toutes les 3 secondes le nombre de bundles actifs :
  shell:watch -n 3 -a 'shell:date & bundle:list -t 80 | grep -v Active | grep -v groovy | wc -l'
• Afficher toutes les 3 secondes le nombre de bundles actifs et inactifs :
  shell:watch -n 3 -a 'actif=$(bundle:list -t 80 --no-format | grep Active | wc -l) && attente=$(bundle:list -t 80 --no-format | grep Resolved | grep -v groovy | wc -l) && fail=$(bundle:list -t 80 --no-format | grep Failure | grep -v Guava | wc -l) && echo "$(date) : Actif=$actif, échec=$fail, attente=$attente"'
• Afficher les noms des bundles en cours de démarrage :
  watch -n 7 -a 'liste= $(bundle:list | grep Starting | exec cut -d "|" -f5 | exec cut -c2- | exec sed -z "s/\n/, /"); echo "$(date) : $liste"'
• Afficher le statut d'un bundle toutes les secondes
  watch -a 'list | grep <bundle>'

Lister les routes et les web servives actifs

Il s'agit d'ajouter une commande à Karaf (nommée Closure) pour afficher l'état des routes et des services : le but est d'afficher toutes les 3 secondes, après avoir saisi une commande, l'état de toutes les routes et de tous les web services.

• Arrêtez Karaf
• Editez le script des alias Karaf :
  nano <runtime>/etc/shell.init.script</runtime>
• Ajoutez la commande suivante afin de créer un nouvel alias :
  // Scrute les bundles de Karaf
  bundles_scrute = { watch -n 3 -a '
       routesResolved=$( bundle:list -l -n | exec grep -P "mvn:(PROJET1|PROJET2)" | grep "(ROUTE_)" | grep Resolved | wc -l)
      ; routesActives=$( bundle:list -l -n | exec grep -P "mvn:(PROJET1|PROJET2)" | grep "(ROUTE_)" | grep Active | wc -l)
      ; routesFailure=$( bundle:list -l -n | grep "(ROUTE_)" | grep Failure | wc -l)
      ; servActifs=$( bundle:list -l -n | exec grep -P "mvn:(PROJET1|PROJET2)" | grep "(WS_)" | grep Active | wc -l)
      ; servResolved=$( bundle:list -l -n | exec grep -P "mvn:(PROJET1|PROJET2)" | grep "(WS_)" | grep Resolved | wc -l)
      ; servFailure=$( bundle:list -l -n | grep "(WS_)" | grep Failure | wc -l)
      ; encours=$( bundle:list -l -n | grep "(Starting|GracePeriod)" | wc -l)
      ; echo "$(date) : EN COURS=$encours | ROUTES actives=$routesActives, resolved=$routesResolved, failure=$routesFailure | SERVICES actifs=$servActifs, resolved=$servResolved, failure=$servFailure"'};
  
  Cette commande est à adapter selon vos besoins ; elle filtre des projets Talend nommés PROJET1 ou PROJET2, sur des routes commençant par ROUTE_ et des web services commençant par WS_ afin d'identifier s'il s'agit de routes ou de web services autres que ceux de Karaf.
• Démarrez Karaf et tapez :
  bundles_scrute

Modifier le fichier de configuration de Karaf

Le fichier de configuration est <runtime>/etc/config.properties.
Vous pouvez y trouver par exemple le start level par défaut des bundles, le paramétrage des logs...

Paramétrer les instances

La documentation complète sur les instances de Karaf se trouve sur svn.apache.org/repos/asf/karaf/site/production/manual/latest-3.0.x/instances.html. Voici quelques commandes utiles pour créer, lister, démarrer et arrêter une instance Karaf :

• Lister les instances :
  <runtime>/bin/instance list
• Démarrer une instance :
  <runtime>/bin/instance start root
• Arrêter une instance :
  <runtime>/bin/instance stop root
• Modifier le port RMI :
  <runtime>/bin/instance rmi-registry-port-change trun 1099
  <runtime>/bin/instance.bat rmi-server-port-change trun 44444
• Créer une instance :
  instance.bat create trun

Lister les routes Camel d'un bundle