hashicorp / consul-template

Dieses Projekt bietet eine bequeme Möglichkeit, Werte aus Consulin mit Hilfe des consul-template-Daemons in das Dateisystem zu übertragen.

Der Daemon consul-template fragt einen Consul- oder Vault-Cluster ab und aktualisiert eine beliebige Anzahl angegebener Vorlagen im Dateisystem. Als zusätzlicher Bonus kann er optional beliebige Befehle ausführen, wenn der Aktualisierungsprozess abgeschlossen ist. Im Ordner mit den Beispielen finden Sie einige Szenarien, in denen sich diese Funktionalität als nützlich erweisen könnte.

Die Dokumentation in dieser README bezieht sich auf den Master-Zweig von Consul Template. Sie kann unveröffentlichte Funktionen oder andere APIs als die zuletzt veröffentlichte Version enthalten.

Bitte sehen Sie sich das Git-Tag an, das Ihrer Version von Consul Template entspricht, um die richtige Dokumentation zu erhalten.

Inhaltsverzeichnis

• Community Support
• Installation
• Schnellbeispiel
• Learn Guides
• Konfiguration
  • Befehlszeilenflags
  • Konfigurationsdatei
• Konfiguration wiederherstellen und Vorlagen
• Vorlagensprache
  • API-Funktionen
  • Scratch
  • Helferfunktionen
  • Mathematische Funktionen
• Beobachtbarkeit
  • Protokollierung
• Modi
  • Einmal-Modus
  • De-Dupliziermodus
  • Ausführungsmodus
• Plugins
• Hinweise
  • Docker-Image-Verwendung
  • Punkte im Dienst Namen
  • Abbruch bei Fehler
  • Befehle
    • Umgebung
    • Mehrere Befehle
  • Mehrf.phase Execution
• Running and Process Lifecycle
• Debugging
• FAQ
• Contributing

Community Support

Wenn Sie Fragen zur Funktionsweise von consul-template, seine Fähigkeiten oder irgendetwas anderes als einen Fehler oder eine Funktionsanfrage (verwenden Sie dazu den Issue Tracker von Github), sehen Sie sich bitte unsere Community-Support-Ressourcen an.

Gemeinschaftsportal: https://discuss.hashicorp.com/c/consul

Andere Ressourcen: https://www.consul.io/community.html

Zusätzlich werden wir für Issues und Pull-Requests die 👍-Reaktionen als grobes Abstimmungssystem nutzen, um die Prioritäten der Community zu messen. Also füge bitte 👍 zu jedem Issue oder Pull Request hinzu, an dem du gerne arbeiten würdest. Danke.

Installation

1. Laden Sie eine vorkompilierte, freigegebene Version von der Consul Template-Releases-Seite herunter.

2. Extrahieren Sie die Binärdatei mit unzip oder tar.

3. Verschieben Sie die Binärdatei nach $PATH.

Um aus dem Quellcode zu kompilieren, beachten Sie bitte die Anweisungen im AbschnittBeiträge.

Schnelles Beispiel

Dieses kurze Beispiel setzt voraus, dass Consul lokal installiert ist.

Weitere Beispiele und Anwendungsfälle finden Sie im Ordner examples in diesem Repository.

Leitfäden

Zusätzlich zu diesen Beispielen hat HashiCorp Leitfäden und eine offizielle Dokumentation veröffentlicht, um einige häufige Anwendungsfälle für ConsulTemplate zu erläutern.

• Consul KV
• Consul Catalog
• Vault Agent Templates
• Vault Secrets

Configuration

Die Konfigurationsdokumentation wurde nach docs/configuration verschoben.md.

Konfiguration und Vorlagen neu laden

Es gibt zwar mehrere Möglichkeiten, Consul Template auszuführen, aber das häufigste Muster ist, Consul Template als Systemdienst auszuführen. Wenn Consul Template zum ersten Mal startet, liest es alle Konfigurationsdateien und Vorlagen von der Festplatte und lädt sie in den Speicher. Von diesem Zeitpunkt an werden Änderungen an den Dateien auf der Festplatte ohne erneutes Laden nicht mehr an den laufenden Prozess weitergegeben.

Der Grund für dieses Verhalten ist einfach und entspricht dem anderer Tools wie haproxy.Ein Benutzer möchte möglicherweise vor dem Laden in den Prozess Validierungsprüfungen an der Konfiguration oder den Vorlagen durchführen. Außerdem kann es sein, dass ein Benutzer die Konfiguration und die Vorlagen gleichzeitig aktualisieren möchte. Wenn Consul Template diese Dateien automatisch überwacht und bei Änderungen neu lädt, ist dies sowohl betrieblich gefährlich als auch gegen einige der Paradigmen moderner Infrastrukturen. Stattdessen wartet Consul Template auf den SIGHUP Syscall, um einen Konfigurationsreload auszulösen. Wenn Sie die Konfiguration oder Vorlagen aktualisieren, senden Sie einfach HUP an den laufenden Consul Template-Prozess und Consul Template lädt alle Konfigurationen und Vorlagen von der Festplatte neu.

Templating Language

Die Dokumentation der Templating Language wurde nachdocs/templating-language.md verschoben.

Caveats

Verwendung von Docker-Images

Das Alpine Docker-Image ist so konfiguriert, dass es ein externes Volume unterstützt, auf dem gemeinsam genutzte Templates gerendert werden. Wenn es eingebunden wird, müssen Sie sicherstellen, dass der Benutzerconsul-template im Docker-Image Schreibrechte für das Verzeichnis hat. Auch wenn Sie Ihr eigenes Image damit erstellen, müssen Sie sicherstellen, dass Sie die richtigen Berechtigungen haben.

Der Benutzer consul-template in docker hat eine UID von 100 und eine GID von 1000.

Dies hat Auswirkungen auf die Verzeichnisse /consul-template/config, die zum Hinzufügen von Konfigurationen verwendet werden, wenn dieses Image als übergeordnetes Image verwendet wird, und /consul-template/data, das als VOLUME exportiert wird, um gemeinsame Ergebnisse zu rendern.

Vormals wurde das Image zunächst als root ausgeführt, um sicherzustellen, dass die Berechtigungen dies zulassen. Dies verstieß jedoch gegen die bewährten Praktiken und Sicherheitsrichtlinien von Docker.

Wenn Sie Ihr eigenes Image auf der Grundlage unseres erstellen, können Sie diese Werte mit--build-arg Parametern überschreiben.

Punkte in Servicenamen

Die Verwendung von Punkten . in Servicenamen führt zu einem Konflikt mit der Verwendung von Punkten für die TAGdelineation im Template. Punkte stören bereits bei der Verwendung vonDNS für Servicenamen, daher empfehlen wir, Punkte zu vermeiden, wo immer es möglich ist.

Beendigung bei Fehler

Standardmäßig ist Consul Template hoch fehlertolerant. Wenn Consul nicht erreichbar ist oder eine Vorlage geändert wird, läuft Consul Template problemlos weiter. Die einzige Ausnahme von dieser Regel ist, wenn das optionale command einen Wert ungleich Null hat. In diesem Fall wird Consul Template ebenfalls mit einem Wert ungleich Null beendet. Der Grund für diese Entscheidung ist, dass der Benutzer leicht etwas wie Upstart oder God konfigurieren kann, um ConsulTemplate als Dienst zu verwalten.

Wenn Sie möchten, dass Consul Template weiterhin auf Änderungen achtet, auch wenn das optionale Befehlsargument fehlschlägt, können Sie || true an Ihren Befehl anhängen. Beachten Sie, dass || ein „Shell-ismus“ ist, keine eingebaute Funktion. Außerdem müssen Sie Ihren Befehl in einer Shell ausführen:

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

In diesem Beispiel gibt die Gesamtfunktion einen OK-Exit-Code zurück, selbst wenn der Nginx-Neustart-Befehl einen Wert ungleich Null zurückgibt; Consul Template wird weiterhin als Dienst ausgeführt. Wenn Sie eine komplexe Logik für den Neustart Ihres Dienstes haben, können Sie außerdem intelligent auswählen, wann Consul Template beendet werden soll und wann es weiterhin nach Änderungen suchen soll. Für diese Art von komplexen Skripten empfehlen wir die Verwendung eines benutzerdefinierten sh- oder bash-Skripts, anstatt die Logik direkt in den consul-template-Befehl oder die Konfigurationsdatei zu schreiben.

Befehle

Umgebung

Die aktuelle Prozessumgebung wird bei der Ausführung von Befehlen mit den folgenden zusätzlichen Umgebungsvariablen verwendet:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Diese Umgebungsvariablen werden mit ihren aktuellen Werten exportiert, wenn derBefehl ausgeführt wird. Andere Consul-Werkzeuge lesen diese Umgebungsvariablen und sorgen für eine reibungslose Integration mit anderen Consul-Werkzeugen (wie consul maint oderconsul lock). Außerdem können Power-User durch die Offenlegung dieser Umgebungsvariablen ihr Befehlsskript weiter anpassen.

Mehrere Befehle

Der Befehl, der für die Ausführung beim Rendering von Vorlagen konfiguriert ist, muss ein einzelner Befehl sein. Das heißt, Sie können nicht mehrere Befehle mit &&, ;, |, usw. verbinden. Sie können dies jedoch tun, indem Sie die mehreren Befehle in einem expliziten Shell-Befehl mit sh -c kombinieren. Dies lässt sich wahrscheinlich am besten anhand eines Beispiels erklären:

Angenommen, Sie haben zwei Skripte, die Sie ausführen müssen, wenn eine Vorlage gerendert wird,/opt/foo und /opt/bar, und Sie möchten, dass /opt/bar nur ausgeführt wird, wenn /opt/foo erfolgreich ist. Das können Sie mit dem Befehl…

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

Da dies ein vollständiger Shell-Befehl ist, können Sie sogar Konditionale verwenden. So erreicht man dasselbe.

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

Mit dieser Methode kann man so viele Shell-Befehle ausführen, wie man braucht, und zwar mit der Logik, die man braucht. Es wird jedoch vorgeschlagen, dass Sie es in ein Shell-Skript verpacken, verteilen und ausführen, wenn es zu lang wird.

Mehrphasige Ausführung

Consul Template führt eine n-Pass-Evaluierung von Vorlagen durch, wobei bei jedem Durchgang Abhängigkeiten akkumuliert werden. Dies ist aufgrund von verschachtelten Abhängigkeiten erforderlich, wie z.B.:

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

Im ersten Durchlauf kennt Consul Template keinen der Dienste inConsul, so dass es eine Abfrage durchführen muss. Wenn diese Ergebnisse zurückgegeben werden, wird die innere Schleife mit diesem Ergebnis ausgewertet, wodurch möglicherweise weitere Abfragen und Überwachungen erzeugt werden.

Aufgrund dieser Implementierung benötigen Template-Funktionen einen Standardwert, der ein akzeptabler Parameter für eine range-Funktion (oder ähnliches) ist, aber die innere Schleife nicht tatsächlich ausführt (was eine Panik verursachen würde). Dies ist wichtig zu erwähnen, da komplexe Vorlagen den „leeren“ Fall berücksichtigen müssen. Zum Beispiel wird das Folgende nicht funktionieren:

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

Das wird einen Fehler auslösen wie:

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

Das liegt daran, dass der serviceSchlüssel bei der ersten Auswertung der Vorlage ein leeres Slice zurückgibt. Sie können dies in Ihrer Vorlage wie folgt berücksichtigen:

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

Dies fügt die Abhängigkeit immer noch zur Liste der Watches hinzu, wertet aber das Inner-if nicht aus, wodurch der Out-of-Index-Fehler vermieden wird.

FAQ

Q: Was ist der Unterschied zu confd?
A: Die Antwort ist einfach: Service Discovery ist ein Bürger erster Klasse. Sie sollten auch diesen Pull Request über das Projekt lesen, um weitere Hintergrundinformationen zu erhalten. Wir denken, dass confd ein großartiges Projekt ist, aber Consul Template füllt eine fehlende Lücke. Darüber hinaus verfügt Consul Template über eine erstklassige Integration mit Vault, die es einfach macht, geheimes Material wie Datenbankanmeldeinformationen oder API-Token in Konfigurationsdateien einzubinden.

Q: Was ist der Unterschied zu Puppet/Chef/Ansible/Salt?
A: Konfigurationsmanagement-Tools sind so konzipiert, dass sie zusammen mit Consul Template verwendet werden können. Anstatt eine veraltete Konfigurationsdatei zu rendern, verwenden Sie Ihre Konfigurationsmanagement-Software, um eine dynamische Vorlage zu rendern, die von Consul ausgefüllt wird.

Contributing

Um Consul-Template lokal zu erstellen und zu installieren, müssen Sie Go installieren.

Klonen Sie das Repository:

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

Um die consul-template-Binärdatei für Ihren lokalen Rechner zu kompilieren:

$ make dev

Dies kompiliert die consul-template-Binärdatei in bin/consul-template sowie Ihre $GOPATH und führt die Testsuite aus.

Wenn Sie eine bestimmte Binärdatei kompilieren wollen, setzen Sie XC_OS und XC_ARCH oder führen Sie folgendes aus, um alle Binärdateien zu generieren:

$ make build

Wenn Sie die Tests ausführen wollen, installieren Sie zuerst consul und vault lokal, dann:

$ make test

oder um einen bestimmten Test in der Suite auszuführen:

go test ./... -run SomeTestFunction_name