hashicorp / consul-template

Tento projekt poskytuje pohodlný způsob doplňování hodnot z Consultu do souborového systému pomocí démona consul-template.

Démon consul-template se dotazuje na Consul nebo Vaultcluster a aktualizuje libovolný počet zadaných šablon v souborovém systému. Jako další bonus může volitelně spouštět libovolné příkazy po dokončení aktualizačního procesu. Některé scénáře, kde se tato funkce může ukázat jako užitečná, najdete ve složce s příklady.

Dokumentace v tomto README odpovídá hlavní větvi Consul Template. Může obsahovat nevydané funkce nebo jiná API než poslední vydaná verze.

Prosím, podívejte se na značku Git, která odpovídá vaší verzi šablony Consul, kde najdete správnou dokumentaci.

Obsah

• Komunitní podpora
• Instalace
• Rychlý příklad
• Návod k použití
• Konfigurace
  • Příznaky příkazového řádku
  • Konfigurační soubor
• Načítání konfigurace. a šablony
• Šablonovací jazyk
  • Funkce API
  • Scratch
  • Pomocné funkce
  • Matematické funkce
• Pozorovatelnost
  • Záznamy
• Režimy
  • Jednorázový režim
  • De-Duplikační režim
  • Výkonný režim
• Zásuvné moduly
• Upozornění
  • Použití obrazu dockeru
  • Body v servisu Názvy
  • Ukončení při chybě
  • Příkazy
    • Prostředí
    • Více příkazů
  • Více-phase Execution
• Running and Process Lifecycle
• Debugging
• FAQ
• Contributing

Community Support

Pokud máte otázky ohledně fungování consul-template, jeho možnostech nebo o čemkoli jiném než o chybě nebo požadavku na funkci (pro ty použijte nástroj pro sledování problémů na githubu), podívejte se prosím na naše zdroje komunitní podpory.

Komunitní portál: https://discuss.hashicorp.com/c/consul

Další zdroje: https://www.consul.io/community.html

Dále budeme u issues a pull requestů používat reakce 👍jako hrubý hlasovací systém, který pomůže určit priority komunity. Proto prosím přidejte 👍 k jakémukoli problému nebo pull requestu, na kterém byste chtěli pracovat. Díky.

Instalace

1. Stáhněte si předkompilovanou, vydanou verzi ze stránky Consul Template releases.

2. Extrahujte binární soubor pomocí unzip nebo tar.

3. Přesuňte binární soubor do $PATH.

Chcete-li kompilovat ze zdrojových kódů, podívejte se na pokyny v sekciPříklady.

Rychlý příklad

Tento krátký příklad předpokládá, že Consul je nainstalován lokálně.

Další příklady a případy použití najdete ve složce examples v tomto úložišti.

Naučte se průvodce

Kromě těchto příkladů společnost HashiCorp zveřejnila průvodce aoficiální dokumentaci, které vám pomohou projít několik běžných případů použití šablony ConsulTemplate.

• Katalog Consul KV
• Katalog Consul
• Šablony záložních agentů
• Záložní tajemství

Konfigurace

Dokumentace ke konfiguraci byla přesunuta do docs/configuration.md.

Načítání konfigurace a šablon

Přestože existuje více způsobů, jak spustit šablonu Consul, nejčastějším vzorem je spustit šablonu Consul jako systémovou službu. Při prvním spuštění načte Consul Template všechny konfigurační soubory a šablony z disku a načte je do paměti. Od tohoto okamžiku se změny souborů na disku nepromítnou do běžícího procesu bez opětovného načtení.

Důvod tohoto chování je jednoduchý a odpovídá ostatním nástrojům, jako je haproxy. uživatel může chtít provést kontrolu platnosti konfigurace nebo šablon před jejich načtením do procesu. Kromě toho může uživatel chtít aktualizovat konfiguraci a šablony současně. Nechat Consul Templateautomaticky sledovat a znovu načítat tyto soubory při změnách je provozně nebezpečné a v rozporu s některými paradigmaty moderní infrastruktury. Místo toho Consul Template naslouchá na syscall SIGHUP, který spustí opětovné načtení konfigurace. Pokud aktualizujete konfiguraci nebo šablony, stačí poslat HUP běžícímu procesu Consul Template a Consul Template znovu načte všechnykonfigurace a šablony z disku.

Šablonovací jazyk

Dokumentace šablonovacího jazyka byla přesunuta todocs/templating-language.md.

Upozornění

Použití obrazu Docker

Obraz Alpine Docker je nakonfigurován tak, aby podporoval externí svazek pro vykreslování sdílených šablon. Pokud je připojen, je třeba se ujistit, že uživatelconsul-template v obrazu dockeru má oprávnění k zápisu do adresáře. Také pokud sestavujete svůj vlastní obraz s jejich použitím, musíte se ujistit, že máte správná oprávnění.

Uživatel consul-template v dockeru má UID 100 a GID 1000.

To má vliv na adresáře v obraze /consul-template/config, který se používá k přidáníkonfigurace při použití tohoto obrazu jako nadřazeného, a /consul-template/data,exportovaný jako VOLUME jako místo pro vykreslení sdílených výsledků.

Předtím se obraz zpočátku spouštěl jako root, aby se zajistilo, že to oprávnění dovolí. To však bylo v rozporu s osvědčenými postupy a bezpečnostními zásadami dockeru.

Pokud si vytvoříte vlastní obraz na základě našeho, můžete tyto hodnoty přepsat pomocí parametrů--build-arg.

Tečky v názvech služeb

Použití teček . v názvech služeb bude v rozporu s použitím teček pro označení TAG v šabloně. Tečky již kolidují s použitímDNSpro názvy služeb, proto doporučujeme vyhnout se tečkám všude, kde je to možné.

Ukončení při chybě

Ve výchozím nastavení je šablona Consul vysoce odolná proti chybám. Pokud je Consul nedostupný nebo se změní šablona, bude Consul Template spokojeně pokračovat v běhu. Jedinouvýjimkou z tohoto pravidla je případ, kdy volitelný command skončí nenulou. V takovém případě šablona Consul také skončí nenulou. Důvodem tohoto rozhodnutí je, aby uživatel mohl snadno nakonfigurovat něco jako Upstart nebo God pro správu ConsulTemplate jako služby.

Chcete-li, aby Consul Template pokračoval ve sledování změn, i když nepovinný argument příkazu selže, můžete k příkazu připojit || true. Všimněte si, že || je „shell-ismus“, nikoli vestavěná funkce. Budete také muset spustit svůj příkaz pod shellem:

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

V tomto příkladu, i když příkaz Nginx restart vrátí nenulovou hodnotu, celková funkce stále vrátí výstupní kód OK; Šablona Consul bude nadále běžet jako služba. Navíc, pokud máte složitou logiku pro restartování služby, můžete inteligentně zvolit, kdy chcete, aby Consul Template skončil, a kdy chcete, aby pokračoval ve sledování změn. Pro tyto typy složitých skriptů doporučujeme použít vlastní skript sh nebo bash namísto vkládání logiky přímo do příkazu consul-template nebo konfiguračního souboru.

Příkazy

Prostředí

Při provádění příkazů se používá prostředí aktuálních procesů s následujícími doplňkovými proměnnými prostředí:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Tyto proměnné prostředí jsou při spuštění příkazu exportovány s jejich aktuálními hodnotami. Ostatní nástroje Consul tyto proměnné prostředí čtou,čímž zajišťují bezproblémovou integraci s jinými nástroji Consul (například consul maint neboconsul lock). Navíc vystavení těchto proměnných prostředí dává zkušenému uživateli možnost dalšího přizpůsobení příkazového skriptu.

Více příkazů

Příkaz nakonfigurovaný pro spuštění při vykreslování šablony musí být jediný příkaz. To znamená, že nelze spojit více příkazů pomocí &&, ;, | atd. jedná se o omezení způsobu jejich provádění. Můžete to však provést spojením více příkazů do explicitního příkazu shellu pomocí sh -c. Nejlépe to asi vysvětlíte na příkladu:

Řekněme, že máte několik skriptů, které potřebujete spustit při vykreslování šablony, /opt/foo a /opt/bar, a chcete, aby se /opt/bar spustil pouze v případě, že se /opt/foo vydá. To můžete udělat pomocí příkazu…

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

Jelikož se jedná o plnohodnotný příkaz shellu, můžete použít i podmíněné příkazy. Dosáhnete tak stejné věci.

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

Pomocí této metody můžete spustit tolik příkazů shellu, kolik potřebujete, s jakoukoli logikou. I když se doporučuje, že pokud je to příliš dlouhé, možná byste to chtělizahrnout do shellového skriptu, nasadit a spustit ten.

Vícefázové provádění

Šablona Consul provádí n-průchodové vyhodnocení šablon, přičemž při každém průchodu kumuluje závislosti. To je nutné kvůli vnořeným závislostem, například:

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

Při prvním průchodu nezná Consul Template žádnou ze služeb vConsul, takže musí provést dotaz. Když jsou tyto výsledky vráceny, vnitřní smyčka je pak vyhodnocena s tímto výsledkem, což potenciálně vytváří další dotazya hodinky.

Z důvodu této implementace potřebují funkce šablony výchozí hodnotu, která jepřijatelným parametrem funkce range (nebo podobné), ale ve skutečnosti neprovádí vnitřní smyčku (což by způsobilo paniku). To je důležitézmínit, protože složité šablony musí počítat s „prázdným“ případem. Například následující šablona nebude fungovat:

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

To vyvolá chybu typu:

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

To proto, že při prvním vyhodnocení šablony vrací klíč service prázdný plátek. Můžete to zohlednit v šabloně takto:

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

Tím se závislost stále přidá do seznamu hlídek, ale nebude se vyhodnocovat vnitřní if, čímž se vyhnete chybě mimo index.

FAQ

Q: Jak se to liší od confd?
A: Odpověď je jednoduchá: Service Discovery jako občan první třídy. Doporučujeme vám také přečíst si tento Pull Request o projektu, kde najdete další základní informace. Myslíme si, že confd je skvělý projekt, ale šablona Consul vyplňuje chybějící mezeru. Navíc má Consul Template prvotřídní integraci s Vaultem, což usnadňuje začlenění tajných materiálů, jako jsou pověření k databázím nebo tokeny API, do konfiguračních souborů.

Q: Jak se to liší od Puppet/Chef/Ansible/Salt?
A: Nástroje pro správu konfigurace jsou navrženy tak, aby se daly používat ve spojení s Consul Template. Namísto vykreslování zastaralého konfiguračního souboru použijte svůj software pro správu konfigurace k vykreslení dynamické šablony, která bude naplněna systémem Consul.

Přispívání

Chcete-li sestavit a nainstalovat Consul-Template lokálně, budete muset nainstalovat Go.

Klonování repozitáře:

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

Kompilace binárky consul-template pro váš lokální počítač:

$ make dev

Tím se binárka consul-template zkompiluje do bin/consul-template a také do vašeho $GOPATH a spustí se sada testů.

Pokud chcete zkompilovat konkrétní binární soubor, nastavte XC_OS a XC_ARCH nebo spusťte následující příkaz pro vygenerování všech binárních souborů:

$ make build

Pokud chcete spustit testy, nainstalujte nejprve lokálně consul a vault a pak:

$ make test

Nebo spusťte konkrétní test ze sady:

go test ./... -run SomeTestFunction_name

.