--- title: "Kubesprayとは？Ansibleで作るKubernetesクラスター構築・運用・kubeadmとの違い" url: "https://www.issoh.co.jp/tech/details/3886/" published: 2024-10-18 updated: 2026-09-16 categories: ["プラットフォーム"] publisher: "株式会社一創" --- # Kubesprayとは？Ansibleで作るKubernetesクラスター構築・運用・kubeadmとの違い Kubespray（クベスプレイ）は、**AnsibleのプレイブックでKubernetesクラスターをOSの準備からネットワーク・高可用性構成まで一括で自動構築する**オープンソースツールです。Kubernetes公式のサブプロジェクト（kubernetes-sigs）として開発され、オンプレミス・クラウド・ハイブリッドのどこでも同じ手順で本番相当のクラスターを立ち上げられます。最新は**v2.31.0（2026年4月25日リリース）**で、Kubernetes v1.30以上に対応します。この記事では、[Kubernetes（クバネティス）とは](https://www.issoh.co.jp/tech/details/2928/)を理解している前提で、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 Moleculeとは？v26系のansible-native設定とmolecule testの実行手順](https://www.issoh.co.jp/tech/details/17630/)で扱っています。 基盤である[Ansible（エージェントレスの構成管理ツール）](https://www.issoh.co.jp/tech/details/6533/)がSSH経由で各ノードへ設定を配るので、対象ノードに専用エージェントを入れる必要はありません。オンプレミスの物理サーバーでも、AWS・Azure・GCPの仮想マシンでも、同一のプレイブックで構築できるのが特徴です。マネージドKubernetes（EKSなど）が使えない閉域環境や、コントロールプレーンまで自前で握りたい要件で採用されます。 ## Kubesprayとkubeadm・マネージドKubernetesの違いと選定基準 Kubernetesの構築手段は主に3つあり、自動化の範囲と運用責任が異なります。 | 観点 | kubeadm | Kubespray | マネージド(EKS等) | | ----- | ------------ | ------------------ | -------------- | | 提供元 | Kubernetes公式 | Kubernetes公式(sigs) | クラウド各社 | | 自動化範囲 | クラスタ初期化のみ | OS設定〜CNI〜HAまで | コントロールプレーン運用込み | | 複数ノード | 手作業で結合 | inventoryで一括 | マネージド | | HA構成 | 手動設計 | プレイブックで自動 | 標準提供 | | 向く場面 | 学習・検証 | オンプレ本番・閉域 | クラウド前提の本番 | 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へ移行しています。 | 系統 | 対応バージョン(例) | | -------------------- | ------------- | | Ubuntu | 22.04 / 24.04 | | Debian | 11 / 12 / 13 | | RHEL / CentOS Stream | 9 / 10 | | Rocky / AlmaLinux | 9 / 10 | | Fedora / openSUSE 他 | 要件はリリースノート参照 | ハードウェアの最小要件は**コントロールプレーンがメモリ2GB、ワーカーがメモリ1GB**（Kubespray公式の最小値）。CPUとディスクは公式に固定値の記載がないため、本番ではCPU2コア以上・ディスク20GB以上を運用目安とし、負荷に応じて上積みします。実行側はAnsible v2.14以上・Jinja 2.11以上・python-netaddrが必要です。 対応Kubernetesは下限がv1.30で、v2.31.0の既定はv1.35系です。**対応バージョンの範囲はKubesprayのリリースごとに変わる**ため、実際に構築・更新する前に[Kubernetes本体のバージョンと変更点](https://www.issoh.co.jp/tech/details/8967/)と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との違い・読み方をわかりやすく解説](https://www.issoh.co.jp/tech/details/2928/) - [Ansibleとは何か？インフラ自動化ツールの基本概念と特徴](https://www.issoh.co.jp/tech/details/6533/) - [Kubernetes 1.34の新機能・変更点とEOL｜DRA GA・再起動ルール・EKS対応を解説](https://www.issoh.co.jp/tech/details/8967/) - [Semaphore UIの基本機能と対応する自動化ツールの全体像](https://www.issoh.co.jp/tech/details/12399/) --- 出典: [Kubesprayとは？Ansibleで作るKubernetesクラスター構築・運用・kubeadmとの違い]()（株式会社一創）