hashicorp / consul-template

Tämä projekti tarjoaa kätevän tavan täyttää arvot Consulista tiedostojärjestelmään käyttäen consul-template daemonia.

Daemon consul-templatekysyy Consul- tai Vaultclusteria ja päivittää minkä tahansa määrän määriteltyjä malleja tiedostojärjestelmään. Lisäbonuksena se voi valinnaisesti suorittaa mielivaltaisia komentoja, kun päivitysprosessi on valmis. Katso esimerkkikansiosta joitakin skenaarioita, joissa tämä toiminto voi osoittautua hyödylliseksi.

Tässä README:ssä oleva dokumentaatio vastaa Consul Template -ohjelman master-haaraa. Se saattaa sisältää julkaisemattomia ominaisuuksia tai erilaisia API:ita kuin viimeisin julkaistu versio.

Katso oikeaa dokumentaatiota Consul Template -versiota vastaavasta Git-tunnisteesta.

Sisällysluettelo

• Yhteisön tuki
• Asennus
• Pikaesimerkki
• Oppaat
• Oppioppaat
• Konfigurointi
  • Komentorivin lipukkeet
  • Konfigurointitiedosto
• Konfiguraatioiden palautus. and Templates
• Templating Language
  • API Functions
  • Scratch
  • Helper Functions
  • Math Functions
• Observability
  • Logging
• Modes
  • Osaintitila
  • Osaintitila
    • Once Mode
    • De-Duplication Mode
    • Exec Mode
  • Plugins
  • Caveats
    • Docker Image Use
    • Dots in Service
    • Dots in Service Names
    • Termination on Error
    • Commands
      • Environment
      • Multiple Commands
    • Multi-phase Execution
  • Running and Process Lifecycle
  • Debugging
  • FAQ
  • Contributing

  Community Support

  Jos sinulla on kysyttävää siitä, miten consul-template toimii, sen kyvyistä tai jostain muusta kuin vika- tai ominaisuuspyynnöstä (käytä githubin ongelmanseurantapalvelua näihin), tutustu yhteisön tukiresursseihin.

  Yhteisön portaali: https://discuss.hashicorp.com/c/consul

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

  Lisäksi käytämme ongelmien ja pull-pyyntöjen kohdalla 👍 reaktioita karkeana äänestysjärjestelmänä, joka auttaa arvioimaan yhteisön prioriteetteja. Lisää siis 👍 mihin tahansa ongelmaan tai pull requestiin, jota haluaisit työstettävän. Kiitos.

  Asennus

  1. Lataa valmiiksi käännetty, julkaistu versio Consul Template releases -sivulta.

  2. Extraktoi binääri käyttäen unzip tai tar.

  3. Siirrä binääri tiedostoon $PATH.

  Kääntääksesi lähdekoodista, katso ohjeetcontributing-osiosta.

  Pikaesimerkki

  Tämä lyhyt esimerkki olettaa, että Consul on asennettu paikallisesti.

  Lisäesimerkkejä ja käyttötapauksia löydät tämän arkiston examples-kansiosta.

  Opi oppaita

  Näiden esimerkkien lisäksi HashiCorp on julkaissut oppaita javirallista dokumentaatiota, jotka auttavat käymään läpi muutamia yleisiä käyttötapauksia ConsulTemplatea varten.

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

  Konfiguraatio

  Konfiguraation dokumentaatio on siirretty docs/configuration.md.

  Konfiguraation ja mallien uudelleenlataus

  Vaikka on olemassa useita tapoja käyttää Consul Templatea, yleisin malli onkäyttää Consul Templatea järjestelmäpalveluna. Kun Consul Template käynnistyy ensimmäisen kerran, se lukee kaikki konfiguraatiotiedostot ja mallit levyltä ja lataa ne muistiin. Tästä eteenpäin levyllä oleviin tiedostoihin tehdyt muutokset eivät leviä käynnissä olevaan prosessiin ilman uudelleenlatausta.

  Syy tähän käytökseen on yksinkertainen ja yhdenmukainen muiden työkalujen, kuten haproxyn, kanssa.Käyttäjä voi haluta suorittaa konfiguraation tai mallien validointitarkistuksia ennen lennon aloittamista ennen niiden lataamista prosessiin. Lisäksi käyttäjä voi haluta päivittää konfiguraation ja mallit samanaikaisesti. Se, että Consul Templateautomaattisesti tarkkailee ja lataa nämä tiedostot uudelleen muutosten yhteydessä, on sekä toiminnallisesti vaarallista että vastoin joitakin nykyaikaisen infrastruktuurin paradigmoja. Sen sijaan Consul Template kuuntelee SIGHUP-syscall-kutsua konfiguraation uudelleenlatauksen käynnistämiseksi. Jos päivität konfiguraatioita tai malleja, lähetä yksinkertaisesti HUP käynnissä olevalle Consul Template -prosessille ja Consul Template lataa kaikki konfiguraatiot ja mallit uudelleen levyltä.

  Templating Language

  Templating Language -dokumentaatio on siirretty todocs/templating-language.md.

  Varoitukset

  Docker-kuvan käyttö

  Alpine Docker-kuva on konfiguroitu niin, että se tukee ulkopuolista tietovälinettä, johon jaetut mallit renderöidään. Jos se asennetaan, sinun on varmistettava, ettäconsul-template-käyttäjällä docker-imagessa on kirjoitusoikeudet hakemistoon. Myös jos rakennat oman kuvasi näiden avulla, sinun on varmistettava, että sinulla on oikeat oikeudet.

  Dockerin consul-template-käyttäjällä on UID 100 ja GID 1000.

  Tämä vaikuttaa kuvassa oleviin hakemistoihin /consul-template/config, jota käytetään konfiguraation lisäämiseen, kun tätä käytetään vanhempana kuvana, ja /consul-template/data,joka viedään VOLUME:na sijaintina jaettujen tulosten renderöintiin.

  Edellisenä kuvana ajettiin aluksi root-käyttäjänä varmistaaksemme, että käyttöoikeudet sallivat sen. Tämä oli kuitenkin dockerin parhaiden käytäntöjen ja tietoturvakäytäntöjen vastaista.

  Jos rakennat oman kuvasi meidän kuvamme pohjalta, voit ohittaa nämä arvot--build-arg parametreilla.

  Pisteet palveluiden nimissä

  Pisteiden . käyttäminen palveluiden nimissä on ristiriidassa pisteiden käytön kanssa TAG-merkinnöissä mallissa. Pisteet häiritsevät jo nytDNS:n käyttämistä palveluiden nimissä, joten suosittelemme pisteiden välttämistä aina kun se on mahdollista.

  Lopettaminen virhetilanteessa

  Consul Template on oletusarvoisesti erittäin vikasietoinen. Jos Consul on tavoittamattomissa taimalli muuttuu, Consul Template jatkaa iloisesti toimintaansa. Ainoa poikkeus tähän sääntöön on, jos valinnainen command poistuu nollasta. Tällöin myös Consul Template poistuu nollasta. Syy tähän päätökseen on se, että käyttäjä voi helposti konfiguroida esimerkiksi Upstartin tai Godin hallitsemaan ConsulTemplatea palveluna.

  Jos haluat, että Consul Template jatkaa muutosten tarkkailua, vaikka valinnainen komentoargumentti ei onnistuisi, voit liittää komentoosi || true. Huomaa, että || on ”shell-ismi”, ei sisäänrakennettu funktio. Sinun on myös suoritettava komentosi komentotulkissa:

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

  Tässä esimerkissä, vaikka Nginxin uudelleenkäynnistyskomento palauttaisi nollasta poikkeavan tuloksen, yleinen funktio palauttaisi silti OK-ulostulokoodin; Consul Template jatkaa toimintaansa palveluna. Lisäksi, jos sinulla on monimutkainen logiikka palvelun uudelleenkäynnistämiseen, voit älykkäästi valita, milloin haluat Consul Templaten poistuvan ja milloin haluat sen jatkavan muutosten tarkkailua. Tällaisia monimutkaisia skriptejä varten suosittelemme käyttämään mukautettua sh- tai bash-skriptiä sen sijaan, että sijoittaisit logiikan suoraan consul-template-komentoon tai konfiguraatiotiedostoon.

  Komennot

  Ympäristö

  Nykyisen prosessin ympäristöä käytetään, kun komentoja suoritetaan seuraavien ylimääräisten ympäristömuuttujien avulla:

  • CONSUL_HTTP_ADDR
  • CONSUL_HTTP_TOKEN
  • CONSUL_HTTP_AUTH
  • CONSUL_HTTP_SSL
  • CONSUL_HTTP_SSL_VERIFY

  Nämä ympäristömuuttujat viedään nykyisine arvoineen komennon suorituksen yhteydessä. Muut Consul-työkalut lukevat nämä ympäristömuuttujat,mikä mahdollistaa sujuvan integroinnin muiden Consul-työkalujen kanssa (kuten consul maint tai consul lock). Lisäksi näiden ympäristömuuttujien paljastaminen antaa tehokäyttäjille mahdollisuuden räätälöidä komentosarjaa entisestään.

  Useita komentoja

  Komennon, joka on konfiguroitu ajettavaksi mallin renderöinnissä, on oltava yksi komento. Toisin sanoen et voi liittää useita komentoja yhteen &&, ;, | jne.Tämä on rajoitus, joka liittyy niiden suoritustapaan. Voit kuitenkin tehdä tämän yhdistämällä useita komentoja yksiselitteiseen komentotulkkikomentoon käyttämällä sh -c. Tämä selittyy luultavasti parhaiten esimerkin avulla.

  Esitetään, että sinulla on pari skriptiä, jotka sinun on suoritettava, kun malli renderöidään,/opt/foo ja /opt/bar, ja haluat, että /opt/bar suoritetaan vain, jos /opt/foo onnistuu. Voit tehdä sen komennolla…

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

  Koska tämä on täysi komentotulkkikomento, voit jopa käyttää ehtolausekkeita. Saavuttaa siis saman asian.

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

  Käyttämällä tätä menetelmää voit suorittaa niin monta komentotulkkikomentoa kuin tarvitset millä tahansa logiikalla. Tosin ehdotetaan, että jos siitä tulee liian pitkä, kannattaa se kietoa shell-skriptiin, ottaa käyttöön ja ajaa se.

  Monivaiheinen suoritus

  Consul Template tekee n-vaiheisen evaluoinnin malleille, kerryttämällä riippuvuudet jokaisessa vaiheessa. Tämä on tarpeen sisäkkäisten riippuvuuksien vuoksi, kuten:

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

  Ensimmäisen läpikäynnin aikana Consul Template ei tunne yhtäänConsulissa olevaa palvelua, joten sen on tehtävä kysely. Kun nämä tulokset palautetaan, sisäinen silmukka arvioidaan tämän tuloksen kanssa, jolloin mahdollisesti syntyy lisää kyselyjä ja kelloja.

  Tämän toteutuksen vuoksi template-funktiot tarvitsevat oletusarvon, joka on hyväksyttävä parametri range-funktiolle (tai vastaavalle), mutta ei itse asiassa suorita sisäistä silmukkaa (mikä aiheuttaisi paniikin). Tämä on tärkeää mainita, koska monimutkaisten mallifunktioiden on otettava huomioon ”tyhjä” tapaus. Esimerkiksi seuraava ei toimi:

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

  Tämä aiheuttaa virheilmoituksen kuten:

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

  Tämä johtuu siitä, että mallin ensimmäisen evaluoinnin aikana serviceavain palauttaa tyhjän siivun. Voit ottaa tämän huomioon mallineessasi esimerkiksi näin:

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

  Tämä lisää riippuvuuden silti kellojen listaan, mutta ei evaluoi inner-if:iä, jolloin vältytään out-of-index-virheeltä.

  FAQ

  Q: Miten tämä eroaa confd:stä?
  A: Vastaus on yksinkertainen: Service Discovery ensimmäisen luokan kansalaisena. Sinua kehotetaan myös lukemaan tämä Pull Request projektista saadaksesi lisää taustatietoa. Mielestämme confd on loistava projekti, mutta Consul Template täyttää puuttuvan aukon. Lisäksi Consul Templatessa on ensiluokkainen integraatio Vaultin kanssa, mikä helpottaa salaisen materiaalin, kuten tietokantojen tunnistetietojen tai API-tunnisteiden sisällyttämistä konfiguraatiotiedostoihin.

  Q: Miten tämä eroaa Puppetista/Chefistä/Ansiblesta/Saltista?
  A: Konfiguraationhallintatyökalut on suunniteltu käytettäväksi yhdessä Consul Templaten kanssa. Sen sijaan, että renderöisit vanhentuneen konfiguraatiotiedoston, käytä konfiguraationhallintaohjelmistoa renderöidäksesi dynaamisen mallin, jonka Consul täyttää.

  Contributing

  Voidaksesi rakentaa ja asentaa Consul-Templatea paikallisesti, sinun täytyy asentaa Go.

  Kloonaa arkisto:

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

  Kääntääksesi consul-template-binäärin paikalliselle koneellesi:

  $ make dev

  Tämä kääntää consul-template-binäärin bin/consul-template:iin sekä omaan $GOPATH:si ja ajaa testisarjan.

  Jos haluat kääntää tietyn binäärin, aseta XC_OS ja XC_ARCH tai suorita seuraava, jotta kaikki binäärit generoituvat:

  $ make build

  Jos haluat ajaa testit, asenna ensin konsuli ja holvi paikallisesti ja sitten:

  $ make test

  Vai jos haluat ajaa tietyn testin testisarjassa:

  go test ./... -run SomeTestFunction_name

  .