前提条件と環境準備
このセクションでは、クラスタを本番稼働させるために最低限必要な OS／ハードウェアスペックと、ネットワーク・ファイアウォールの設定要件をまとめます。適切なリソースが確保できていないと、パフォーマンス低下や障害時の復旧が困難になるため、必ず事前に確認してください。
OS・ハードウェア要件
Ubuntu 22.04 LTS（64bit）を対象にしています。CPU・メモリ・ディスクはノードの役割ごとに推奨値がありますので、計画段階で余裕を持った構成を選択してください。
- OS: Ubuntu 22.04 LTS（公式 apt リポジトリが利用可能）
- CPU: 最低 2 コア（コントロールプレーンは 4 コア以上推奨）
- メモリ: 4 GB 以上
- コントロールプレーンノード：8 GB 以上推奨
- ワーカーノード：2 GB でも可（負荷が高いワークロードは増量してください）
- ディスク: 空き容量 20 GB 以上、etcd 用データは SSD が望ましい
公式ドキュメント: 「Kubernetes クラスター作成 – kubeadm」
ネットワーク設定とファイアウォールの考慮
以下に示すポートは コントロールプレーンノード と ワーカーノード の両方で相互に開放しておく必要があります。ufw、iptables、もしくはクラウドベンダー提供のセキュリティグループで設定してください。
- IP アドレス: 各ノードは静的 IP か DHCP 予約で一意に割り当てる
- ポート要件（TCP）
| ポート | 用途 |
|---|---|
| 6443 | API Server（kubectl、kubelet が利用） |
| 2379‑2380 | etcd クラスタ間通信 |
| 10250 | kubelet の API |
| 10251 | kube-scheduler |
| 10252 | kube-controller-manager |
| 30000‑32767 | NodePort（ユーザーアプリが外部公開する場合） |
- ファイアウォール: 上記ポートを全ノード間で許可し、外部からの不要なアクセスはブロックします。
- 名前解決: コントロールプレーンのホスト名は
/etc/hostsもしくは内部 DNS に登録し、ワーカーノードから正しく参照できるようにしておきます。
必須コンポーネントのインストール
本章では、公式 apt リポジトリから containerd（推奨）と Kubernetes コンポーネント を取得し、システムレベルで必要な設定を行う手順を示します。パッケージ管理によるバージョン固定により、将来的なアップグレードが安全かつ容易になります。
Docker/Containerd のインストールと設定
Docker は互換性の観点から残すことも可能ですが、Kubernetes 1.28 系では containerd がデフォルトランタイムとして推奨されています。以下は containerd をインストールする例です。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
# 必要ツールのインストールとパッケージリスト更新 sudo apt-get update && sudo apt-get install -y \ ca-certificates curl gnupg lsb-release # Docker（containerd）公式 GPG 鍵を keyring 方式で保存 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg # apt ソースに署名付きリポジトリ情報を追加 echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] \ https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # パッケージリスト更新後に containerd のみをインストール sudo apt-get update && sudo apt-get install -y containerd.io # systemd に登録し、起動状態を確認 sudo systemctl enable --now containerd systemctl status containerd |
ポイント：
containerdは軽量で Kubernetes と相性が良く、CNI プラグインとの連携もスムーズです。Docker エンジンは不要な場合はインストールしない方がリソースの無駄遣いを防げます。
kubeadm・kubelet・kubectl のインストール手順
apt-key は非推奨となったため、ここでは keyring 方式 に置き換えて安全性を高めています。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# Kubernetes 公開 GPG 鍵を keyring に保存 curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | \ sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.gpg # apt ソースに署名付きリポジトリ情報を追加 echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] \ https://apt.kubernetes.io/ kubernetes-xenial main" | \ sudo tee /etc/apt/sources.list.d/kubernetes.list # パッケージリスト更新 sudo apt-get update |
次に、クラスターで使用する kubeadm・kubelet・kubectl のバージョンを固定します。
|
1 2 3 4 5 6 7 |
# 例として最新安定版 (1.28.x) を取得し、バージョン文字列を抽出 VERSION=$(apt-cache madison kubeadm | grep '\s1\.28\.' | head -n1 | awk '{print $3}') # バージョン指定でインストールし、アップデート時の自動更新を防止 sudo apt-get install -y kubelet=$VERSION kubeadm=$VERSION kubectl=$VERSION sudo apt-mark hold kubelet kubeadm kubectl |
kubelet が systemd で有効かどうかを確認します。
|
1 2 3 |
sudo systemctl enable --now kubelet systemctl status kubelet |
スワップ無効化と sysctl 推奨パラメータ設定
Kubernetes は スワップが有効 な状態では動作しません。永続的に無効化したうえで、CNI がブリッジを正しく処理できるようカーネルパラメータも調整します。
|
1 2 3 4 5 6 7 8 9 10 11 12 |
# スワップの即時オフと /etc/fstab からの除去 sudo swapoff -a sudo sed -i '/\sswap\s/s/^/#/' /etc/fstab # 必要な sysctl 設定をファイルに保存し、反映 cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables = 1 net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-ip6tables = 1 EOF sudo sysctl --system |
シングルコントロールプレーン構成でのクラスター初期化
単一ノードでも本番環境として十分に機能します。ここでは kubeadm init の実行例と、Calico CNI の導入手順、ワーカーノードの参加方法を示します。
kubeadm init の実行例とオプション解説
以下のコマンドは、シングルコントロールプレーンノード上でクラスタを作成する最小構成です。--upload-certs を付与すると、後続ノード追加時に証明書を再利用できます。
|
1 2 3 4 5 6 |
sudo kubeadm init \ --apiserver-advertise-address=$(hostname -i) \ --pod-network-cidr=192.168.0.0/16 \ --control-plane-endpoint=$(hostname -i):6443 \ --upload-certs |
--apiserver-advertise-address… API Server がリッスンする IP（ノードのプライベートアドレス）--pod-network-cidr… Calico のデフォルト CIDR と合わせることで、Pod の IP 割り当てが正しく行われます--control-plane-endpoint… 将来 HA 化する際にロードバランサの VIP を指定できるようにしておくと移行が楽です
初期化後の設定（kubectl へのアクセス権付与）
非 root ユーザーでも kubectl が使えるように設定ファイルをコピーします。
|
1 2 3 4 |
mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config |
マスターノード状態の確認方法
kubectl get nodes と kubectl get pod -A でコンポーネントの稼働状況をチェックします。
|
1 2 3 4 5 6 |
# ノード一覧とステータス kubectl get nodes # kube-system 名前空間以下の主要 Pod の状態 kubectl get pods -n kube-system |
期待される出力例（抜粋）:
|
1 2 3 4 5 6 7 8 9 |
NAME STATUS ROLES AGE VERSION master01 Ready control-plane,master 5m v1.28.3 NAMESPACE NAME READY STATUS RESTARTS AGE kube-system coredns-xxxxxx 2/2 Running 0 4m kube-system etcd-master01 1/1 Running 0 5m ... calico-system calico-node-xxxxx 1/1 Running 0 4m |
Calico CNI プラグインのデプロイと基本ネットワークポリシー設定
Calico はスケールしやすく、NetworkPolicy の表現力が高いことから多くのプロダクション環境で採用されています。
|
1 2 3 4 5 6 7 |
# マニフェストを取得して適用 curl -O https://projectcalico.docs.tigera.io/manifests/calico.yaml kubectl apply -f calico.yaml # デプロイ完了確認（calico-system 名前空間） kubectl get pods -n calico-system |
最小限のデフォルト拒否ポリシー例
以下は 全 Namespace のすべての Pod に対して Ingress/Egress を禁止 するテンプレートです。必要に応じて個別の許可ルールを追加してください。
|
1 2 3 4 5 6 7 8 9 10 11 |
apiVersion: networking.k8s.io/v1 kind: NetworkPolicy metadata: name: default-deny-all namespace: default spec: podSelector: {} policyTypes: - Ingress - Egress |
適用は kubectl apply -f deny.yaml で実行します。
ワーカーノードの参加手順 (kubeadm join の取得と実行)
kubeadm init 実行時に表示された join コマンド を各ワーカーノードで実行します。通常のワーカーは --control-plane オプションを付けません。
|
1 2 3 4 5 |
# 例：マスターノードが 192.168.1.10 の場合 sudo kubeadm join 192.168.1.10:6443 \ --token abcdef.0123456789abcdef \ --discovery-token-ca-cert-hash sha256:1234567890abcdef... |
重要：
--control-planeは追加のコントロールプレーンノード（マスターノード）を増設する際にのみ使用します。ワーカーノードでは必ず省略してください。
参加後、マスターノードで再度 kubectl get nodes を実行し、Ready 状態のワーカーが表示されることを確認します。
高可用性 (HA) 構成の実装
単一コントロールプレーンはシングルポイント障害（SPOF）になるため、本番環境では ロードバランサ + 複数コントロールプレーン の構成が推奨されます。ここでは Keepalived による VIP と HAProxy による TCP ロードバランシングの設定手順、そして追加マスターの作成方法を解説します。
HAProxy と Keepalived によるロードバランサー設置手順
まずは Keepalived で仮想 IP（VIP） を割り当て、HAProxy がその VIP 経由で API Server へリクエストを転送します。
必要パッケージのインストール
|
1 2 |
sudo apt-get update && sudo apt-get install -y haproxy keepalived |
Keepalived 設定例（VIP: 10.0.0.100/24）
以下は master01 に配置する設定ファイルです。2 台目以降は priority の数値だけ変更してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
# /etc/keepalived/keepalived.conf vrrp_instance VI_1 { state MASTER # 1 台目は MASTER、2 台目は BACKUP に自動切替 interface eth0 # 使用インターフェース名 virtual_router_id 51 priority 150 # 2 台目は例として 100 を設定 advert_int 1 authentication { auth_type PASS auth_pass secret123 } virtual_ipaddress { 10.0.0.100/24 dev eth0 label eth0:vip } } |
設定を反映させてサービスを再起動します。
|
1 2 3 |
sudo systemctl restart keepalived sudo systemctl enable keepalived |
HAProxy 設定例（TCP モード）
/etc/haproxy/haproxy.cfg に以下のブロックを追加し、API Server へのロードバランシングを有効にします。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
# /etc/haproxy/haproxy.cfg （抜粋） frontend k8s-api bind *:6443 mode tcp default_backend k8s-backend backend k8s-backend mode tcp balance roundrobin option tcp-check server master1 10.0.0.11:6443 check fall 3 rise 2 server master2 10.0.0.12:6443 check fall 3 rise 2 server master3 10.0.0.13:6443 check fall 3 rise 2 |
|
1 2 3 |
sudo systemctl restart haproxy sudo systemctl enable haproxy |
VIP（例：10.0.0.100） を kubeadm init --control-plane-endpoint に指定すれば、クライアントは常に同一エンドポイントで API Server へアクセスできます。
複数コントロールプレーンノードの追加方法と kubeadm init の再利用
最初に作成したマスターで 証明書キー を取得し、2 台目以降のマスターで kubeadm init（--control-plane）を実行します。
|
1 2 3 4 5 6 7 8 9 10 11 |
# 1 台目（既存）の出力例からコピー CERT_KEY=$(kubeadm init phase upload-certs --upload-certs | tail -1) # 2 台目以降で実行 sudo kubeadm init \ --control-plane-endpoint=10.0.0.100:6443 \ --certificate-key ${CERT_KEY} \ --upload-certs \ --apiserver-advertise-address=$(hostname -i) \ --pod-network-cidr=192.168.0.0/16 |
--certificate-keyに 1 台目で取得したキーを渡すことで、etcd の証明書が安全に共有されます。--upload-certsを付与し続けると、さらに新しいマスター追加時にも同様の手順が利用可能です。
kubelet 再起動
|
1 2 |
sudo systemctl restart kubelet |
HA 環境での状態確認とフェイルオーバーテスト
以下のコマンドで各ノードのステータスや VIP の割り当て状況を確認し、意図した通りにフェイルオーバーが機能するか検証します。
|
1 2 3 4 5 6 7 8 9 |
# 全ノードの詳細情報 kubectl get nodes -o wide # VIP に対して API バージョン取得（curl でヘルスチェック） curl -k https://10.0.0.100:6443/version # 任意のマスターを停止し、VIP が別ノードへ移動したか確認 sudo systemctl stop kubelet # （例）master1 停止後に ip a show dev eth0 で VIP の有無をチェック |
運用・保守ガイド
本番環境では 計画的なアップグレード と 障害時の迅速な切り分け が不可欠です。ここでは kubeadm を利用した安全なバージョン上げ手順と、主要コンポーネントのトラブルシューティング項目をまとめます。
基本的なアップグレード手順 (kubeadm upgrade)
-
対象バージョンの確認
bash
apt-cache madison kubeadm | grep '\s1\.28\.' # 例: 1.29.x に上げる場合は公式リリースノート参照 -
kubeadm 本体だけを先にアップグレード
bash
sudo apt-get install -y kubeadm=1.29.0-00 # バージョンは実際のリリストから選択 -
クラスター全体のアップグレードプランを取得
bash
sudo kubeadm upgrade plan -
コントロールプレーンノードを順次アップグレード（マスターごとに実行）
bash
sudo kubeadm upgrade apply v1.29.0 -
kubelet と kubectl も同バージョンへ固定
bash
sudo apt-get install -y kubelet=1.29.0-00 kubectl=1.29.0-00
sudo systemctl daemon-reload && sudo systemctl restart kubelet -
ワーカーノードをローテーションでアップグレード（各ノードで実行）
bash
sudo kubeadm upgrade node config --kubelet-version v1.29.0
sudo apt-get install -y kubelet=1.29.0-00
sudo systemctl restart kubelet
トラブルシューティングの主要ポイント
以下は障害発生時にまず確認すべき項目と、代表的なエラー例です。
| 項目 | 確認コマンド | 主なエラー例と対処 |
|---|---|---|
| コンポーネント全体の状態 | kubectl get componentstatuses |
SchedulerUnhealthy → journalctl -u kube-scheduler でログ確認 |
| kubelet の起動状況 | systemctl status kubelet、journalctl -u kubelet -f |
swap is enabled → 再度スワップ無効化と /etc/fstab 修正 |
| etcd ヘルスチェック | ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 endpoint health |
unhealthy → 証明書期限切れ、ディスク容量不足、ネットワーク遮断を確認 |
| Pod ネットワーク | kubectl get pods -A -o wide、kubectl logs -n kube-system <calico-pod> |
Failed to create pod network → sysctl 設定漏れや Calico の IPIP モジュール無効化 |
| API サーバーへのアクセス | curl -k https://<VIP>:6443/healthz |
タイムアウト → HAProxy / Keepalived 設定ミス、ファイアウォールブロック |
公式ドキュメントの 「Kubernetes クラスター作成 – kubeadm」 には、さらに詳細なアップグレード手順とトラブルシューティングガイドが掲載されています。実施前に必ず目を通してください。
まとめ
- 前提条件：Ubuntu 22.04、CPU≥2、メモリ≥4 GB、必要ポートの開放を確保したネットワーク基盤を用意。
- コンポーネントインストール：
containerdと公式 apt リポジトリから取得したkubeadm/kubelet/kubectlを keyring 方式で安全に導入し、スワップ無効化・sysctl 設定を実施。 - シングルコントロールプレーン構築：
kubeadm init --pod-network-cidr=192.168.0.0/16によりクラスタを初期化し、Calico CNI をデプロイ。ワーカーノードは--control-planeなしで参加させます。 - HA 構成：Keepalived が提供する VIP と HAProxy の TCP ロードバランサーで API Server を冗長化し、
kubeadm init --control-planeと証明書キー共有で複数コントロールプレーンノードを追加。フェイルオーバーテストも必ず実施してください。 - 運用・保守：
kubeadm upgradeによる段階的バージョン上げと、componentstatuses・etcd health・kubelet ログのチェック項目を標準化しておくことで障害時に迅速対応できます。
以上の手順を踏めば、Ubuntu 22.04 上で 本番レベル の Kubernetes クラスタを安全かつ安定的に構築・運用できるようになります。ぜひ実環境で検証し、CI/CD パイプラインやマイクロサービスデプロイへと活用してください。