hashicorp / consul-template

by

このプロジェクトは、consul-template デーモンを使って Consul からファイルシステムへ値を入力する便利な方法を提供します。

デーモン consul-template は Consul または Vault クラスターに問い合わせ、ファイルシステム上の任意の数のテンプレートを指定し、更新します。 追加ボーナスとして、更新プロセスが完了したときに、オプションで任意のコマンドを実行することができます。 この機能が有用であることを証明するいくつかのシナリオについては、examples フォルダを参照してください。

この README の文書は Consul Template の master ブランチに対応しています。 最新のリリース版とは異なる機能やAPIが含まれている可能性があります。

適切なドキュメントについては、Consul Template のバージョンに対応する Git タグを参照してください。

目次

  • コミュニティ サポート
  • インストール
  • クイック例
  • ラーニング ガイド
  • 設定
    • コマンドライン フラグ
    • 設定ファイル
  • リロード 設定値
  • リロード とテンプレート
  • テンプレート言語
    • API 関数
    • スクラッチ
    • ヘルパー関数
    • 数学関数
  • Observability
    • Logging
  • Modes
    • One Mode
    • De-Japan
    • Dual Mode

    Dual Mode

  • Dual Mode
  • Dual Mode
    • One Mode

      • Dual Mode

      • One Mode
      • Dual Mode
        • Dual Mode

          • Dual Mode

        • Exec Mode
      • Plugins
      • Caveats
        • Docker Image Use
        • Dots in Service 名前
        • エラー時の終了
        • コマンド
          • 環境
          • 複数コマンド
        • マルチコマンドフェーズ実行
      • 実行とプロセスライフサイクル
      • デバッグ
      • FAQ
      • 貢献

      コミュニティサポート

      consul-template の動作について質問がある場合、以下のフォームに記入してください。 また、バグや機能のリクエスト（github の issue tracker を使用）以外であれば、コミュニティサポートリソースを参照してください。

      コミュニティ ポータル をご覧ください。 https://discuss.hashicorp.com/c/consul

      その他のリソース。 https://www.consul.io/community.html

      さらに、issue と pull request では、コミュニティの優先順位を判断するための大まかな投票システムとして 👍 リアクションを使用する予定です。 そのため、取り組んでほしい課題またはプルリクエストに 👍 を付けてください。

      Installation

    1. Consul Template releases page からコンパイル済みのリリース版をダウンロードします。

    2. unzip または tar でバイナリを展開し、

    3. バイナリは $PATH に移動してください。

    ソースからコンパイルするには、貢献セクションの説明を参照してください。

    クイック例

    この短い例は Consul がローカルにインストールされていると仮定しています。

    ガイドを学ぶ

    これらの例に加え、HashiCorp は ConsulTemplate の一般的な使用例を説明するためのガイドと公式ドキュメントを公開しています。

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

    Configuration

    設定に関する文書は docs/configuration へ移動されました。md.

    Reload Configuration and Templates

    Consul Template を実行する方法は複数ありますが、最も一般的なパターンは、システムサービスとして Consul Template を実行することです。 Consul Templateが最初に起動するとき、ディスクから設定ファイルとテンプレートを読み込んで、メモリにロードします。 この動作の理由は単純で、haproxy などの他のツールと一致しています。 さらに、ユーザーは設定とテンプレートを同時に更新したいと思うかもしれません。 Consul Templateが自動的にこれらのファイルを監視し、変更時に再ロードすることは、運用上危険であり、最新のインフラストラクチャのパラダイムにも反しています。 その代わりに、Consul TemplateはSIGHUPシステムコールをリッスンして、設定の再読み込みをトリガーします。 設定やテンプレートを更新した場合、HUPを実行中のConsul Templateプロセスに送るだけで、Consul Templateはすべての設定とテンプレートをディスクから再読み込みします。

    Templating Language

    Templating Language documentation has been moved todocs/templating-language.md.

    Caveats

    Docker Image Use

    Alpine Docker イメージは共有テンプレートのレンダーとして外部ボリュームをサポートするよう構成されます。 マウントする場合は、Dockerイメージのconsul-templateユーザにディレクトリへの書き込み権限があることを確認する必要があります。 また、これらを使用して独自のイメージを構築する場合、パーミッションが正しいことを確認する必要があります。

    docker の consul-template ユーザーは UID が 100、GID が 1000 です。

    これは、イメージ内のディレクトリ /consul-template/config (これを親イメージとして使用する際に設定を追加するために使用) および /consul-template/data (共有結果をレンダーする場所として VOLUME としてエクスポートされる) に影響を及ぼします。 しかし、これは docker のベストプラクティスとセキュリティポリシーに反していました。

    私たちのものをベースに独自のイメージを構築する場合、--build-arg パラメーターでこれらの値を上書きすることができます。 ドットはすでにサービス名に DNS を使用する際に干渉しますので、可能な限りドットを避けることをお勧めします。

    Termination on Error

    デフォルトで Consul Template は高度な耐障害性を持っています。 もし、Consulにアクセスできない場合や、テンプレートが変更された場合、Consul Templateは喜んで実行を継続します。 このルールの唯一の例外は、オプションのcommandが0以外で終了した場合です。 この場合、Consul Templateもゼロ以外の値で終了します。 この決定の理由は、ユーザーがUpstart や God のようなものを設定して、サービスとして ConsulTemplate を管理しやすくするためです。

    オプションのコマンド引数が失敗しても、Consul Template に変更を監視し続けてほしい場合、コマンドに || true を追加できます。 ただし、||は「シェルイズム」であり、組み込み関数ではありません。 

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

    この例では、Nginx restart コマンドがゼロ以外を返しても、overallfunction は OK 終了コードを返します; Consul Template はサービスとして実行しつづけます。 さらに、サービスを再起動するための複雑なロジックがある場合、Consul Templateをいつ終了させ、いつ変更を監視し続けるかをインテリジェントに選択することができます。 このような複雑なスクリプトの場合、consul-templateコマンドや設定ファイルに直接ロジックを記述するのではなく、カスタムshやbashスクリプトを使用することをお勧めします。

    コマンド

    環境

    以下の環境変数を追加してコマンドを実行すると、現在のプロセス環境が使用されます。

    • CONSUL_HTTP_ADDR
    • CONSUL_HTTP_TOKEN
    • CONSUL_HTTP_AUTH
    • CONSUL_HTTP_SSL
    • CONSUL_HTTP_SSL_VERIFY

    これらの環境変数はコマンド実行時に現在の値で出力されます． 他の Consul ツールはこれらの環境変数を読み取るので、他の Consul ツール (consul maint や consul lock など) とスムーズに統合することができます。 さらに、これらの環境変数を公開することにより、パワーユーザーはコマンド スクリプトをさらにカスタマイズすることができます。

    複数コマンド

    テンプレート レンダリングの実行用に設定されたコマンドは、単一のコマンドでなければなりません。 つまり、複数のコマンドを&&、;、|などで結合することはできません。これは、コマンドの実行方法に関する制限です。 しかし、sh -cを使用して複数のコマンドを明示的なシェルコマンドに結合することで、これを行うことができる。

    たとえば、テンプレートがレンダリングされたときに実行する必要がある /opt/foo と /opt/bar というスクリプトがあり、/opt/foo が成功した場合にのみ /opt/bar を実行するようにしたい場合。 これを行うには、コマンド…

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

    これは完全なシェル コマンドなので、条件文も使用できます。

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

    この方法を使用すると、必要な論理で必要なだけシェル コマンドを実行できます。 しかし、長くなりすぎる場合は、シェルスクリプトにラップし、それを展開して実行することをお勧めします。

    マルチフェーズ実行

    Consul Template はテンプレートの評価を n パス行い、各パスで依存性を蓄積します。 これは、次のようなネストされた依存関係のために必要です:

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

    最初のパスで、Consul TemplateはConsulのサービスを知らないので、クエリーを実行する必要があります。 これらの結果が返されると、その結果で内部ループが評価され、潜在的にさらなるクエリーとウォッチが作成されます。

    この実装のため、テンプレート関数には、range関数 (または類似) への受け入れられるパラメーターであり、実際に内部ループを実行しない (パニックを引き起こす) デフォルト値が必要とされます。 複雑なテンプレートは「空」の場合を考慮しなければならないので、これは重要なことです。 たとえば、次のコードは動作しません。

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

    このコードは次のようなエラーを発生させます： 

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

    これは、テンプレートの最初の評価時に、serviceキーが空のスライスを返しているためです。 

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

    のようにテンプレートでこれを考慮できます。

    FAQ

    Q: これは confd とどう違うのですか? サービス ディスカバリーを第一級市民としています。 また、このプロジェクトに関するこの Pull Request を読んで、より多くの背景情報を得ることが推奨されます。 私たちは confd がすばらしいプロジェクトであると考えていますが、Consul Template は欠けているギャップを埋めるものです。 さらに、Consul Template は Vault とファーストクラスの統合を行い、データベース認証情報や API トークンのような秘密資料を設定ファイルに簡単に組み込むことができます。

    Q: これは Puppet/Chef/Ansible/Salt とどう違うのですか A: 設定管理ツールは Consul Template と一緒に使用するように設計されています。

    Contributing

    Consul-Template をローカルにビルドしてインストールするには、Go をインストールする必要があります。

    リポジトリをクローンします:

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

    ローカルマシン用に consul-template バイナリをコンパイルします:

    $ make dev

    これは $GOPATH と同じように consul-template バイナリを bin/consul-template にコンパイルしてテストスイートを実行するものです。

    特定のバイナリをコンパイルしたい場合は、XC_OS と XC_ARCH を設定するか、すべてのバイナリを生成するために以下を実行します:

    $ make build

    テストを実行したい場合は、まずローカルに consul と vault をインストールしてから:

    $ make test

    またはスイートで特定のテストを実行する:

    go test ./... -run SomeTestFunction_name

    。

コメントする