Contrat configuration et commandes

Contrat de compatibilité 1.3.3 : configuration YAML locale, sélection des conteneurs, commandes et codes de sortie. Les décisions introduites en 0.0.80 sont conservées.

Configuration et priorités

Utilisez -c FILE, sinon MONIT_DOCKER_CONFFILE, sinon /etc/monit-docker/monit-docker.yml. Un fichier existant prime sur le YAML fourni par MONIT_DOCKER_CONFIG ; une erreur de lecture ou d’analyse ne déclenche aucun repli. Sans source, les commandes historiques de surveillance utilisent une configuration vide, tandis que check-config, run et scenario renvoient 110.

La racine est une table YAML : {} est valide, un document vide ou une liste ne l’est pas. Les sections sont general, vars, clients, serve, cron, stats, monit, ctn-groups, dir-groups, conditions, commands et scenarios. Tous les modes valident la configuration complète, y compris les entrées inutilisées, avant l’accès Docker. Les sections ou champs inconnus et les valeurs invalides renvoient 110. general alimente le contexte des modèles, pas les options par défaut des commandes.

Les fichiers importés contiennent directement les entrées, sans répéter leur section. Les imports relatifs partent du répertoire du fichier principal ; les derniers remplacent les premiers et les entrées locales remplacent intégralement celles importées. Les chemins d’état et de journal restent relatifs au répertoire de travail. Les modèles Mako exécutent du code de confiance, même pendant la validation hors connexion.

Un client explicitement nommé mais inconnu est refusé, même avec --client-from-env. Pour un nom connu, --client-from-env est prioritaire. Sinon, utilisez --client NAME ou le premier client configuré. Sans client configuré, le fonctionnement historique utilise l’environnement Docker et, par défaut, le socket local.

Réglages des commandes directes

Chaque commande lit sa propre section. Une option explicite en ligne de commande l’emporte sur le fichier. Les listes de règles et de ressources passées au lancement remplacent la liste correspondante. Une lecture explicite avec monit --rsc écarte les actions configurées pour cette invocation. La simulation reste accessible avec --dry-run.

stats:
  rsc: [cpu_percent, mem_usage]
  output: json
serve:
  interval: 60
  status_token_file: /run/secrets/status

Sélection des conteneurs

• Les motifs de nom, identifiant, image et étiquette sont combinés avec OU. Les filtres d’état s’appliquent en plus.
• --ctn-group prend des noms de groupes exacts ; l’union de leurs motifs est intersectée avec l’union des motifs directs lorsqu’ils sont présents.
• Les motifs ordinaires utilisent les jokers du shell, sont sensibles à la casse et couvrent la valeur entière. Le préfixe ~ active une expression rationnelle Python appliquée depuis le début ; ajoutez $ pour la fin.
• Les étiquettes Docker sont recherchées par leur valeur, pas leur clé ni clé=valeur. Les images sont recherchées par leurs étiquettes. Un identifiant historique alphanumérique de 12 caractères reçoit un joker final.
• Les virgules ne découpent jamais les sélecteurs. Répétez les options : --name web --name api. Le motif ~worker-[0-9]{1,3}$ reste intact.
• Sans sélecteur, tous les conteneurs autorisés par le filtre d’état sont retenus ; aucun résultat renvoie 114. Leur ordre n’est pas garanti.

Commandes et sorties

Les options globales précèdent la sous-commande ; ses options propres la suivent. Entourez sélecteurs et règles de guillemets pour éviter leur interprétation par le shell.

monit-docker -c config.yml --name 'web-*' stats --rsc status
monit-docker -c config.yml check-config --output json
monit-docker -c config.yml run web-guard --dry-run

Les règles produisent des décisions JSON contenant container_id, rule, command et status. Aucune règle satisfaite peut rester un succès. La première action en échec arrête les suivantes et les autres conteneurs. La simulation consulte réellement Docker et peut inscrire des événements simulés et créer un verrou d’état.

Scénarios et validation des droits

Les noms suivent [a-z0-9][a-z0-9-]{0,63}. Le mode par défaut est cron ; stats et serve sont également disponibles. Choisissez explicitement select ou all: true, exclusivement. Groupes et motifs directs se combinent par intersection ; l’état est un filtre supplémentaire. Les remplacements globaux de cible ou de client sont refusés ; les champs de journal et de fenêtre d’événements du scénario priment sur les valeurs héritées.

Les champs booléens exigent de vrais booléens. Les champs numériques acceptent les types numériques documentés ou du texte numérique, puis appliquent les bornes de la commande. Les champs inconnus ou incompatibles avec le mode sont rejetés. La configuration est rendue une seule fois puis transmise à l’exécution. Consultez les scénarios nommés pour le tableau des champs.

Depuis la 0.0.77, les ressources fs_readable, fs_writable et fs_executable des scénarios stats/serve exigent une identité access explicite dans le groupe de répertoires dès la validation hors connexion. Auparavant, la consultation pouvait réussir alors que la collecte était impossible. Les ressources disque, inodes et mode de montage n’en ont pas besoin. Les contrôles d’accès nécessitent toujours Python 3 dans le conteneur Linux ciblé.

Principales valeurs par défaut

• Délai entre tentatives automatiques : 300 secondes ; maximum de trois tentatives de redémarrage par conteneur jusqu’au réarmement.
• Délai de déclenchement : 0 ; une valeur positive exige un intervalle maximal positif entre observations, supérieur à l’intervalle de collecte en mode serve.
• Écoute : 127.0.0.1:9808 ; intervalle : 30 secondes ; seuil de péremption : max(90, 3 × intervalle).
• Fenêtre d’événements Docker : 300 secondes, de 1 à 86400.
• Rétention du journal : cinq fichiers de 5 Mio maximum chacun par défaut ; limite configurable minimale de 65536 octets, entre 1 et 100 fichiers.

La référence complète de cette version détaille toutes les options, bornes, valeurs d’environnement, syntaxes d’action et règles de priorité.

Codes de sortie

La consultation unique monit --rsc status renvoie running 0, created 10, paused 20, restarting 30, removing 40, exited 50, dead 60. Pour health : healthy 0, starting 10, unhealthy 20, none 30, unknown 115. Les pourcentages ordinaires renvoient un entier tronqué et borné entre 0 et 100 ; les mesures brutes ne sont pas plafonnées. Ces retours anticipés décrivent le premier conteneur sélectionné. La propagation du code d’une commande interne peut renvoyer 1..255 et recouvrir les autres codes.

Décisions de compatibilité retenues

Validation stricte partagée, refus des clients inconnus, intersection groupes/motifs et virgules littérales sont en vigueur. Les comparaisons chaînées suivent Python : 10 < cpu_percent < 90 signifie 10 < cpu_percent and cpu_percent < 90. Relisez les anciennes règles avant une mise à niveau : les cibles et les actions déclenchées peuvent changer.

Les motifs sont limités à 4096 caractères ; chaque comparaison d’expression rationnelle dispose de 50 ms. Un motif invalide ou trop lent échoue explicitement. Cela ne constitue pas une limite de durée du cycle complet.

La commande explicite tui ouvre l’interface terminal en lecture seule. Les commandes CLI et cron n’activent jamais curses automatiquement. Les détails de migration figurent dans les notes de version.

Les classes Python internes, diagnostics, abréviations implicites et ordre Docker ne sont pas des interfaces stables. Les évolutions suivent la politique de dépréciation.