hashicorp / consul-template

Dette projekt giver en bekvem måde at udfylde værdier fra Consultiltil filsystemet ved hjælp af consul-template-dæmonen.

Dæmonen consul-template forespørger et Consul- eller Vaultcluster og opdaterer et vilkårligt antal angivne skabeloner på filsystemet. Som en ekstra bonus kan den valgfrit køre vilkårlige kommandoer, når opdateringsprocessen afsluttes. Se venligst mappen eksempler for nogle scenarier, hvordenne funktionalitet kan vise sig nyttig.

Dokumentationen i denne README svarer til mastergrenen af Consul Template. Den kan indeholde uudgivne funktioner eller andre API’er end den senest udgivne version.

Se venligst det Git-tag, der svarer til din version af Consul Template, for at få den korrekte dokumentation.

Indholdsfortegnelse

• Samfundssupport
• Installation
• Kort eksempel
• Læringsvejledninger
• Konfiguration
  • Kommandolinjeflag
  • Konfigurationsfil
• Installeringsfil

Community Support

Hvis du har spørgsmål om, hvordan consul-template fungerer, dets muligheder eller noget andet end en fejl eller en anmodning om en funktion (brug githubs problemtracker til disse), så se venligst vores ressourcer til fællesskabsstøtte.

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

Andre ressourcer: https://discuss.hashicorp.com/c/consul

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

For issues og pull requests vil vi desuden bruge 👍 reactionsas et groft afstemningssystem til at hjælpe med at måle fællesskabets prioriteter. Så tilføj venligst 👍 til ethvert issue eller pull request, som du gerne vil have, at der arbejdes på. Tak.

Installation

1. Download en forkompileret, frigivet version fra siden Consul Template releases.

2. Udpak den binære fil ved hjælp af unzip eller tar.

3. Flyt den binære fil til $PATH.

For at kompilere fra kildekode, se venligst instruktionerne i afsnittetbidrag.

Hurtigt eksempel

Dette korte eksempel forudsætter, at Consul er installeret lokalt.

For flere eksempler og anvendelsestilfælde, se venligst mappen eksempler i dette arkiv.

Lær vejledninger

Ud over disse eksempler har HashiCorp udgivet vejledninger ogofficiel dokumentation for at hjælpe med at gennemgå nogle få almindelige anvendelsestilfælde for ConsulTemplate.

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

Configuration

Dokumentation om konfiguration er blevet flyttet til docs/configuration.md.

Genindlæsning af konfiguration og skabeloner

Selv om der er flere måder at køre Consul Template på, er det mest almindelige mønsterat køre Consul Template som en systemtjeneste. Når Consul Template starter første gang, læser den eventuelle konfigurationsfiler og skabeloner fra disken og indlæser dem i hukommelsen. Fra det tidspunkt og fremefter overføres ændringer i filerne på disken ikke til den kørende proces uden en genindlæsning.

Grunden til denne adfærd er enkel og stemmer overens med andre værktøjer som haproxy.En bruger ønsker måske at udføre valideringskontroller af konfigurationen eller skabelonerne før flyvningen, før de indlæses i processen. Desuden kan en bruger ønske at opdatere konfiguration og skabeloner samtidig. At Consul Template automatisk overvåger og genindlæser disse filer ved ændringer er både operationelt farligt og i strid med nogle af paradigmerne i moderne infrastruktur. I stedet lytter Consul Template efter SIGHUP syscall for at udløse en genindlæsning af konfigurationen. Hvis du opdaterer konfigurationen eller skabeloner, skal du blot sende HUP til den igangværende Consul Template-proces, og Consul Template vil genindlæse alle konfigurationer og skabeloner fra disken.

Templating Language

Dokumentationen til Templating Language er blevet flyttet til toocs/templating-language.md.

Caveats

Docker Image Use

Alpine Docker image er konfigureret til at understøtte et eksternt volumen til at gengive delte skabeloner til. Hvis den er monteret, skal du sikre dig, atconsul-template-brugeren i docker-aftrykket har skrivetilladelser til denmappe. Hvis du opbygger dit eget image ved hjælp af disse, skal du også sikre dig, at du har de korrekte tilladelser.

Brugeren consul-template i docker har et UID på 100 og et GID på 1000.

Dette påvirker mapperne i billedet /consul-template/config, der bruges til at tilføje konfiguration, når dette bruges som et overordnet billede, og /consul-template/data, der eksporteres som et VOLUME som en placering til at gengive delte resultater.

Tidligere kørte billedet oprindeligt som root for at sikre, at tilladelserne tillod det. Men dette løb imod docker bedste praksis og sikkerhedspolitikker.

Hvis du bygger dit eget image baseret på vores, kan du tilsidesætte disse værdier med--build-arg parametre.

Punkter i servicenavne

Brug af prikker . i servicenavne vil være i konflikt med brugen af prikker til TAGdelineation i skabelonen. Punkter forstyrrer allerede brugen afDNS til servicenavne, så vi anbefaler at undgå punkter, hvor det er muligt.

Afslutning ved fejl

Som standard er Consul Template meget fejltolerant. Hvis Consul er utilgængelig elleren skabelon ændres, fortsætter Consul Template gladeligt med at køre. Den enesteundtagelse til denne regel er, hvis den valgfrie command afsluttes ikke-nul. I dette tilfælde vil Consul Template også afsluttes uden nul. Grunden til denne beslutning er, at brugeren nemt kan konfigurere noget som Upstart eller God til at administrere Consul Template som en tjeneste.

Hvis du vil have Consul Template til at fortsætte med at holde øje med ændringer, selv hvis det valgfrie kommandoargument mislykkes, kan du tilføje || true til din kommando. Bemærk, at || er en “shell-isme”, ikke en indbygget funktion. Du skal også køre din kommando under en shell:

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

I dette eksempel vil den overordnede funktion stadig returnere en OK-exitkode, selv hvis Nginx-genstartkommandoen returnerer en anden værdi end nul, og Consul Template vil fortsætte med at køre som en tjeneste. Hvis du har en kompleks logik for genstart af din tjeneste, kan du desuden på intelligent vis vælge, hvornår Consul Template skal afsluttes, og hvornår den skal fortsætte med at holde øje med ændringer. For disse typer af komplekse scripts anbefaler vi, at du bruger et brugerdefineret sh- eller bash-script i stedet for at sætte logikken direkte i consul-template-kommandoen eller konfigurationsfilen.

Kommandoer

Miljø

Det aktuelle procesmiljø bruges ved udførelse af kommandoer med følgende yderligere miljøvariabler:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Disse miljøvariabler eksporteres med deres aktuelle værdier, nårkommandoen udføres. Andre Consul-værktøjer læser disse miljøvariabler, hvilket giver en problemfri integration med andre Consul-værktøjer (som consul maint ellerconsul lock). Desuden giver eksponering af disse miljøvariabler powerusers mulighed for at tilpasse deres kommandoscript yderligere.

Flere kommandoer

Kommandoen, der er konfigureret til at blive kørt ved rendering af skabeloner, skal være en enkeltkommando. Det vil sige, at du ikke kan sammenføje flere kommandoer med &&, ;, | osv.Dette er en begrænsning af, hvordan de udføres. Du kan dog gøre dette ved at kombinere de flere kommandoer i en eksplicit shell-kommando med sh -c. Dette forklares nok bedst ved hjælp af et eksempel.

Sæt, du har et par scripts, som du skal køre, når en skabelon gengives,/opt/foo og /opt/bar, og du ønsker kun, at /opt/bar skal køre, hvis /opt/foo issuccessful. Det kan du gøre med kommandoen …

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

Da dette er en fuld shell-kommando, kan du endda bruge conditionals. Så opnår du det samme.

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

Med denne metode kan du køre så mange shell-kommandoer, som du har brug for, med den logik, du har brug for. Det foreslås dog, at hvis det bliver for langt, kan du måske pakke det ind i et shellscript, implementere og køre det.

Udførelse i flere faser

Consul Template foretager en n-pass-evaluering af skabeloner og akkumulerer afhængigheder ved hver passage. Dette er nødvendigt på grund af indlejrede afhængigheder, f.eks.:

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

I det første gennemløb kender Consul-skabelonen ikke nogen af tjenesterne iConsul , så den skal udføre en forespørgsel. Når disse resultater returneres, evalueres den indre sløjfe derefter med dette resultat, hvilket potentielt skaber flere forespørgsler og ure.

På grund af denne implementering har skabelonfunktioner brug for en standardværdi, som er en acceptabel parameter for en range-funktion (eller lignende), men som ikke rent faktisk udfører den indre sløjfe (hvilket ville forårsage panik). Dette er vigtigt at nævne, fordi komplekse skabeloner skal tage højde for det “tomme” tilfælde. Eksempelvis vil følgende ikke fungere:

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

Dette vil give en fejl som:

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

Det skyldes, at servicenøglen under den første evaluering af skabelonen returnerer en tom skive. Du kan tage højde for dette i din skabelon som:

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

Dette vil stadig tilføje afhængigheden til listen over ure, men vil ikke evaluere inner-if’et, hvorved du undgår out-of-index-fejlen.

FAQ

Q: Hvordan er dette anderledes end confd?
A: Svaret er enkelt: Service Discovery som en førsteklasses borger. Du opfordres også til at læse denne Pull Request om projektet for at få flere baggrundsoplysninger. Vi synes, at confd er et godt projekt, men Consul Template udfylder et manglende hul. Derudover har Consul Template førsteklasses integration med Vault, hvilket gør det nemt at inkorporere hemmeligt materiale som databaseoplysninger eller API-tokens i konfigurationsfiler.

Q: Hvordan er dette anderledes end Puppet/Chef/Ansible/Salt?
A: Konfigurationshåndteringsværktøjer er designet til at blive brugt i samspil med Consul Template. I stedet for at gengive en forældet konfigurationsfil skal du bruge dit konfigurationshåndteringsprogram til at gengive en dynamisk skabelon, der vil blive udfyldt af Consul.

Bidrage

For at bygge og installere Consul-Template lokalt skal du installere Go.

Klonér repositoriet:

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

For at kompilere consul-templatebinærfilen til din lokale maskine:

$ make dev

Dette vil kompilere consul-templatebinærfilen til bin/consul-template samt din $GOPATH og køre testpakken.

Hvis du ønsker at kompilere en specifik binær fil, skal du indstille XC_OS og XC_ARCH eller køre følgende for at generere alle binære filer:

$ make build

Hvis du ønsker at køre testene, skal du først installere consul og vault lokalt og derefter:

$ make test

Og for at køre en specifik test i suiten:

go test ./... -run SomeTestFunction_name