Contents
1. Consul エージェントのインストールとサービス登録
このセクションでは、サーバーモード と クライアントモード の構築手順、および Consul にサービスを登録する際のベストプラクティスを紹介します。正しく構成すれば、CTS が期待どおりに情報を取得できる基盤が完成します。
1.1 最新バージョンの確認方法
HashiCorp のリリース API を利用すると、常に最新バージョン番号を取得できます。
|
1 2 3 4 5 6 7 8 |
# Consul の最新版取得例 curl -s https://releases.hashicorp.com/consul/index.json | \ jq -r '.versions[] | select(.stable==true) | .version' | sort -V | tail -1 # CTS (Consul Terraform Sync) の最新版取得例 curl -s https://releases.hashicorp.com/consul-terraform-sync/index.json | \ jq -r '.versions[] | select(.stable==true) | .version' | sort -V | tail -1 |
2026‑06‑13 現在、Consul 1.20.3 と CTS 0.8.2 が最新の安定版です。以降の手順はこのバージョンを前提に記述していますが、上記コマンドで取得したバージョン文字列に差し替えて実行してください。
1.2 サーバーモード構築手順
サーバーノードは Raft コンセンサスで状態を保持し、クライアントからの問い合わせに対して一貫した情報を返します。以下では Ubuntu 22.04 に Consul 1.20.3 をインストールし、systemd で管理するまでの流れを示します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
# ① バイナリ取得・配置 CONSUL_VER=1.20.3 curl -L https://releases.hashicorp.com/consul/${CONSUL_VER}/consul_${CONSUL_VER}_linux_amd64.zip -o consul.zip unzip consul.zip -d /usr/local/bin chmod +x /usr/local/bin/consul # ② 必要ディレクトリ作成 mkdir -p /etc/consul.d /var/lib/consul # ③ server.hcl（基本設定）を作成 cat <<'EOF' >/etc/consul.d/server.hcl datacenter = "dc1" data_dir = "/var/lib/consul" bind_addr = "0.0.0.0" client_addr = "0.0.0.0" server = true bootstrap_expect = 3 # 本番環境ではノード数に合わせる ui = true EOF # ④ systemd ユニット作成 cat <<'EOF' >/etc/systemd/system/consul.service [Unit] Description=HashiCorp Consul Agent After=network-online.target Wants=network-online.target [Service] ExecStart=/usr/local/bin/consul agent -config-dir=/etc/consul.d ExecReload=/bin/kill -HUP $MAINPID Restart=on-failure LimitNOFILE=65536 EnvironmentFile=-/etc/consul.d/env [Install] WantedBy=multi-user.target EOF # ⑤ 起動・有効化 systemctl daemon-reload systemctl enable --now consul.service |
ポイント
bootstrap_expectはサーバーノード数の過半数が起動した時点でクラスタが確立する目安です。テスト環境では 1、実運用では 3〜5 を推奨します。
ブラウザから http://<node-ip>:8500/ui にアクセスできれば UI が表示されます。
1.3 クライアントモード構築手順
クライアントは軽量エージェントとしてサービス登録のみを行い、サーバーへの負荷を最小化します。以下の例では AWS 環境に自動参加させる retry_join 設定を用いています。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# /etc/consul.d/client.hcl datacenter = "dc1" data_dir = "/var/lib/consul" client = true bind_addr = "{{ GetInterfaceIP \"eth0\" }}" retry_join = [ "provider=aws tag_key=ConsulServer tag_value=true", "provider=azure tag_name=consul-server" ] |
設定ファイルを保存したら、同じ systemd ユニットで再起動します。
|
1 2 |
systemctl restart consul.service |
ポイント
クライアントはserver = falseがデフォルトです。retry_joinに複数のプロバイダーを列挙すればハイブリッド環境でも自動参加が可能です。
1.4 サービス定義のベストプラクティス
Consul に登録するサービスは JSON または YAML のいずれかで記述し、必須項目（name, port）に加えて ヘルスチェック, タグ, メタデータ を付与します。以下に実務で頻繁に利用される要素をまとめました。
1.4.1 JSON 例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "service": { "name": "web-app", "id": "web-app-01", "port": 8080, "tags": ["http", "prod"], "meta": { "env": "production", "owner": "team-a" }, "check": { "id": "web-app-http", "name": "HTTP health check", "http": "http://localhost:8080/health", "interval": "10s", "timeout": "2s" } } } |
1.4.2 YAML 例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
service: name: db-proxy id: db-proxy-01 port: 5432 tags: - tcp - prod meta: env: production owner: team-b check: id: db-proxy-tcp name: TCP health check tcp: "localhost:5432" interval: 15s timeout: 3s |
1.4.3 登録コマンド
|
1 2 3 4 |
consul services register /path/to/web-app.json # または consul services register /path/to/db-proxy.yaml |
注意：外部サイト（例:
app‑tatsujin.com）への参照は一次情報ではないため、公式ドキュメントや GitHub のリポジトリを優先してください。
2. Consul Terraform Sync (CTS) の取得・インストール
このセクションでは、CTS バイナリの入手方法と、Terraform 本体とのバージョン互換性について解説します。
2.1 バージョン互換性と Terraform 要件
| CTS バージョン | 対応 Terraform バージョン |
|---|---|
| 0.8.x | ≥ 1.6, ≤ 1.9 |
| 0.7.x | ≥ 1.4, < 1.6 |
| 0.6.x | ≥ 1.2, < 1.4 |
推奨：本稿では Terraform 1.8.5 と CTS 0.8.2 の組み合わせを前提にしています。terraform -version コマンドで実行中のバージョンを確認し、互換性表と照らし合わせてください。
2.2 バイナリ取得手順（Linux / macOS）
公式リリースページからプラットフォーム別に zip ファイルをダウンロードし、実行権限を付与します。以下は最新バージョン 0.8.2 の例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
CTS_VER=0.8.2 # Linux x86_64 curl -L https://releases.hashicorp.com/consul-terraform-sync/${CTS_VER}/consul-terraform-sync_${CTS_VER}_linux_amd64.zip -o cts_linux.zip unzip cts_linux.zip -d $HOME/.local/bin # macOS (Apple Silicon) curl -L https://releases.hashicorp.com/consul-terraform-sync/${CTS_VER}/consul-terraform-sync_${CTS_VER}_darwin_arm64.zip -o cts_mac.zip unzip cts_mac.zip -d $HOME/.local/bin chmod +x $HOME/.local/bin/consul-terraform-sync |
$HOME/.local/bin を PATH に追加していない場合は、以下をシェルの初期化ファイルに追記してください。
|
1 2 |
export PATH=$HOME/.local/bin:$PATH |
インストール後はバージョン確認で完了です。
|
1 2 3 |
consul-terraform-sync version # Consul Terraform Sync v0.8.2 |
2.3 systemd（Linux）／launchd（macOS）によるデーモン化
本番運用では systemd（Linux）または launchd（macOS）で永続起動させ、障害時の自動再起動を確保します。
2.3.1 systemd ユニット例（Linux）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# /etc/systemd/system/cts.service [Unit] Description=Consul Terraform Sync After=network-online.target consul.service Wants=consul.service [Service] ExecStart=/usr/local/bin/consul-terraform-sync run -config=/etc/cts/cts.hcl Restart=on-failure RestartSec=10 LimitNOFILE=65536 EnvironmentFile=-/etc/cts/cts.env # 環境変数は別ファイルで管理 [Install] WantedBy=multi-user.target |
|
1 2 3 4 |
systemctl daemon-reload systemctl enable --now cts.service journalctl -u cts.service -f # ログをリアルタイムで確認 |
2.3.2 launchd プロパティリスト例（macOS）
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key><string>com.hashicorp.cts</string> <key>ProgramArguments</key> <array> <string>/usr/local/bin/consul-terraform-sync</string> <string>run</string> <string>-config=/etc/cts/cts.hcl</string> </array> <key>RunAtLoad</key><true/> <key>KeepAlive</key><true/> <key>StandardOutPath</key><string>/var/log/cts.log</string> <key>StandardErrorPath</key><string>/var/log/cts.err</string> </dict> </plist> |
保存後は launchctl load /Library/LaunchDaemons/com.hashicorp.cts.plist でロードします。
3. CTS 設定ファイルとタスク定義
CTS が参照する cts.hcl は大きく log, buffer, task の３ブロックから構成されます。ここでは各ブロックの役割と実務で推奨されるパラメータを解説します。
3.1 ログ設定 (log ブロック)
ログはトラブルシューティングの根幹です。INFO 以上のレベルを出力しつつ、ファイルローテーションは OS の logrotate に委任する構成が一般的です。
|
1 2 3 4 5 |
log { level = "INFO" # DEBUG/INFO/WARN/ERROR file = "/var/log/cts/cts.log" } |
ポイント：
DEBUGは開発時のみ有効化し、実運用ではINFOに抑えることでディスク使用量を削減できます。
3.2 バッファ設定 (buffer ブロック)
バッファは短時間に多数のサービス変更があった場合の「まとめ処理」に利用します。以下は 5 秒 のタイムアウトと 10 件 の最大蓄積数です。
|
1 2 3 4 5 |
buffer { size = 10 # 同時に保持できるイベント数上限 timeout = "5s" # バッファが満たされなくてもこの時間でフラッシュ } |
ポイント：ネットワーク機器の設定変更は API 呼び出し回数を抑えるべきなので、
sizeとtimeoutはインフラ規模に合わせて調整してください。
3.3 タスク定義 (task ブロック)
タスクは どのサービスが変化したら どの Terraform モジュールを実行するか を決める中心要素です。以下は多プロバイダー対応の実装例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
task { name = "network-automation" # 監視対象サービス（ワイルドカード可） services = ["web-*", "db-proxy"] # Terraform モジュールへの相対パス source = "./modules/network" # プロバイダー別設定。各 provider の version 制約と必須フィールドを明示。 providers { aws = { version = "~> 5.0" region = "ap-northeast-1" } azurerm = { version = "~> 4.2" features {} } cisco = { version = "~> 2.1" endpoint = "https://cisco.example.com/api" } } # Consul のサービス属性を Terraform 変数へマッピング variables = { subnet_id = "${service.tags.subnet}" vpc_cidr = "${service.meta.cidr}" device_name = "${service.name}" } # 任意：plan 実行前に任意のシェルコマンドを走らせるフック pre_hook = "echo 'Starting plan for ${var.device_name}'" post_hook = "curl -X POST https://monitor.example.com/cts-complete" } |
ポイント
servicesにワイルドカード (*) を使うと、同一パターンのサービスが増えても自動的に検知できます。
variablesでは HCL の式展開が可能です。実際の変数名はモジュール側で定義したものと合わせてください。
4. セキュリティ：ACL、TLS、Vault 連携
自動化基盤を本番運用する上で不可欠なのが 認可・暗号化 と シークレット管理 です。この章では Consul の ACL ポリシー例、TLS 設定手順、Vault を介したトークンの安全な取得方法を示します。
4.1 ACL ポリシーの詳細例
単なる read 権限だけでなく、名前空間（namespace）, サービスプレフィックス, キー/バリュー権限 を組み合わせた実務向きポリシーです。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# cts-policy.hcl # ------------------------------------------------- # 1. CTS が読み取る全てのサービス情報 service_prefix "" { policy = "read" } # 2. CTS がノード情報を書き込む（登録されたエージェントのヘルス更新等） node_prefix "" { policy = "write" } # 3. 名前空間単位で UI アクセスを許可 namespace "default" { policy = "read" } # 4. キー/バリューストアへの限定的書き込み（Vault と連携したシークレット更新用） key_prefix "secret/cts/" { policy = "write" } # ------------------------------------------------- |
ポリシー適用手順
|
1 2 3 4 5 6 7 |
# 1. ポリシーファイルを登録 consul acl policy create -name cts-policy -rules @cts-policy.hcl # 2. トークン作成（期限付きにするとローテーションが楽になる） consul acl token create -description "CTS token" \ -policy-name cts-policy -ttl "72h" -format=json > cts-token.json |
4.2 TLS 設定手順
TLS は 双方向認証（mTLS）を推奨します。以下は自己署名 CA を用いた最小構成です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# 1. 自己署名 CA 作成 openssl genrsa -out ca.key 4096 openssl req -x509 -new -nodes -key ca.key -sha256 -days 3650 -out ca.pem \ -subj "/CN=Consul-CA" # 2. サーバー証明書作成（CN はサーバーノードの FQDN） openssl genrsa -out server.key 4096 openssl req -new -key server.key -out server.csr \ -subj "/CN=consul-server.example.com" openssl x509 -req -in server.csr -CA ca.pem -CAkey ca.key -CAcreateserial \ -out server.crt -days 365 -sha256 # 3. クライアント証明書作成（CTS 用） openssl genrsa -out client.key 4096 openssl req -new -key client.key -out client.csr \ -subj "/CN=cts-client" openssl x509 -req -in client.csr -CA ca.pem -CAkey ca.key -CAcreateserial \ -out client.crt -days 365 -sha256 |
consul.hcl に TLS パラメータを追記します。
|
1 2 3 4 5 6 7 8 9 10 |
tls { defaults { ca_file = "/etc/consul.d/certs/ca.pem" cert_file = "/etc/consul.d/certs/server.crt" key_file = "/etc/consul.d/certs/server.key" verify_incoming = true verify_outgoing = true } } |
CTS 側は環境変数で証明書パスを渡します（cts.env に記載）。
|
1 2 3 4 5 |
export CONSUL_HTTP_SSL=true export CONSUL_CACERT=/etc/consul.d/certs/ca.pem export CONSUL_CLIENT_CERT=/etc/consul.d/certs/client.crt export CONSUL_CLIENT_KEY=/etc/consul.d/certs/client.key |
4.3 Vault を用いたトークン自動取得
Vault の KV シークレットエンジン に CTS 用 ACL トークンを格納し、CTS 起動時に動的に注入します。
|
1 2 3 4 5 6 7 8 |
# Vault 側でシークレット作成（例: admin が実行） vault kv put secret/consul/cts token=$(jq -r .SecretID cts-token.json) # CTS 用 systemd ユニットの EnvironmentFile に vault コマンドを組み込む例 cat <<'EOF' >/etc/cts/cts.env export CONSUL_HTTP_TOKEN=$(vault kv get -field=token secret/consul/cts) EOF |
ベストプラクティス：Vault の AppRole で短命トークンを取得し、
Consul HTTP Tokenとして使用することで、漏洩リスクを最小化できます。
5. トラブルシューティングと CI/CD 統合
実運用ではエラーの早期検知と自動テストが不可欠です。この章では代表的なエラーコードと対処法、さらに GitHub Actions を利用した CTS の CI パイプライン例を示します。
5.1 主なエラーコードと対処法
| エラーコード | 発生シーン | 主な原因 | 推奨対策 |
|---|---|---|---|
ERR_CONFIG_PARSE |
cts run 起動時 |
HCL 文法ミス、必須ブロック欠如 | consul-terraform-sync config validate -config=cts.hcl で事前検証 |
ERR_CONSUL_UNREACHABLE |
Consul API 呼び出し失敗 | ACL トークン無効・TLS 証明書不一致 | 環境変数 (CONSUL_HTTP_TOKEN, CONSUL_CLIENT_CERT) を再確認 |
ERR_TF_PROVIDER_NOT_FOUND |
Terraform 実行時 | .terraformrc がロードされない、バージョン不整合 |
$HOME/.terraformrc に provider_installation {} 設定を追加し、terraform init -upgrade |
ERR_BUFFER_OVERFLOW |
大量変更が短時間に集中 | バッファサイズ不足 | buffer.size と buffer.timeout を増加させる |
ERR_TLS_HANDSHAKE |
TLS 接続失敗 | 証明書期限切れ、CN 不一致 | 期限を定期的に更新し、verify_incoming/outgoing の設定を見直す |
ログの読み方
- INFO：正常フロー（検知 → plan → apply）
- WARN：リトライや非致命的エラー（例: Consul 再接続）
- ERROR：プロセス停止要因。journalctl -u cts.service -p err で抽出し、上表を参照してください。
5.2 GitHub Actions での CTS テストパイプライン例
CI では 一回だけ実行（-once）して結果を検証する方式が推奨されます。以下は最小構成です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 |
name: CTS Integration Test on: push: paths: - 'cts/**' - 'modules/**' jobs: test-cts: runs-on: ubuntu-latest env: CONSUL_HTTP_ADDR: ${{ secrets.CONSUL_HTTP_ADDR }} CONSUL_HTTP_TOKEN: ${{ secrets.CONSUL_HTTP_TOKEN }} VAULT_ADDR: ${{ secrets.VAULT_ADDR }} VAULT_TOKEN: ${{ secrets.VAULT_TOKEN }} steps: - name: Checkout repository uses: actions/checkout@v3 - name: Install Terraform (1.8) uses: hashicorp/setup-terraform@v2 with: terraform_version: 1.8.5 - name: Install CTS run: | CTS_VER=$(curl -s https://releases.hashicorp.com/consul-terraform-sync/index.json \ | jq -r '.versions[] | select(.stable==true) | .version' | sort -V | tail -1) curl -L https://releases.hashicorp.com/consul-terraform-sync/${CTS_VER}/consul-terraform-sync_${CTS_VER}_linux_amd64.zip -o cts.zip unzip cts.zip -d $HOME/.local/bin chmod +x $HOME/.local/bin/consul-terraform-sync - name: Run CTS in one‑shot mode run: | export CONSUL_HTTP_TOKEN=$(vault kv get -field=token secret/consul/cts) consul-terraform-sync run -config=cts/cts.hcl -once |
実運用上の注意点
- シークレットは GitHub Secrets に保存し、コード内に平文を書かないこと。
- -once オプションでテストを終了させ、本番環境では systemd デーモン化した長期実行モードへ切り替えてください。
6. まとめ
- 最新版の確認は HashiCorp のリリース API を活用し、常に
Consul 1.xとCTS 0.xの最新安定版を取得します。 - サーバー／クライアントモードの構築手順とサービス登録方法を示したことで、CTS が情報を正確に取得できる基盤が整います。
- CTS バイナリ取得・インストールは公式サイトからダウンロードし、Terraform 1.8 系との互換性を確認します。systemd/launchd でデーモン化すれば障害時の自動復旧も実現できます。
- cts.hcl の構成（log, buffer, task）はそれぞれの役割と推奨パラメータを把握し、マルチプロバイダー対応タスク例で実装すればネットワーク機器・クラウドリソースの自動化がシームレスに行えます。
- セキュリティは ACL ポリシーを細かく定義し、TLS による双方向認証と Vault でのトークン管理を組み合わせて、漏洩リスクを最小化します。
- トラブルシューティング用エラー表と CI/CD パイプライン例により、障害検知・復旧・自動テストが高速化されます。
以上の手順とベストプラクティスに沿って構築すれば、Consul Terraform Sync を活用したネットワークインフラ自動化 が本番環境でも安定して運用できるようになります。必要に応じて各ブロックやポリシーをプロジェクト固有の要件に合わせてカスタマイズし、継続的なバージョン管理とテストで品質を保ちましょう。