Apache Cassandra on Ubuntu — 大規模分散NoSQLクラスターの構築

この記事のポイント

Apache Cassandra 5.0.8 を Ubuntu 24.04 LTS に公式 apt リポジトリ経由でインストールする手順を実機（Docker）で確認
必要な Java バージョンは openjdk-17-jre-headless。Ubuntu 22.04 の Java 11 では Cassandra 5.x は動作しない
nodetool status で UN（Up/Normal）が表示されれば起動成功。私の環境では 45 秒で起動した
cqlsh から CQL（Cassandra Query Language）でテーブルを作成し、UUID プライマリキーでデータを挿入・取得できる
マルチノードに拡張する場合は cassandra.yaml の seeds・listen_address・rpc_address を変更するだけでよい

Apache Cassandra は、Netflix・Apple・Instagram など世界規模のサービスが採用してきた分散型 NoSQL データベースです。単一障害点がなく、ノードを追加するだけで読み書き性能を水平スケールできる点が最大の特徴です。

この記事では、Ubuntu 24.04 LTS（Docker 公式イメージで検証）に Cassandra 5.0.8 をインストールし、nodetool でクラスター状態を確認、cqlsh で実際にデータを操作するところまでを実際のコマンド出力と合わせて解説します。VPS でも同じ手順が使えます。

検証環境

本記事のコマンドは Ubuntu 24.04 LTS（Docker 公式イメージ ubuntu:24.04）で実行しています。VPS での実機運用の場合も手順は同じです。

目次
Cassandra とは
前提条件と環境確認
Java 17 をインストールする
Cassandra apt リポジトリを追加する
1. 手順1：GPG キーを取得する
2. 手順2：apt リポジトリを追加する
Cassandra をインストールして起動する
1. 手順3：Cassandra サービスを起動する
nodetool でクラスター状態を確認する
cqlsh でデータを操作する
1. 手順1：キースペースを作成する
2. 手順2：テーブルを作成してデータを操作する
cassandra.yaml の主要設定を理解する
マルチノードクラスターの基本
よくあるエラーと対処
まとめ

Cassandra とは
前提条件と環境確認
Java 17 をインストールする
Cassandra apt リポジトリを追加する
Cassandra をインストールして起動する
nodetool でクラスター状態を確認する
cqlsh でデータを操作する
cassandra.yaml の主要設定を理解する
マルチノードクラスターの基本
よくあるエラーと対処
まとめ

Cassandra とは

Cassandra は Facebook が開発し、現在は Apache Software Foundation が管理しているオープンソースの分散型 NoSQL データベースです。行指向の RDBMS（MySQL / PostgreSQL）や、ドキュメント型の MongoDB とはアーキテクチャが根本的に異なります。

最大の特徴はマスターレス（Peer-to-Peer）アーキテクチャです。すべてのノードが対等で、単一の「マスターノード」が存在しません。1台が落ちても他のノードが処理を引き継ぐため、理論上は停止時間がゼロのシステムを構築できます。

データベース	種別	スケール方式	強み	向かないケース
MySQL / PostgreSQL	RDBMS	垂直スケール（主）	複雑なJOIN・トランザクション	書き込み集中・大規模分散
MongoDB	ドキュメントDB	水平スケール	柔軟なスキーマ・JSON操作	厳密なACIDが必要な場合
Cassandra	Wide-column NoSQL	水平スケール（線形）	大量書き込み・高可用性	集計クエリ・アドホック検索
Redis	Key-Value（インメモリ）	水平スケール	低遅延キャッシュ	大容量永続ストレージ

Cassandra が特に向いているのは、センサーログ・IoTデータ・アクセスログ・タイムラインのような「大量書き込みが続き、読み取りは最新データ中心」というパターンです。個人のVPS での学習から始めて、将来的には複数ノードのクラスターへ拡張できます。

前提条件と環境確認

Cassandra 5.x を動かすには以下の環境が必要です。

Ubuntu 22.04 LTS または 24.04 LTS（この記事では 24.04 を使用）
Java 17（Ubuntu 24.04 なら openjdk-17-jre-headless が apt で入る）
RAM 最低 4 GB（本番では 8 GB 以上を推奨。設定次第で 2 GB でも動作する）
ディスク容量に余裕があること（データが増えるほど消費する）

Ubuntu バージョンと Java の関係

Cassandra 5.x は Java 17 が必須です。Ubuntu 22.04 のデフォルトは Java 11（OpenJDK 11.0.31）であるため、Cassandra 5.x を入れる場合は別途 Java 17 を追加インストールする必要があります。Ubuntu 24.04 なら openjdk-17-jre-headless が標準でインストールできます。

まず OS と Java の状態を確認します。

ubuntu@linuxlab: ~

$ lsb_release -a
No LSB modules are available.
Distributor ID: Ubuntu
Description: Ubuntu 24.04.1 LTS
Release: 24.04
Codename: noble
$ free -h
total used free shared buff/cache available
Mem: 7.7Gi 1.2Gi 5.1Gi 120Mi 1.4Gi 6.2Gi

Ubuntu 22.04 vs 24.04 の Java バージョン比較（実測）

Java 17 をインストールする

Cassandra 5.x は内部で JVM（Java Virtual Machine）上で動作します。まず openjdk-17-jre-headless を入れます。

ubuntu@linuxlab: ~

$ sudo apt-get update && sudo apt-get install -y openjdk-17-jre-headless
Reading package lists… Done
Building dependency tree… Done
Setting up openjdk-17-jre-headless (17.0.19+10-1-24.04.2-Ubuntu) …
$ java -version
openjdk version “17.0.19” 2026-04-21
OpenJDK Runtime Environment (build 17.0.19+10-1-24.04.2-Ubuntu)
OpenJDK 64-Bit Server VM (build 17.0.19+10-1-24.04.2-Ubuntu, mixed mode, sharing)

Ubuntu 24.04 での実測では OpenJDK 17.0.19 がインストールされました。java -version で 17.x が表示されれば問題ありません。

Cassandra apt リポジトリを追加する

Cassandra は Ubuntu の標準リポジトリには含まれていません。Apache 公式の apt リポジトリを追加します。

手順1：GPG キーを取得する

ubuntu@linuxlab: ~

$ sudo apt-get install -y curl gnupg
Setting up curl (8.5.0-2ubuntu10.9) …
$ curl -sL https://downloads.apache.org/cassandra/KEYS | sudo gpg –dearmor -o /usr/share/keyrings/cassandra-archive.gpg
# エラーが出なければ成功（コマンドは何も出力しない）
$ ls -la /usr/share/keyrings/cassandra-archive.gpg
-rw-r–r– 1 root root 3013 Jun 20 07:30 /usr/share/keyrings/cassandra-archive.gpg

手順2：apt リポジトリを追加する

ubuntu@linuxlab: ~

$ echo “deb [signed-by=/usr/share/keyrings/cassandra-archive.gpg] https://debian.cassandra.apache.org 50x main” | sudo tee /etc/apt/sources.list.d/cassandra.list
deb [signed-by=/usr/share/keyrings/cassandra-archive.gpg] https://debian.cassandra.apache.org 50x main
$ sudo apt-get update
Hit:1 http://archive.ubuntu.com/ubuntu noble InRelease
Get:5 https://apache.jfrog.io/artifactory/cassandra-deb 50x InRelease [3902 B]
Get:6 https://apache.jfrog.io/artifactory/cassandra-deb 50x/main amd64 Packages [696 B]
Reading package lists… Done

apache.jfrog.io/artifactory/cassandra-deb からパッケージリストが取得できれば、リポジトリの登録は成功です。apt-cache policy cassandra でバージョンを確認します。

ubuntu@linuxlab: ~

$ apt-cache policy cassandra
cassandra:
Installed: (none)
Candidate: 5.0.8
Version table:
5.0.8 500
500 https://debian.cassandra.apache.org 50x/main amd64 Packages

Candidate: 5.0.8 が表示されました。インストール可能な最新版が 5.0.8 であることが確認できます。

Cassandra をインストールして起動する

ubuntu@linuxlab: ~

$ sudo apt-get install -y cassandra
Setting up python3-dbus (1.3.2-5build3) …
Setting up ntp (1:4.2.8p15+dfsg-2~1.2.2+dfsg1-4build2) …
Setting up cassandra (5.0.8) …
Processing triggers for systemd …
$ cassandra -v
5.0.8

インストール時に ntp パッケージが同時に入ったのは少し意外でした。Cassandra は分散クラスター内のノード間で時刻同期が必須なので、時刻合わせの仕組みを依存に含めているわけです。

Cassandra 5.0.8 apt インストール実ログ（Ubuntu 24.04 実測）

手順3：Cassandra サービスを起動する

インストール後、systemd サービスとして起動します。

ubuntu@linuxlab: ~

$ sudo systemctl start cassandra
$ sudo systemctl enable cassandra
Created symlink /etc/systemd/system/multi-user.target.wants/cassandra.service → /lib/systemd/system/cassandra.service
$ sudo systemctl status cassandra
● cassandra.service – LSB: distributed storage system for structured data
Loaded: loaded (/etc/init.d/cassandra; generated)
Active: active (running)
Process: … Started LSB: distributed storage system for structured data.

起動に時間がかかります

Cassandra は JVM 上で動くため、起動完了まで 30〜90 秒かかることがあります。私の Docker 環境では 45 秒後に nodetool status で UN が表示されました。起動直後に nodetool を実行するとエラーになるので、少し待ってから確認しましょう。

nodetool でクラスター状態を確認する

nodetool status は Cassandra の「現在の健康状態」を確認する最重要コマンドです。UN（Up/Normal）が表示されれば、ノードが正常に動作しています。

ubuntu@linuxlab: ~

$ nodetool status
Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
— Address Load Tokens Owns (effective) Host ID Rack
UN 172.17.0.6 144.31 KiB 16 100.0% c9ac97da-fbdd-4326-b71b-e929a517fa0c rack1
$ nodetool info
ID : c9ac97da-fbdd-4326-b71b-e929a517fa0c
Gossip active : true
Native Transport active: true
Load : 144.31 KiB
Uptime (seconds) : 52
Heap Memory (MB) : 162.42 / 256.00
Percent Repaired : 100.0%

各カラムの意味を簡単にまとめます。

カラム	値（実測）	意味
`UN`	UN	Up/Normal — 正常稼働中
Load	144.31 KiB	このノードが保持するデータ量
Tokens	16	仮想ノード（vnode）数。デフォルトは 16
Owns	100.0%	全データの何%を担当しているか（1ノードなら100%）
Rack	rack1	障害ドメイン。マルチノードでラックを分けると冗長性が上がる

nodetool status と nodetool info の実出力（Cassandra 5.0.8）

cqlsh でデータを操作する

CQL（Cassandra Query Language）は SQL に似た構文でデータを操作できます。cqlsh コマンドでインタラクティブシェルを起動します。

ubuntu@linuxlab: ~

$ cqlsh 127.0.0.1
Connected to Test Cluster at 127.0.0.1:9042
[cqlsh 6.2.0 | Cassandra 5.0.8 | CQL spec 3.4.7 | Native protocol v5]
Use HELP for help.
cqlsh> SELECT release_version, cql_version FROM system.local;
release_version | cql_version
—————–+————-
5.0.8 | 3.4.7
(1 rows)

手順1：キースペースを作成する

キースペースは RDBMS でいう「データベース」に相当します。replication_factor は「何台のノードにデータをコピーするか」です。

ubuntu@linuxlab: ~ (cqlsh)

cqlsh> CREATE KEYSPACE IF NOT EXISTS linuxlab
… WITH replication = {‘class’: ‘SimpleStrategy’, ‘replication_factor’: 1};
cqlsh> USE linuxlab;
cqlsh:linuxlab>
# キースペース切り替え完了。プロンプトが “cqlsh:linuxlab>” に変わります

手順2：テーブルを作成してデータを操作する

ubuntu@linuxlab: ~ (cqlsh:linuxlab)

cqlsh:linuxlab> CREATE TABLE IF NOT EXISTS servers (
… id UUID PRIMARY KEY,
… hostname TEXT,
… region TEXT,
… status TEXT,
… created TIMESTAMP
… );
cqlsh:linuxlab> INSERT INTO servers (id, hostname, region, status, created)
… VALUES (uuid(), ‘vps-tokyo-01’, ‘ap-northeast-1’, ‘running’, toTimestamp(now()));
cqlsh:linuxlab> INSERT INTO servers (id, hostname, region, status, created)
… VALUES (uuid(), ‘vps-osaka-01’, ‘ap-northeast-3’, ‘running’, toTimestamp(now()));
cqlsh:linuxlab> SELECT * FROM servers;
id | created | hostname | region | status
————————————–+———————————+————–+—————-+———
6b2b60ae-5a5f-4c02-aa93-3918dacc4de3 | 2026-06-20 07:42:49.080000+0000 | vps-osaka-01 | ap-northeast-3 | running
c8e19838-d375-4a1d-ada4-c3a87e1bc9fd | 2026-06-20 07:42:49.076000+0000 | vps-tokyo-01 | ap-northeast-1 | running
(2 rows)
# 挿入順と取得順が逆になっています。UUID ハッシュ値で物理配置が決まるためです

INSERT した 2 行が取得できました。気をつける点が 1 つあります。返ってきた行の順番が INSERT 順と逆になっています。Cassandra では ORDER BY を使えるのは同一パーティション内のみで、UUID プライマリキーの場合は順序制御ができません。これは Cassandra の設計上の仕様です。

cqlsh 接続 + CQL でのデータ操作（Cassandra 5.0.8 実測）

cassandra.yaml の主要設定を理解する

設定ファイルは /etc/cassandra/cassandra.yaml にあります。本番環境に移行する前に知っておくべきパラメータをまとめます。

ubuntu@linuxlab: ~

$ grep -E “^(cluster_name|num_tokens|partitioner|rpc_address|listen_address|seeds)” /etc/cassandra/cassandra.yaml
cluster_name: ‘Test Cluster’
num_tokens: 16
partitioner: org.apache.cassandra.dht.Murmur3Partitioner
rpc_address: 0.0.0.0
listen_address: localhost

cassandra.yaml 主要パラメータ（Cassandra 5.0.8 実測）

VPS で本番運用する場合は、少なくとも次の 3 つを変更します。

cluster_name：わかりやすい名前に変える（一度設定したら変更不可なので慎重に）
listen_address：ノード間通信用の実 IP アドレスを設定する
rpc_address：クライアントが接続するIPアドレス（外部公開する場合は実IPを指定する）

マルチノードクラスターの基本

Cassandra の本領は複数ノードのクラスターです。基本的な構成手順を理解しておきます。

①シードノードを決める

クラスターの「最初の参加窓口」となるノードを シードノード と呼びます。新しいノードはシードノードに接続してクラスター情報を取得します。全ノードの cassandra.yaml に同じシードIPを書きます。

ubuntu@node1: ~ (cassandra.yaml 抜粋)

seed_provider:
– class_name: org.apache.cassandra.locator.SimpleSeedProvider
parameters:
– seeds: “192.168.1.10,192.168.1.11” # シードノードのIPを列挙
listen_address: 192.168.1.10 # このノード自身のIP
rpc_address: 192.168.1.10

②レプリケーション係数を設定する

本番では replication_factor を 3 にするのが一般的です。3 ノード中 1 台が落ちてもデータが失われません。

ubuntu@linuxlab: ~ (cqlsh)

cqlsh> CREATE KEYSPACE prod_data WITH replication = {
… ‘class’: ‘NetworkTopologyStrategy’,
… ‘dc1’: 3
… };
# NetworkTopologyStrategy は本番推奨。dc1 のレプリカ数を 3 に設定

③3ノード構成での nodetool status

3ノードが正常に結合すると、nodetool status には 3 行の UN が表示されます。

ubuntu@node1: ~

$ nodetool status
Datacenter: dc1
===============
— Address Load Tokens Owns Host ID Rack
UN 192.168.1.10 512.32 KiB 16 33.3% … rack1
UN 192.168.1.11 498.17 KiB 16 33.4% … rack1
UN 192.168.1.12 521.44 KiB 16 33.3% … rack1
# 3ノードで均等にデータを分担（各 33%）

よくあるエラーと対処

エラー1：nodetool で “Connection refused” が出る

症状と原因

nodetool: Failed to connect to '127.0.0.1:7199' - Connection refused. → Cassandra がまだ完全に起動していない場合に出ます。起動に 30〜90 秒かかるため、journalctl -u cassandra -f でログを見ながら待ちましょう。Startup complete のメッセージが出れば接続可能になります。

エラー2：cqlsh で “Unable to connect to any servers” が出る

症状と原因

Connection error: ('Unable to connect to any servers', ...) → nodetool info で Native Transport active: false になっていると cqlsh は繋がりません。Cassandra が完全起動するまで待つか、/etc/cassandra/cassandra.yaml の start_native_transport: true を確認してください。私の実測では起動から 51 秒後に Native Transport active: true になりました。

エラー3：”Package cassandra is not available” が出る

症状と原因

E: Package 'cassandra' has no installation candidate → GPG キーの登録方法が間違っています。古い情報では apt-key add を使う手順が紹介されていますが、Ubuntu 22.04 以降では非推奨です。本記事の gpg --dearmor -o /usr/share/keyrings/ を使った手順を使ってください。

エラー4：Java バージョンエラーで起動しない

症状と原因

Unsupported Java version: 11 → Cassandra 5.x には Java 17 が必要です。java -version で 11.x が表示されている場合は、sudo apt-get install -y openjdk-17-jre-headless を実行し、sudo update-alternatives --config java で Java 17 を選択してください。

まとめ

Ubuntu 24.04 に Apache Cassandra 5.0.8 をインストールして、cqlsh でデータを操作するところまで確認しました。

インストールは Apache 公式 apt リポジトリ（debian.cassandra.apache.org 50x）から apt-get install cassandra で完了する
Java 17（openjdk-17-jre-headless）が必須。Ubuntu 24.04 なら標準リポジトリから入る
nodetool status で UN が表示されれば起動成功。私の実測では 45 秒かかった
cqlsh で CQL を使い、キースペース・テーブルの作成とデータの挿入・取得ができた
マルチノードに拡張するには cassandra.yaml の seeds・listen_address・rpc_address を設定するだけでよい