hashicorp / consul-template

Acest proiect oferă o modalitate convenabilă de a popula valorile din Consulîn sistemul de fișiere folosind demonul consul-template.

Demonul consul-templateinteroghează un Consul sau Vaultcluster și actualizează orice număr de șabloane specificate pe sistemul de fișiere. Ca un bonus suplimentar, acesta poate rula opțional comenzi arbitrare atunci când procesul de actualizare se finalizează. Vă rugăm să consultați dosarul de exemple pentru câteva scenarii în care această funcționalitate s-ar putea dovedi utilă.

Documentația din acest README corespunde ramurii master a Consul Template. Este posibil să conțină caracteristici nepublicate sau API-uri diferite față de cea mai recentă versiune publicată.

Vă rugăm să consultați eticheta Git care corespunde versiunii dumneavoastră de Consul Template pentru documentația corespunzătoare.

Cuprins

• Sprijin comunitar
• Instalare
• Exemplu rapid
• Ghiduri de învățare
• Configurare
  • Semnale din linia de comandă
  • Fișier de configurare
• Reîncărcare configurație și șabloane
• Limbajul de șabloane
  • Funcții API
  • Scratch
  • Funcții ajutătoare
  • Funcții matematice
• Observabilitate
  • Logging
• Moduri
  • Once Mode
  • De-Duplication Mode
  • Exec Mode
• Plugins
• Caveats
  • Docker Image Use
  • Dots in Service Names
  • Terminare în caz de eroare
  • Comenzi
    • Mediu
    • Comandă multiplă
  • Comandă multiplă
• Multi-phase Execution

Asistență comunitară

Dacă aveți întrebări legate de modul în care funcționează consul-template, capacitățile sale sau orice altceva în afară de o cerere de erori sau de caracteristici (folosiți trackerul de probleme de pe github pentru acestea), vă rugăm să consultați resursele noastre de asistență pentru comunitate.

Portalul comunității: https://discuss.hashicorp.com/c/consul

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

În mod suplimentar, pentru probleme și cereri de extragere, vom folosi reacțiile 👍ca un sistem de vot aproximativ pentru a ajuta la măsurarea priorităților comunității. Așadar, vă rugăm să adăugați 👍la orice problemă sau cerere de extragere pe care ați dori să o vedeți lucrată. Mulțumesc.

Instalare

1. Descărcați o versiune precompilată, lansată, de pe pagina de lansări Consul Template.

2. Extrageți binarul folosind unzip sau tar.

3. Mutați binarul în $PATH.

Pentru a compila din sursă, vă rugăm să consultați instrucțiunile din secțiuneacontribuție.

Exemplu rapid

Acest scurt exemplu presupune că Consul este instalat local.

Pentru mai multe exemple și cazuri de utilizare, vă rugăm să consultați dosarul de exemple dinacest depozit.

Ghiduri de învățare

În plus față de aceste exemple, HashiCorp a publicat ghiduri șidocumentație oficială pentru a vă ajuta să parcurgeți câteva cazuri de utilizare comune pentru ConsulTemplate.

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

Configurație

Documentația privind configurația a fost mutată în docs/configuration.md.

Reîncărcarea configurației și a șabloanelor

Deși există mai multe moduri de a rula Consul Template, cel mai comun model este de a rula Consul Template ca un serviciu de sistem. Când Consul Template pornește pentru prima dată,acesta citește orice fișiere de configurare și șabloane de pe disc și le încarcă în memorie. Din acel moment, modificările aduse fișierelor de pe disc nu se propagă la procesul în curs de execuție fără o reîncărcare.

Motivul acestui comportament este simplu și se aliniază cu alte instrumente precum haproxy.Un utilizator poate dori să efectueze verificări de validare înainte de zbor a configurației sau a șabloanelor înainte de a le încărca în proces. În plus, un utilizator poate dori să actualizeze simultan configurația și șabloanele. Faptul ca Consul Templateaut să urmărească și să reîncarce în mod automat aceste fișiere la modificări este periculos din punct de vedere operațional și contravine unora dintre paradigmele infrastructurii moderne. În schimb, Consul Template ascultă apelul de sistem SIGHUP pentru a declanșa o reîncărcare a configurației. Dacă actualizați configurația sau șabloanele, trimiteți pur și simplu HUP la procesul Consul Template în curs de execuție și Consul Template va reîncărca toate configurațiile și șabloanele de pe disc.

Limbajul de șabloane

Documentația limbajului de șabloane a fost mutată todocs/templating-language.md.

Caveats

Utilizarea imaginii Docker

Imaginea Alpine Docker este configurată pentru a suporta un volum extern pe care să fie redate șabloanele partajate. Dacă este montat, va trebui să vă asigurați că utilizatorulconsul-template din imaginea docker are permisiuni de scriere ladirectorul. De asemenea, dacă vă construiți propria imagine folosind acestea, trebuie să vă asigurați că aveți permisiunile corecte.

Utilizatorul consul-template din docker are un UID de 100 și un GID de 1000.

Acest lucru afectează directoarele din imagine /consul-template/config, folosit pentru a adăugaconfigurația atunci când se folosește aceasta ca imagine părinte, și /consul-template/data, exportat ca VOLUME ca locație pentru a reda rezultatele partajate.

Anterior, imaginea a rulat inițial ca root pentru a se asigura că permisiunile permit acest lucru. Dar acest lucru a mers împotriva celor mai bune practici docker și a politicilor de securitate.

Dacă vă construiți propria imagine pe baza imaginii noastre, puteți suprascrie aceste valori cu parametrii--build-arg.

Puncte în numele serviciilor

Utilizarea punctelor . în numele serviciilor va intra în conflict cu utilizarea punctelor pentru delimitarea TAG-urilor în șablon. Punctele interferează deja cu utilizareaDNSpentru nume de servicii, așa că vă recomandăm să evitați punctele ori de câte ori este posibil.

Terminarea în caz de eroare

În mod implicit, Consul Template este foarte tolerant la erori. Dacă Consul este inaccesibil sau dacă se schimbă șablonul, Consul Template va continua cu plăcere să funcționeze. Singuraexcepție de la această regulă este dacă command opționalul command iese non-zero. În acest caz, Consul Template va ieși, de asemenea, non-zero. Motivul acestei decizii este acela că utilizatorul poate configura cu ușurință ceva precum Upstart sau God pentru a gestiona ConsulTemplate ca serviciu.

Dacă doriți ca Consul Template să continue să urmărească modificările, chiar dacă argumentul opțional al comenzii eșuează, puteți adăuga || true la comanda dumneavoastră. Rețineți că || este un „shell-ism”, nu o funcție încorporată. De asemenea, va trebui să rulați comanda dvs. sub un shell:

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

În acest exemplu, chiar dacă comanda de repornire Nginx returnează o valoare diferită de zero, funcția generală va returna în continuare un cod de ieșire OK; Consul Template va continua să funcționeze ca un serviciu. În plus, dacă aveți o logică complexă pentru repornirea serviciului, puteți alege în mod inteligent când doriți ca Consul Template să iasă și când doriți ca acesta să continue să urmărească modificările. Pentru aceste tipuri de scripturi complexe, vă recomandăm să folosiți un script sh sau bash personalizat în loc să puneți logica direct în comanda consul-template sau în fișierul de configurare.

Comenzi

Mediu

Mediul proceselor curente este utilizat la executarea comenzilor cu următoarele variabile de mediu suplimentare:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Aceste variabile de mediu sunt exportate cu valorile lor curente atunci când se executăcomanda. Alte instrumente Consul citesc aceste variabile de mediu,asigurând o integrare fără probleme cu alte instrumente Consul (cum ar fi consul maint sauconsul lock). În plus, expunerea acestor variabile de mediu oferă utilizatorilor experimentați posibilitatea de a-și personaliza și mai mult scriptul de comandă.

Comenzi multiple

Comanda configurată pentru a fi executată la redarea șablonului trebuie să fie o singură comandă. Adică nu puteți uni mai multe comenzi cu &&, ;, |, etc. Aceasta este o restricție a modului în care sunt executate. Cu toate acestea, puteți face acest lucru prin combinarea mai multor comenzi într-o comandă shell explicită folosind sh -c. Acest lucru este probabil cel mai bine explicat printr-un exemplu.

Să spunem că aveți câteva scripturi pe care trebuie să le executați atunci când un șablon este redat,/opt/foo și /opt/bar, și doriți ca /opt/bar să fie executat numai dacă /opt/foo are succes. Puteți face acest lucru cu comanda…

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

Pentru că aceasta este o comandă completă de shell, puteți folosi chiar și condiționale. Deci realizează același lucru.

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

Utilizând această metodă puteți rula oricâte comenzi shell doriți cu orice logică aveți nevoie. Deși se sugerează că, dacă devine prea lung, ați putea dori să îl înfășurați într-un script shell, să îl implementați și să îl rulați pe acela.

Execuție în mai multe faze

Consul Template face o evaluare în n treceri a șabloanelor, acumulând dependențele la fiecare trecere. Acest lucru este necesar din cauza dependențelor imbricate, cum ar fi:

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

În timpul primei treceri, Consul Template nu cunoaște niciunul dintre serviciile dinConsul, așa că trebuie să efectueze o interogare. Când aceste rezultate sunt returnate, bucla interioară este apoi evaluată cu acel rezultat, creând potențial mai multe interogăriși ceasuri.

Din cauza acestei implementări, funcțiile șablon au nevoie de o valoare implicită care esteun parametru acceptabil pentru o funcție range (sau similară), dar care nu execută efectiv bucla interioară (ceea ce ar provoca o panică). Acest lucru este important de menționat deoarece șabloanele complexe trebuie să țină cont de cazul „gol”. De exemplu, următoarele nu vor funcționa:

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

Aceasta va genera o eroare de genul:

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

Aceasta deoarece, în timpul primei evaluări a șablonului, cheia service returnează o felie goală. Puteți să țineți cont de acest lucru în șablonul dvs. astfel:

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

Aceasta va adăuga în continuare dependența la lista de ceasuri, dar nu va evalua inner-if, evitând eroarea out-of-index.

Întrebări frecvente

Întrebare: Care este diferența față de confd?
A: Răspunsul este simplu: Service Discovery ca un cetățean de primă clasă. Sunteți, de asemenea, încurajați să citiți această Pull Request privind proiectul pentru mai multe informații de fond. Credem că confd este un proiect grozav, dar Consul Template umple un gol lipsă. În plus, Consul Template are o integrare de primă clasă cu Vault, facilitând încorporarea în fișierele de configurare a materialelor secrete, cum ar fi acreditările bazelor de date sau token-urile API.

Întrebare: În ce fel este diferit față de Puppet/Chef/Ansible/Salt?
R: Instrumentele de gestionare a configurației sunt concepute pentru a fi utilizate la unison cu Consul Template. În loc să redați un fișier de configurare învechit, utilizați software-ul de gestionare a configurației pentru a reda un șablon dinamic care va fi populat de Consul.

Contribuire

Pentru a construi și instala Consul-Template la nivel local, va trebui să instalați Go.

Clonați depozitul:

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

Pentru a compila binarul consul-template pentru mașina dvs. locală:

$ make dev

Aceasta va compila binarul consul-template în bin/consul-template precum și în $GOPATH al dvs. și va rula suita de teste.

Dacă doriți să compilați un anumit binar, setați XC_OS și XC_ARCH sau rulați următoarele pentru a genera toate binarele:

$ make build

Dacă doriți să rulați testele, mai întâi instalați consul și vault local, apoi:

$ make test

Sau pentru a rula un test specific din suită:

go test ./... -run SomeTestFunction_name

.