Cassandra シングルノード構築手順 — 検証環境を最短で立てる

目的

本稿は Cassandra の 検証用シングルノード を最小手順で立てる手順書です。 本番ではシングルノード運用は推奨しません (そもそも Cassandra を使うモチベーションが可用性とスケールにあるため)。 PoC・学習・スキーマ検証向け。

前提知識は Cassandra データモデル入門 と Cassandra 読み書き内部フロー を参照。

Java ランタイム

Cassandra は Java 製なので JRE が必須。

Cassandra バージョン	対応 JVM
3.x	Java 8
4.0	Java 8 / 11
4.1	Java 11 (recommended)
5.0	Java 11 / 17

本稿は 2017 年執筆当時の 3.11 系を想定しますが、新規なら 4.1 以降 を選びましょう。

# Amazon Linux / RHEL 系
sudo yum install -y java-11-amazon-corretto

# Debian / Ubuntu
sudo apt-get install -y openjdk-11-jre-headless

Cassandra のインストール

RPM 系 (yum)

/etc/yum.repos.d/cassandra.repo:

[cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/41x/
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://downloads.apache.org/cassandra/KEYS

インストール:

sudo yum install -y cassandra
sudo systemctl daemon-reload

Docker で手早く

検証なら Docker が最速:

docker run -d --name cassandra -p 9042:9042 cassandra:4.1

cassandra.yaml の最小設定

/etc/cassandra/cassandra.yaml (Docker なら docker exec で確認):

cluster_name: 'glv-dev'

listen_address: <自ホストの到達可能 IP>
rpc_address:    <自ホストの到達可能 IP>

endpoint_snitch: SimpleSnitch       # 単一 DC 用

seed_provider:
  - class_name: org.apache.cassandra.locator.SimpleSeedProvider
    parameters:
      - seeds: "<自分の IP>"

各項目の意味

キー	意味	シングルノード時の値
cluster_name	クラスタ名。将来マルチノードにするときのグルーピング	任意 (例: glv-dev)
listen_address	ノード間通信 (ゴシップ) で使う自分の IP	自ホスト IP
rpc_address	クライアントからの CQL 受け口	自ホスト IP
endpoint_snitch	クラスタトポロジ解決の戦略	SimpleSnitch (単 DC)
seed_provider / seeds	クラスタ参加時に最初にコンタクトするノード	自分の IP

本番は必ず GossipingPropertyFileSnitch を選び、 cassandra-rackdc.properties で DC / Rack を明示します (クラスタ構築編 参照)。

listen_address に localhost は使わない

Docker コンテナ内でも VM でも、他ノードから到達可能な IP を指定する必要があります。 後で複数ノード化する際にハマるので、最初から正しい IP に。

DC / Rack の設定

/etc/cassandra/cassandra-rackdc.properties:

dc=dc1
rack=rack1

本番運用時は dc を物理 DC / リージョン名 (例: ap-northeast-1) に、 rack を AZ (例: ap-northeast-1a) に合わせるのが鉄則。

起動と確認

sudo systemctl start cassandra
sudo systemctl enable cassandra

# ログ確認
sudo tail -f /var/log/cassandra/system.log

起動後 30 秒ほどで Starting listening for CQL clients on ... が出れば OK。

nodetool status で確認

nodetool status

Datacenter: dc1
===============
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
--  Address        Load       Tokens  Owns (effective)  Host ID                               Rack
UN  10.0.0.10      282 KiB    256     100.0%            a1c9c548-1ed2-453d-aee3-927fb0ab8279  rack1

カラム	意味
Status	U (Up) / D (Down)
State	N (Normal) / L (Leaving) / J (Joining) / M (Moving)
Address	ノード IP
Load	保持データサイズ (スナップショット時点)
Tokens	仮想ノード数 (既定 256)
Owns	リング内で担当しているキー範囲の割合
Host ID	ノード固有 UUID
Rack	設定した Rack 名

UN = Up & Normal。これが出れば CQL 接続可能。

CQL で最初のテーブル

cqlsh 10.0.0.10

CREATE KEYSPACE app WITH replication = {
  'class': 'SimpleStrategy',       -- 単 DC 検証用
  'replication_factor': 1
};

USE app;

CREATE TABLE users (
  id text PRIMARY KEY,
  name text,
  created_at timestamp
);

INSERT INTO users (id, name, created_at) VALUES ('u1', 'Alice', toTimestamp(now()));
SELECT * FROM users;

本番は NetworkTopologyStrategy を必ず選ぶこと (RF 設計の自由度を保つため)。

よくあるハマり

1. nodetool status で DN (Down & Normal) になる

ログ /var/log/cassandra/system.log を見る。 典型は OutOfMemoryError (ヒープ不足) か AddressAlreadyInUse (ポート衝突)。 検証環境のヒープは -Xms2G -Xmx2G 程度で十分 (/etc/cassandra/jvm-server.options)。

2. rpc_address: 0.0.0.0 にしたら接続できない

Cassandra は 0.0.0.0 を listen には使えますが、 ドライバがコンタクトする時のアドレス解決には broadcast_rpc_address を明示する必要があります:

rpc_address: 0.0.0.0
broadcast_rpc_address: 10.0.0.10

3. ポート確認

• 9042: CQL (ドライバ接続)
• 7000: ノード間ゴシップ (TLS は 7001)
• 7199: JMX (nodetool)

セキュリティグループ / firewalld でこれらを許容しないとクラスタ化時に詰まる。

4. 初期ユーザの認証

既定では認証無効。本番化する前に authenticator: PasswordAuthenticator に切り替え、 初期ユーザ cassandra/cassandra を必ず変更。

---

まとめ: Cassandra のシングルノードは cassandra.yaml の 4 項目 (listen_address / rpc_address / snitch / seeds) を書くだけで動きます。 検証はシングル → クラスタ化は追加設定だけ、という流れが設計の綺麗さ。 本番用途では必ず クラスタ構築手順 に進み、RF と一貫性レベルも合わせて設計を。