hashicorp / consul-template

av

Detta projekt tillhandahåller ett bekvämt sätt att fylla värden från Consultill filsystemet med hjälp av daemon consul-template.

Daemon consul-template frågar efter ett Consul- eller Vaultkluster och uppdaterar ett valfritt antal specificerade mallar i filsystemet. Som en extra bonus kan den valfritt köra godtyckliga kommandon när uppdateringsprocessen avslutas. Se mappen med exempel för några scenarier där denna funktionalitet kan vara användbar.

Dokumentationen i denna README motsvarar mastergrenen av Consul Template. Den kan innehålla outgivna funktioner eller andra API:er än den senast släppta versionen.

Se Git-taggen som motsvarar din version av Consul Template för rätt dokumentation.

Innehållsförteckning

  • Samhällsstöd
  • Installation
  • Snabbt exempel
  • Lärguider
  • Konfiguration
    • Kommandoradsflaggor
    • Konfigurationsfil
  • Reload konfiguration. och mallar
  • Mallspråk
    • API-funktioner
    • Skratch
    • Hjälpfunktioner
    • Matematiska funktioner
  • Observationsförmåga
    • Loggning
  • Metodlägen
    • En gångläge
    • De-Dupliceringsläge
    • Exec-läge
  • Plugins
  • Garanterier
    • Användning av Dockerbild
    • Punkter i tjänsten Names
    • Termination on Error
    • Commands
      • Environment
      • Multiple Commands
    • Multi-phase Execution
  • Running and Process Lifecycle
  • Debugging
  • FAQ
  • Contributing

Community Support

Om du har frågor om hur consul-template fungerar, dess möjligheter eller något annat än en fel- eller funktionsförfrågan (använd githubs problemspårare för dessa), se våra resurser för samhällsstöd.

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

Andra resurser: https://www.consul.io/community.html

För frågor och pull requests kommer vi dessutom att använda 👍 reactionsas a rough voting system to help gauge community priorities. Så lägg gärna till 👍 till varje fråga eller pull request som du vill att vi ska arbeta med. Tack.

Installation

  1. Hämta en förkompilerad, släppt version från sidan Consul Template releases.

  2. Extrahera binärfilen med hjälp av unzip eller tar.

  3. Flytta binären till $PATH.

För att kompilera från källkod, se instruktionerna i avsnittetcontributing.

Snabbt exempel

Det här korta exemplet förutsätter att Consul är installerat lokalt.

För fler exempel och användningsfall, se mappen examples i detta arkiv.

Lär dig guider

Inom dessa exempel har HashiCorp publicerat guider och officiell dokumentation för att hjälpa till att gå igenom några vanliga användningsfall för ConsulTemplate.

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

Configuration

Dokumentationen om konfiguration har flyttats till docs/configuration.md.

Ladda om konfiguration och mallar

Det finns flera sätt att köra Consul Template, men det vanligaste mönstret är att köra Consul Template som en systemtjänst. När Consul Template startar första gången läser den alla konfigurationsfiler och mallar från disken och laddar dem i minnet. Från och med då sprids inte ändringar i filerna på disken till den körda processen utan en omladdning.

Anledningen till detta beteende är enkel och stämmer överens med andra verktyg som haproxy.En användare kanske vill utföra valideringskontroller av konfigurationen eller mallarna före flygning innan de laddas in i processen. Dessutom kan en användare vilja uppdatera konfiguration och mallar samtidigt. Att Consul Template automatiskt bevakar och laddar om dessa filer vid ändringar är både operativt farligt och strider mot några av paradigmen för modern infrastruktur. Istället lyssnar Consul Template på SIGHUP syscall för att utlösa en omladdning av konfigurationen. Om du uppdaterar konfiguration eller mallar skickar du bara HUP till den pågående Consul Template-processen och Consul Template kommer att ladda om alla konfigurationer och mallar från disken.

Templating Language

Templating Language-dokumentationen har flyttats till toocs/templating-language.md.

Caveats

Docker Image Use

Alpine Docker-avbildningen är konfigurerad för att stödja en extern volym för att göra delade mallar till. Om den monteras måste du se till att användarenconsul-template i docker-avbildningen har skrivbehörighet till katalogtjänsten. Om du bygger din egen image med hjälp av dessa måste du också se till att du har rätt behörigheter.

Utomatiseringsanvändaren consul-template i docker har ett UID på 100 och ett GID på 1000.

Det här påverkar de ingående katalogerna /consul-template/config, som används för att lägga till konfiguration när den här bilden används som en överordnad bild, och /consul-template/data, som exporteras som VOLUME som en plats för att återge delade resultat.

Förut kördes bilden först som root för att se till att behörigheterna tillät det. Men detta stred mot dockers bästa praxis och säkerhetspolicy.

Om du bygger en egen avbildning baserad på vår kan du åsidosätta dessa värden med--build-arg parametrar.

Punkter i tjänstens namn

Användning av punkter . i tjänstens namn kommer att stå i konflikt med användningen av punkter för TAGdelineation i mallen. Punkter stör redan användningen avDNS för tjänstens namn, så vi rekommenderar att man undviker punkter när det är möjligt.

Avslutning vid fel

Som standard är Consul Template mycket feltolerant. Om Consul inte går att nå eller om en mall ändras fortsätter Consul Template glatt att köra. Det enda undantaget från denna regel är om det valfria alternativet command inte är noll. I detta fall kommer Consul Template också att sluta utan noll. Anledningen till detta beslut är för att användaren enkelt ska kunna konfigurera något som Upstart eller God för att hantera ConsulTemplate som en tjänst.

Om du vill att Consul Template ska fortsätta att hålla utkik efter ändringar, även om detoptionella kommandoargumentet misslyckas, kan du lägga till || true till ditt kommando. Observera att || är en ”shell-ism”, inte en inbyggd funktion. Du måste också köra ditt kommando under ett skal:

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

I det här exemplet kommer den övergripande funktionen att returnera en OK-exitkod även om kommandot Nginx restart inte returnerar noll, Consul Template kommer att fortsätta att köras som en tjänst. Om du har en komplex logik för omstart av tjänsten kan du dessutom på ett intelligent sätt välja när du vill att Consul Template ska avslutas och när du vill att den ska fortsätta att hålla utkik efter ändringar. För dessa typer av komplexa skript rekommenderar vi att du använder ett anpassat sh- eller bash-skript i stället för att lägga logiken direkt i kommandot consul-template eller konfigurationsfilen.

Kommandon

Miljö

Den aktuella processmiljön används när du utför kommandon med följande ytterligare miljövariabler:

  • CONSUL_HTTP_ADDR
  • CONSUL_HTTP_TOKEN
  • CONSUL_HTTP_AUTH
  • CONSUL_HTTP_SSL
  • CONSUL_HTTP_SSL_VERIFY

Dessa miljövariabler exporteras med sina aktuella värden närkommandot utförs. Andra Consul-verktyg läser dessa miljövariabler, vilket ger en smidig integration med andra Consul-verktyg (som consul maint ellerconsul lock). Att exponera dessa miljövariabler ger dessutom avancerade användare möjlighet att ytterligare anpassa sitt kommandoskript.

Flera kommandon

Kommandot som konfigurerats för att köras vid rendering av mallar måste vara ett endakommando. Det innebär att du inte kan sammanfoga flera kommandon med &&, ;, | etc. Detta är en begränsning av hur de exekveras. Du kan dock göra detta genom att kombinera flera kommandon i ett explicit skalkommando med sh -c. Detta förklaras förmodligen bäst med ett exempel.

Säg att du har ett par skript som du behöver köra när en mall renderas,/opt/foo och /opt/bar, och du vill bara att /opt/bar ska köras om /opt/foo är lyckad. Du kan göra det med kommandot…

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

Då detta är ett fullständigt skalkommando kan du även använda villkor. Så åstadkommer samma sak.

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

Med den här metoden kan du köra så många skalkommandon som du behöver med den logik du behöver. Det föreslås dock att om det blir för långt så kanske du vill slå in det i ett skalskript, distribuera och köra det.

Exekvering i flera faser

Consul Template gör en utvärdering av mallar i n-genomgångar och ackumulerar beroenden vid varje genomgång. Detta krävs på grund av inbäddade beroenden, t.ex.:

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

Under det första passet känner Consul Template inte till någon av tjänsterna iConsul, så den måste utföra en förfrågan. När resultaten returneras utvärderas sedan den inre slingan med det resultatet, vilket kan skapa fler förfrågningar och klockor.

På grund av denna implementering behöver mallfunktioner ett standardvärde som är en godtagbar parameter för en range-funktion (eller liknande), men som inte utför den inre slingan (vilket skulle orsaka en panik). Detta är viktigt att nämna eftersom komplexa mallar måste ta hänsyn till det ”tomma” fallet. Exempelvis fungerar inte följande:

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

Detta ger upphov till ett fel som:

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

Det beror på att servicenyckeln under den första utvärderingen av mallen returnerar ett tomt skikt. Du kan ta hänsyn till detta i din mall som:

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

Detta kommer fortfarande att lägga till beroendet i listan över bevakningar, men kommer inte att utvärdera inner-if, vilket gör att du undviker felet out-of-index.

FAQ

Q: Hur skiljer sig detta från confd?
A: Svaret är enkelt: Service Discovery som en första klassens medborgare. Du uppmanas också att läsa denna Pull Request om projektet för mer bakgrundsinformation. Vi tycker att confd är ett utmärkt projekt, men Consul Template fyller en saknad lucka. Dessutom har Consul Template förstklassig integration med Vault, vilket gör det enkelt att införliva hemligt material som databasreferenser eller API-token i konfigurationsfiler.

Q: Hur skiljer sig detta från Puppet/Chef/Ansible/Salt?
A: Konfigurationshanteringsverktygen är utformade för att användas tillsammans med Consul Template. Istället för att rendera en gammal konfigurationsfil använder du ditt konfigurationshanteringsprogram för att rendera en dynamisk mall som kommer att fyllas på av Consul.

Bidra

För att bygga och installera Consul-Template lokalt måste du installera Go.

Klona repository:

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

För att kompilera binärfilen consul-template för din lokala maskin:

$ make dev

Detta kommer att kompilera binärfilen consul-template till bin/consul-template samt din $GOPATH och köra testsviten.

Om du vill kompilera en specifik binärfil, ställ in XC_OS och XC_ARCH eller kör följande för att generera alla binärer:

$ make build

Om du vill köra testerna, installera först consul och vault lokalt, sedan:

$ make test

Och för att köra ett specifikt test i sviten:

go test ./... -run SomeTestFunction_name

Lämna en kommentar