k8s-cluster-api

Kubernetes Cluster API

Kubernetes Cluster API（CAPI）は、複数の Kubernetes クラスターのプロビジョニング、アップグレード、運用を簡素化するための宣言型 API とツールの提供に重点を置く、Kubernetes のサブプロジェクトです。

概要

SIG Cluster Lifecycle によって開始された Cluster API は、Kubernetes スタイルの API とパターンを使用して、クラスターのライフサイクル管理を自動化します。インフラストラクチャ（VM、ネットワーク、ロードバランサー、VPC）と Kubernetes の設定を宣言的に定義できるため、環境間で一貫性と再現性のあるクラスターのデプロイが可能になります。

Cluster API を使う理由

kubeadm はインストールの複雑さを軽減しますが、日々のクラスター管理には対応していません。

• プロバイダーや場所をまたいで、一貫性のある方法でインフラストラクチャをプロビジョニングするにはどうすればよいですか？
• クラスターのライフサイクル（アップグレード、削除）をどう自動化すればよいですか？
• あらゆる数のクラスターを管理できるよう、プロセスをどう拡張すればよいですか？

Cluster API は、クラスターの作成、設定、管理を自動化する宣言型の Kubernetes スタイル API によって、こうした課題に対応します。

目標

• 宣言型 API を通じて、Kubernetes 準拠クラスターのライフサイクル（作成、スケーリング、アップグレード、破棄）を管理する
• さまざまな環境（オンプレミスとクラウド）で動作する
• 共通の操作を、差し替え可能な実装で定義する
• 既存のエコシステムコンポーネント（cluster-autoscaler、node-problem-detector）を再利用する
• 既存のツールが段階的に採用できる移行経路を提供する

目標ではないこと

• Kubernetes コアに API を追加する
• Kubernetes クラスターとは無関係なインフラストラクチャを管理する
• すべてのライフサイクル製品にこれらの API の使用を強制する
• CAPI でプロビジョニングされていないクラスターを管理する
• 複数のプロバイダーにまたがる単一のクラスターを管理する
• 作成／アップグレード後にマシンを設定する

クイックナビゲーション

トピック	参照先
はじめに	getting-started.md
概念とアーキテクチャ	concepts.md
証明書	certificates.md
ブートストラップ（Kubeadm/MicroK8s）	bootstrap.md
クラスター操作	cluster-operations.md
実験的機能	experimental.md
clusterctl CLI	clusterctl.md
開発者ガイド	developer.md
トラブルシューティング	troubleshooting.md
API リファレンスとプロバイダー	api-reference.md
セキュリティと PSS	security.md
コントローラー	controllers.md
バージョン移行	migrations.md
FAQ	faq.md
ベストプラクティス	best-practices.md

使用する場面

• 複数のインフラストラクチャプロバイダーにまたがって Kubernetes クラスターをプロビジョニングする
• クラスターのライフサイクル（作成、スケーリング、アップグレード、破棄）を管理する
• 宣言型 API を使用してクラスター操作を自動化する
• クラスター管理に GitOps ワークフローを導入する
• カスタムインフラストラクチャプロバイダーを構築する

コアコンセプト

アーキテクチャ

┌─────────────────────────────────────────┐
│         Management Cluster              │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │ CAPI Core   │  │ Infrastructure  │   │
│  │ Controllers │  │ Provider        │   │
│  └─────────────┘  └─────────────────┘   │
│  ┌─────────────┐  ┌─────────────────┐   │
│  │  Bootstrap  │  │  Control Plane  │   │
│  │  Provider   │  │  Provider       │   │
│  └─────────────┘  └─────────────────┘   │
└─────────────────────┬───────────────────┘
                      │ manages
          ┌───────────┴───────────┐
          ▼                       ▼
┌─────────────────┐     ┌─────────────────┐
│ Workload        │     │ Workload        │
│ Cluster 1       │     │ Cluster N       │
└─────────────────┘     └─────────────────┘

主要コンポーネント

コンポーネント	目的
管理クラスター	CAPI コントローラーをホストし、ワークロードを管理します
ワークロードクラスター	CAPI が管理するユーザークラスターです
インフラストラクチャープロバイダー	VM、ネットワーク、ロードバランサーをプロビジョニングします
ブートストラッププロバイダー	cloud-init/ignition の設定を生成します
コントロールプレーンプロバイダー	コントロールプレーンノードのライフサイクルを管理します

コアリソース

リソース	説明
Cluster	Kubernetes クラスターを表します
Machine	単一のノード／VM を表します
MachineSet	Machine のレプリカを管理します
MachineDeployment	MachineSet の宣言的な更新を行います
MachineHealthCheck	異常なノードを自動的に修復します

クイックスタート

# Install clusterctl
curl -L https://github.com/kubernetes-sigs/cluster-api/releases/download/v1.12.0/clusterctl-linux-amd64 -o clusterctl
chmod +x clusterctl
sudo mv clusterctl /usr/local/bin/

# Initialize management cluster
clusterctl init --infrastructure docker

# Create workload cluster
clusterctl generate cluster my-cluster --kubernetes-version v1.32.0 --control-plane-machine-count 1 --worker-machine-count 3 | kubectl apply -f -

# Get cluster kubeconfig
clusterctl get kubeconfig my-cluster > my-cluster.kubeconfig

# Delete cluster
kubectl delete cluster my-cluster

一般的なワークフロー

クラスターのライフサイクル

# Create cluster from template
clusterctl generate cluster prod-cluster \
  --infrastructure aws \
  --kubernetes-version v1.32.0 \
  --control-plane-machine-count 3 \
  --worker-machine-count 5 \
  | kubectl apply -f -

# Scale workers
kubectl scale machinedeployment prod-cluster-md-0 --replicas=10

# Upgrade Kubernetes version
kubectl patch cluster prod-cluster --type merge -p '{"spec":{"topology":{"version":"v1.33.0"}}}'

# Move cluster to new management cluster
clusterctl move --to-kubeconfig target-mgmt.kubeconfig

ヘルスモニタリング

apiVersion: cluster.x-k8s.io/v1beta1
kind: MachineHealthCheck
metadata:
  name: my-cluster-mhc
spec:
  clusterName: my-cluster
  maxUnhealthy: 40%
  nodeStartupTimeout: 10m
  selector:
    matchLabels:
      cluster.x-k8s.io/cluster-name: my-cluster
  unhealthyConditions:
    - type: Ready
      status: "False"
      timeout: 5m
    - type: Ready
      status: Unknown
      timeout: 5m

重大な禁止事項

• 適切なバックアップを行わずに、管理クラスターを直接変更しないでください
• Machine オブジェクトを直接削除しないでください（MachineDeployment のスケールを使用してください）
• 互換性を確認せずにプロバイダーバージョンを混在させないでください
• クラスターのアップグレード手順を省略しないでください（コントロールプレーンを先に、その後ワーカーをアップグレードします）
• MachineHealthCheck のアラートを無視しないでください

リリースの主な変更点（1.14.x）

• 1.14.1 系では、Kubernetes の互換性対象が管理クラスターで v1.33.x -> v1.37.x、ワークロードクラスターで v1.31.x -> v1.37.x になります。
• API 型が専用の Golang モジュールに移行します。これにより、互換性の保証が強化され、依存関係ツリーが大幅に縮小されて厳密に管理されるため、推移的依存関係に起因する CVE への露出が抑えられます。
• Kubeadm コントロールプレーンの堅牢性が向上します。古い Kubernetes バージョンでのワーカーノードの安全な参加、コントロールプレーンマシンの削除時における etcd のリーダーシップの適切な引き継ぎ、連鎖的なアップグレードの中間ステップでの異常なマシンの修復が改善されます。
• 可観測性が向上します。アップグレード計画がクラスターのステータスに表示され、集約されたマシンバージョンがステータスで公開され、ランタイム拡張機能のエラーがクラスターの条件に表示されます。
• スケール／パフォーマンスが向上します。ClusterCache クライアントでキャッシュのチューニングオプションが利用可能になり、メモリ使用量が削減されます。また、managedFields のインターン化により、保存される状態が削減されます。
• 非推奨に関する警告：v1beta1 API は CAPI v1.16 で提供停止となる予定です（v1beta2 に移行してください）。また、Docker* リソースは v1.15 で削除される予定です（Dev* リソースに移行してください）。実験的な clusterctl convert コマンドを利用できます。

リリースの主な変更点（1.13.x）

• 1.13.2 系では、Kubernetes の互換性対象が管理クラスターで v1.32.x -> v1.36.x、ワークロードクラスターで v1.30.x -> v1.36.x になります。
• v1alpha3 と v1alpha4 の API バージョンが削除されました。プロバイダーは引き続き v1beta2 コントラクトへの移行を進めてください。v1beta1 は、後のリリースで提供停止となる予定です。
• クラスタートポロジーから、コントロールプレーンと MachineDeployment リソースの両方に対して rolloutAfter を指定できるようになりました。
• KubeadmControlPlane では、複数の障害に対する修復許容度が向上し、一般的な参加／修復の症状がより明確に示されるようになりました。
• PriorityQueue と ReconcilerRateLimiting が 1.13 系でベータ版のデフォルトになりました。これにより、高負荷時の調整動作が変わる場合があります。

スクリプト

scripts/ 内の Go ベースのツールです。scripts ディレクトリから go run ./tool-name を実行してください。

ツール	目的
validate-manifests	YAML マニフェストを CRD スキーマに照らして検証します
run-clusterctl-diagnose	clusterctl describe を実行し、診断レポートを保存します
migration-checker	v1beta1→v1beta2 への移行準備状況を確認します
check-cluster-health	すべてのクラスターオブジェクトの状態を分析します
analyze-conditions	False/Unknown の状態を解析して報告します
scaffold-provider	新しいプロバイダーディレクトリ構造を生成します
generate-cluster-template	ClusterClass からテンプレートを生成します
export-cluster-state	バックアップ／移動用にクラスターの状態をエクスポートします
audit-security	PSS への準拠状況とセキュリティ態勢を確認します
timeline-events	プロビジョニングイベントのタイムラインを作成します
compare-versions	CAPI のバージョン仕様と API の変更を比較します
check-provider-contract	プロバイダー CRD のコントラクトへの準拠を検証します
lint-cluster-templates	CAPI マニフェストをリントして検証します

アセット

再利用可能なテンプレートは assets/ にあります。

• クラスターのテンプレート: cluster-minimal.yaml、cluster-production.yaml、cluster-clusterclass.yaml、clusterclass-example.yaml
• プロバイダー設定: docker-quickstart.yaml、aws-credentials.yaml、azure-credentials.yaml、provider-matrix.md
• 運用: upgrade-checklist.md、migration-v1beta2.md、troubleshooting-flow.md、security-audit-report.md、dr-backup-restore.md、etcd-backup.yaml
• GitOps: argocd-cluster-app.yaml、flux-kustomization.yaml、gitops-rbac.yaml
• モニタリング: prometheus-alerts.yaml

リンク

• ドキュメント
• GitHub
• リリース