hashicorp / consul-template

Dit project biedt een handige manier om waarden van Consul in het bestandssysteem te laden met behulp van de consul-template daemon.

De daemon consul-template ondervraagt een Consul- of Vault-cluster en werkt een willekeurig aantal gespecificeerde sjablonen op het bestandssysteem bij. Als extra bonus kan het optioneel willekeurige commando’s uitvoeren wanneer het update proces is voltooid. Zie de voorbeelden map voor enkele scenario’s waar deze functionaliteit nuttig kan blijken.

De documentatie in deze README komt overeen met de master branch van Consul Template. Deze kan nog niet uitgebrachte functies of andere API’s bevatten dan de meest recent uitgebrachte versie.

Zie a.u.b. de Git tag die overeenkomt met uw versie van Consul Template voor de juiste documentatie.

Inhoudsopgave

• Community Support
• Installatie
• Snel voorbeeld
• Leergidsen
• Configuratie
  • Command Line Flags
  • Configuratiebestand
• Reload Configuratie en Templates
• Templating Language
  • API Functions
  • Scratch
  • Helper Functions
  • Math Functions
• Waarneembaarheid
  • Logging
• Modes
  • Once Mode
  • De-Duplication Mode
  • Exec Mode
• Plugins
• Caveats
  • Docker Image Use
  • Dots in Service Names
  • Termination on Error
  • Commands
    • Environment
    • Multiple Commands
  • Multi-phase Execution
• Running en Process Lifecycle
• Debugging
• FAQ
• Contributing

Community Support

Als u vragen heeft over hoe consul-template werkt, de mogelijkheden of iets anders dan een bug of een verzoek om een functie (gebruik hiervoor de issue tracker op github), raadpleeg dan onze bronnen voor gemeenschapsondersteuning.

Community-portaal: https://discuss.hashicorp.com/c/consul

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

Voor problemen en pull requests gebruiken we bovendien de 👍-reacties als een grof stemsysteem om de prioriteiten van de community te peilen. Voeg dus a.u.b. 👍 toe aan elke issue of pull request waaraan u graag zou willen werken. Bedankt.

Installatie

1. Download een voorgecompileerde, vrijgegeven versie van de Consul Template-releasepagina.

2. Uitpakken van de binary met unzip of tar.

3. Verplaats de binary in $PATH.

Om te compileren vanaf de broncode, zie de instructies in de sectie bijdragen.

Kort voorbeeld

Dit korte voorbeeld gaat ervan uit dat Consul lokaal is geïnstalleerd.

Voor meer voorbeelden en gebruikssituaties, zie de map met voorbeelden in dit archief.

Leergidsen

Naast deze voorbeelden heeft HashiCorp ook gidsen en officiële documentatie gepubliceerd om u te helpen een aantal veelvoorkomende gebruikssituaties van ConsulTemplate te doorlopen.

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

Configuratie

Configuratie-documentatie is verplaatst naar docs/configuratie.md.

Reload Configuration and Templates

Er zijn meerdere manieren om Consul Template te draaien, maar het meest gebruikelijke patroon is om Consul Template als een systeem service te draaien. Wanneer Consul Template voor het eerst wordt gestart, worden configuratiebestanden en sjablonen van de schijf gelezen en in het geheugen geladen. Vanaf dat moment worden wijzigingen in de bestanden op de schijf niet doorgevoerd in het lopende proces zonder opnieuw te laden.

De reden voor dit gedrag is eenvoudig en komt overeen met andere tools zoals haproxy.Een gebruiker wil misschien validatiecontroles uitvoeren op de configuratie of sjablonen voordat ze in het proces worden geladen. Daarnaast kan het zijn dat een gebruiker configuratie en templates tegelijkertijd wil updaten. Consul Template automatisch laten kijken naar deze bestanden en ze opnieuw laden bij wijzigingen is zowel operationeel gevaarlijk als in strijd met sommige paradigma’s van de moderne infrastructuur. In plaats daarvan luistert Consul Template naar de SIGHUP syscall om een configuratie herladen te triggeren. Als je een configuratie of templates update, stuur je gewoon HUP naar het lopende Consul Template proces en Consul Template zal alle configuraties en templates van schijf herladen.

Templating Language

Templating Language documentatie is verplaatst naardocs/templating-language.md.

Caveats

Docker Image Use

De Alpine Docker image is geconfigureerd om een extern volume te ondersteunen om gedeelde templates op te renderen. Indien gemonteerd moet u ervoor zorgen dat deconsul-template gebruiker in de docker image schrijfrechten heeft voor de directory. Ook als je je eigen image bouwt met deze, moet je er zeker van zijn dat je de juiste rechten hebt.

De consul-template gebruiker in docker heeft een UID van 100 en een GID van 1000.

Dit heeft effect op de in image directories /consul-template/config, gebruikt om configuratie toe te voegen wanneer je dit als parent image gebruikt, en /consul-template/data, geëxporteerd als een VOLUME als een locatie om gedeelde resultaten te renderen.

Vorig draaide de image als root om er zeker van te zijn dat de permissies het toelieten. Maar dit ging in tegen de docker best practices en security policies.

Als je je eigen image bouwt op basis van de onze kun je deze waarden overschrijven met--build-arg parameters.

Puntjes in Servicenamen

Het gebruik van puntjes . in servicenamen zal conflicteren met het gebruik van puntjes voor TAGdelineation in de template. Punten interfereren al met het gebruik van DNS voor service namen, dus we raden aan om punten waar mogelijk te vermijden.

Beëindiging bij Fout

De Consul Template is standaard zeer fout-tolerant. Als Consul onbereikbaar is of een sjabloon verandert, zal Consul Template vrolijk doorgaan met draaien. De enige uitzondering op deze regel is als de optionele command niet nul is. In dat geval zal Consul Template ook zonder nul eindigen. De reden hiervoor is dat de gebruiker dan eenvoudig iets als Upstart of God kan configureren om ConsulTemplate als een service te beheren.

Als je wilt dat ConsulTemplate blijft kijken naar wijzigingen, zelfs als het optionele commando-argument faalt, kun je || true aan je commando toevoegen. Merk op dat || een “shell-isme” is, geen ingebouwde functie. U moet uw opdracht ook onder een shell uitvoeren:

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

In dit voorbeeld zal, zelfs als het Nginx-herstartcommando niet nul retourneert, de algemene functie toch een OK-exitcode retourneren; Consul Template zal als een service blijven draaien. Bovendien, als u complexe logica heeft voor het herstarten van uw service, kunt u intelligent kiezen wanneer u wilt dat Consul Template afsluit en wanneer u wilt dat het blijft kijken naar wijzigingen. Voor dit soort complexe scripts raden we aan een aangepast sh of bash script te gebruiken in plaats van de logica direct in het consul-template commando of configuratiebestand te zetten.

Commando’s

Omgeving

De huidige procesomgeving wordt gebruikt bij het uitvoeren van commando’s met de volgende extra omgevingsvariabelen:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Deze omgevingsvariabelen worden met hun huidige waarden geëxporteerd wanneer de opdracht wordt uitgevoerd. Andere Consul-tools lezen deze omgevingsvariabelen, waardoor een soepele integratie met andere Consul-tools (zoals consul maint ofconsul lock) mogelijk is. Bovendien geeft het blootleggen van deze omgevingsvariabelen powerusers de mogelijkheid om hun commandoscript verder aan te passen.

Meerdere commando’s

Het commando dat is geconfigureerd om op sjabloonrendering te worden uitgevoerd, moet een enkel commando zijn. Dat wil zeggen dat u niet meerdere commando’s kunt samenvoegen met &&, ;, |, etc. Dit is een beperking van hoe ze worden uitgevoerd. U kunt dit echter wel doen door de meerdere commando’s te combineren in een expliciet shell commando met sh -c. Dit is waarschijnlijk het beste uit te leggen met een voorbeeld.

Zeg dat je een paar scripts hebt die je moet uitvoeren als een template wordt gerenderd,/opt/foo en /opt/bar, en je wilt dat /opt/bar alleen wordt uitgevoerd als /opt/foo issuccesvol is. U kunt dat doen met het commando…

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

Omdat dit een volledig shell commando is kunt u zelfs conditionals gebruiken.

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

Met deze methode kunt u zoveel shell-opdrachten uitvoeren als u nodig hebt, met welke logica u ook werkt. Als het te lang wordt, kunt u het beter in een shellscript verpakken, implementeren en uitvoeren.

Multi-phase Execution

Consul Template evalueert de sjablonen in n stappen, waarbij de afhankelijkheden bij elke stap worden opgeteld. Dit is nodig vanwege geneste afhankelijkheden, zoals:

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

Tijdens de eerste pass kent Consul Template geen van de services inConsul, dus moet het een query uitvoeren. Wanneer de resultaten worden geretourneerd, wordt de binnenste lus met dat resultaat geëvalueerd, waardoor mogelijk meer query’s en wachttijden ontstaan.

Door deze implementatie hebben sjabloonfuncties een standaardwaarde nodig die een acceptabele parameter is voor een range-functie (of iets dergelijks), maar niet daadwerkelijk de binnenste lus uitvoert (wat een panic zou veroorzaken). Dit is belangrijk om te vermelden omdat complexe sjablonen rekening moeten houden met het “lege” geval. Het volgende zal bijvoorbeeld niet werken:

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

Dit zal een fout geven als:

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

Dit komt omdat, tijdens de eerste evaluatie van het sjabloon, de service-toets een lege slice teruggeeft. U kunt hier rekening mee houden in uw sjabloon, zoals:

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

Dit voegt de afhankelijkheid nog steeds toe aan de lijst met waarnemingen, maar evalueert de inner-if niet, waardoor de out-of-index-fout wordt voorkomen.

FAQ

Q: Waarin verschilt dit van confd?
A: Het antwoord is eenvoudig: Service Discovery als een eerste klas burger. U wordt ook aangemoedigd om deze Pull Request over het project te lezen voor meer achtergrondinformatie. Wij denken dat confd een geweldig project is, maar Consul Template vult een ontbrekend gat. Bovendien heeft Consul Template eersteklas integratie met Vault, waardoor het eenvoudig is om geheim materiaal zoals database-referenties of API-tokens in configuratiebestanden op te nemen.

Q: Hoe is dit anders dan Puppet/Chef/Ansible/Salt?
A: Configuratiemanagementtools zijn ontworpen om samen met Consul Template te worden gebruikt. In plaats van een oud configuratiebestand te renderen, gebruikt u uw configuratiebeheersoftware om een dynamisch sjabloon te renderen dat door Consul wordt gevuld.

Bijdragen

Om Consul-Template lokaal te bouwen en te installeren, moet u Go installeren.

Kloon de repository:

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

Om de consul-template binary voor uw lokale machine te compileren:

$ make dev

Dit zal de consul-template binary in bin/consul-template compileren, evenals uw $GOPATH en de testsuite uitvoeren.

Als u een specifieke binary wilt compileren, stel dan XC_OS en XC_ARCH in of voer het volgende uit om alle binaries te genereren:

$ make build

Als u de tests wilt uitvoeren, installeer dan eerst consul en vault lokaal, dan:

$ make test

Of om een specifieke test in de suite uit te voeren:

go test ./... -run SomeTestFunction_name