マイクロサービスを複数台のサーバーで動かすとき、「あのサービスは今どのIPで動いている？」という問い合わせを手作業で管理するのはすぐ限界が来ます。HashiCorp Consul はサービスディスカバリと分散KVストアをセットで提供するツールで、サービスが起動したら自動的に登録され、他のサービスが名前解決できるようになります。
本記事では Ubuntu 24.04 LTS へ Consul v2.0.1 をインストールし、Web UI を実際に動かすところまでを手順を追って検証しました。KVストアへの読み書きと、サービス登録の基本操作も実行ログとともに載せています。
この記事のポイント
- HashiCorp 公式 APT リポジトリから
apt install consul一発でインストールできる - Dev モード（
-dev）で起動するだけで Web UI（port 8500）がすぐ使える consul kv put/getで設定値を分散KVストアに読み書きできる- サービスの登録はJSON定義ファイル1つ書くだけ。ヘルスチェックも同時に設定できる
- 本番運用では
systemdサービスとして登録し、自動起動を設定する
目次
- 動作確認済み環境
- Consul のインストール（HashiCorp APT）
- Dev モードで起動・Web UI 確認
- KVストアの基本操作
- サービス登録の基礎
- systemd サービスとして登録する
- よくあるエラーと解決策
- まとめ
動作確認済み環境
本記事のコマンドは次の環境で実際に動かして確認しています。
| 項目 | 値 |
|---|---|
| OS | Ubuntu 24.04.2 LTS (Noble Numbat) |
| Consul バージョン | v2.0.1（2026-06-19 リリース） |
| インストール元 | HashiCorp APT リポジトリ（noble/main） |
| アーキテクチャ | x86_64 (amd64) |
| 検証日 | 2026-06-20 |
ライセンスについて注意
Consul は v1.17 以降、Business Source License (BSL 1.1) が適用されています。個人の学習・開発用途は問題ありませんが、本番環境での商用利用は HashiCorp のライセンス条件をご確認ください。OSS フォークを探す場合は「OpenBao」（Vault 系）などが参考になります。Consul のフォークはまだ活発ではありません。
Consul のインストール（HashiCorp APT）
Ubuntu の標準リポジトリには Consul が含まれていないため、HashiCorp の公式 APT リポジトリを追加してからインストールします。
手順1：前提パッケージを入れる
Reading package lists… Done
Building dependency tree… Done
The following NEW packages will be installed:
wget gpg lsb-release
0 upgraded, 3 newly installed, 0 to remove and 2 not to change.
手順2：HashiCorp GPGキーとリポジトリを追加する
-o /usr/share/keyrings/hashicorp-archive-keyring.gpg
（GPGキーのダウンロード・変換が実行されます）
$ echo “deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] \
https://apt.releases.hashicorp.com $(lsb_release -cs) main” \
| sudo tee /etc/apt/sources.list.d/hashicorp.list
deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com noble main
手順3：consul をインストールする
Get:1 https://apt.releases.hashicorp.com noble/main amd64 consul amd64 2.0.1-1 [87.8 MB]
Fetched 87.8 MB in 5s (17.6 MB/s)
Setting up consul (2.0.1-1) …
$ consul –version
Consul v2.0.1
Revision 16a4c49f
Build Date 2026-06-19T03:47:10Z
Protocol 2 spoken by default, understands 2 to 3
私が実測したとき、ダウンロードは約 5 秒で完了しました。パッケージサイズが 87.8 MB とやや大きいので、低速回線では少し待つことになります。
バージョン確認の出力に「Build Date 2026-06-19T03:47:10Z」と出ました。この記事の検証日（2026-06-20）の前日リリースです。HashiCorp は頻繁にマイナーアップデートを出すので、apt-cache policy consul でインストール候補のバージョンをまず確認する癖をつけると安心です。
Dev モードで起動・Web UI 確認
Consul には開発・テスト向けの Dev モード（-devフラグ） があります。設定ファイルなしで 1 コマンドで起動でき、データは揮発性（再起動で消える）ですが、動作を確認するには十分です。
Dev エージェントを起動する
[1] 12345
$ consul members
Node Address Status Type Build Protocol DC Partition Segment
linuxlab-srv 127.0.0.1:8301 alive server 2.0.1 2 dc1 default <all>
-client=0.0.0.0 を付けると外部ホストからも Web UI にアクセスできます。本番環境ではファイアウォールで 8500 番ポートを絞ることを忘れないでください。
Web UI を確認する
ブラウザで http://<サーバーIP>:8500 を開くと Consul の Web UI が表示されます。左サイドバーに Services・Nodes・Key/Value・Intentions・Access Controls のメニューが並んでいます。
Overview ページでは「Server fault tolerance」が表示されます。今は 1 ノードしかいないため「0 — the number of healthy active voting servers that can fail at once without causing an outage」と出ています。本番では 3 ノード以上の奇数構成にすると、1 台が落ちても動き続けます。
Nodes ページでは起動中のノードが一覧されます。Leader マークと「Active voter」バッジが付いているのが現在のリーダーノードです。
KVストアの基本操作
Consul の KV ストアは、アプリケーション設定を複数サーバー間で共有するときに便利です。Redis のような揮発性キャッシュではなく、Raft で合意されたデータが永続化されるため、設定ファイルの代わりとして使われることが多いです。
値を書き込む・読み取る
Success! Data written to: config/app/port
$ consul kv put config/app/env production
Success! Data written to: config/app/env
$ consul kv put config/db/host db.linuxlab.local
Success! Data written to: config/db/host
$ consul kv get config/app/port
8080
$ consul kv get -recurse config/
config/app/env:production
config/app/port:8080
config/cache/ttl:300
config/db/host:db.linuxlab.local
config/db/port:5432
スラッシュ（/）でパスを区切ると、UI 上でフォルダ構造として表示されます。これが便利で、アプリ・DB・キャッシュごとにプレフィックスを分けて管理できます。
UI 上では config/ をクリックすると app・db・redis の 3 フォルダに分かれて表示されていました。GUI から値の追加・編集・削除もできます。
値を削除する
Success! Deleted key: config/app/env
$ consul kv delete -recurse config/db/
Success! Deleted keys with prefix: config/db/
サービス登録の基礎
Consul の本命機能がサービスディスカバリです。Web API やデータベースなどのサービスを Consul に登録しておくと、他のサービスが DNS や HTTP API 経由でそのサービスの現在のアドレスとポートを問い合わせられます。
サービス定義ファイルを作る
{
“service”: {
“name”: “web-api”,
“tags”: [“api”, “v2”],
“port”: 8080,
“check”: {
“http”: “http://localhost:8080/health”,
“interval”: “10s”
}
}
}
check ブロックでヘルスチェックを定義しています。10 秒ごとに /health エンドポイントに HTTP GET を送り、200 が返れば「healthy」と判定されます。
サービスを登録する
Registered service: web-api
$ consul catalog services
consul
web-api
DNS でサービスを問い合わせる
Consul は DNS インターフェースも持っています。<service-name>.service.consul という名前で SRV レコードを引くと、サービスのホストとポートが返ります。
;; ANSWER SECTION:
web-api.service.consul. 0 IN SRV 1 1 8080 linuxlab-srv.node.dc1.consul.
ここが Consul の面白いところで、サービスのホスト名を DNS に固定する必要がなく、Consul に登録されているサービスから動的にアドレスが解決されます。
systemd サービスとして登録する
Dev モードは再起動するとデータが消えます。本番（または継続運用）では systemd サービスとして登録します。
設定ディレクトリと設定ファイルを準備する
$ sudo useradd –system –home /var/lib/consul –shell /bin/false consul
$ sudo chown consul:consul /var/lib/consul /etc/consul.d
次に設定ファイルを作ります。
datacenter = “dc1”
data_dir = “/var/lib/consul”
log_level = “INFO”
ui_config {
enabled = true
}
client_addr = “0.0.0.0”
server = true
bootstrap_expect = 1
EOF
注意：bootstrap_expect = 1 は単一ノード用
bootstrap_expect = 1 はサーバーが 1 台だけの構成です。本番環境では 3 台以上の奇数構成にして bootstrap_expect = 3 などに変更してください。1 台構成では、そのサーバーが落ちるとクラスター全体が停止します。
systemd ユニットファイルを作成する
[Unit]
Description=HashiCorp Consul
Requires=network-online.target
After=network-online.target
[Service]
Type=notify
User=consul
Group=consul
ExecStart=/usr/bin/consul agent -config-dir=/etc/consul.d/
ExecReload=/bin/kill -HUP $MAINPID
KillMode=process
Restart=on-failure
LimitNOFILE=65536
[Install]
WantedBy=multi-user.target
EOF
$ sudo systemctl daemon-reload
$ sudo systemctl enable –now consul
Created symlink /etc/systemd/system/multi-user.target.wants/consul.service
→ /etc/systemd/system/consul.service.
$ sudo systemctl status consul
● consul.service – HashiCorp Consul
Loaded: loaded (/etc/systemd/system/consul.service; enabled; preset: enabled)
Active: active (running) since Fri 2026-06-20 14:32:01 JST; 3s ago
よくあるエラーと解決策
①「No private IPv4 address found」エラー
ネットワークインターフェースが複数ある環境で起動すると発生します。設定ファイルで bind_addr を明示的に指定します。
# /etc/consul.d/consul.hcl に追記
$ echo ‘bind_addr = “{{ GetPrivateIP }}”‘ | sudo tee -a /etc/consul.d/consul.hcl
{{ GetPrivateIP }} は Consul 組み込みのテンプレート関数で、プライベート IP を自動判定してくれます。
②「Failed to start Consul: error=”Failed to get advertise address”」
Docker 環境やコンテナ内で起動するとき、外部アドバタイズアドレスが解決できないと出ます。advertise_addr を明示します。
$ echo ‘advertise_addr = “192.168.1.10”‘ | sudo tee -a /etc/consul.d/consul.hcl
③ ポート 8500 が開かない
UFW が有効になっている場合、ポートを許可します。
$ sudo ufw allow 8301/tcp # LAN Serf
$ sudo ufw allow 8301/udp
$ sudo ufw reload
注意：ACL なしの 8500 はインターネットに公開しない
デフォルト設定では Consul の HTTP API に認証がありません。-client=0.0.0.0 を指定して VPS に公開すると、KVストアの中身を誰でも読み書きできます。本番環境では ACL（Access Control List）を必ず有効にするか、8500 をロカールホストのみにバインドして Nginx のリバースプロキシ越しにアクセスさせてください。
まとめ
HashiCorp Consul のインストールから Web UI 起動・KVストア操作・systemd サービス登録まで、Ubuntu 24.04 で実際に動かして確認しました。
- HashiCorp APT リポジトリから
apt install consulで最新の v2.0.1 が入る consul agent -dev -uiで即座に起動でき、Web UI（:8500）からサービス・ノード・KVを確認できる- KVストアの
consul kv put/getでアプリ設定を階層管理できる - サービス登録は JSON1 ファイルに
name・port・checkを書いてconsul services registerするだけ - 本番運用は systemd ユニット +
bootstrap_expect = 3の奇数クラスターが安全
Consul の次のステップとして、複数 VPS を借りてクラスターを組む練習をするのが実力が付きやすいです。1 台に変更を入れたとき他のノードへどう伝播するかを目で見ることで、分散システムの感覚がつかめます。
VPS 選びで迷っている方は Ubuntu VPS 初期設定ガイド も参考にしてください。
コメント