hashicorp / consul-template

Questo progetto fornisce un modo conveniente per popolare i valori di Consul nel file system usando il demone consul-template.

Il demone consul-template interroga un Consul o Vaultcluster e aggiorna qualsiasi numero di template specificato sul file system. Come bonus aggiuntivo, può opzionalmente eseguire comandi arbitrari quando il processo di aggiornamento viene completato. Si veda la cartella examples per alcuni scenari in cui questa funzionalità potrebbe rivelarsi utile.

La documentazione in questo README corrisponde al ramo master di Consul Template. Può contenere caratteristiche non rilasciate o API diverse dalla versione più recente rilasciata.

Si prega di vedere il tag Git che corrisponde alla propria versione di Consul Template per la documentazione corretta.

Indice

• Supporto comunitario
• Installazione
• Esempio rapido
• Guida all’apprendimento
• Configurazione
  • Bandiere della linea di comando
  • File di configurazione
• Ricarica configurazione e modelli
• Linguaggio di template
  • Funzioni API
  • Scratch
  • Funzioni di aiuto
  • Funzioni matematiche
• Osservabilità
  • Logging
• Modalità
  • Once Mode
  • De-Modalità di duplicazione
  • Modalità Exec
• Plugins
• Caveats
  • Uso immagine dock
  • Punti nel servizio Names
  • Termination on Error
  • Commands
    • Environment
    • Multiple Commands
  • Multi-fase
• Esecuzione e ciclo di vita del processo
• Debugging
• FAQ
• Contribuire

Supporto della comunità

Se hai domande su come funziona consul-template, le sue capacità o qualsiasi altra cosa che non sia un bug o una richiesta di funzionalità (usa il tracker dei problemi di github per queste), per favore vedi le risorse di supporto della nostra comunità.

Portale della comunità: https://discuss.hashicorp.com/c/consul

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

Inoltre, per i problemi e le richieste di pull, useremo le reazioni 👍 come un sistema di voto approssimativo per aiutare a valutare le priorità della comunità. Quindi per favore aggiungi 👍 a qualsiasi problema o richiesta di pull che vorresti vedere lavorata. Grazie.

Installazione

1. Scarica una versione precompilata e rilasciata dalla pagina delle release di Consul Template.

2. Estrai il binario usando unzip o tar.

3. Sposta il binario in $PATH.

Per compilare dai sorgenti, vedi le istruzioni nella sezione di contribuzione.

Esempio rapido

Questo breve esempio assume che Consul sia installato localmente.

Per altri esempi e casi d’uso, vedi la cartella examples in questo repository.

Impara le guide

In aggiunta a questi esempi, HashiCorp ha pubblicato delle guide e la documentazione ufficiale per aiutare ad affrontare alcuni casi d’uso comuni per ConsulTemplate.

• Consul KV
• Consul Catalog
• Modelli Agente di Sicurezza
• Segreti di Sicurezza

Configurazione

La documentazione di configurazione è stata spostata in docs/configuration.md.

Ricarica la configurazione e i modelli

Mentre ci sono diversi modi per eseguire Consul Template, il modello più comune è quello di eseguire Consul Template come servizio di sistema. Quando Consul Template si avvia per la prima volta, legge tutti i file di configurazione e i modelli dal disco e li carica in memoria. Da quel punto in poi, le modifiche ai file su disco non si propagano al processo in esecuzione senza un ricaricamento.

La ragione di questo comportamento è semplice e si allinea con altri strumenti come haproxy.Un utente potrebbe voler eseguire controlli di validazione pre-volo sulla configurazione o sui modelli prima di caricarli nel processo. Inoltre, un utente potrebbe voler aggiornare la configurazione e i template simultaneamente. Avere Consul Template che guarda e ricarica automaticamente questi file in caso di cambiamenti è pericoloso dal punto di vista operativo e va contro alcuni dei paradigmi dell’infrastruttura moderna. Invece, Consul Template ascolta la chiamata al sistema SIGHUP per innescare un ricaricamento della configurazione. Se si aggiorna la configurazione o i modelli, è sufficiente inviare HUP al processo Consul Template in esecuzione e Consul Template ricaricherà tutte le configurazioni e i modelli dal disco.

Linguaggio di template

La documentazione sul linguaggio di template è stata spostata in todocs/templating-language.md.

Caveats

Uso dell’immagine Docker

L’immagine Docker Alpine è configurata per supportare un volume esterno per renderizzare i template condivisi. Se montato dovrai assicurarti che l’utenteconsul-template nell’immagine docker abbia i permessi di scrittura sulla directory. Inoltre, se costruisci la tua immagine usando questi, devi essere sicuro di avere i permessi corretti.

L’utente consul-template in docker ha un UID di 100 e un GID di 1000.

Questo ha effetto sulle directory dell’immagine /consul-template/config, usata per aggiungere la configurazione quando si usa questa come immagine madre, e /consul-template/data, esportata come VOLUME come posizione per rendere i risultati condivisi.

In precedenza l’immagine inizialmente veniva eseguita come root per assicurarsi che i permessi lo permettessero. Ma questo andava contro le migliori pratiche di docker e le politiche di sicurezza.

Se costruisci la tua immagine basata sulla nostra puoi sovrascrivere questi valori con--build-arg parametri.

Punti nei nomi dei servizi

L’uso di punti . nei nomi dei servizi andrà in conflitto con l’uso dei punti per la delineazione dei TAG nel template. I punti interferiscono già con l’uso del DNS per i nomi dei servizi, quindi raccomandiamo di evitare i punti quando possibile.

Terminazione in caso di errore

Di default Consul Template è altamente tollerante agli errori. Se Consul è irraggiungibile o il template cambia, Consul Template continuerà felicemente a funzionare. L’unica eccezione a questa regola è se l’opzionale command esce non-zero. In questo caso, anche Consul Template uscirà non zero. La ragione di questa decisione è che l’utente può facilmente configurare qualcosa come Upstart o Dio per gestire Consul Template come un servizio.

Se volete che Consul Template continui a guardare i cambiamenti, anche se l’argomento opzionale del comando fallisce, potete aggiungere || true al vostro comando. Notate che || è una “shell-ism”, non una funzione integrata. Avrete anche bisogno di eseguire il vostro comando sotto una shell:

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

In questo esempio, anche se il comando Nginx restart restituisce un valore diverso da zero, la funzione generale restituirà comunque un codice di uscita OK; Consul Template continuerà a funzionare come servizio. Inoltre, se avete una logica complessa per il riavvio del vostro servizio, potete scegliere in modo intelligente quando volete che Consul Template esca e quando volete che continui a guardare i cambiamenti. Per questi tipi di script complessi, raccomandiamo di usare uno script sh o bash personalizzato invece di mettere la logica direttamente nel comando consul-template o nel file di configurazione.

Comandi

Ambiente

L’ambiente dei processi correnti è usato quando si eseguono comandi con le seguenti variabili d’ambiente aggiuntive:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Queste variabili di ambiente sono esportate con i loro valori correnti quando il comando viene eseguito. Altri strumenti Consul leggono queste variabili d’ambiente, fornendo un’agevole integrazione con altri strumenti Consul (come consul maint oconsul lock). Inoltre, esporre queste variabili d’ambiente dà agli utenti la possibilità di personalizzare ulteriormente il loro script di comando.

Comandi multipli

Il comando configurato per l’esecuzione sul rendering dei template deve essere un singolo comando. Cioè non puoi unire più comandi con &&, ;, |, ecc. Questa è una restrizione di come vengono eseguiti. Tuttavia potete farlo combinando i comandi multipli in un comando di shell esplicito usando sh -c. Questo è probabilmente meglio spiegato con un esempio.

Diciamo che avete un paio di script che avete bisogno di eseguire quando un modello viene reso, /opt/foo e /opt/bar, e volete che /opt/bar venga eseguito solo se /opt/foo ha avuto successo. Potete farlo con il comando…

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

Come questo è un comando completo della shell potete anche usare i condizionali. Così si ottiene la stessa cosa.

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

Utilizzando questo metodo potete eseguire tutti i comandi di shell di cui avete bisogno con qualsiasi logica. Anche se si suggerisce che se diventa troppo lungo si potrebbe desiderare di avvolgerlo in uno script di shell, distribuirlo ed eseguirlo.

Esecuzione multifase

Consul Template fa una valutazione a n passaggi dei modelli, accumulando le dipendenze ad ogni passaggio. Questo è necessario a causa delle dipendenze annidate, come:

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

Durante il primo passaggio, Consul Template non conosce nessuno dei servizi inConsul, quindi deve eseguire una query. Quando questi risultati vengono restituiti, l’inner-loop viene poi valutato con quel risultato, creando potenzialmente più query e orologi.

A causa di questa implementazione, le funzioni template hanno bisogno di un valore predefinito che è un parametro accettabile per una funzione range (o simile), ma non esegue effettivamente l’inner loop (che causerebbe un panico). Questo è importante da menzionare perché i template complessi devono tenere conto del caso “vuoto”. Per esempio, il seguente non funzionerà:

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

Questo solleverà un errore come:

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

Questo perché, durante la prima valutazione del template, la chiave service restituisce una fetta vuota. Puoi tenerne conto nel tuo template in questo modo:

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

Questo aggiungerà ancora la dipendenza alla lista degli orologi, ma non valuterà l’inner-if, evitando l’errore out-of-index.

FAQ

Q: Come è diverso da confd?
A: La risposta è semplice: Service Discovery come cittadino di prima classe. Sei anche incoraggiato a leggere questa Pull Request sul progetto per maggiori informazioni di base. Pensiamo che confd sia un grande progetto, ma Consul Template riempie una lacuna mancante. Inoltre, Consul Template ha un’integrazione di prima classe con Vault, rendendo facile incorporare materiale segreto come credenziali di database o token API nei file di configurazione.

Q: Come è diverso da Puppet/Chef/Ansible/Salt?
A: Gli strumenti di gestione della configurazione sono progettati per essere usati all’unisono con Consul Template. Invece di rendere un file di configurazione stantio, usa il tuo software di gestione della configurazione per rendere un template dinamico che sarà popolato da Consul.

Contribuire

Per costruire e installare Consul-Template localmente, è necessario installare Go.

Clona il repository:

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

Per compilare il binario consul-template per la tua macchina locale:

$ make dev

Questo compilerà il binario consul-template in bin/consul-template così come il tuo $GOPATH ed eseguirà il test suite.

Se vuoi compilare un binario specifico, imposta XC_OS e XC_ARCH o esegui il seguente per generare tutti i binari:

$ make build

Se vuoi eseguire i test, prima installa console e vault localmente, poi:

$ make test

O per eseguire un test specifico nella suite:

go test ./... -run SomeTestFunction_name