hashicorp / consul-template

Projekt ten zapewnia wygodny sposób wypełniania wartości z Consulina do systemu plików za pomocą demona consul-template.

Demon consul-template odpytuje klaster Consul lub Vault i aktualizuje dowolną liczbę określonych szablonów w systemie plików. Jako dodatkowy bonus, może on opcjonalnie uruchamiać dowolne polecenia, gdy proces aktualizacji zostanie zakończony. W folderze z przykładami można znaleźć kilka scenariuszy, w których ta funkcjonalność może okazać się przydatna.

Dokumentacja w tym README odpowiada głównej gałęzi Consul Template. Może ona zawierać niewydane funkcje lub inne API niż ostatnio wydana wersja.

W celu uzyskania właściwej dokumentacji proszę zapoznać się z tagiem Git odpowiadającym twojej wersji programu Consul Template.

Spis treści

• Pomoc społeczności
• Instalacja
• Szybki przykład
• Podręczniki
• Konfiguracja
  • Flagi wiersza poleceń
  • Plik konfiguracyjny
• Przywróć konfigurację and Templates
• Templating Language
  • API Functions
  • Scratch
  • Helper Functions
  • Math Functions
• Observability
  • Logging
• Tryby
  • Once Mode
  • De-Duplication Mode
  • Exec Mode
• Plugins
• Caveats
  • Docker Image Use
  • Dots in Service Names
  • Termination on Error
  • Commands
    • Environment
    • Multiple Commands
  • Multi-phase Execution
• Running and Process Lifecycle
• Debugging
• FAQ
• Contributing

Community Support

Jeśli masz pytania dotyczące działania consul-template, jego możliwości lub czegokolwiek innego niż zgłoszenie błędu lub funkcji (w tym celu użyj issue trackera na githubie), proszę zobacz nasze zasoby pomocy społeczności.

Portal społeczności: https://discuss.hashicorp.com/c/consul

Inne zasoby: https://www.consul.io/community.html

Dodatkowo, dla problemów i pull requestów, będziemy używać 👍 reactionsas a rough voting system to help gauge community priorities. Proszę więc dodać 👍 do każdego problemu lub żądania, nad którym chciałbyś popracować. Dzięki.

Instalacja

1. Pobierz prekompilowaną, wydaną wersję ze strony Consul Template releases page.

2. Wyodrębnij binarkę używając unzip lub tar.

3. Przenieś binarkę do $PATH.

Aby skompilować z kodu źródłowego, zapoznaj się z instrukcjami w sekcji dotyczącej wkładu.

Szybki przykład

Ten krótki przykład zakłada, że Consul jest zainstalowany lokalnie.

Więcej przykładów i przypadków użycia można znaleźć w folderze examples w tym repozytorium.

Learn Guides

Oprócz tych przykładów firma HashiCorp opublikowała przewodniki i oficjalną dokumentację, które pomagają przejść przez kilka typowych przypadków użycia szablonu Consul.

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

Configuration

Dokumentacja konfiguracji została przeniesiona do docs/configuration.md.

Przeładuj konfigurację i szablony

Mimo że istnieje wiele sposobów na uruchomienie Szablonu Consul, najczęstszym schematem jest uruchomienie Szablonu Consul jako usługi systemowej. Gdy Consul Template uruchamia się po raz pierwszy, wczytuje z dysku pliki konfiguracyjne i szablony, a następnie ładuje je do pamięci. Od tego momentu zmiany w plikach na dysku nie są propagowane do uruchomionego procesu bez przeładowania.

Powód tego zachowania jest prosty i zgodny z innymi narzędziami, takimi jak haproxy. Użytkownik może chcieć wykonać sprawdzanie poprawności konfiguracji lub szablonów przed załadowaniem ich do procesu. Dodatkowo, użytkownik może chcieć jednocześnie aktualizować konfigurację i szablony. Posiadanie szablonu Consul Templateautomatycznie obserwującego i ładującego te pliki przy zmianach jest zarówno operacyjnie niebezpieczne, jak i sprzeczne z niektórymi paradygmatami nowoczesnej infrastruktury. Zamiast tego szablon Consul nasłuchuje wywołania syscall SIGHUP, aby wywołać przeładowanie konfiguracji. Jeśli aktualizujesz konfigurację lub szablony, po prostu wyślij HUP do uruchomionego procesu Consul Template, a Consul Template przeładuje wszystkie konfiguracje i szablony z dysku.

Templating Language

Dokumentacja języka szablonów została przeniesiona do todocs/templating-language.md.

Caveats

Docker Image Use

Obraz Alpine Docker jest skonfigurowany do obsługi zewnętrznego woluminu do renderowania współdzielonych szablonów. Jeśli zamontowane trzeba będzie upewnić się, żeconsul-template użytkownik w obrazie docker ma uprawnienia do zapisu do katalogu. Również jeśli zbudujesz swój własny obraz używając ich, musisz być pewny, że masz poprawne uprawnienia.

Użytkownik consul-template w docker ma UID równy 100 i GID równy 1000.

Wpływa to na katalogi obrazu /consul-template/config, używany do dodawania konfiguracji, gdy używamy go jako obrazu nadrzędnego, oraz /consul-template/data, eksportowany jako VOLUME jako lokalizacja do renderowania wyników współdzielonych.

Poprzednio obraz był uruchamiany jako root, aby upewnić się, że uprawnienia na to pozwalają. Ale to było sprzeczne z najlepszymi praktykami dockera i polityką bezpieczeństwa.

Jeśli zbudujesz swój własny obraz na podstawie naszego, możesz zastąpić te wartości parametrami--build-arg.

Kropki w nazwach usług

Używanie kropek . w nazwach usług będzie kolidować z używaniem kropek do oznaczania TAGów we wzorcu. Kropki już kolidują z używaniem DNS dla nazw usług, więc zalecamy unikanie kropek, gdy tylko jest to możliwe.

Zakończenie pracy po błędzie

Domyślnie szablon Consul jest wysoce odporny na błędy. Jeśli Consul jest nieosiągalny lub szablon się zmieni, szablon Consul będzie kontynuował pracę. Jedynym wyjątkiem od tej reguły jest sytuacja, gdy opcjonalny command wyjdzie niezerowy. W tym przypadku, szablon Consul również zakończy pracę niezerową. Powodem tej decyzji jest to, że użytkownik może łatwo skonfigurować coś takiego jak Upstart lub God, aby zarządzać ConsulTemplate jako usługą.

Jeśli chcesz, aby Consul Template kontynuował obserwowanie zmian, nawet jeśli opcjonalny argument polecenia nie powiedzie się, możesz dodać || true do swojego polecenia. Zauważ, że || jest „izmem powłoki”, a nie wbudowaną funkcją. Będziesz również musiał uruchomić swoje polecenie pod powłoką:

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

W tym przykładzie, nawet jeśli polecenie restartu Nginx zwróci wartość niezerową, funkcja ogólna nadal zwróci kod wyjścia OK; Szablon Consul będzie nadal działał jako usługa. Dodatkowo, jeśli masz złożoną logikę ponownego uruchamiania usługi, możesz inteligentnie wybrać, kiedy chcesz, aby szablon Consul zakończył pracę, a kiedy kontynuował obserwację zmian. W przypadku tego typu złożonych skryptów zalecamy użycie niestandardowego skryptu sh lub bash zamiast umieszczania logiki bezpośrednio w poleceniu consul-template lub pliku konfiguracyjnym.

Polecenia

Środowisko

Bieżące środowisko procesów jest używane podczas wykonywania poleceń z następującymi dodatkowymi zmiennymi środowiskowymi:

• CONSUL_HTTP_ADDR
• CONSUL_HTTP_TOKEN
• CONSUL_HTTP_AUTH
• CONSUL_HTTP_SSL
• CONSUL_HTTP_SSL_VERIFY

Te zmienne środowiskowe są eksportowane z ich bieżącymi wartościami podczas wykonywania polecenia. Inne narzędzia Consul odczytują te zmienne środowiskowe, zapewniając płynną integrację z innymi narzędziami Consul (takimi jak consul maint lubconsul lock). Ponadto ujawnienie tych zmiennych środowiskowych daje użytkownikom możliwość dalszego dostosowywania skryptu poleceń.

Wiele poleceń

Polecenie skonfigurowane do uruchamiania podczas renderowania szablonu musi być pojedynczym poleceniem. Oznacza to, że nie można łączyć wielu poleceń za pomocą &&, ;, |, itd. Jest to ograniczenie sposobu ich wykonywania. Jest to ograniczenie sposobu ich wykonywania. Jednakże możesz to zrobić łącząc wiele poleceń w jawne polecenie powłoki przy użyciu sh -c. Prawdopodobnie najlepiej wyjaśnić to na przykładzie.

Powiedzmy, że masz kilka skryptów, które musisz uruchomić, gdy szablon jest renderowany, /opt/foo i /opt/bar, i chcesz, aby /opt/bar został uruchomiony tylko wtedy, gdy /opt/foo się powiedzie. Możesz to zrobić za pomocą polecenia…

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

Jako że jest to pełne polecenie powłoki, możesz nawet użyć warunków. Więc osiąga tę samą rzecz.

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

Używając tej metody możesz uruchomić tyle poleceń powłoki ile potrzebujesz z jakąkolwiek logiką potrzebujesz. Chociaż sugeruje się, że jeśli będzie to zbyt długie, możesz chcieć zawinąć to w skrypt powłoki, wdrożyć i uruchomić.

Wykonywanie wielofazowe

Consul Template wykonuje n-przejściową ocenę szablonów, kumulując zależności przy każdym przejściu. Jest to wymagane ze względu na zagnieżdżone zależności, takie jak:

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

Podczas pierwszego przejścia, Szablon Consul nie zna żadnej z usług w Consul, więc musi wykonać zapytanie. Gdy te wyniki zostaną zwrócone, wewnętrzna pętla jest następnie obliczana z tym wynikiem, potencjalnie tworząc więcej zapytań i zegarków.

Z powodu tej implementacji, funkcje szablonów potrzebują wartości domyślnej, która jest akceptowalnym parametrem funkcji range (lub podobnej), ale nie wykonuje faktycznie wewnętrznej pętli (co spowodowałoby panikę). Jest to ważne, aby wspomnieć, ponieważ złożone szablony muszą uwzględniać „pusty” przypadek. Na przykład, poniższe rozwiązanie nie będzie działać:

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

Wywoła to błąd taki jak:

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

Dzieje się tak, ponieważ podczas pierwszej oceny szablonu, klucz service zwraca pusty plaster. Możesz uwzględnić to w swoim szablonie w następujący sposób:

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

To nadal doda zależność do listy obserwowanych, ale nie będzie oceniać inner-if, unikając błędu out-of-index.

FAQ

Q: Czym to się różni od confd?
A: Odpowiedź jest prosta: Service Discovery jako obywatel pierwszej klasy. Zachęcamy również do przeczytania tego Pull Request na temat projektu, aby uzyskać więcej informacji. Uważamy, że confd jest świetnym projektem, ale Consul Template wypełnia brakującą lukę. Dodatkowo, Consul Template posiada pierwszorzędną integrację z Vault, ułatwiając włączenie tajnych materiałów, takich jak dane uwierzytelniające bazy danych lub tokeny API do plików konfiguracyjnych.

Q: Czym to się różni od Puppet/Chef/Ansible/Salt?
A: Narzędzia do zarządzania konfiguracją są zaprojektowane tak, aby mogły być używane w połączeniu z Consul Template. Zamiast renderować nieświeży plik konfiguracyjny, użyj swojego oprogramowania do zarządzania konfiguracją, aby renderować dynamiczny szablon, który zostanie wypełniony przez Consul.

Contributing

Aby zbudować i zainstalować Consul-Template lokalnie, musisz zainstalować Go.

Klonowanie repozytorium:

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

Aby skompilować plik binarny consul-template dla twojej lokalnej maszyny:

$ make dev

To skompiluje plik binarny consul-template do bin/consul-template tak samo jak twój $GOPATH i uruchomi zestaw testów.

Jeśli chcesz skompilować konkretny plik binarny, ustaw XC_OS i XC_ARCH lub wykonaj poniższe polecenie, aby wygenerować wszystkie pliki binarne:

$ make build

Jeśli chcesz uruchomić testy, najpierw zainstaluj lokalnie consul i vault, a następnie:

$ make test

Albo aby uruchomić konkretny test w zestawie:

go test ./... -run SomeTestFunction_name