hashicorp / consul-template

Ez a projekt kényelmes módot biztosít a Consulból származó értékek feltöltésére a fájlrendszerbe a consul-template daemon segítségével.

A daemon consul-template lekérdez egy Consul vagy Vaultclustert, és tetszőleges számú megadott sablont frissít a fájlrendszerben. További bónuszként opcionálisan tetszőleges parancsokat futtathat, amikor a frissítési folyamat befejeződik. Kérjük, tekintse meg a példák mappát néhány forgatókönyvhöz, ahol ez a funkció hasznosnak bizonyulhat.

A jelen README-ben található dokumentáció a Consul Template master ágának felel meg. Ez tartalmazhat kiadatlan funkciókat vagy eltérő API-kat, mint a legutóbb kiadott verzió.

A megfelelő dokumentációt lásd a Consul Template verziójának megfelelő Git tagben.

Tartalomjegyzék

• Community Support
• Telepítés
• Gyors példa
• Tanulási útmutatók
• Konfiguráció
  • Parancssorjelzők
  • Konfigurációs fájl
• Konfiguráció visszaállítása. and Templates
• Templating Language
  • API Functions
  • Scratch
  • Helper Functions
  • Math Functions
• Observability
  • Logging
• Modes
  • Once Mode
  • De-Duplikációs mód
  • Exec mód
• Plugins
• Caveats
  • Docker Image Use
  • Dots in Service
  • Dots in Service Names
  • Termination on Error
  • Commands
    • Environment
    • Multiple Commands
  • Multi-phase Execution
• Futtatás és folyamat életciklus
• Hibakeresés
• FAQ
• Contributing

Közösségi támogatás

Ha kérdése van a consul-template működésével kapcsolatban, képességeivel, vagy bármi mással, mint hiba- vagy funkciókérelemmel (használd a github issue trackerét ezekhez), kérjük, nézd meg a közösségi támogatási forrásainkat.

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

Egyéb erőforrások: https://www.consul.io/community.html

Kiegészítésképpen, a problémák és a pull-kérelmek esetében a 👍 reakciókat fogjuk használni, mint egy durva szavazási rendszert, amely segít felmérni a közösség prioritásait. Tehát kérlek, add hozzá 👍minden olyan issue-hez vagy pull request-hez, amin szeretnéd, hogy dolgozzanak. Köszönöm.

Telepítés

1. Töltsd le az előre lefordított, kiadott verziót a Consul Template releases oldalról.

2. Kivonatold a bináris fájlt a unzip vagy a tar segítségével.

3. Told a bináris fájlt a $PATH-be.

A forrásból való fordításhoz lásd a Hozzájárulás szakaszban található utasításokat.

Gyors példa

Ez a rövid példa feltételezi, hogy a Consul lokálisan telepítve van.

További példákért és felhasználási esetekért lásd a példák mappát ebben az adattárban.

Útmutatók

A példákon kívül a HashiCorp útmutatókat és hivatalos dokumentációt tett közzé, amelyek segítenek végigjárni a ConsulTemplate néhány gyakori felhasználási esetét.

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

Configuration

A konfigurációs dokumentáció átkerült a docs/configuration oldalra.md.

Konfiguráció és sablonok újratöltése

Míg a Consul Template futtatásának több módja is van, a leggyakoribb minta a Consul Template rendszerszolgáltatásként történő futtatása. A Consul Template első indításakor beolvassa a konfigurációs fájlokat és sablonokat a lemezről, és betölti azokat a memóriába. Ettől a ponttól kezdve a lemezen lévő fájlok változásai nem terjednek át a futó folyamatra újratöltés nélkül.

A viselkedés oka egyszerű, és összhangban van más eszközökkel, például a haproxyval.A felhasználó a konfiguráció vagy a sablonok repülés előtti érvényesítési ellenőrzését szeretné elvégezni, mielőtt betölti őket a folyamatba. Emellett a felhasználó esetleg egyszerre szeretné frissíteni a konfigurációt és a sablonokat. Az, hogy a Consul Templateautomatikusan figyelje és újratöltse ezeket a fájlokat a változásokkor, mind működési szempontból veszélyes, mind pedig a modern infrastruktúra néhány paradigmája ellen való. Ehelyett a Consul Template a SIGHUP rendszerhívásra figyel, hogy a konfiguráció újratöltését kiváltsa. Ha frissíti a konfigurációt vagy a sablonokat, egyszerűen küldje el a HUP-t a futó Consul Template folyamatnak, és a Consul Template újratölti az összes konfigurációt és sablont a lemezről.

Templating Language

A templating Language dokumentációja átkerült a todocs/templating-language.md.

Caveats

Docker Image Use

Az Alpine Docker image úgy van konfigurálva, hogy támogassa a külső kötetet, amelyre a megosztott sablonokat rendereli. Ha csatlakoztatva van, akkor meg kell győződnie arról, hogy aconsul-template felhasználónak a dokkerképben van írási jogosultsága a könyvtárhoz. Ha saját képet készít ezek felhasználásával, akkor is meg kell győződnie arról, hogy a jogosultságok megfelelőek.

A consul-template felhasználó a dockerben 100-as UID-vel és 1000-es GID-vel rendelkezik.

Ez hatással van a képen belüli /consul-template/config könyvtárakra, amelyet a konfiguráció hozzáadására használnak, amikor ezt a képet szülő képként használják, és a /consul-template/data,amelyet VOLUME-ként exportálnak a megosztott eredmények renderelésének helyeként.

Előzőleg a kép kezdetben root-ként futott, hogy a jogosultságokat biztosítsák. De ez ellenkezett a docker legjobb gyakorlatával és a biztonsági irányelvekkel.

Ha saját image-t készít a miénk alapján, akkor ezeket az értékeket felülírhatja--build-arg paraméterekkel.

Dots in Service Names

Using dots . in service names will conflict with the use of dots for TAGdelineation in theetemplate. A pontok már zavarják aDNS használatát a szolgáltatásneveknél, ezért javasoljuk a pontok elkerülését, ahol csak lehetséges.

Hiba esetén történő megszüntetés

A Consul sablon alapértelmezés szerint nagymértékben hibatűrő. Ha a Consul elérhetetlen vagya sablon megváltozik, a Consul Template boldogan folytatja a futást. Az egyetlen kivétel ez alól a szabály alól, ha az opcionális command nem nulla. Ebben az esetben a Consul Template szintén nem nullával fog kilépni. Ennek a döntésnek az az oka, hogy a felhasználó könnyen beállíthasson valami olyasmit, mint az Upstart vagy a God, hogy a ConsulTemplate-et szolgáltatásként kezelje.

Ha azt szeretné, hogy a Consul Template továbbra is figyelje a változásokat, még akkor is, ha az opcionális parancs argumentum sikertelen, akkor a || true-t hozzáadhatja a parancshoz. Megjegyzendő, hogy a || egy “shell-izmus”, nem egy beépített funkció. A parancsot egy shell alatt is futtatnia kell:

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

Ebben a példában, még ha az Nginx restart parancs nem nullával tér is vissza, az általános függvény akkor is OK kilépési kódot ad vissza; a Consul Template továbbra is szolgáltatásként fog futni. Továbbá, ha összetett logikája van a szolgáltatás újraindítására, intelligens módon kiválaszthatja, hogy mikor akarja, hogy a Consul Template kilépjen, és mikor akarja, hogy továbbra is figyelje a változásokat. Az ilyen típusú összetett szkriptek esetében azt javasoljuk, hogy használjon egyéni sh vagy bash szkriptet ahelyett, hogy a logikát közvetlenül a consul-template parancsba vagy a konfigurációs fájlba helyezné.

Parancsok

Környezet

Az aktuális folyamatok környezetét használja a parancsok végrehajtásakor a következő további környezeti változókkal:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

A parancs végrehajtásakor ezek a környezeti változók az aktuális értékeikkel kerülnek exportálásra. Más Consul-eszközök olvassák ezeket a környezeti változókat,zökkenőmentes integrációt biztosítva más Consul-eszközökkel (például consul maint vagy consul lock). Ezen túlmenően, ezeknek a környezeti változóknak a közzététele lehetővé teszi a poweruserek számára, hogy tovább testre szabják a parancsszkriptjüket.

Több parancs

A sablon rendereléskor futtatásra konfigurált parancsnak egyetlen parancsnak kell lennie. Vagyis nem lehet több parancsot összekapcsolni &&, ;, |, stb. betűkkel.Ez a végrehajtásuk módjának korlátozása. Ezt azonban megteheti úgy, hogy a több parancsot egy explicit shell parancsban egyesíti a sh -c használatával. Ezt valószínűleg egy példával lehet a legjobban elmagyarázni.

Tegyük fel, hogy van néhány szkripted, amit egy sablon megjelenítésekor kell futtatnod,/opt/foo és /opt/bar, és azt akarod, hogy az /opt/bar csak akkor fusson, ha a /opt/foo sikertelen. Ezt a következő paranccsal teheted meg…

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

Mivel ez egy teljes héjparancs, még feltételeseket is használhatsz. Így ugyanazt éri el.

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

Ezzel a módszerrel annyi shell parancsot futtathatsz, amennyit csak akarsz, bármilyen logikával. Bár javasolt, hogy ha túl hosszú lesz, akkor érdemes egy shell scriptbe csomagolni, telepíteni és futtatni.

Többfázisú végrehajtás

A Consul Template a sablonok n-menetes kiértékelését végzi, minden egyes menetben felhalmozva a függőségeket. Erre az egymásba ágyazott függőségek miatt van szükség, például:

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

Az első menet során a Consul Template nem ismeri aConsulban lévő szolgáltatások egyikét sem, ezért lekérdezést kell végrehajtania. Amikor ezek az eredmények visszakerülnek, a belső hurok kiértékelésre kerül ezzel az eredménnyel, ami potenciálisan további lekérdezéseket és órákat hoz létre.

Ez a megvalósítás miatt a sablonfüggvényeknek szükségük van egy alapértelmezett értékre, amely elfogadható paramétere egy range függvénynek (vagy hasonlónak), de ténylegesen nem hajtja végre a belső hurkot (ami pánikot okozna). Ezt azért fontos megemlíteni, mert az összetett sablonoknak figyelembe kell venniük az “üres” esetet. Például a következő nem fog működni:

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

Ez olyan hibát fog kiváltani, mint:

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

Ez azért van, mert a sablon első kiértékelése során a servicekulcs egy üres szeletet ad vissza. Ezt figyelembe veheted a sablonodban, például:

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

Ez továbbra is hozzáadja a függőséget az órák listájához, de nem értékeli ki a belső-if-et, elkerülve az out-of-index hibát.

GYIK

K: Miben különbözik ez a confd-től?
A: A válasz egyszerű: A Service Discovery első osztályú állampolgárként. Javasoljuk, hogy olvassa el ezt a Pull Requestet a projektről további háttérinformációkért. Úgy gondoljuk, hogy a confd egy nagyszerű projekt, de a Consul Template egy hiányzó űrt tölt be. Ráadásul a Consul Template első osztályú integrációval rendelkezik a Vault-tal, ami megkönnyíti az olyan titkos anyagok, mint az adatbázis hitelesítő adatok vagy API tokenek beépítését a konfigurációs fájlokba.

K: Miben különbözik ez a Puppet/Chef/Ansible/Salt-tól?
A: A konfigurációkezelő eszközöket úgy terveztük, hogy a Consul Template-tel együtt lehessen használni. Ahelyett, hogy egy elavult konfigurációs fájlt renderelne, használja a konfigurációkezelő szoftverét egy dinamikus sablon renderelésére, amelyet a Consul tölt fel.

Hozzájárulás

A Consul-Template helyi építéséhez és telepítéséhez a Go-t kell telepítenie.

Klónozd a repository-t:

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

A consul-template bináris lefordításához a helyi gépedre:

$ make dev

Ez a consul-template bináris lefordítja a bin/consul-template-be, valamint a $GOPATH-be és futtatja a tesztcsomagot.

Ha egy adott binárist akarsz lefordítani, állítsd be a XC_OS és XC_ARCH értékeket, vagy futtasd a következőt az összes bináris generálásához:

$ make build

Ha a teszteket akarod futtatni, először telepítsd a consult és a vaultot lokálisan, majd:

$ make test

Vagy egy adott teszt futtatásához a csomagban:

go test ./... -run SomeTestFunction_name

.