hashicorp / consul-template

Ce projet fournit un moyen pratique de peupler les valeurs de Consulinto au système de fichiers en utilisant le démon consul-template.

Le démon consul-template interroge un cluster Consul ou Vault et met à jour un nombre quelconque de modèles spécifiés sur le système de fichiers. Comme un bonus supplémentaire, il peut éventuellement exécuter des commandes arbitraires lorsque le processus de mise à jourcomplet. Veuillez consulter le dossier des exemples pour quelques scénarios où cette fonctionnalité pourrait s’avérer utile.

La documentation de ce README correspond à la branche maître de Consul Template. Elle peut contenir des fonctionnalités non publiées ou des API différentes de celles de la dernière version publiée.

Veuillez consulter la balise Git qui correspond à votre version de Consul Template pour obtenir la documentation appropriée.

Table des matières

• Support communautaire
• Installation
• Exemple rapide
• Guides d’apprentissage
• Configuration
  • Flags de ligne de commande
  • Fichier de configuration
• Reload Configuration. et modèles
• Langage de modélisation
  • Fonctions API
  • Scratch
  • Fonctions d’aide
  • Fonctions mathématiques
• Observabilité
  • Logging
• Modes
  • Mode Une fois
  • De-.Mode Duplication
  • Mode Exec
• Plugins
• Avertissements
  • Utilisation de l’image du docker
  • Points en service. Noms
  • Arrêt sur erreur
  • Commandes
    • Environnement
    • Commandes multiples
  • Exécution à phases multiples
  • .phase
• Exécution et cycle de vie du processus
• Débogage
• FAQ
• Contribuer

Support communautaire

Si vous avez des questions sur le fonctionnement de consul-template, ses capacités ou tout autre chose qu’une demande de bogue ou de fonctionnalité (utilisez le traqueur de problèmes de github pour cela), veuillez consulter nos ressources de support communautaire.

Portail communautaire : https://discuss.hashicorp.com/c/consul

Autres ressources : https://www.consul.io/community.html

En outre, pour les problèmes et les demandes de pull, nous utiliserons les réactions 👍 comme un système de vote approximatif pour aider à évaluer les priorités de la communauté. Donc, s’il vous plaît ajouter 👍à toute question ou demande de pull que vous aimeriez voir travailler sur. Merci.

Installation

1. Téléchargez une version pré-compilée et publiée sur la page des versions de Consul Template.

2. Extrait le binaire en utilisant unzip ou tar.

3. Déplacez le binaire dans $PATH.

Pour compiler à partir des sources, veuillez consulter les instructions dans la sectioncontribuer.

Exemple rapide

Ce court exemple suppose que Consul est installé localement.

Pour plus d’exemples et de cas d’utilisation, veuillez consulter le dossier exemples dansce dépôt.

Guides d’apprentissage

En plus de ces exemples, HashiCorp a publié des guides et une documentation officielle pour aider à parcourir quelques cas d’utilisation courants de ConsulTemplate.

• Consul KV
• Consul Catalog
• Modèles d’agents de sécurité
• Secrets de sécurité

Configuration

La documentation sur la configuration a été déplacée vers docs/configuration.md.

Rechargement de la configuration et des modèles

Bien qu’il existe plusieurs façons d’exécuter Consul Template, le modèle le plus courant consiste à exécuter Consul Template en tant que service système. Lorsque Consul Template démarre, il lit les fichiers de configuration et les modèles sur le disque et les charge en mémoire. À partir de ce moment, les modifications apportées aux fichiers sur le disque ne se propagent pas au processus en cours d’exécution sans un rechargement.

La raison de ce comportement est simple et s’aligne sur d’autres outils comme haproxy.Un utilisateur peut vouloir effectuer des contrôles de validation avant le vol sur la configuration ou les modèles avant de les charger dans le processus. De plus, un utilisateur peut vouloir mettre à jour la configuration et les modèles simultanément. Le fait que Consul Template surveille et recharge automatiquement ces fichiers lors des modifications est à la fois dangereux sur le plan opérationnel et contraire à certains paradigmes de l’infrastructure moderne. Au lieu de cela, Consul Template écoute l’appel système SIGHUP pour déclencher le rechargement de la configuration. Si vous mettez à jour la configuration ou les modèles, il suffit d’envoyer HUP au processus Consul Template en cours d’exécution et Consul Template rechargera toutes lesconfigurations et tous les modèles à partir du disque.

Langage de Templating

La documentation sur le langage de templating a été déplacée vers todocs/templating-language.md.

Caveats

Utilisation de l’image Docker

L’image Docker Alpine est configurée pour supporter un volume externe vers lequel rendre les templates partagés. S’il est monté, vous devrez vous assurer que l’utilisateurconsul-template de l’image docker a les droits d’écriture sur le répertoire. De plus, si vous construisez votre propre image en les utilisant, vous devez vous assurer que vous avez les permissions correctes.

L’utilisateur consul-template dans docker a un UID de 100 et un GID de 1000.

Cela affecte les répertoires dans l’image /consul-template/config, utilisés pour ajouter laconfiguration lors de l’utilisation de ceci comme image parent, et /consul-template/data,exporté comme VOLUME comme emplacement pour rendre les résultats partagés.

Auparavant, l’image s’exécutait initialement en tant que root afin de s’assurer que les permissionsle permettaient. Mais cela allait à l’encontre des meilleures pratiques et des politiques de sécurité de docker.

Si vous construisez votre propre image basée sur la nôtre, vous pouvez remplacer ces valeurs par des paramètres--build-arg.

Points dans les noms de service

L’utilisation de points . dans les noms de service entrera en conflit avec l’utilisation de points pour la désignation des TAG dans le modèle. Les points interfèrent déjà avec l’utilisation duDNSpour les noms de service, nous recommandons donc d’éviter les points dans la mesure du possible.

Termination sur erreur

Par défaut, Consul Template est hautement tolérant aux pannes. Si Consul est injoignable ou qu’un modèle change, Consul Template continuera joyeusement de fonctionner. La seule exception à cette règle est si l’option command sort non nulle. Dans ce cas, Consul Template sort également par une valeur non nulle. La raison de cette décision est pour que l’utilisateur puisse facilement configurer quelque chose comme Upstart ou God pour gérer ConsulTemplate comme un service.

Si vous voulez que Consul Template continue à surveiller les changements, même si l’argument optionnel de la commande échoue, vous pouvez ajouter || true à votre commande. Notez que || est un « shell-ism », et non une fonction intégrée. Vous devrez également exécuter votre commande sous un shell :

$ consul-template \ -template "in.ctmpl:out.file:/bin/bash -c 'service nginx restart || true'"

Dans cet exemple, même si la commande de redémarrage de Nginx renvoie un résultat non nul, la fonction globale renverra un code de sortie OK ; Consul Template continuera de fonctionner en tant que service. De plus, si vous avez une logique complexe pour redémarrer votre service, vous pouvez choisir intelligemment le moment où vous voulez que Consul Template se termine et celui où vous voulez qu’il continue à surveiller les changements. Pour ces types de scripts complexes, nous recommandons d’utiliser un script sh ou bash personnalisé au lieu de mettre la logique directement dans la commande consul-template ou le fichier de configuration.

Commandes

Environnement

L’environnement des processus actuels est utilisé lors de l’exécution des commandes avec les variables d’environnement supplémentaires suivantes :

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Ces variables d’environnement sont exportées avec leurs valeurs actuelles lorsque la commande s’exécute. Les autres outils de Consul lisent ces variables d’environnement,ce qui permet une intégration harmonieuse avec les autres outils de Consul (comme consul maint ouconsul lock). En outre, l’exposition de ces variables d’environnement donne aux powerusers la possibilité de personnaliser davantage leur script de commande.

Commandes multiples

La commande configurée pour être exécutée sur le rendu du modèle doit être une commande unique. C’est-à-dire que vous ne pouvez pas joindre plusieurs commandes avec &&, ;, |, etc.C’est une restriction de la façon dont elles sont exécutées. Cependant, vous êtes en mesure de le faire en combinant les commandes multiples dans une commande shell explicite en utilisant sh -c. Ceci est probablement mieux expliqué par l’exemple.

Disons que vous avez un couple de scripts que vous devez exécuter quand un modèle est rendu,/opt/foo et /opt/bar, et vous voulez seulement que /opt/bar s’exécute si /opt/foo sort avec succès. Vous pouvez le faire avec la commande…

command = "sh -c '/opt/foo && /opt/bar'"

Comme c’est une commande shell complète, vous pouvez même utiliser des conditionnels. Donc accomplit la même chose.

command = "sh -c 'if /opt/foo; then /opt/bar ; fi'"

En utilisant cette méthode, vous pouvez exécuter autant de commandes shell que vous avez besoin avec n’importe quelle logique dont vous avez besoin. Bien qu’il soit suggéré que si cela devient trop long, vous pourriez vouloir l’envelopper dans un script shell, le déployer et l’exécuter.

Exécution multiphase

Consul Template fait une évaluation à n passes des modèles, accumulant les dépendances à chaque passe. Ceci est nécessaire en raison des dépendances imbriquées, telles que :

{{ range services }}{{ range service .Name }} {{ .Address }}{{ end }}{{ end }}

Lors de la première passe, Consul Template ne connaît aucun des services deConsul, il doit donc effectuer une requête. Lorsque ces résultats sont retournés, la boucle interne est alors évaluée avec ce résultat, créant potentiellement plus de requêtes et de montres.

En raison de cette mise en œuvre, les fonctions de modèle ont besoin d’une valeur par défaut qui est un paramètre acceptable pour une fonction range (ou similaire), mais n’exécute pas réellement la boucle interne (ce qui provoquerait une panique). Il est important de le mentionner car les modèles complexes doivent tenir compte du cas « vide ». Par exemple, ce qui suit ne fonctionnera pas :

{{ with index (service "foo") 0 }}# ...{{ end }}

Ceci provoquera une erreur du type :

<index $services 0>: error calling index: index out of range: 0

C’est parce que, pendant la première évaluation du modèle, la clé service renvoie une tranche vide. Vous pouvez en tenir compte dans votre modèle commeo:

{{ with service "foo" }}{{ with index . 0 }}{{ .Node }}{{ end }}{{ end }}

Cela ajoutera toujours la dépendance à la liste des montres, mais n’évaluera pas l’inner-if, évitant l’erreur out-of-index.

FAQ

Q : En quoi est-ce différent de confd?
A : La réponse est simple : La découverte de services en tant que citoyen de première classe. Vous êtes également encouragé à lire cette Pull Request sur le projet pour plus d’informations de fond. Nous pensons que confd est un excellent projet, mais Consul Template comble un manque. En outre, Consul Template a une intégration de première classe avec Vault, ce qui facilite l’incorporation de matériel secret comme les informations d’identification de la base de données ou les jetons API dans les fichiers de configuration.

Q : En quoi est-ce différent de Puppet/Chef/Ansible/Salt?
A : Les outils de gestion de la configuration sont conçus pour être utilisés à l’unisson avec Consul Template. Au lieu de rendre un fichier de configuration périmé, utilisez votre logiciel de gestion de configuration pour rendre un modèle dynamique qui sera peuplé par Consul.

Contribuer

Pour construire et installer Consul-Template localement, vous devrez installer Go.

Cloner le dépôt:

$ git clone https://github.com/hashicorp/consul-template.git

Pour compiler le binaire consul-template pour votre machine locale:

$ make dev

Ceci compilera le binaire consul-template dans bin/consul-template ainsi que votre $GOPATH et exécutera la suite de tests.

Si vous voulez compiler un binaire spécifique, définissez XC_OS et XC_ARCH ou exécutez ce qui suit pour générer tous les binaires:

$ make build

Si vous voulez exécuter les tests, installez d’abord consul et vault localement, puis:

$ make test

Ou pour exécuter un test spécifique dans la suite:

go test ./... -run SomeTestFunction_name

.