Kubespray徹底解説 — Ansibleで構築するプロダクション級オンプレKubernetes

+--------------------------------------------------------------------+
| Ansibleコントロールノード(運用者PCまたは踏み台)                     |
|                                                                    |
|  inventory/prod/                                                   |
|   ├─ hosts.yaml            ← ノード一覧とグループ(トポロジー)定義   |
|   └─ group_vars/                                                   |
|       ├─ all/all.yml       ← 全域変数(LB、プロキシ、レジストリ)     |
|       └─ k8s_cluster/                                              |
|           ├─ k8s-cluster.yml  ← バージョン、CIDR、CNI、プロキシ     |
|           └─ addons.yml       ← ingress、metallb、cert-manager     |
|                                                                    |
|  ansible-playbook cluster.yml                                      |
|        │                                                           |
|        ▼                                                           |
|  [ロール実行順序]                                                   |
|   1. kubernetes/preinstall  → OS検証、sysctl、モジュール、スワップ  |
|   2. container-engine       → containerd / crio のインストール     |
|   3. download               → バイナリ・イメージ取得(またはミラー)  |
|   4. etcd                   → etcdクラスタ構成・証明書              |
|   5. kubernetes/control-plane → kubeadm init / join (CPノード)     |
|   6. kubernetes/node        → kubelet構成、kubeadm join (ワーカー)  |
|   7. network_plugin         → Calico / Cilium マニフェスト適用      |
|   8. kubernetes-apps        → CoreDNS、アドオン、MetalLBなど        |
+--------------------------------------------------------------------+
        │ SSH (become: root)
        ▼
+-------------------+  +-------------------+  +-------------------+
|  cp1 (CP+etcd)    |  |  cp2 (CP+etcd)    |  |  cp3 (CP+etcd)    |
+-------------------+  +-------------------+  +-------------------+
+-------------------+  +-------------------+  +-------------------+
|  worker1          |  |  worker2          |  |  workerN ...      |
+-------------------+  +-------------------+  +-------------------+

ノードネットワーク : 10.10.0.0/24    (物理サーバーIP — 社内IPAMから割当)
Pod CIDR          : 10.233.64.0/18  (kube_pods_subnet — デフォルト)
Service CIDR      : 10.233.0.0/18   (kube_service_addresses — デフォルト)

ノードあたりPodレンジ: /24 (kube_network_node_prefix)
→ ノードあたり最大約110 Pod、/18基準で最大64ノード

# コントロールノードで鍵を生成し全ノードへ配布
ssh-keygen -t ed25519 -f ~/.ssh/kubespray_ed25519
for h in 10.10.0.11 10.10.0.12 10.10.0.13 10.10.0.21 10.10.0.22; do
  ssh-copy-id -i ~/.ssh/kubespray_ed25519.pub deploy@"$h"
done

# deployアカウントへパスワードなしsudoを付与(各ノード)
echo 'deploy ALL=(ALL) NOPASSWD: ALL' | sudo tee /etc/sudoers.d/deploy

# 必ずリリースタグをチェックアウト — masterブランチでのプロダクション構築は禁止
git clone --branch v2.28.0 https://github.com/kubernetes-sigs/kubespray.git
cd kubespray

# Ansibleバージョン衝突を避けるため専用の仮想環境を使用
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -r requirements.txt

# サンプルインベントリをコピーしてプロダクション用を作成
cp -rfp inventory/sample inventory/prod

# inventory/prod/hosts.yaml
all:
  hosts:
    cp1:
      ansible_host: 10.10.0.11
      ip: 10.10.0.11          # kubelet/etcdがバインドする内部IP
      access_ip: 10.10.0.11   # 他ノードがこのノードへ到達するIP
    cp2:
      ansible_host: 10.10.0.12
      ip: 10.10.0.12
      access_ip: 10.10.0.12
    cp3:
      ansible_host: 10.10.0.13
      ip: 10.10.0.13
      access_ip: 10.10.0.13
    worker1:
      ansible_host: 10.10.0.21
      ip: 10.10.0.21
    worker2:
      ansible_host: 10.10.0.22
      ip: 10.10.0.22
    worker3:
      ansible_host: 10.10.0.23
      ip: 10.10.0.23
  children:
    kube_control_plane:
      hosts:
        cp1:
        cp2:
        cp3:
    kube_node:
      hosts:
        worker1:
        worker2:
        worker3:
    etcd:
      hosts:
        cp1:
        cp2:
        cp3:
    k8s_cluster:
      children:
        kube_control_plane:
        kube_node:
    calico_rr:
      hosts: {}

# inventory/prod/group_vars/k8s_cluster/k8s-cluster.yml

# Kubernetesバージョン — 当該Kubesprayリリースのサポート範囲内のみ
kube_version: "1.32.5"

# ネットワークプラグイン: calico、cilium、flannel、kube-ovnなど
kube_network_plugin: calico

# CIDR — 構築後の変更不可、社内レンジとの重複禁止
kube_service_addresses: 10.233.0.0/18
kube_pods_subnet: 10.233.64.0/18
kube_network_node_prefix: 24

# kube-proxyモード: ipvs推奨(サービス数千件規模でiptablesより有利)
kube_proxy_mode: ipvs

# コンテナランタイム
container_manager: containerd

# DNS
dns_mode: coredns
enable_nodelocaldns: true        # ノードローカルDNSキャッシュ — 大規模では必須級

# クラスタ名(内部ドメイン)
cluster_name: cluster.local

# 構築完了後にコントロールノードへadmin kubeconfigをコピー
kubeconfig_localhost: true

# 証明書の自動更新(systemd timerが毎月更新を試行)
auto_renew_certificates: true

# inventory/prod/group_vars/all/all.yml

# 外部LB(HAProxy+keepalivedまたはハードウェアLB)を使う場合
apiserver_loadbalancer_domain_name: "k8s-api.prod.internal"
loadbalancer_apiserver:
  address: 10.10.0.100   # VIP
  port: 6443

# 各ノードのnginx-proxyローカルLB(デフォルト有効 — 内部コンポーネントのHA)
loadbalancer_apiserver_localhost: true

# kube-vipによるコントロールプレーンVIP構成(ARPモード)
kube_vip_enabled: true
kube_vip_controlplane_enabled: true
kube_vip_arp_enabled: true
kube_vip_address: 10.10.0.100
loadbalancer_apiserver:
  address: 10.10.0.100
  port: 6443

# inventory/prod/group_vars/k8s_cluster/addons.yml

helm_enabled: true
metrics_server_enabled: true

# Ingressコントローラ
ingress_nginx_enabled: true
ingress_nginx_host_network: false

# ベアメタルにおけるLoadBalancerサービスの実装 — MetalLB
metallb_enabled: true
metallb_speaker_enabled: true
metallb_config:
  address_pools:
    primary:
      ip_range:
        - 10.10.0.150-10.10.0.180
      auto_assign: true
  layer2:
    - primary

# 証明書の自動化
cert_manager_enabled: true

# シンプルなローカルPVで足りる場合
local_path_provisioner_enabled: true

# 事前の疎通確認
ansible -i inventory/prod/hosts.yaml all -m ping \
  --private-key ~/.ssh/kubespray_ed25519 -u deploy -b

# 本実行 — 6ノードで約20〜40分
ansible-playbook -i inventory/prod/hosts.yaml \
  --private-key ~/.ssh/kubespray_ed25519 -u deploy \
  --become --become-user=root \
  cluster.yml

# kubeconfig_localhost: true ならインベントリ配下にadmin.confがコピーされる
export KUBECONFIG=$PWD/inventory/prod/artifacts/admin.conf

kubectl get nodes -o wide
# NAME      STATUS   ROLES           VERSION   INTERNAL-IP
# cp1       Ready    control-plane   v1.32.5   10.10.0.11
# cp2       Ready    control-plane   v1.32.5   10.10.0.12
# cp3      Ready    control-plane   v1.32.5   10.10.0.13
# worker1   Ready    <none>          v1.32.5   10.10.0.21
# ...

# コントロールプレーンPodとCNIの状態
kubectl get pods -n kube-system

# etcdメンバーとヘルス(cp1で実行)
sudo ETCDCTL_API=3 etcdctl \
  --endpoints=https://10.10.0.11:2379 \
  --cacert=/etc/ssl/etcd/ssl/ca.pem \
  --cert=/etc/ssl/etcd/ssl/node-cp1.pem \
  --key=/etc/ssl/etcd/ssl/node-cp1-key.pem \
  endpoint health --cluster

# スモークテスト: デプロイ → 公開 → DNS → 削除
kubectl create deployment nginx --image=nginx --replicas=3
kubectl expose deployment nginx --port=80
kubectl run dns-test --rm -it --image=busybox:1.36 --restart=Never \
  -- nslookup nginx.default.svc.cluster.local
kubectl delete deployment nginx svc/nginx

# 1) hosts.yamlにworker4を追加してから
# 2) 新規ノードだけを対象にscaleを実行
ansible-playbook -i inventory/prod/hosts.yaml \
  --become --limit=worker4 \
  scale.yml

# limit実行の前に全体のファクトを更新
ansible-playbook -i inventory/prod/hosts.yaml --become playbooks/facts.yml

# ドレイン → クラスタから削除 → ノードのクリーンアップまで一括
ansible-playbook -i inventory/prod/hosts.yaml \
  --become \
  -e node=worker3 \
  remove-node.yml

# 例: 1.31.x → 1.32.x
cd kubespray && git checkout v2.28.0
pip install -r requirements.txt   # 要求されるAnsibleバージョンも変わる

ansible-playbook -i inventory/prod/hosts.yaml \
  --become \
  -e kube_version=1.32.5 \
  upgrade-cluster.yml

# 1台ずつ、ドレインのタイムアウトを十分に
ansible-playbook -i inventory/prod/hosts.yaml --become \
  -e kube_version=1.32.5 \
  -e serial=1 \
  -e drain_timeout=600s \
  -e drain_grace_period=120 \
  upgrade-cluster.yml

# クラスタをノードから完全に撤去 — ディスク上のetcdデータも削除される
ansible-playbook -i inventory/prod/hosts.yaml --become reset.yml

# バックアップ(etcdノードで — cron/systemd timerで定期実行)
sudo ETCDCTL_API=3 etcdctl snapshot save /backup/etcd-snap-20260613.db \
  --endpoints=https://10.10.0.11:2379 \
  --cacert=/etc/ssl/etcd/ssl/ca.pem \
  --cert=/etc/ssl/etcd/ssl/node-cp1.pem \
  --key=/etc/ssl/etcd/ssl/node-cp1-key.pem

# 整合性の確認
ETCDCTL_API=3 etcdctl --write-out=table snapshot status /backup/etcd-snap-20260613.db

# 月1回systemd timer(k8s-certs-renew.timer)が期限間近の証明書を更新
auto_renew_certificates: true

# 必要時にプレイブック実行で強制再発行
# -e force_certificate_regeneration=true

# inventory/prod/group_vars/all/offline.yml
registry_host: "harbor.internal:443/k8s-mirror"
files_repo: "https://mirror.internal/kubespray-files"

# コンテナイメージのリポジトリをすべて内部レジストリへ
kube_image_repo: "{{ registry_host }}"
gcr_image_repo: "{{ registry_host }}"
github_image_repo: "{{ registry_host }}"
docker_image_repo: "{{ registry_host }}"
quay_image_repo: "{{ registry_host }}"

# バイナリのダウンロードURLを内部ファイルサーバーへ
kubeadm_download_url: "{{ files_repo }}/kubeadm/{{ kube_version }}/kubeadm"
kubelet_download_url: "{{ files_repo }}/kubelet/{{ kube_version }}/kubelet"
kubectl_download_url: "{{ files_repo }}/kubectl/{{ kube_version }}/kubectl"
etcd_download_url: "{{ files_repo }}/etcd/etcd-{{ etcd_version }}-linux-{{ host_architecture }}.tar.gz"
cni_download_url: "{{ files_repo }}/cni/cni-plugins-linux-{{ host_architecture }}-{{ cni_version }}.tgz"
crictl_download_url: "{{ files_repo }}/crictl/crictl-{{ crictl_version }}-linux-{{ host_architecture }}.tar.gz"
runc_download_url: "{{ files_repo }}/runc/{{ runc_version }}/runc.{{ host_architecture }}"
containerd_download_url: "{{ files_repo }}/containerd/containerd-{{ containerd_version }}-linux-{{ host_architecture }}.tar.gz"

# プライベートCAを使うレジストリならcontainerdへ信頼を登録
containerd_registries_mirrors:
  - prefix: "harbor.internal"
    mirrors:
      - host: "https://harbor.internal"
        capabilities: ["pull", "resolve"]
        skip_verify: false

# inventory/prod/group_vars/k8s_cluster/k8s-cluster.yml
additional_sysctl:
  - name: net.core.somaxconn
    value: 65535
  - name: net.ipv4.tcp_max_syn_backlog
    value: 65535
  - name: fs.inotify.max_user_instances
    value: 8192
  - name: fs.inotify.max_user_watches
    value: 1048576

# kubeletにノードリソースを予約させる
kube_reserved: true
kube_memory_reserved: 512Mi
kube_cpu_reserved: 200m
system_reserved: true
system_memory_reserved: 1Gi
system_cpu_reserved: 500m

# APIサーバーのハードニング
kube_apiserver_request_timeout: 120s
kube_apiserver_enable_admission_plugins:
  - NodeRestriction
  - AlwaysPullImages
  - EventRateLimit
kube_apiserver_admission_event_rate_limits:
  limit_1:
    type: Namespace
    qps: 50
    burst: 100
    cache_size: 2000
kube_profiling: false

# kubeletのハードニング
kubelet_protect_kernel_defaults: true
kubelet_event_record_qps: 1
kubelet_streaming_connection_idle_timeout: 5m
kubelet_make_iptables_util_chains: true

# 匿名認証の遮断はkubeadmデフォルトで処理されるが明示的に
kube_api_anonymous_auth: false

kubernetes_audit: true
audit_log_path: /var/log/kubernetes/audit/audit.log
audit_log_maxage: 30        # 保存日数
audit_log_maxbackups: 10
audit_log_maxsize: 100      # MB
# デフォルトポリシーの代わりにカスタムポリシーを使うなら
# audit_policy_custom_rules にルールを定義

kube_encrypt_secret_data: true
# デフォルトのプロバイダはsecretbox — aescbcなどへ変更可能
kube_encryption_algorithm: "secretbox"
kube_encryption_resources: [secrets]

kube_pod_security_use_default: true
kube_pod_security_default_enforce: baseline   # 新規Namespaceへ既定適用
kube_pod_security_default_audit: restricted
kube_pod_security_default_warn: restricted
kube_pod_security_exempt_namespaces:
  - kube-system

k8s-clusters/                  ← 社内Gitリポジトリ
├─ README.md                   ← クラスタ・Kubesprayバージョン対応表
├─ clusters/
│   ├─ prod-seoul/
│   │   ├─ hosts.yaml
│   │   └─ group_vars/ ...
│   └─ stage-seoul/
│       ├─ hosts.yaml
│       └─ group_vars/ ...
└─ pipelines/
    └─ run-kubespray.yaml      ← CI定義

# GitLab CIの例 — 概念的な骨格
stages: [lint, diff, apply]

lint:
  stage: lint
  script:
    - ansible-lint clusters/prod-seoul || true
    - python3 scripts/validate_inventory.py clusters/prod-seoul

apply-prod:
  stage: apply
  when: manual            # プロダクションは必ず手動承認
  script:
    - git clone --branch v2.28.0 --depth 1
        https://github.com/kubernetes-sigs/kubespray.git
    - pip install -r kubespray/requirements.txt
    - ansible-playbook -i clusters/prod-seoul/hosts.yaml
        --become kubespray/cluster.yml
  environment: prod-seoul

# ansible.cfg
[defaults]
forks = 50                 # デフォルト5 — 数十ノードなら必ず引き上げ
strategy = linear
[ssh_connection]
pipelining = True          # SSH往復の削減 — 体感効果が大きい
ssh_args = -o ControlMaster=auto -o ControlPersist=30m

# 特定ノードのみ — 必ずfactsを更新してから
ansible-playbook -i inventory/prod/hosts.yaml --become playbooks/facts.yml
ansible-playbook -i inventory/prod/hosts.yaml --become \
  --limit=worker7 cluster.yml

# 特定コンポーネントのタグのみ — 例: CoreDNS設定変更の反映
ansible-playbook -i inventory/prod/hosts.yaml --become \
  --tags=coredns cluster.yml

# ダウンロード段階をスキップして反復実行を短縮
ansible-playbook -i inventory/prod/hosts.yaml --become \
  --skip-tags=download cluster.yml

# 詳細ログで再実行 — 冪等性により完了済みタスクはchangedなしで通過
ansible-playbook -i inventory/prod/hosts.yaml --become cluster.yml -vvv \
  2>&1 | tee /tmp/kubespray-run.log

# ノード側の一次確認ポイント
journalctl -u kubelet -f          # kubelet起動失敗の原因
journalctl -u containerd -f      # ランタイム/レジストリの問題
crictl ps -a                      # コントロールプレーンのスタティックPod状態
ls /etc/kubernetes/manifests/     # kubeadmスタティックPodマニフェスト

[ ] インベントリ・group_varsがGitでPRレビュー管理されているか
[ ] Kubesprayリリースタグとkube_versionの対応が文書化されているか
[ ] CP3台+etcdクォーラム、etcdはSSD/NVMeか
[ ] APIサーバーVIP(kube-vipまたはHAProxy+keepalived)のフェイルオーバーテスト合格
[ ] Pod/Service CIDRが社内IPAMに登録され重複がないか
[ ] etcdスナップショットの定期取得+外部搬出+四半期ごとのリストア演習
[ ] auto_renew_certificates有効+証明書失効の監視
[ ] kubernetes_audit有効+中央ログ収集
[ ] kube_encrypt_secret_data有効
[ ] PSAデフォルト(enforce baseline以上)の適用
[ ] kube-bench実行結果と例外理由の文書化
[ ] アップグレード手順(スキップ禁止、serial、PDB点検)がランブック化されているか
[ ] ステージングクラスタで同一変更を先に検証するプロセス
[ ] OSパッチポリシーとKubernetesパッケージのhold設定