Custom Service Control

Le Custom Service Control (abrégé CSC) est un outil qui vous permet d’exécuter vos propres services sur un serveur Flex. Ces «Custom Services» peuvent par exemple être des backends pour des applications Web ou des daemons propres avec des tâches spéciales. Avec le framework CSC de Hostpoint, vous pouvez configurer ces applications propres pour qu’elles s’arrêtent, s’éteignent proprement et redémarrent automatiquement lorsque le serveur est redémarré.

Exigences

Le CSC est disponible à partir de Managed Flex Server M.

Quelles fonctions vous offre le Custom Service Control?

• Vous pouvez démarrer et arrêter vos propres applications en tant que daemon. Il peut par exemple s’agir d’une application Node.js, que vous intégrez via la fonction proxy de NGINX.
• Le CSC peut détecter et redémarrer les applications bloquées. Event Listener vous permet d’exécuter des actions dans un tel cas, p. ex. envoyer un e-mail.
• Le CSC peut s’occuper du logging et de la rotation de journal pour votre application. Cela permet de toujours garantir l’ordre dans les journaux de votre application.
• Le CSC peut éteindre proprement vos applications et Custom Services avant de redémarrer votre serveur (p. ex. pour les mises à jour du système) et les redémarrer dès que votre serveur est à nouveau opérationnel.

Vue d’ensemble du framework Custom Service Control

Le CSC comprend deux composants:

• Le hpservices Tool, qui gère l’ensemble du framework et qui active et commande le supervisor service.
• Le superviseur de service Supervisord, qui permet la surveillance et le contrôle des processus. Le Supervisor Service utilise le très répandu Supervisord.

Aperçu rapide de hpservices Utility

Le hpservices Utility est la centrale de commande vers l’administration du CSC. Cet outil active, démarre et arrête le Supervisord et vous aide à configurer de nouveaux Custom Services.

Aperçu des principales fonctions:

hpservices supervisord start

Démarre le Supervisord. Votre serveur vérifie ensuite périodiquement (environ toutes les 60 secondes) si le Supervisord fonctionne. Si ce n’est pas le cas, il est automatiquement démarré. Lorsque vous démarrez le Supervisord pour la première fois, la configuration de base est créée et le Supervisord est activé. Cet état est sauvegardé. Après un redémarrage de votre serveur (p. ex. après une mise à jour), le Supervisord est redémarré avec la configuration que vous avez enregistrée.

hpservices supervisord stop

Arrête le Supervisord et toutes ses applications. Cet état est également sauvegardé jusqu’à ce que vous redémarriez le Supervisord.

hpservices supervisord status

Indique si le Supervisord fonctionne ou non.

hpservices supervisord restart

Arrête et redémarre le Supervisord. La configuration est lue à nouveau. Les applications gérées par Supervisord sont également arrêtées et redémarrées. Vous pouvez ainsi tester si votre configuration globale atteint le résultat souhaité après un redémarrage.

hpservices supervisord add exemple1

Crée un squelette composé des répertoires requis et d’un modèle pour la configuration Supervisord pour le service exemple1.

hpservices supervisord remove exemple2

Supprime les répertoires et la configuration Supervisord pour le service exemple2.

hpservices supervisord list

Liste toutes les applications que vous avez ajoutées avec hpservices supervisord add.

Travailler avec le CSC

Tout comme votre application fonctionne en tant que «Custom Service» sur votre serveur, le CSC est également exécuté sur votre serveur et il est contrôlé, configuré et utilisé à partir de celui-ci. Afin d’utiliser le CSC, connectez-vous sur votre serveur via SSH.

Démarrage du Supervisord

Pour pouvoir démarrer, arrêter et gérer vos propres services avec le CSC, vous devez activer le Supervisord sur votre serveur. Les répertoires nécessaires et une configuration initiale cohérente sont créés au premier démarrage.

hpservices supervisord start
supervisord successfully started

La sous-commande status vous permet de vous assurer que votre Supervisord fonctionne:

hpservices supervisord status
supervisord is running as pid 1337

Si votre Supervisord se bloque ou est arrêté manuellement par vous-même (killé), le CSC redémarre automatiquement le Supervisord avec la configuration que vous avez enregistrée et vos applications. Si vous voulez désactiver la fonction du Supervisord, désactivez soit les applications correspondantes via supervisorctl (effet temporaire jusqu’au prochain redémarrage du Supervisord) ou arrêtez le Supervisord avec le hpservices Utility (effet durable pour toutes les applications, jusqu’à ce que vous le redémarriez avec hpservices).

Arrêt du Supervisord

Si vous voulez désactiver les fonctions du CSC et du Supervisord, vous pouvez les arrêter.

hpservices supervisord stop
supervisord has been stopped

Le Supervisord et toutes les applications qu’il a démarrées sont alors arrêtés. Cet état est sauvegardé. Cela signifie que même après un redémarrage, le Supervisord et les applications éventuellement configurées ne sont pas démarrées automatiquement.

Ajout d’un nouveau service

En prenant l’exemple d’une application «hellojs», nous montrons comment une application peut être configurée comme Custom Service.

Si vous voulez exécuter une application propre sous le contrôle du CSC, vous devez l’ajouter à la configuration de Supervisord. Les fichiers de configuration du Supervisord se trouvent dans le dossier ~/.services/supervisord/ dans votre Home (voir aussi la section «Annexe: structure de répertoire et de fichier» à la fin de ce manuel). La sous-commande hpservices supervisord add, suivie du nom de l’application souhaitée crée un squelette à partir des répertoires nécessaires et de la configuration du service pour le Supervisord. Voici le résultat pour notre application exemple hellojs:

hpservices supervisord add hellojs
successfully created dir for hellojs: /home/username/.services/supervisord/hellojs
successfully created dir for hellojs: /home/username/.services/supervisord/hellojs/log
supervisord service config file written: /home/username/.services/supervisord/hellojs/service.conf

Installation de l’application

Comme pratique optimale, nous proposons que vous installiez vos applications dans le sous-dossier ~/app/nomdelapplication/. Vous avez ainsi un ordre propre dans votre Home et il est assuré que le code source de votre application est en dehors de la racine de document de votre serveur Web. Bien entendu, il est également possible d’installer votre application à un autre emplacement dans votre Home.

cd app/hellojs

var express = require('express');
var app = express();
				
app.get('*', function (req, res) {
  res.send('Hello World!\n'.concat(process.argv[2],'\n'));
  console.log(req.method,req.url.concat('\n'),req.headers);
});
				
app.listen(process.argv[2], function () {
  console.log('Example app listening on port '.concat(process.argv[2],'!'));
});

ls
start.js
npm install express
ls
log     node_modules     package-lock.json     start.js

node start.js 1234
Example app listening on port 1234!
^C

Configuration comme service Supervisord

Le hpservices Utility a créé un sous-dossier dans le répertoire de configuration du Supervisord pour notre application hello.js: ~/.services/supervisord/hellojs/. Il contient une configuration exemple commentée comme point de départ pour vous, ainsi qu’un dossier «log» où les fichiers journaux sortie standard (stdout) et sortie erreur standard (stderr) (stderr) de votre service peuvent être écrits (voir aussi à ce propos la description détaillée des options de logging ci-dessous):

ls -l
total 8
drwxr-xr-x 2 username username 4096 Jan 22 17:45 log
-rw-r--r-- 1 username username 882 Jan 22 17:45 service.conf

Vous pouvez configurer le nouveau service, l’application hello.js, dans le fichier service.conf. Vous y trouverez un cadre de suggestions que vous pouvez reprendre, adapter ou compléter. Les lignes commençant par un point-virgule («;») sont considérées comme des commentaires et ne sont pas prises en compte. Pour que Supervisord puisse démarrer un service, sa configuration minimale nécessite un bloc program et une command:

[program:hellojs]
command=/usr/local/bin/node /home/username/app/hellojs/start.js 1234 ; the program (can take args)
;directory=/home/username/app/hellojs/ ; directory to cwd to before exec (default no cwd)
;autostart=true ; start application at supervisord start (default: true)
;stopwaitsecs=10 ; max num secs to wait before SIGKILL (default 10)
;stdout_logfile=/home/username/.services/supervisord/hellojs/log/default.log
;stdout_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default ist 50MB)
;stdout_logfile_backups=10 ; number of stdout logfile backups (0 means none, default 10)
;stderr_logfile=/home/username/.services/supervisord/hellojs/log/default.err
;stderr_logfile_maxbytes=1MB ; filesize at which to rotate logfiles (default is 50MB)
;stderr_logfile_backups=10 ; number of stderr logfile backups (0 means none, default 10)

Options de service

[program]

Nom du service. Il est utilisé pour gérer le service avec la commande supervisorctl.

command

La commande à utiliser pour démarrer le service. Dans notre exemple, nous donnons l’Interpreter «/usr/local/bin/node», notre programme «%(ENV_HOME)s/app/hello.js/start.js» et comme unique argument attendu par notre appli hello.js, le port «1234».

directory

Répertoire de travail du service. Avant de démarrer l’application, Supervisord «bascule» dans ce répertoire.

autostart

Si vous réglez cette valeur sur «false», le programme ne démarrera pas automatiquement au démarrage de Supervisord. Cela peut être utile, par exemple, lors du développement de services.

stopwaitsecs

Définit le temps maximum pendant lequel Supervisord attend que l’application se termine lors de la procédure d’arrêt. Une fois ce temps écoulé, il arrête l’application de force (KILL).
Avertissement​: Augmentez uniquement cette valeur en cas de besoin urgent et justifié. Vous augmentez ainsi le downtime de votre serveur pendant les travaux de maintenance! Le temps d’attente maximum possible est de 120 secondes.

Options de logging

Si votre programme effectue des sorties sur la sortie standard (stdout) ou sur la sortie erreur standard (stderr), vous pouvez les écrire dans un fichier journal. C’est une façon très élégante de réaliser le logging pour votre application. Vous pouvez d’ailleurs configurer Supervisord pour qu’il s’occupe de la gestion propre et de la rotation de ces journaux. Ceci vous assure d’avoir toujours un ordre clair avec vos fichiers journaux. Les lignes commentées suggérées contiennent déjà des paramètres par défaut utiles, vous pouvez simplement les reprendre si vous le souhaitez.

stdout_logfile

Définit le chemin d’accès au fichier journal de la sortie standard

stdout_logfile_maxbytes

La taille maximale d’un fichier journal de la sortie standard. Si elle est atteinte, le fichier journal actuel est archivé et un nouveau fichier est commencé.

stdout_logfile_backups

Le nombre de fichiers journaux archivés de la sortie standard, qui sont stockés.

stderr_logfile

Définit le chemin d’accès au fichier journal de la sortie erreur standard

stderr_logfile_maxbytes

La taille maximale d’un fichier journal de la sortie erreur standard. Si elle est atteinte, le fichier journal actuel est archivé et un nouveau fichier est commencé.

stderr_logfile_backups

Le nombre de fichiers journaux archivés de la sortie erreur standard qui sont stockés.

Pour de plus amples détails et d’autres options de configuration de vos services, consultez la documentation officielle de Supervisord.

Démarrage du nouveau service

Une fois que vous avez installé et testé votre application et configuré le service correspondant dans Supvervisord, vous pouvez demander à votre Supervisord de lire la nouvelle configuration. Il existe plusieurs possibilités pour cela.

supervisord restart

La variante la plus simple est de redémarrer le Supervisord dans son ensemble. Toutes les applications qu’il gère sont toutefois également redémarrées. L’avantage est que vous avez ainsi immédiatement vérifié si votre configuration CSC dans son ensemble est correcte et fonctionne.

hpservices supervisord restart
supervisord has been stopped
supervisord successfully started

Vous pouvez également lire la nouvelle configuration manuellement avec supervisorctl et activer le nouveau service. Il existe ici deux variantes différentes:

supervisorctl update

La sous-commande update lit et applique fraîchement la configuration du Supervisord. Un nouveau service est ainsi automatiquement lancé:

supervisorctl
hello-world                   RUNNING     pid 11106, uptime 21:47:53
supervisor> update
hellojs: added process group
supervisor> status
hello-world                   RUNNING     pid 11106, uptime 21:47:59
hellojs                       RUNNING     pid 11105, uptime 21:47:59
supervisor>

supervisorctl reread & add

Il est un peu plus prudent de faire un ajout avec les sous-commandes reread et add. Vous pouvez ainsi voir à l’avance quelles modifications seraient appliquées au cours d’un update, et add vous permet de les exécuter de manière sélective.

1. Relire la configuration. Supvervisord découvre ainsi qu’un nouveau service est disponible et l’annonce:
   

   supervisorctl reread
   hellojs: available

   La nouvelle application n’est toutefois pas encore active:

   supervisorctl status
   hello-moon                    RUNNING    pid 2408, uptime 0:11:36
   supervisorctl avail
   hello-moon                    in use     auto      999:999
   hellojs                       avail      auto      999:999

2. Ajouter notre «hellojs» aux applications en cours d’exécution:
   

   supervisorctl add hellojs
   hellojs: added process group

   Le nouveau service est ajouté et démarré automatiquement:

   supervisorctl status
   hello-moon                    RUNNING     pid 2408,   uptime 0:11:36
   hellojs                       RUNNING     pid 234269, uptime 0:0:07

Pratiques optimales

Afin de garantir un fonctionnement aussi fiable et efficace que possible de vos applications, nous vous recommandons de respecter les pratiques optimales suivantes:

• Loggez dans votre application sur stdout et stderr et laissez Supvervisord s’occuper de l’écriture des fichiers journaux, de leur rotation et du rangement.
• Si votre application logge elle-même, écrivez volontairement à un emplacement qui vous permet de vous occuper facilement de la gestion de vos fichiers journaux. Il peut par exemple s’agir de ~/app/appname/log/. Configurez un automatisme qui fait tourner et supprime régulièrement vos fichiers journaux. En gérant activement vos journaux, vous identifiez les problèmes et évitez que votre espace Web ne se remplisse de messages de journaux jusqu’à planter.
• Après chaque modification de la configuration de votre Supvervisord et de votre application, vérifiez si les deux se comportent comme vous le souhaitez. Vous pouvez par exemple le faire en redémarrant l’ensemble du framework CSC avec hpservices supervisord restart.
• Saisissez une adresse e-mail pour les messages techniques. Vous serez ainsi informé dans le cas où votre Supervisord n’aurait pas pu être activé au démarrage du système en raison d’une erreur dans votre configuration.

Travailler avec les services: supversisorctl

Vous pouvez aisément et individuellement manipuler et commander les applications que vous avez configurées en tant que service dans le Supervisord, avec le supversisorctl Utility.

Si vous démarrez supversisorctl via SSH, il se présente comme un shell interactif sur lequel vous pouvez ouvrir directement les différentes sous-commandes.

supervisorctl
hello-world                   RUNNING    pid 11106, uptime 0:00:03
hellojs                       RUNNING    pid 11105, uptime 0:00:03
hellojs2                      STOPPED    Not started
supervisor>

Le shell Supversiorctl interactif est compatible avec une forme simple de complètement de ligne de commande avec la touche Tab (pour tester, appuyez par exemple sur la lettre «h» suivie par la touche Tab, ou les lettres «st» puis deux fois la touche Tab). Une petite aide est également intégrée:

Vous pouvez également exécuter directement toutes les sous-commandes sans utiliser le mode interactif:

Vous trouverez un manuel détaillé sur l’utilisation et les possibilités de supervisorctl dans la documentation officielle de Supervisorctl.

Exemple

Dans la section suivante, nous vous invitons à une petite visite guidée. Nous aimerions vous donner une idée de la façon dont une application pourrait (continuer à) être développée, comment supervisorctl vous soutient en cela et comment vous pouvez utiliser cet outil.

Dans notre scénario exemple, nous voulons continuer de développer notre hello.js présenté ci-dessus. Afin de pouvoir le tester sans soucis, nous en avons fait une copie et créé un nouveau service: hellojs2. L’original reste quant à lui en usage productif. Tout d’abord, nous voulons démarrer l’application hellojs2 encore inchangée exactement comme notre hellojs:

supervisor> start hellojs2
hellojs2: ERROR (spawn error)

Oula! Une erreur s’est produite. Ceci est également visible avec la sous-commande status:

supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:52
hellojs                       RUNNING    pid 11105, uptime 0:20:52
hellojs2                      FATAL      Exited too quickly (process log may have details)

Nous trouvons la raison dans le fichier journal stderr que Supervisord écrit pour nous:

tail -18 .services/supervisord/hellojs2/log/default.err
Error: listen EADDRINUSE: address already in use :::1234
    at Server.setupListenHandle [as _listen2] (net.js:1290:14)
    at listenInCluster (net.js:1338:12)
    at Server.listen (net.js:1425:7)
    at Function.listen
(/home/username/app/hellojs2/node_modules/express/lib/application.js:618:24)
    at Object.<anonymous> (/home/username/app/hellojs2/index.js:14:5)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
Emitted 'error' event at:
    at emitErrorNT (net.js:1317:8)
    at process._tickCallback (internal/process/next_tick.js:63:19)
    at Function.Module.runMain (internal/modules/cjs/loader.js:745:11)
    at startup (internal/bootstrap/node.js:283:19)
    at bootstrapNodeJSCore (internal/bootstrap/node.js:743:3)

C’est vrai! Rappelez-vous que plus haut, nous avions déjà utilisé le port 1234 pour l’appli hellojs productive. L’erreur est normale car on ne peut ouvrir qu’un seul listening socket sur un port TCP d’une adresse IP: le port est déjà utilisé. Afin de corriger le problème, nous ajustons la ligne command dans la configuration Supervisord de hellojs2 et choisissons un autre port libre:

command=/usr/local/bin/node /home/username/app/hellojs2/index.js 1235 ; the program (relative uses PATH, can take args)

Nous pouvons ensuite lire et activer la nouvelle configuration:

supervisor> update
hellojs2: stopped
hellojs2: updated process group
supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:02
hellojs                       RUNNING    pid 11105, uptime 0:20:02
hellojs2                      STOPPED    Not started

La prochaine tentative de démarrage fonctionne et nous sommes prêts à continuer le développement de hellojs2:

supervisor> start hellojs2
hellojs2: started
supervisor> status
hello-world                   RUNNING    pid 11106, uptime 0:20:52
hellojs                       RUNNING    pid 11105, uptime 0:20:52
hellojs2                      RUNNING    pid 21305, uptime 0:00:04

Nous pouvons maintenant redémarrer notre nouvelle application à notre guise afin de tester les changements:

supervisor> restart hellojs2
hellojs2: stopped
hellojs2: started

Même le programmeur le plus vif commence à fatiguer après un temps. Nous arrêtons donc notre application hellojs2 jusqu’à la prochaine session de développement.

supervisor> stop hellojs2
hellojs2: stopped

Et comme nous avons mis autostart sur «false» dans la configuration des services de hellojs2, nous sommes sûrs que tout restera tel quel.

Suppression d’un service

Si vous souhaitez supprimer de façon permanente (supprimer) les applications personnalisées, vous pouvez le faire avec l'outil hpservices et supervisorctl. La structure des dossiers avec la configuration Supervisord correspondante (~/.services/supervisord/exemple) et le dossier avec l’application sont alors supprimés.

supervisorctl stop ahoi.js

Utilisez ensuite l'outil hpservices pour supprimer la configuration:

hpservices supervisord remove ahoi.js
Are you sure to delete the service in the following directory with all its content?
/home/username/.services/supervisord/ahoi.js
Are you sure? (y/n): y
successfully removed service ahoi.js
Are you sure to delete the application directory with all its content?
/home/username/app/ahoi.js
Are you sure? (y/n): y
successfully removed application directory ahoi.js

Et enfin supprimer le service du superviseur avec la commande suivante:

supervisorctl remove ahoi.js

Désactiver un service au lieu de le supprimer

Vous pouvez également ajuster la configuration Supvervisord pour cette application de sorte que le Supervisord ne la démarre plus automatiquement. Pour cela, modifiez la valeur d’autostart sur «false».

autostart=false          ; start at supervisord start (default: true)

Si vous désactivez les services dont vous n’avez plus besoin au lieu de les supprimer, veuillez noter que les logiciels non maintenus sur votre serveur représentent un potentiel risque de sécurité. Le logiciel qui n’avait pas été mis à jour depuis des années peut être redémarré par inadvertance. Préférez la création d’une sauvegarde des données et applications qui ne sont plus nécessaires et supprimez-les de votre serveur productif

Annexe: structure de répertoire et de fichier

~/.services/supervisord/hostpoint.conf

Le fichier de configuration principal Supervisord

~/.services/supervisord/myservice/service.conf

Le fichier de configuration de service Supervisord pour le service myservice

~/.services/supervisord/myservice/log/

Le répertoire pour les fichiers journaux stdout et stderr du service myservice