Kubesprayとは？Ansibleで作るKubernetesクラスター構築・運用・kubeadmとの違い

Kubespray（クベスプレイ）は、AnsibleのプレイブックでKubernetesクラスターをOSの準備からネットワーク・高可用性構成まで一括で自動構築するオープンソースツールです。Kubernetes公式のサブプロジェクト（kubernetes-sigs）として開発され、オンプレミス・クラウド・ハイブリッドのどこでも同じ手順で本番相当のクラスターを立ち上げられます。最新はv2.31.0（2026年4月25日リリース）で、Kubernetes v1.30以上に対応します。この記事では、Kubernetes（クバネティス）とはを理解している前提で、kubeadmとの違い・具体的な構築手順・CNIの選び方・ノード追加やアップグレードといった運用までをまとめます。

まとめ：Kubesprayの要点

• 正体：Ansible製のKubernetes構築・運用ツール（kubernetes-sigs公式）。設定をコード（inventoryとplaybook）で管理する。
• kubeadmとの違い：kubeadmは1ノードずつ初期化する公式の最小ツール。KubesprayはOS設定・コンテナランタイム・CNI・HA・複数ノードまでを1コマンドで自動化する。
• 構築の流れ：inventoryにノードを定義 → cluster.ymlを実行。運用はscale.yml（追加）・upgrade-cluster.yml（更新）・reset.yml（初期化）。
• CNI：既定はCalico。高性能なCilium（eBPF）なども選べる。かつて選べたWeave Netはプロジェクト終了に伴い削除済み。
• 対応環境：Ubuntu 22.04/24.04、Debian、RHEL系・Rocky・AlmaLinux 9/10など。最小メモリはコントロールプレーン2GB・ワーカー1GB。

Kubesprayとは｜Ansibleで本番Kubernetesを自動構築するOSS

Kubesprayは、Kubernetesクラスターの構築に必要な作業一式をAnsibleのプレイブックとしてコード化したツールです。手動なら数十ステップになるカーネルパラメータ調整・コンテナランタイム導入・証明書発行・コントロールプレーンの冗長化などを、インベントリ（ノード一覧）を書いてコマンドを1回叩くだけで自動実行します。設定がコードとして残るため、同じクラスターを再現したり、複数環境へ横展開したりが容易です。

基盤であるAnsible（エージェントレスの構成管理ツール）がSSH経由で各ノードへ設定を配るので、対象ノードに専用エージェントを入れる必要はありません。オンプレミスの物理サーバーでも、AWS・Azure・GCPの仮想マシンでも、同一のプレイブックで構築できるのが特徴です。マネージドKubernetes（EKSなど）が使えない閉域環境や、コントロールプレーンまで自前で握りたい要件で採用されます。

Kubesprayとkubeadm・マネージドKubernetesの違いと選定基準

Kubernetesの構築手段は主に3つあり、自動化の範囲と運用責任が異なります。

kubeadmは「Kubernetes本体を1ノードで初期化する」最小の公式ツールで、ノードの結合やCNI導入は手作業です。Kubesprayはそのkubeadmを内部で呼びつつ、OSの前提設定から複数ノードのHAクラスターまでを自動化します。両者は競合ではなく役割の重なる別レイヤーと捉えると選びやすくなります。

逆に、Kubesprayを選ぶべきでないのは次の場合です。クラウド上でEKS/GKE/AKSが使えるなら、コントロールプレーンの運用まで自前で背負うKubesprayは過剰で、マネージドの方が運用コストは低くなります。1ノードで動きを試したいだけならkubeadmやkind/minikubeで十分です。Kubesprayが効くのは、オンプレや閉域で本番相当のHAクラスターを再現性高く何度も立てたいケースに絞られます。

Kubesprayでクラスターを構築する手順

構築はリポジトリの取得 → 依存導入 → インベントリ定義 → プレイブック実行の順です。事前に、Ansibleを実行するマシンにPythonとpython-netaddrを用意し、各ノードへSSH鍵でログインできる状態にしておきます。加えて全ノードでIPv4/IPv6フォワーディングを有効化しておくと、ネットワーク周りのエラーを避けられます。

git clone https://github.com/kubernetes-sigs/kubespray.git
cd kubespray
pip install -r requirements.txt

# サンプルのインベントリを複製して自分用に編集
cp -rfp inventory/sample inventory/mycluster
# inventory/mycluster/inventory.ini に各ノードのIPと役割(kube_control_plane, etcd, kube_node)を記載

# クラスターを一括構築（-b はroot昇格）
ansible-playbook -i inventory/mycluster/inventory.ini cluster.yml -b

cluster.ymlが完了すると、コントロールプレーン・etcd・ワーカー・CNIまで揃ったクラスターが立ち上がります。構築後はkubectl get nodesで全ノードがReadyか、Podが正常に起動しているかを確認します。エラー時はAnsibleの実行ログでどのタスクが失敗したかを特定し、該当ノードのSSH到達性や依存パッケージを見直します。

ネットワークプラグイン(CNI)の選択｜既定Calico・Cilium・Weave削除

Kubesprayはインベントリの変数（kube_network_plugin）を書き換えるだけでCNIを切り替えられます。既定はCalicoで、NetworkPolicyによる通信制御まで含めて実績が豊富なため、迷ったらCalicoが無難です。

• Calico（既定）：NetworkPolicy対応。大規模・セキュリティ要件のある本番向け。
• Cilium：eBPFベースでL3/L4に加えL7ポリシーに対応し、Hubbleで通信を可視化できる。高度なポリシーや可観測性を重視する場合に選ぶ。
• Flannel：機能を絞った軽量なオーバーレイ。検証や小規模で手早く動かしたいとき。
• Kube-OVN / Kube-router / Macvlan：VLAN連携やL2直結など特殊要件向け。Multusは他CNIと併用してPodへ複数NICを割り当てるためのメタCNI。

注意点として、旧来よく紹介されていたWeave Netは、開発元Weaveworksの事業終了（2024年）に伴いKubesprayのサポート対象から削除されています。古い記事や手順のweave指定はv2.31時点では通らないため、CalicoかCiliumへ読み替えてください。

クラスターの運用：ノード追加・アップグレード・リセット

Kubesprayは構築後の日常運用も専用プレイブックで自動化します。稼働中のクラスターに対して実行できるため、ダウンタイムを抑えながらメンテナンスできます。

ノードの追加・削除（scale.yml / remove-node.yml）

ワーカーを増やすときはインベントリに新ノードを追記し、scale.ymlを実行すると既存クラスターへ組み込まれます。全ノードを対象にするcluster.ymlより影響範囲が狭く、稼働中の追加に向きます。ノードを外す際はremove-node.ymlで安全にドレイン・離脱させます。

バージョンアップグレード（upgrade-cluster.yml）

Kubernetes本体の更新はupgrade-cluster.ymlで行い、ノードを1台ずつローリングで更新します。Kubernetesはマイナーバージョンの飛び越えアップグレードが非対応のため、1マイナーずつ順に上げるのが原則です。実行前にetcdのバックアップを取り、目的のKubernetes版を既定に含むKubesprayへ先に上げてから実施します。

クラスターの初期化（reset.yml）

構築をやり直したいときはreset.ymlで各ノードからKubernetes関連コンポーネント・設定を削除し、クリーンな状態へ戻せます。破壊的な操作なので、実行前に必要なデータのバックアップとインベントリの対象範囲を必ず確認します。

対応OS・システム要件と対応Kubernetesバージョン

Kubespray v2.31.0が公式に対応する主なLinuxディストリビューションは次のとおりです。CentOS Linux 7/8はEOLのため、現行はCentOS Stream・Rocky Linux・AlmaLinuxなどのRHEL系9/10へ移行しています。

ハードウェアの最小要件はコントロールプレーンがメモリ2GB、ワーカーがメモリ1GB（Kubespray公式の最小値）。CPUとディスクは公式に固定値の記載がないため、本番ではCPU2コア以上・ディスク20GB以上を運用目安とし、負荷に応じて上積みします。実行側はAnsible v2.14以上・Jinja 2.11以上・python-netaddrが必要です。

対応Kubernetesは下限がv1.30で、v2.31.0の既定はv1.35系です。対応バージョンの範囲はKubesprayのリリースごとに変わるため、実際に構築・更新する前にKubernetes本体のバージョンと変更点とKubespray公式のリリースノートで組み合わせを確認してください。

よくある質問

Kubesprayとは何ですか？

AnsibleのプレイブックでKubernetesクラスターを本番構成ごと自動構築するオープンソースツールです。Kubernetes公式のkubernetes-sigsが開発し、オンプレ・クラウド・ハイブリッドで同じ手順が使えます。

Kubesprayとkubeadmの違いは何ですか？

kubeadmは1ノードでクラスターを初期化する公式の最小ツールで、ノード結合やCNI導入は手作業です。KubesprayはOS設定からCNI・HA・複数ノードまでを自動化し、内部でkubeadmを利用します。

Kubesprayの最新バージョンと対応Kubernetesは？

最新はv2.31.0（2026年4月25日）で、既定のKubernetesはv1.35系、対応下限はv1.30です。対応範囲はリリースごとに変わるため公式リリースノートで確認します。

KubesprayではどのCNIを選べばよいですか？

迷ったら既定のCalico（NetworkPolicy対応で実績豊富）。性能やeBPFの可観測性を重視するならCilium。軽量に試すならFlannelです。Weaveは削除済みで選べません。

稼働中のクラスターにノードを追加するには？

インベントリに新ノードを追記し、scale.ymlプレイブックを実行します。cluster.ymlより影響範囲が狭く、ダウンタイムを抑えて追加できます。

関連記事

• Kubernetes（クバネティス）とは？仕組み・Dockerとの違い・読み方をわかりやすく解説
• Ansibleとは何か？インフラ自動化ツールの基本概念と特徴
• Kubernetes 1.34の新機能・変更点とEOL｜DRA GA・再起動ルール・EKS対応を解説
• Semaphore UIの基本機能と対応する自動化ツールの全体像