kubeadm でマスタ1台のクラスタを構築(参考訳:v1.11)
このドキュメントについて
現行バージョンの v1.11のドキュメント Creating a single master cluster with kubeadm に対する今日現在の参考訳です。ドキュメントは常に更新されているため、最新版かつ正確な情報は、オリジナルのサイトをご覧ください。
kubeadm はベスト・プラクティスに従う最小環境の Kubernetes クラスタ構築に役立ちます。kubeadm とあわせ、クラスタの環境は kubernetes適合試験 に合格しているべきです。また、kubeadm は他にもクラスタのライフサイクル機能も支援します。たとえばクラスタのアップグレードやダウングレード、 ブートストラップ・トークン(Bootstrap Tokens) の管理です。
kubeadm を様々なマシン(例:ノートPC、サーバ、Raspberry Pi、等)にインストールできますので、Terraform や Ansible のようなプロビジョニング・システムとの同時利用も適います。
kubeadm は広範囲にわたる利用場面を簡単にします。
- Kubernetes を始めて使おうとする新規利用者は、kubeadm で始められる。
- Kubernetes に慣れている利用者は、kubeadm で素早くクラスタを準備し、アプリケーションをテストできる。
- より複雑なシステムの構築範囲で、他のインストーラ・ツールを含むプロジェクトでも、kubeadm を導入できる。
新規利用者が Kubernetes を試すにあたり、初めから可能な限り最も簡単な手法となるように Kubeadm は設計されています。それだけでなく、既存利用者はアプリケーションをテストし、クラスタを簡単に組み上げ、広範囲に亘るインストール用ツールや他とのエコシステムを築き上げるためです。
kubeadm をオペレーティングシステムにインストールするのは非常に簡単です。そのために deb あるいは rpm パッケージのインストールをサポートしています。kubeadm 用 SIG の対応としては、SIG クラスタ・ライフサイクル では構築済みのパッケージが提供されているだけでなく、その他の OS 向けにも提供されています。
kubeadm 完成度
領域 | 成熟度 |
---|---|
コマンドライン UX | beta |
実装 | beta |
設定ファイル API | alpha |
セルフ・ホスティング | alpha |
kubeadm alpha コマンド | alpha |
CoreDNS | GA |
DynamicKubeletConfig | alpha |
kubeadm 機能の大半は Beta ですが、間もなく2018 年内には 一般利用可能 (GA) に到達予定です。機能にはセルフ・ホスティングや設定ファイル API といった複数のサブ機能を含んでおり、活発に開発が進められています。クラスタ構築の実装は、ツールの進化によって若干の変化があるかもしれません。しかし、大部分の実装はおおよそ安定しています。kubeadm alpha
配下で定義されているコマンドは、アルファ・レベルのサポートです。
サポート期間
Kubernetes のリリースは通常9ヶ月間サポートされており、何らかのバグやセキュリティ問題が発見されれば、リリース・ブランチから分岐して、定期的にパッチを提供します。以下は Kubernetes の最新リリースとサポート期間であり、 kubeadm
にも適用されます。
Kubernetes バージョン | リリース月 | 提供終了(End-of-life-month) |
---|---|---|
v1.6.x | 2017年3月 | 2017年12月 |
v1.7.x | 2017年6月 | 2018年3月 |
v1.8.x | 2017年9月 | 2018年6月 |
v1.9.x | 2017年12月 | 2018年9月 |
v1.10.x | 2018年3月 | 2018年12月 |
v1.11.x | 2018年6月 | 2019年3月 |
事前準備
- dev/rpm 互換 OS を実行可能な1つまたは複数のマシン。例: Ubuntu または CentOS 。
- マシンごとに 2 GB 以上のメモリ(動作アプリケーションが小さければ少なくても可能)
- マスタは 2 CPU 以上
- クラスタ内の全てのマシン間で完全なネットワーク接続性がある(パブリックまたはプライベート・ネットワークでも)
目標
- 単一マスタ Kubernetes クラスタか、 高可用性クラスタ をインストール
- クラスタ上に Pod ネットワークをインストールするので、Pod 間で相互通信できる
手順
ホスト上に kubeadm をインストール
kubeadm のインストール をご覧ください。
メモ: 既に kubeadm をインストールしている場合は、apt-get update && apt-get upgrade
か yum update
を実行し、kubeadm の最新版を入手します。
kubelet は数秒ごとに再起動するため、kubeadm が次に何をすべきか伝えるためクラッシュループ (crashloop) で待機します。クラッシュループは予測可能であり、正常ですから、次のステップに進めば、kubelet は通常通り動作します。
マスタの初期化
マスタとはコントロール・プレーン・コンポーネントを実行するためのマシンであり、 etcd(クラスタのデータベース)と API サーバ(kubectl CLI との通信)を含みます。
- ポッド・ネットワーク・アドオンを選択し、kubeadm 初期化に必要な引数があるかどうかを確認します。選択したサードパーティ・プロバイダに依存しますが、プロバイダ特有の値を
--pod-network-cidr
での指定が必要な場合があります。詳細は ポッド・ネットワーク・アドオンのインストールをご覧ください。 - (オプション)特に指定がなければ、kubeadm はマスタの IP を広報(advertise)するために、デフォルト・ゲートウェイに関連付けられたネットワーク・インターフェースを使います。別のネットワーク・インターフェースを使うには、
kubeadm init
の引数で--apiserver-advertise-address=<ip-address>
を指定します。IPv6 アドレスを割り当てて IPv6 Kubernetes クラスタを展開するには、--apiserver-advertise-address=fd00::101
のように、必ず IPv6 アドレスを指定します。 - (オプション)gcr.io レジストリに対する接続性を確認するには、
kubeadm init
よりも前にkubeadm config images pull
を実行します。
それから、実行します。
kubeadm init <引数>
詳細情報
kubeadm init
で指定可能なフラグの詳細を知りたい場合は、 [kubeadm 参照ガイド] (https://kubernetes.io/docs/reference/setup-tools/kubeadm/kubeadm/) をご覧ください。
設定オプションの完全な一覧は、 設定ファイル資料 をご覧ください。
コントロール・プレーンに対してカスタマイズをする場合、たとえばオプションの IPv6 アドレス割り当て、コントロール・プレーン構成要素や ctcd サーバに対する生存確認に対しては、カスタム引数 に記載されている追加引数の指定が必要です。
kubeadm init
を実行するには、最初に クラスタをディア・ダウン(tear down) します。
クラスタに対して異なったアーキテクチャを持つノードを追加する場合は、分けて展開(Deployment)するか、ノード上に kube-proxy
と kube-dns
に対する別のデーモンセット(DaemonSet)が必要です。これは、各構成要素用の Docker イメージが、マルチ・アーキテクチャに現時点では対応していないからです。
kubeadm init
の初回実行時、マシンで Kubernetes を稼働する準備が整っているかどうか、一連の事前確認を行います。この事前確認により、警告の表示や、 エラーによる停止が起こるかもしれません。 kubeadm init
の後、クラスタのコントロール・プレーン構成要素のダウンロードとインストールをします。これには数分かかるでしょう。出力は次のようになります。
[init] Using Kubernetes version: vX.Y.Z
[preflight] Running pre-flight checks
[kubeadm] WARNING: starting in 1.8, tokens expire after 24 hours by default (if you require a non-expiring token use --token-ttl 0)
[certificates] Generated ca certificate and key.
[certificates] Generated apiserver certificate and key.
[certificates] apiserver serving cert is signed for DNS names [kubeadm-master kubernetes kubernetes.default kubernetes.default.svc kubernetes.default.svc.cluster.local] and IPs [10.96.0.1 10.138.0.4]
[certificates] Generated apiserver-kubelet-client certificate and key.
[certificates] Generated sa key and public key.
[certificates] Generated front-proxy-ca certificate and key.
[certificates] Generated front-proxy-client certificate and key.
[certificates] Valid certificates and keys now exist in "/etc/kubernetes/pki"
[kubeconfig] Wrote KubeConfig file to disk: "admin.conf"
[kubeconfig] Wrote KubeConfig file to disk: "kubelet.conf"
[kubeconfig] Wrote KubeConfig file to disk: "controller-manager.conf"
[kubeconfig] Wrote KubeConfig file to disk: "scheduler.conf"
[controlplane] Wrote Static Pod manifest for component kube-apiserver to "/etc/kubernetes/manifests/kube-apiserver.yaml"
[controlplane] Wrote Static Pod manifest for component kube-controller-manager to "/etc/kubernetes/manifests/kube-controller-manager.yaml"
[controlplane] Wrote Static Pod manifest for component kube-scheduler to "/etc/kubernetes/manifests/kube-scheduler.yaml"
[etcd] Wrote Static Pod manifest for a local etcd instance to "/etc/kubernetes/manifests/etcd.yaml"
[init] Waiting for the kubelet to boot up the control plane as Static Pods from directory "/etc/kubernetes/manifests"
[init] This often takes around a minute; or longer if the control plane images have to be pulled.
[apiclient] All control plane components are healthy after 39.511972 seconds
[uploadconfig] Storing the configuration used in ConfigMap "kubeadm-config" in the "kube-system" Namespace
[markmaster] Will mark node master as master by adding a label and a taint
[markmaster] Master master tainted and labelled with key/value: node-role.kubernetes.io/master=""
[bootstraptoken] Using token: <token>
[bootstraptoken] Configured RBAC rules to allow Node Bootstrap tokens to post CSRs in order for nodes to get long term certificate credentials
[bootstraptoken] Configured RBAC rules to allow the csrapprover controller automatically approve CSRs from a Node Bootstrap Token
[bootstraptoken] Creating the "cluster-info" ConfigMap in the "kube-public" namespace
[addons] Applied essential addon: CoreDNS
[addons] Applied essential addon: kube-proxy
Your Kubernetes master has initialized successfully!
To start using your cluster, you need to run (as a regular user):
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
You should now deploy a pod network to the cluster.
Run "kubectl apply -f [podnetwork].yaml" with one of the addon options listed at:
http://kubernetes.io/docs/admin/addons/
You can now join any number of machines by running the following on each node
as root:
kubeadm join --token <token> <master-ip>:<master-port> --discovery-token-ca-cert-hash sha256:<hash>
root ではないユーザでも kubectl を動作するには、以下のコマンドを実行します。こちらは kubeadm init
の出力結果にも表示されます。
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
Alternatively, if you are the `root` user, you can run:
あるいは、 root
ユーザの場合は次のように実行できます。
export KUBECONFIG=/etc/kubernetes/admin.conf
kubeadm init
で出力される kubeadm join
コマンドを記録します。ノードをクラスタに参加 するために必要です。
トークンはマスタと参加ノード間が相互認証のために使います。トークンにはシークレットも含みます。このトークンがあれば、誰でもクラスタに認証されたノードとしてつかが可能となります。そのため、トークンは安全な場所に保管してください。トークンの一覧表示、作成、削除は kubeadm token
コマンドで行います。詳しい情報は リファレンス・ガイド をご覧ください。
ポッド・ネットワーク・アドオンのインストール
注意: インストールと展開に関する重要な情報がこのセクションにあります。作業前に注意してお読みください。
ポットがお互いに通信できるようにするためには ポッド・ネットワーク・アドオンのインストールが必須です。
アプリケーションより先に、ネットワークの展開が必要です。また、ネットワークのインストール前に CoreDNS をセットアップできません。kubeadm がサポートしているのは、コンテナ・ネットワーク・インターフェース(CNI)をベースとしたネットワークのみです(そして、kubenet はサポートしません)。
いくつかのプロジェクトでは Kubernetes ポッド・ネットワークに CNI が使われたものを提供しますが、またいくつかは ネットワーク・ポリシー もサポートします。アドオン・ページ をご覧いただくと、利用可能なネットワーク・アドオンの完全な一覧をご覧いただけます。IPv6 サポートは CNI v0.6.0 で追加されました。 CNI bridge と local-ipam がサポートされているのは、1.9 における IPv6 ネットワーク・プラグインです。
kubeadm はより安全なクラスタをセットアップするため、標準で RBAC の利用を強制します。ネットワーク・マニフェストでは、 RBAC のサポートを選択しているかどうかを確認してください。
ポッド・ネットワークのアドオンは、以下のコマンドでインストールできます:
kubectl apply -f <add-on.yaml>
クラスタごとに1つのポッド・ネットワークをインストールできます。
ポッドのインストール
対象となるサードパーティ製ポッド・ネットワークのインストール手順を見るには、タブをクリックします。
Calico
Calico の詳細は、 Quickstart for Calico on Kubernetes、 Installing Calico for policy and networking、そして関連リソースをご覧ください。
ネットワーク・ポリシーを正常に動かすためには、kubeadm init
で --pod-network-cidr=192.168.0.0/16
を 指定する必要があります。Calico が動作するのは amd64
のみです。
kubectl apply -f https://docs.projectcalico.org/v3.1/getting-started/kubernetes/installation/hosted/rbac-kdd.yaml
kubectl apply -f https://docs.projectcalico.org/v3.1/getting-started/kubernetes/installation/hosted/kubernetes-datastore/calico-networking/1.7/calico.yaml
Canal
Canal はポリシーのために Calico を、ネットワーク機能のために Flannel を使います。Calico ドキュメントを参照するには、 official getting started guide をご覧ください。
Canal を正常に動かすためには、kubeadm init
で --pod-network-cidr=10.244.0.0/16
を指定する必要があります。Canal が動作するのは amd64
のみです。
kubectl apply -f https://docs.projectcalico.org/v3.1/getting-started/kubernetes/installation/hosted/canal/rbac.yaml
kubectl apply -f https://docs.projectcalico.org/v3.1/getting-started/kubernetes/installation/hosted/canal/canal.yaml
Flannel
flannel
を正常に動かすためには kubeadm init
で --pod-network-cidr=10.244.0.0/16
を指定する必要があります。flannel
が動作するのは amd64
、 arm
、 arm64
、ppc64le
ですが、amd64
以外のプラットフォームで動作する場合は、マニフェストを手動でダウンロードし、 amd64
の部分を適切なプラットフォームに書き換える必要があります。
実行時に /proc/sys/net/bridge/bridge-nf-call-iptables
を 1
にセットすると、 sysctl net.bridge.bridge-nf-call-iptables=1
によって IPv4 トラフィックを iptables のチェーンにブリッジします。これはいくつかの CNI プラグインを実行するために必要であり、より詳しい情報は こちら をご覧ください。
kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/v0.10.0/Documentation/kube-flannel.yml
flannel
に関するより詳しい情報は、こちら をご覧ください。
Kube-router
実行時に /proc/sys/net/bridge/bridge-nf-call-iptables
を 1
にセットすると、 sysctl net.bridge.bridge-nf-call-iptables=1
によって IPv4 トラフィックを iptables のチェーンにブリッジします。これはいくつかの CNI プラグインを実行するために必要であり、より詳しい情報は こちら をご覧ください。
Kube-router がノードに対してポッド CIDR を割り当てるには、 kube-controller-manager に依存します。そのため、 kubeadm init
で --pod-network-cidr
フラグの指定が必要です。
Kube-router が提供するのはポッド・ネットワーク機能、ネットワーク・ポリシー、サービス・プロキシをベースと下高性能 IP 仮想サーバ(IPVS)/Linux 仮想サーバ(LVS)です。
kubeadm で kube-router に対応した Kubernetes クラスタをセットアップするための詳細については、公式の セットアップ・ガイド をご覧ください。
Romana
実行時に /proc/sys/net/bridge/bridge-nf-call-iptables
を 1
にセットすると、 sysctl net.bridge.bridge-nf-call-iptables=1
によって IPv4 トラフィックを iptables のチェーンにブリッジします。これはいくつかの CNI プラグインを実行するために必要であり、より詳しい情報は こちら をご覧ください。
公式の Romana セットアップ・ガイドは こちら です。
Romana が動作するのは amd64
のみです
kubectl apply -f https://raw.githubusercontent.com/romana/romana/master/containerize/specs/romana-kubeadm.yml
Weave Net
実行時に /proc/sys/net/bridge/bridge-nf-call-iptables
を 1
にセットすると、 sysctl net.bridge.bridge-nf-call-iptables=1
によって IPv4 トラフィックを iptables のチェーンにブリッジします。これはいくつかの CNI プラグインを実行するために必要であり、より詳しい情報は こちら をご覧ください。
公式の Weave Net セットアップ・ガイドは こちら です。
Weave Net は追加設定を必要とせず amd64
、 arm
、 arm64
、 ppc64le
で動作します。Weave Net はデフォルトではヘアピン・モード(hairpin mode)です。これにより、Pod は PodIP を知らなくても自身のサービス IP アドレスを経由してアクセスできます。
kubectl apply -f "https://cloud.weave.works/k8s/net?k8s-version=$(kubectl version | base64 | tr -d '\n')"
ポッド・ネットワークのインストール後、CoreDNS ポッドが正常に動作しているかどうかの確認は、 kubectl get pods --all-namespaces
で行えます。CoreDNS ポッドが起動・実行中になれば、続けてノードを追加可能になります。
ネットワークが稼働していないか CoreDNS が実行中の状態でなければ、 トラブルシューティング・ドキュメントをご覧ください。
マスタの分離(isolation)
デフォルトでは、安全上の理由により、クラスタはマスタ上にポッドをスケジュールしません。もしもマスタ上にポッドをスケジュールできるようにしたい場合、例えば、1台のマシンで 開発用 Kubernetes クラスタを動作させたい場合は、次のように実行します:
kubectl taint nodes --all node-role.kubernetes.io/master-
実行結果は次のようになります。
node "test-01" untainted
taint key="dedicated" and effect="" not found.
taint key="dedicated" and effect="" not found.
これはマスタ・ノードを含むあらゆるノードから node-role.kubernetes.io/master
テイントを削除するもので、これにより、スケジューラはポッドをどこでもスケジュール可能にします。
ノードの追加
ノードとはワークロード(コンテナ、ポッド等)を実行する場所です。クラスタの各マシンで新しいノードを追加するには、次のようにします:
- マシンに SSH
- root になる (例:
sudo su -
) -
kubeadm init
の出力結果のコマンドを実行。実行例:
kubeadm join --token <token> <master-ip>:<master-port> --discovery-token-ca-cert-hash sha256:<hash>
メモ: IPv6 タプルを <master-ip>:<master-port>
で指定するには、 [fd00::101]:2073
のように IPv6 アドレスを角括弧で囲む必要があります。
出力結果は次のようなものです。
[preflight] Running pre-flight checks
... (log output of join workflow) ...
Node join complete:
* Certificate signing request sent to master and response
received.
* Kubelet informed of new secure connection details.
Run 'kubectl get nodes' on the master to see this machine join.
数秒の後、マスタ上で kubectl get nodes
を実行すると、出力結果から対象ノードを確認できるでしょう。
(オプション) マスタ以外のマシンからクラスタを制御
kubectl で他のコンピュータ(例: ノートPC)からクラスタと通信可能にするには、以下のように、管理用 kubeconfig ファイルをマスタから対象マシンに対してコピーする必要があります。
scp root@<master ip>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf get nodes
メモ: この例は root での SSH 接続が可能な場合です。そうでない場合は、 root に代りadmin.conf
を接続可能な他のユーザでコピーと scp
を用います。
admin.conf
ファイルはユーザに対し、クラスタを超えて スーパーユーザ 特権をあたえます。このファイルは慎重に扱うべきです。通常のユーザでは、ホワイトリスト権限をあたえたユニークな認証情報(クレデンシャル)生成を推奨します。そのためには kubeadm alpha phase kubeconfig user --client-name <CN>
コマンドを実行します。このコマンドによって KubeConfig ファイルの情報を標準出力し、出力結果をファイルに保存し、ユーザに与えられます。以降、ホワイトリスト権限は kubectl create (cluster)rolebinding
を用います。
(オプション) API サーバをローカルホストにプロキシ
クラスタ外から API サーバにアクセスしたい場合は、kubectl proxy
が使えます。
scp root@<master ip>:/etc/kubernetes/admin.conf .
kubectl --kubeconfig ./admin.conf proxy
これでローカルから API サーバには http://localhost:8001/api/v1
でアクセスできます。
ティア・ダウン(Tear down)
kubeadm で行ったことを取り消したい場合、まず ノードをドレーン(排出;drain) し、ノードを停止する前にノードが空なのを確認します。
マスタと適切な認証情報で通信し、実行します。
kubectl drain <node name> --delete-local-data --force --ignore-daemonsets
kubectl delete node <node name>
それから、削除するノード上で、kubeadm がインストールした状態をリセットします:
kubeadm reset
もしもやり直したい場合は、単純に kubeadm init
や kubeadm join
に適切な引数を付けるだけです。
詳しいオプションや追加情報については
kubeadm reset コマンド
をご覧ください。
クラスタの維持
kubeadm クラスタを維持(メンテナンス)する手順(例:アップグレード、ダウングレード、等)は、こちら にあります。
他のアドオンを探す
アドオンの一覧 ご覧いただくと、ログ記録、モニタリング、ネットワーク・ポリシー、可視化、Kubernetes クラスタの管理する他のアドオンを探せます。
次は何をしますか
- Sonobuoy でクラスタが正しく稼働しているか確認
- kubeadm 参照ドキュメント で kubeadm の高度な使い方を学ぶ
- Kubernetes 概念 and
kubectl
について更に学ぶ -
logrotate でログ・ローテーション(入れ替え)を設定する。Docker の利用時は、Docker デーモンのオプションでログ・ローテーションを指定できます。例
--log-driver=json-file --log-opt=max-size=10m --log-opt=max-file=5
。詳細は Configure and troubleshoot the Docker daemon をご覧ください。
フィードバック
- バグについては、kubeadm Github issue tracker をご覧ください。
- サポートについては、kubeadm Slack Channel をご覧ください:
#kubeadm - General SIG Cluster Lifecycle Development Slack Channel:
#sig-cluster-lifecycle - SIG Cluster Lifecycle SIG information
- SIG Cluster Lifecycle Mailing List:
kubernetes-sig-cluster-lifecycle
バージョンの差違に対するポリシー
kubeadm CLI ツールのバージョン vX.Y は、コントロール・プレーンのバージョン vX.Y または vX.(Y-1) でも展開可能な場合があります。また、kubeadm CLI vX.Y は、既存の kubeadm バージョン vX.(Y-1)で作成した場合はアップロードできます。
将来的に期限切れで利用できなくなる kubeadm CLI vX.Y は、 vX.(Y+1) クラスタに展開できない場合があります。
例: kubeadm v1.8 は v1.7 と v1.8 クラスタの両方にデプロイでき、v1.7 kubeadm で作成したクラスタは v1.8 にアップグレードできる。
また、kubeletes と コントロール・プレーン間のバージョンずれに関しては インストール・ガイド をご確認ください。
複数のプラットフォームで動作する kubeadm
kubeadm の deb/rpm パッケージとバイナリを構築している対象は、amd64、 arm (32-bit)、 arm64、 ppc64le、s390x、そして以下の マルチプラットフォーム提案 です。
ネットワーク・プロバイダによっては各プラットフォームに対応した解決策を提供している場合があります。先ほどのネットワーク・プロバイダと相談するか、選択したプラットフォームがサポートしているプロバイダが指示するドキュメントをご覧ください。
制限事項
ご注意ください: kubeadm の開発は進行中であり、用途によっては制限が加わる場合もあります。
-
ここで作成したクラスタはマスタが1つだけで、1つの etcd データベースを動かしています。つまり、もしもマスタで障害が起こればデータを失うかもしれませんし、場合によってはゼロから環境再構築の必要が出てくるかもしれません。HA サポート(複数の ecd サーバ、複数の API サーバ等)の追加により、kubeadm は動作し続けるようになります。
回避方法: 通常は etcd をバックアップ 。マスタ上の kubeadm が設定する etcd データ・ディレクトリは
/var/lib/etcd
です。
トラブルシューティング
kubeadm の挙動で問題があれば、 トラブルシューティング・ドキュメント をご覧ください。