Contents
前提条件と環境準備
| 項目 | 推奨バージョン(2026/04 時点) | 補足 |
|---|---|---|
| OS | Ubuntu 24.04 LTS / Debian 12, WSL2 (Ubuntu) | カーネル 6.5 系が標準搭載されているものを想定 |
| CPU/Memory | 2 コア以上、4 GB RAM 推奨(kind は 1 GB 程度でも動作) |
本番向け kubeadm は最低 8 GB を推奨 |
| Docker エンジン | Docker CE 24.0 系列 | docker.io パッケージは非公式な旧バージョンです |
※重要
Debian/Ubuntu 系ディストリビューションではapt-keyが 2023 年に非推奨 となり、キーリングファイル (*.gpg) を/usr/share/keyrings/に配置してからsources.list.d/*.listに署名情報を書き込む手順が標準です。以下のインストール例はすべてこの方式で実装しています。
Docker CE の公式インストール(Debian / Ubuntu)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
# 1. 依存パッケージと HTTPS 用 transport を取得 sudo apt-get update sudo apt-get install -y \ ca-certificates curl gnupg lsb-release # 2. Docker の GPG キーをキーリングに保存(apt-key 非推奨) sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker-archive-keyring.gpg # 3. リポジトリ情報を追加(Ubuntu の場合) echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/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 # 4. パッケージインデックス更新 & Docker CE 本体をインストール sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin # 5. 動作確認 docker version # Engine と Client のバージョンが表示されれば成功 |
補足情報
| 項目 | 内容 |
|---|---|
| cgroup driver | Docker CE はデフォルトで systemd を使用します。kubelet も同じドライバーに合わせると cgroup driver mismatch が防げます。 |
| Docker Desktop (WSL2) | Windows 環境では Docker Desktop の WSL2 統合機能が便利です。Linux ディストリビューション上で直接 dockerd を走らせても問題ありません。 |
kubectl と kind の最新インストール手順
2026/04 時点の最新版
-kubectl: v1.29.3(Kubernetes 1.29 系列)
-kind: v0.22.2
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# ---------- kubectl ---------- VERSION=$(curl -s https://dl.k8s.io/release/stable.txt) # 例: v1.29.3 curl -LO "https://dl.k8s.io/release/${VERSION}/bin/linux/amd64/kubectl" sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl # ---------- kind ---------- KIND_VERSION=v0.22.2 curl -Lo ./kind "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-linux-amd64" sudo install -o root -g root -m 0755 ./kind /usr/local/bin/kind # バージョン確認 kubectl version --client && kind version |
注意点
kubectlのバイナリは公式の stable リリースを取得するので、将来的にメジャーバージョンが上がっても自動で最新安定版が入ります。kindは GitHub のリリースページから直接ダウンロードしますが、CI/CD パイプラインで使用する場合はgo install sigs.k8s.io/kind@latestでも取得可能です(Go がインストールされている前提)。
WSL2 上でのセットアップポイント
| 手順 | コマンド例 |
|---|---|
| WSL2 の有効化 | wsl --install -d Ubuntu (PowerShell) |
| Docker Desktop との連携 | Docker Desktop → Settings → Resources → WSL Integration → Ubuntu をオン |
| Linux 側での Docker デーモン確認 | docker ps が正常に実行できれば OK |
| kubectl / kind のインストール | 前節の手順をそのまま実行 |
Tip:
WSL2 では/etc/docker/daemon.jsonに"exec-opts": ["native.cgroupdriver=systemd"]を追記すると、Docker と kubelet が同一 cgroup driver を使用するように強制できます。
ローカル開発向け kind クラスタ作成(ポート設定を統一)
1. 設定ファイルの作成
以下は ホスト側ポート 30080 と Service の NodePort も同じ 30080 を使用した例です。これにより「どちらのポートでアクセスすれば良いか」について混乱が起きません。
|
1 2 3 4 5 6 7 8 9 10 11 |
# kind-config.yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraPortMappings: # コンテナ内部の 80 番ポート(nginx)をホスト側 30080 に転送 - containerPort: 80 hostPort: 30080 protocol: TCP |
ポイント
extraPortMappingsはkindが内部で起動する Docker コンテナのポートマッピングです。
NodePort を使用しない場合でも、hostPortによりローカルブラウザから直接アクセスできます。
2. クラスタ作成
|
1 2 3 |
kind create cluster --config kind-config.yaml # 約30秒で完了 kubectl cluster-info # コントロールプレーンの URL が表示されるはず |
3. テスト用 nginx デプロイと Service 作成
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
# Deployment(公式サンプル)をそのまま適用 kubectl apply -f https://k8s.io/examples/application/deployment.yaml # NodePort Service を作成(ポートは 30080 に統一) cat <<EOF | kubectl apply -f - apiVersion: v1 kind: Service metadata: name: nginx-nodeport spec: type: NodePort selector: app: nginx ports: - port: 80 # クラスタ内部のポート targetPort: 80 nodePort: 30080 # ホスト側に公開するポート(30,000-32,767 が必須) EOF |
4. アクセス確認
|
1 2 3 |
# ブラウザまたは curl で直接アクセス curl http://localhost:30080 |
期待結果
Welcome to nginx!と表示されれば成功です。
hostPort と NodePort の違い(初心者向けまとめ)
| 項目 | hostPort (extraPortMappings) | NodePort |
|---|---|---|
| 作成場所 | kind 設定ファイルで Docker コンテナに直接バインド |
Kubernetes Service オブジェクトで自動的に割り当て |
| ポート範囲 | 任意(ただしコンフリクトに注意) | 30000‑32767 が予約済み |
| 用途 | ローカル開発・デバッグ向け、外部から直接アクセスしたいとき | 複数ノードがある本格クラスターでの外部公開に必須 |
kubeadm によるマルチノード構築(apt-key 非推奨対応)
1. Kubernetes リポジトリの追加(Debian/Ubuntu 共通)
|
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 # GPG キーをキーリングに保存 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-archive-keyring.gpg # apt ソースリストを作成(apt-key ではなく signed-by を使用) cat <<EOF | sudo tee /etc/apt/sources.list.d/kubernetes.list deb [signed-by=/etc/apt/keyrings/kubernetes-archive-keyring.gpg] \ https://apt.kubernetes.io/ kubernetes-xenial main EOF # パッケージインデックス更新 & 必要パッケージをインストール sudo apt-get update sudo apt-get install -y kubelet=1.29.3-00 kubeadm=1.29.3-00 kubectl=1.29.3-00 sudo apt-mark hold kubelet kubeadm kubectl # 予期せぬバージョンアップを防止 |
ポイント
kubeadm、kubectl、kubeletは同一バージョンで揃える必要があります。上記は 2026/04 時点の最新安定版です。
2. Docker CE の設定と cgroup driver 統一
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Docker が systemd を使用しているか確認 docker info | grep -i 'cgroup Driver' # 出力が "systemd" でなければ、/etc/docker/daemon.json に追記 sudo mkdir -p /etc/docker cat <<EOF | sudo tee /etc/docker/daemon.json { "exec-opts": ["native.cgroupdriver=systemd"] } EOF sudo systemctl restart docker # kubelet 側にも同様の設定を付与(/etc/default/kubelet) echo 'KUBELET_EXTRA_ARGS=--cgroup-driver=systemd' | sudo tee -a /etc/default/kubelet sudo systemctl daemon-reload && sudo systemctl restart kubelet |
3. コントロールプレーンの初期化
|
1 2 3 4 5 6 7 8 9 10 11 |
# Pod ネットワークは Calico の CIDR に合わせる(例: 192.168.0.0/16) sudo kubeadm init \ --pod-network-cidr=192.168.0.0/16 \ --control-plane-endpoint=$(hostname -I | awk '{print $1}'):6443 \ --upload-certs # 一般ユーザー向け設定($HOME/.kube 配下に kubeconfig をコピー) mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config |
重要
--control-plane-endpointは外部ロードバランサや仮想 IP(VIP)を使用する際に必須です。シングルノードでテストするときは上記のように自ホスト IP を指定しても問題ありません。
4. ワーカーノード参加手順
|
1 2 3 4 5 6 |
# マスター側で join コマンド(証明書とトークン)を取得 kubeadm token create --print-join-command --ttl=24h # 出力例: # kubeadm join 192.168.1.10:6443 --token abcdef.0123456789abcdef \ # --discovery-token-ca-cert-hash sha256:<hash> |
ワーカーノード上で上記コマンドを root または sudo 付きで実行すれば自動的に Ready 状態になります。
5. CNI プラグイン(Calico)導入
|
1 2 3 4 |
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27/manifests/calico.yaml # 完了後に確認 kubectl get pods -n kube-system -l k8s-app=calico-node |
備考
kubeadmのオプションは 2026 年度に一部変更されました。最新フラグは公式ドキュメント (kubeadm config print init-defaults) で随時確認してください。
CNI プラグイン導入と基本的なセキュリティ設定
Calico と Cilium の選択指針
| 項目 | Calico | Cilium |
|---|---|---|
| 実装方式 | L3 ルーティング + IPIP (デフォルト) | eBPF ベースの高性能パケット処理 |
| 導入コスト | シンプルな YAML 1 ファイルで完了 | Helm が必要(依存関係が多い) |
| ネットワークポリシー | 標準的な NetworkPolicy に完全対応 |
同上 + L7 ポリシーや CiliumClusterwideNetworkPolicy |
| 推奨環境 | 小〜中規模、学習コスト最小化 | 大規模クラスター、パフォーマンス重視、Observability が重要なケース |
Calico 導入(再掲)
|
1 2 |
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27/manifests/calico.yaml |
Cilium 導入(Helm 使用例)
|
1 2 3 4 5 6 7 |
helm repo add cilium https://helm.cilium.io/ helm install cilium cilium/cilium \ --version 1.14.0 \ --namespace kube-system \ --set ipam.mode=kubernetes \ --set hubble.enabled=true # 可視化ツール有効化 |
RBAC と API Server の認証強化
kubeadm init 時点で RBAC は自動的に有効です。さらに以下の設定を追加するとセキュリティが向上します。
|
1 2 3 4 5 6 7 |
# /etc/kubernetes/manifests/kube-apiserver.yaml に追記 - --authorization-mode=Node,RBAC - --authentication-token-webhook=true - --requestheader-client-ca-file=/etc/kubernetes/pki/front-proxy-ca.crt - --proxy-client-cert-file=/etc/kubernetes/pki/front-proxy-client.crt - --proxy-client-key-file=/etc/kubernetes/pki/front-proxy-client.key |
変更後は kubelet が自動的に Pod を再起動し、設定が反映されます。
サンプルアプリ(nginx)での外部アクセス確認
1. Manifest の作成(Deployment + Service)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 |
# nginx-app.yaml apiVersion: apps/v1 kind: Deployment metadata: name: nginx-deploy spec: replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.25-alpine ports: - containerPort: 80 --- apiVersion: v1 kind: Service metadata: name: nginx-svc spec: type: NodePort selector: app: nginx ports: - port: 80 # クラスタ内部のポート targetPort: 80 nodePort: 30080 # 前節と同一に統一 |
|
1 2 |
kubectl apply -f nginx-app.yaml |
2. 動作確認
|
1 2 3 4 5 6 |
# Pod が Running になるまで待機(watch 推奨) watch kubectl get pods -l app=nginx # Service の NodePort を再確認 kubectl get svc nginx-svc -o wide |
ブラウザまたは CLI から次の URL にアクセスします。
|
1 2 3 4 |
curl http://$(hostname -I | awk '{print $1}'):30080 # またはローカル環境なら: curl http://localhost:30080 |
期待結果: Welcome to nginx! の HTML が返ってくること。
Tip:
kindでextraPortMappings.hostPort=30080を設定している場合、上記 URL は Docker ホスト(WSL2/VM)から直接アクセスできます。NodePort のみを使用した場合はkubectl proxyや外部ロードバランサが必要になる点に注意してください。
よくあるエラーとトラブルシューティング集
| エラー | 主な原因 | 推奨対処 |
|---|---|---|
| cgroup driver mismatch | Docker が systemd、kubelet が cgroupfs |
両者を systemd に統一(上記「Docker 設定」参照) |
Pod で DNS 解決できない (kubernetes.default.svc.cluster.local) |
CNI 未起動または CoreDNS Pod が CrashLoopBackOff |
kubectl -n kube-system get pods で coredns の状態を確認、必要なら kubectl rollout restart deployment/coredns -n kube-system |
| NodePort が外部から届かない | ホスト側ファイアウォールがポート 30000‑32767 を遮断 | sudo ufw allow 30000:32767/tcp(Ubuntu)または iptables -A INPUT -p tcp --dport 30080 -j ACCEPT |
| Calico の IPIP モジュールがロードされない | カーネルに ip_tables, xt_conntrack が無い |
sudo modprobe ip_tables && sudo modprobe xt_conntrack |
| kubeadm init 後に etcd が空 | /var/lib/etcd ディレクトリが破損または権限不足 |
既存ディレクトリを削除し、kubeadm reset -f && kubeadm init … 再実行 |
| kubectl が “connection refused” | API Server の --advertise-address が誤っている |
sudo kubeadm init --apiserver-advertise-address=$(hostname -I | awk '{print $1}') で再初期化 |
ログの取り方
bashkubelet
journalctl -u kubelet -f
Docker デーモン
journalctl -u docker -f
特定 Pod のログ
kubectl logs
-n
次のステップ – 学習ロードマップ
-
ローカル
kindクラスタで基本操作を完了
nginx デプロイ → Service/Ingress まで体感 -
本番に近い構成へ移行
kubeadmで マスター + ワーカー (最低 2 ノード) を構築-
CNI は Calico(IPIP)か Cilium(eBPF)を選択し、ネットワークポリシーを書いてみる
-
セキュリティ強化
RBACで最小権限ロールを作成 (kubectl create rolebinding …)- API Server の認証フラグ追加・Audit ログ有効化
-
etcd バックアップスクリプト(cron +
etcdctl snapshot save) -
CI/CD パイプライン構築
- GitHub Actions で
kindクラスタにテストデプロイ → PR の自動検証 -
Helm Chart を作成し、バージョン管理・リリース手順を体験
-
クラウドマネージドへの移行
| サービス | 移行のハンドオフポイント |
|----------|------------------------|
| EKS (AWS) |eksctl create cluster→ VPC CNI がデフォルト、Calico の有効化はオプション |
| GKE (Google Cloud) |gcloud container clusters create→--enable-network-policyで Calico 有効 |
| AKS (Azure) |az aks create→--network-plugin azureまたはkubenet| -
ナレッジシェア
- GitHub リポジトリに Dockerfile、Manifests、Helm Chart をまとめる
- Markdown ドキュメントをブログや社内 Wiki に投稿し、レビューを受ける
まとめ
- apt-key は使用せず、キーリングファイル (
/usr/share/keyrings/*.gpg) とsigned-byオプションでリポジトリを管理 - Docker CE の公式レポジトリからインストールし、cgroup driver を
systemdに統一 kindのextraPortMappings.hostPortと Service の NodePort を同じ 30080 に揃えて、ポート混乱を防止- kubeadm インストール時も apt-key 非推奨に対応し、バージョン固定で安定運用
- CNI は Calico(シンプル)か Cilium(高性能)から選択し、RBAC と API Server の認証フラグでセキュリティを強化
この手順通りに進めれば、ローカル環境での学習 → 本格マルチノード構築 → クラウド移行 という一連の流れを安全かつ最新のベストプラクティスで実現できます。ぜひ手元で試し、次のプロジェクトに活かしてください。