Configuration

La configuration Apprise repose sur une abstraction centrale unique : AppriseConfig.

Cet objet est chargé de charger, résoudre et produire des définitions de services de notification consommables par la CLI Apprise, l’Apprise-API ou des applications Python embarquées.

Contrairement aux services de notification, la configuration n’envoie pas de messages. Elle définit ce qui peut envoyer des messages, comment ces éléments sont groupés et comment ils sont découverts.

AppriseConfig

AppriseConfig est le chargeur de configuration central utilisé partout dans Apprise.

Il est responsable de :

• charger des définitions de notification depuis une ou plusieurs sources ;
• résoudre les directives include ;
• appliquer le filtrage par tags ;
• produire une configuration unifiée consommable par Apprise.

Chaque exécution d’Apprise, quelle que soit son interface, s’appuie au final sur une instance de AppriseConfig.

from apprise import Apprise, AppriseConfig

apprise = Apprise()
config = AppriseConfig()

config.add('config.yml')
apprise.add(config)

apprise.notify(
    title='Statut',
    body='Tous les systèmes sont opérationnels',
)

Modèles de configuration courants

Source unique

from apprise import Apprise, AppriseConfig

apprise = Apprise()
config = AppriseConfig()

config.add('config.yml')
apprise.add(config)

apprise.notify(
    title='Configuration unique',
    body='Chargé depuis une seule source de configuration',
)

Sources multiples

Les sources de configuration sont traitées dans l’ordre où elles sont ajoutées. Toutes les entrées valides de chaque source sont fusionnées dans une seule configuration effective.

from apprise import Apprise, AppriseConfig

apprise = Apprise()
config = AppriseConfig()

config.add('config-1.yml')
config.add('config-2.yml')

apprise.add(config)

apprise.notify(
    title='Configurations multiples',
    body='Chargé depuis plusieurs sources de configuration',
)

Source distante

Du point de vue de AppriseConfig, les sources de configuration distantes sont traitées de la même manière que les sources locales. Toute restriction concernant la configuration distante est appliquée par l’environnement hôte qui sert cette configuration.

from apprise import Apprise, AppriseConfig

apprise = Apprise()
config = AppriseConfig()

config.add('https://apprise.example.com/cfg/mykey')
apprise.add(config)

apprise.notify(
    title='Configuration distante',
    body='Configuration chargée depuis un emplacement distant',
)

Sources de configuration

Une instance de AppriseConfig peut charger la configuration depuis plusieurs sources. Chaque source est traitée puis fusionnée dans une seule configuration effective.

Les sources prises en charge incluent :

• les fichiers locaux ;
• les URL distantes ;
• la configuration en mémoire ;
• le contenu de configuration inline.

Chaque source est traitée uniformément par le moteur de configuration, quelle que soit son origine.

Formats de configuration

Apprise prend en charge les fichiers de configuration texte et YAML. Les formats sont équivalents sur le plan fonctionnel, mais structurés différemment.

Pour une explication côte à côte et des exemples, consultez Bien démarrer : configuration.

Paramètres d’URL en YAML

La configuration YAML peut décrire une URL Apprise comme une simple chaîne ou comme une correspondance avec des clés supplémentaires :

urls:
  - mailto://gmail.com:
      user: alerts
      password: "myP@ss#w0rd!"
      to: ops@example.com
      tag: ops

Les clés YAML sont fusionnées avec l’URL analysée avant la création du plugin. Les champs d’URL courants comme user, password, host, port, verify et tag peuvent être fournis ainsi, tout comme les paramètres propres au service indiqués dans son tableau de paramètres.

Lorsqu’une liste est placée sous une URL, Apprise crée une définition de service par élément de liste. Chaque élément part de la même URL analysée, puis applique ses propres valeurs YAML :

urls:
  - mailto://user:pass@gmail.com:
      - to: manager@example.com
        tag: boss
      - to: coworker@example.com
        tag: new-hire

Cela charge deux services email avec des identifiants partagés et des destinations différentes.

Includes

La directive include permet à une source de configuration d’en référencer une autre.

Les inclusions sont résolues récursivement et peuvent servir à :

• partager des définitions de notification communes ;
• centraliser la configuration ;
• superposer des configurations propres à un environnement ;
• réduire la duplication.

Du point de vue de AppriseConfig, une inclusion n’est qu’une autre source de configuration à charger puis fusionner.

Les inclusions peuvent référencer :

• des fichiers locaux ;
• des URL distantes.

Les inclusions sont résolues dans l’ordre où elles sont rencontrées.

Empilement et précédence

Les sources de configuration sont traitées séquentiellement.

Les sources ajoutées plus tard peuvent :

• ajouter de nouvelles définitions de notification ;
• étendre des entrées existantes ;
• affiner les tags et le routage.

Apprise n’impose pas de modèle fixe base/surcharge. Toutes les entrées sont additives, sauf si elles sont explicitement filtrées ou contraintes par des tags.

Règles de sécurité entre inclusions

Pour éviter des comportements de configuration dangereux ou non souhaités, Apprise applique des règles de sécurité lors de la résolution des inclusions.

Ces règles contrôlent si une source de configuration peut en inclure une autre d’un type différent.

Par exemple :

• un fichier local peut inclure un autre fichier local ;
• une source de configuration distante peut être empêchée d’inclure arbitrairement des fichiers locaux ;
• la profondeur de récursion est limitée afin d’éviter les boucles infinies.

Ces règles sont appliquées par le moteur de configuration et peuvent varier selon l’environnement hôte.

Sources de configuration distantes authentifiées

Les sources de configuration distantes peuvent nécessiter une authentification.

Avec des URL HTTP ou HTTPS, les identifiants d’authentification basique peuvent être intégrés directement dans l’URL :

config = AppriseConfig()
config.add('https://user:pass@apprise.example.com/cfg/mykey')

Sous cette forme, les identifiants sont utilisés automatiquement lors de la récupération de la configuration.

Attention

Intégrer des identifiants directement dans une URL peut les exposer dans les journaux, l’historique du shell ou la liste des processus.

Lorsque c’est possible, préférez d’autres mécanismes d’authentification ou assurez-vous que l’accès aux URL de configuration est convenablement restreint.

Sécurité et frontières de confiance

AppriseConfig n’applique pas lui-même la politique de sécurité.

Il est responsable du chargement et de la résolution de la configuration, mais les décisions de confiance sont appliquées par l’environnement hôte.

Par exemple :

• la CLI Apprise peut autoriser librement les inclusions locales ;
• un serveur Apprise-API en cours d’exécution peut restreindre les sources autorisées ;
• des applications embarquées peuvent imposer leurs propres contraintes de sécurité.

Si une source de configuration est rejetée en raison de la politique de l’hôte, elle est exclue avant la fusion finale.

Verrouillage de configuration dans Apprise-API

Lorsque la configuration est hébergée par une instance Apprise-API, des contrôles de sécurité supplémentaires peuvent s’appliquer.

Un serveur Apprise-API peut activer le verrouillage de configuration afin d’empêcher des clients distants de charger la configuration côté serveur.

Quand ce verrouillage est activé :

• les inclusions distantes ciblant l’Apprise-API sont rejetées ;
• les endpoints de configuration ne peuvent pas être consommés par des clients externes ;
• seule la configuration définie localement est autorisée.

Ce comportement est appliqué par le serveur Apprise-API, pas par AppriseConfig lui-même.

Le verrouillage de configuration existe pour empêcher :

• l’exposition accidentelle d’identifiants ;
• la découverte non autorisée de configuration ;
• les attaques SSRF.

Le verrouillage de configuration n’affecte pas :

• les fichiers de configuration locaux ;
• la configuration en mémoire ;
• les sources de configuration personnalisées hébergées en dehors d’Apprise-API.

Tags et filtrage

Les entrées de configuration peuvent être associées à un ou plusieurs tags.

Les tags servent à contrôler quels services de notification seront sélectionnés lors de l’envoi d’un message.

Le filtrage peut servir à :

• inclure uniquement les tags correspondants ;
• toujours inclure les services non tagués ;
• combiner plusieurs tags avec une sémantique OU ou ET.

La résolution des tags s’effectue au moment de la notification, pas pendant le chargement de la configuration.

Lors d’un envoi via la bibliothèque Python, notify(tag=...) suit ces règles :

Expression notify(tag=...)	Services sélectionnés
"TagA"	Possède TagA
"TagA,TagB"	Possède TagA ET TagB
["TagA", "TagB"]	Possède TagA OU TagB
["TagA,TagC", "TagB"]	Possède (TagA ET TagC) OU TagB

Note

Les listes sont évaluées comme des groupes OU. Pour exprimer ET par programme, utilisez une chaîne séparée par des virgules dans l’argument tag.

Étapes suivantes

• Pour l’utilisation de la CLI et ses options, consultez la documentation CLI
• Pour les endpoints Apprise-API et les contrôles de sécurité, consultez la documentation Apprise-API
• Pour les définitions de services de notification, consultez Ressources et image de marque
• Pour l’escalade par priorité, les tentatives/délai par service et les remplacements par appel, consultez Routage par Tags & Tentatives