kubeadm でマスタ１台のクラスタを構築（参考訳：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 のリリースは通常９ヶ月間サポートされており、何らかのバグやセキュリティ問題が発見されれば、リリース・ブランチから分岐して、定期的にパッチを提供します。以下は 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 を実行可能な１つまたは複数のマシン。例： 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 参照ガイドをご覧ください。

設定オプションの完全な一覧は、設定ファイル資料をご覧ください。

コントロール・プレーンに対してカスタマイズをする場合、たとえばオプションの 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>

クラスタごとに１つのポッド・ネットワークをインストールできます。

ポッドのインストール

対象となるサードパーティ製ポッド・ネットワークのインストール手順を見るには、タブをクリックします。

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

Kube-router がノードに対してポッド CIDR を割り当てるには、 kube-controller-manager に依存します。そのため、 kubeadm init で --pod-network-cidr フラグの指定が必要です。

Kube-router が提供するのはポッド・ネットワーク機能、ネットワーク・ポリシー、サービス・プロキシをベースと下高性能 IP 仮想サーバ（IPVS）/Linux 仮想サーバ(LVS)です。

kubeadm で kube-router に対応した Kubernetes クラスタをセットアップするための詳細については、公式のセットアップ・ガイドをご覧ください。

Romana

公式の Romana セットアップ・ガイドはこちらです。

Romana が動作するのは amd64 のみです

kubectl apply -f https://raw.githubusercontent.com/romana/romana/master/containerize/specs/romana-kubeadm.yml

Weave Net

公式の 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）

デフォルトでは、安全上の理由により、クラスタはマスタ上にポッドをスケジュールしません。もしもマスタ上にポッドをスケジュールできるようにしたい場合、例えば、１台のマシンで開発用 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 の開発は進行中であり、用途によっては制限が加わる場合もあります。

ここで作成したクラスタはマスタが１つだけで、１つの etcd データベースを動かしています。つまり、もしもマスタで障害が起こればデータを失うかもしれませんし、場合によってはゼロから環境再構築の必要が出てくるかもしれません。HA サポート（複数の ecd サーバ、複数の API サーバ等）の追加により、kubeadm は動作し続けるようになります。

回避方法: 通常は etcd をバックアップ。マスタ上の kubeadm が設定する etcd データ・ディレクトリは /var/lib/etcd です。

トラブルシューティング

kubeadm の挙動で問題があれば、トラブルシューティング・ドキュメントをご覧ください。