kubeadmによる証明書管理

FEATURE STATE: Kubernetes v1.15 [stable]

kubeadmで生成されたクライアント証明書は1年で失効します。 このページでは、kubeadmで証明書の更新を管理する方法について説明します。

始める前に

KubernetesにおけるPKI証明書と要件を熟知している必要があります。

カスタム証明書の使用

デフォルトでは、kubeadmはクラスターの実行に必要なすべての証明書を生成します。 独自の証明書を提供することで、この動作をオーバーライドできます。

そのためには、--cert-dirフラグまたはkubeadmのClusterConfigurationのcertificatesDirフィールドで指定された任意のディレクトリに配置する必要があります。 デフォルトは/etc/kubernetes/pkiです。

kubeadm init を実行する前に与えられた証明書と秘密鍵のペアが存在する場合、kubeadmはそれらを上書きしません。 つまり、例えば既存のCAを/etc/kubernetes/pki/ca.crtと/etc/kubernetes/pki/ca.keyにコピーすれば、kubeadmは残りの証明書に署名する際、このCAを使用できます。

外部CAモード

また、ca.crtファイルのみを提供し、ca.keyファイルを提供しないことも可能です(これはルートCAファイルのみに有効で、他の証明書ペアには有効ではありません)。 他の証明書とkubeconfigファイルがすべて揃っている場合、kubeadmはこの状態を認識し、外部CAモードを有効にします。 kubeadmはディスク上のCAキーがなくても処理を進めます。

代わりに、Controller-managerをスタンドアロンで、--controllers=csrsignerと実行し、CA証明書と鍵を指し示します。

PKI certificates and requirementsには、外部CAを使用するためのクラスターのセットアップに関するガイダンスが含まれています。

証明書の有効期限の確認

check-expirationサブコマンドを使うと、証明書の有効期限を確認することができます。

kubeadm certs check-expiration

このような出力になります:

CERTIFICATE                EXPIRES                  RESIDUAL TIME   CERTIFICATE AUTHORITY   EXTERNALLY MANAGED
admin.conf                 Dec 30, 2020 23:36 UTC   364d                                    no
apiserver                  Dec 30, 2020 23:36 UTC   364d            ca                      no
apiserver-etcd-client      Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
apiserver-kubelet-client   Dec 30, 2020 23:36 UTC   364d            ca                      no
controller-manager.conf    Dec 30, 2020 23:36 UTC   364d                                    no
etcd-healthcheck-client    Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
etcd-peer                  Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
etcd-server                Dec 30, 2020 23:36 UTC   364d            etcd-ca                 no
front-proxy-client         Dec 30, 2020 23:36 UTC   364d            front-proxy-ca          no
scheduler.conf             Dec 30, 2020 23:36 UTC   364d                                    no

CERTIFICATE AUTHORITY   EXPIRES                  RESIDUAL TIME   EXTERNALLY MANAGED
ca                      Dec 28, 2029 23:36 UTC   9y              no
etcd-ca                 Dec 28, 2029 23:36 UTC   9y              no
front-proxy-ca          Dec 28, 2029 23:36 UTC   9y              no

このコマンドは、/etc/kubernetes/pkiフォルダ内のクライアント証明書と、kubeadmが使用するKUBECONFIGファイル(admin.conf,controller-manager.conf,scheduler.conf)に埋め込まれたクライアント証明書の有効期限/残余時間を表示します。

また、証明書が外部管理されている場合、kubeadmはユーザーに通知します。この場合、ユーザーは証明書の更新を手動または他のツールを使用して管理する必要があります。

証明書の自動更新

kubeadmはコントロールプレーンのアップグレード時にすべての証明書を更新します。

この機能は、最もシンプルなユースケースに対応するために設計されています。 証明書の更新に特別な要件がなく、Kubernetesのバージョンアップを定期的に行う場合(各アップグレードの間隔が1年未満)、kubeadmがクラスターを最新かつ適度に安全に保つための処理を行います。

証明書の更新に関してより複雑な要求がある場合は、--certificate-renewal=falseをkubeadm upgrade applyやkubeadm upgrade nodeに渡して、デフォルトの動作から外れるようにすることができます。

手動による証明書更新

kubeadm certs renew コマンドを使えば、いつでも証明書を手動で更新することができます。

このコマンドは/etc/kubernetes/pkiに格納されているCA(またはfront-proxy-CA)の証明書と鍵を使って更新を行います。

コマンド実行後、コントロールプレーンのPodを再起動する必要があります。 これは、現在すべてのコンポーネントと証明書について動的な証明書のリロードがサポートされていないため、必要な作業です。 スタティックPodはローカルkubeletによって管理され、API Serverによって管理されないため、kubectlで削除および再起動することはできません。

スタティックPodを再起動するには、一時的に/etc/kubernetes/manifests/からマニフェストファイルを削除して20秒間待ちます(KubeletConfiguration structのfileCheckFrequency値を参照してください)。 マニフェストディレクトリにPodが無くなると、kubeletはPodを終了します。 その後ファイルを戻して、さらにfileCheckFrequency期間後に、kubeletはPodを再作成し、コンポーネントの証明書更新を完了することができます。

kubeadm certs renew は以下のオプションを提供します:

Kubernetesの証明書は通常1年後に有効期限を迎えます。

  • --csr-onlyを使用すると、証明書署名要求を生成して外部CAとの証明書を更新することができます(実際にはその場で証明書を更新しません)。詳しくは次の段落を参照してください。

  • また、すべての証明書を更新するのではなく、1つの証明書を更新することも可能です。

Kubernetes certificates APIによる証明書の更新

ここでは、Kubernetes certificates APIを使用して手動で証明書更新を実行する方法について詳しく説明します。

署名者の設定

Kubernetesの認証局は、そのままでは機能しません。 cert-managerなどの外部署名者を設定するか、組み込みの署名者を使用することができます。

ビルトインサイナーはkube-controller-managerに含まれるものです。

ビルトインサイナーを有効にするには、--cluster-signing-cert-fileと--cluster-signing-key-fileフラグを渡す必要があります。

新しいクラスターを作成する場合は、kubeadm設定ファイルを使用します。

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
controllerManager:
  extraArgs:
    cluster-signing-cert-file: /etc/kubernetes/pki/ca.crt
    cluster-signing-key-file: /etc/kubernetes/pki/ca.key

証明書署名要求の作成 (CSR)

Kubernetes APIでのCSR作成については、Create CertificateSigningRequestを参照ください。

外部CAによる証明書の更新

ここでは、外部認証局を利用して手動で証明書更新を行う方法について詳しく説明します。

外部CAとの連携を強化するために、kubeadmは証明書署名要求(CSR)を生成することもできます。 CSRとは、クライアント用の署名付き証明書をCAに要求することを表します。 kubeadmの用語では、通常ディスク上のCAによって署名される証明書をCSRとして生成することができます。しかし、CAはCSRとして生成することはできません。

証明書署名要求の作成 (CSR)

kubeadm certs renew --csr-onlyで証明書署名要求を作成することができます。

CSRとそれに付随する秘密鍵の両方が出力されます。 ディレクトリを--csr-dirで渡すと、指定した場所にCSRを出力することができます。 csr-dirを指定しない場合は、デフォルトの証明書ディレクトリ(/etc/kubernetes/pki)が使用されます。

証明書はkubeadm certs renew --csr-onlyで更新することができます。 kubeadm initと同様に、--csr-dirフラグで出力先ディレクトリを指定することができます。

CSRには、証明書の名前、ドメイン、IPが含まれますが、用途は指定されません。 証明書を発行する際に、正しい証明書の使用法を指定するのはCAの責任です。

お好みの方法で証明書に署名した後、証明書と秘密鍵をPKIディレクトリ(デフォルトでは/etc/kubernetes/pki)にコピーする必要があります。

認証局(CA)のローテーション

Kubeadmは、CA証明書のローテーションや交換を最初からサポートしているわけではありません。

CAの手動ローテーションや交換についての詳細は、manual rotation of CA certificatesを参照してください。

署名付きkubeletサービング証明書の有効化

デフォルトでは、kubeadmによって展開されるkubeletサービング証明書は自己署名されています。 これは、metrics-serverのような外部サービスからキューブレットへの接続がTLSで保護されないことを意味します。 新しいkubeadmクラスター内のkubeletが適切に署名されたサービング証明書を取得するように設定するには、kubeadm initに以下の最小限の設定を渡す必要があります。

apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
---
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
serverTLSBootstrap: true

すでにクラスターを作成している場合は、以下の手順で適応させる必要があります。

  • kube-systemネームスペースにあるkubelet-config-1.25` ConfigMapを見つけて編集します。

そのConfigMapのkubeletキーの値としてKubeletConfigurationドキュメントを指定します。KubeletConfigurationドキュメントを編集し、serverTLSBootstrap: trueを設定します。

  • 各ノードで、/var/lib/kubelet/config.yamlにserverTLSBootstrap: trueフィールドを追加し、systemctl restart kubeletでkubeletを再起動します。

serverTLSBootstrap: trueフィールドは、kubeleサービングのブートストラップを有効にします。 証明書をcertificates.k8s.ioAPIにリクエストすることで、証明書を発行することができます。

既知の制限事項として、これらの証明書のCSR(Certificate Signing Requests)はkube-controller-managerのデフォルトサイナーによって自動的に承認されないことがあります。 kubernetes.io/kubelet-serving を参照してください。

これには、ユーザーまたはサードパーティーのコントローラーからのアクションが必要です。

これらのCSRは、以下を使用して表示できます:

kubectl get csr
NAME        AGE     SIGNERNAME                        REQUESTOR                      CONDITION
csr-9wvgt   112s    kubernetes.io/kubelet-serving     system:node:worker-1           Pending
csr-lz97v   1m58s   kubernetes.io/kubelet-serving     system:node:control-plane-1    Pending

承認するためには、次のようにします:

kubectl certificate approve <CSR-name>

デフォルトでは、これらのサービング証明書は1年後に失効します。

KubeadmはKubeletConfigurationフィールドrotateCertificatesをtrueに設定します。これは有効期限が切れる間際に、サービング証明書のための新しいCSRセットを作成し、ローテーションを完了するために承認する必要があることを意味します。

詳しくはCertificate Rotationをご覧ください。

これらのCSRを自動的に承認するためのソリューションをお探しの場合は、以下をお勧めします。 クラウドプロバイダーに連絡し、ノードの識別をアウトオブバンドのメカニズムで行うCSRの署名者がいるかどうか尋ねてください。

サードパーティーのカスタムコントローラーを使用することができます。

このようなコントローラーは、CSRのCommonNameを検証するだけでなく、要求されたIPやドメイン名も検証しなければ、安全なメカニズムとは言えません。これにより、kubeletクライアント証明書にアクセスできる悪意のあるアクターが、任意のIPやドメイン名に対してサービング証明書を要求するCSRを作成することを防ぐことができます。

このページの項目は、Kubernetesが必要とする機能を提供するサードパーティー製品またはプロジェクトです。Kubernetesプロジェクトの作者は、それらのサードパーティー製品またはプロジェクトに責任を負いません。詳しくは、CNCFウェブサイトのガイドラインをご覧ください。第三者のリンクを追加するような変更を提案する前に、コンテンツガイドを読むべきです。

最終更新 May 06, 2022 at 12:41 AM PST: [ja] replace Go Doc URL with pkg.go.dev (8862f113e3)