これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.

このページの通常のビューに戻る.

リファレンス

本セクションには、Kubernetesのドキュメントのリファレンスが含まれています。

APIリファレンス

APIクライアントライブラリー

プログラミング言語からKubernetesのAPIを呼ぶためには、クライアントライブラリーを使うことができます。公式にサポートしているクライアントライブラリー:

CLIリファレンス

  • kubectl - コマンドの実行やKubernetesクラスターの管理に使う主要なCLIツールです。
  • kubeadm - セキュアなKubernetesクラスターを簡単にプロビジョニングするためのCLIツールです。

コンポーネントリファレンス

  • kubelet - 各ノード上で動作する最も重要なノードエージェントです。kubeletは一通りのPodSpecを受け取り、コンテナーが実行中で正常であることを確認します。
  • kube-apiserver - Pod、Service、Replication Controller等、APIオブジェクトのデータを検証・設定するREST APIサーバーです。
  • kube-controller-manager - Kubernetesに同梱された、コアのコントロールループを埋め込むデーモンです。
  • kube-proxy - 単純なTCP/UDPストリームのフォワーディングや、一連のバックエンド間でTCP/UDPのラウンドロビンでのフォワーディングを実行できます。
  • kube-scheduler - 可用性、パフォーマンス、およびキャパシティを管理するスケジューラーです。

設計のドキュメント

Kubernetesの機能に関する設計ドキュメントのアーカイブです。KubernetesアーキテクチャKubernetesデザイン概要から読み始めると良いでしょう。

1 - 標準化用語集

2 - API概要

このセクションでは、Kubernetes APIのリファレンス情報を提供します。

REST APIはKubernetesの基本的な構造です。 すべての操作とコンポーネント間のと通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。

その結果、Kubernetesプラットフォーム内のすべてのものは、APIオブジェクトとして扱われ、APIに対応するエントリーがあります。

Kubernetes APIリファレンスは、Kubernetesバージョンv1.25のAPI一覧を提供します。

一般的な背景情報を知るには、The Kubernetes APIControlling Access to the Kubernetes APIを読んでください。 それらはKubernetes APIサーバーがクライアントを認証する方法とリクエストを認可する方法を説明します。

APIバージョニング

JSONとProtobufなどのシリアル化スキーマの変更については同じガイドラインに従います。 以下の説明は、両方のフォーマットをカバーしています。

APIのバージョニングとソフトウェアのバージョニングは間接的に関係しています。 API and release versioning proposalは、APIバージョニングとソフトウェアバージョニングの関係を説明しています。

APIのバージョンが異なると、安定性やサポートのレベルも異なります。 各レベルの基準については、API Changes documentationで詳しく説明しています。

各レベルの概要は以下の通りです:

  • Alpha:

    • バージョン名に「alpha」が含まれています(例:「v1alpha1」)。
    • バグが含まれている可能性があります。 機能を有効にするとバグが露呈する可能性があります。 機能がデフォルトで無効になっている可能性があります。
    • ある機能のサポートは、予告なしにいつでも中止される可能性があります。
    • 後にリリースされるソフトウェアで、互換性のない方法で予告なく変更される可能性があります。
    • バグのリスクが高く、長期的なサポートが得られないため、短期間のテストクラスターのみでの使用を推奨します。
  • Beta:

    • バージョン名には beta が含まれています(例:v2beta3)。

    • ソフトウェアは十分にテストされています。 機能を有効にすることは安全であると考えられています。 機能はデフォルトで有効になっています。

    • 機能のサポートが打ち切られることはありませんが、詳細は変更される可能性があります。

    • オブジェクトのスキーマやセマンティクスは、その後のベータ版や安定版のリリースで互換性のない方法で変更される可能性があります。 このような場合には、移行手順が提供されます。 スキーマの変更に伴い、APIオブジェクトの削除、編集、再作成が必要になる場合があります。 編集作業は単純ではないかもしれません。 移行に伴い、その機能に依存しているアプリケーションのダウンタイムが必要になる場合があります。

    • 本番環境での使用は推奨しません。 後続のリリース は、互換性のない変更を導入する可能性があります。 独立してアップグレード可能な複数のクラスターがある場合、この制限を緩和できる可能性があります。

  • Stable:

    • バージョン名は vX であり、X は整数である。
    • 安定版の機能は、リリースされたソフトウェアの中で、その後の多くのバージョンに登場します。

APIグループ

API groupsで、KubernetesのAPIを簡単に拡張することができます。 APIグループは、RESTパスとシリアル化されたオブジェクトのapiVersionフィールドで指定されます。

KubernetesにはいくつかのAPIグループがあります:

  • core(legacyとも呼ばれる)グループは、RESTパス /api/v1 にあります。 コアグループは apiVersion フィールドの一部としては指定されません。 例えば、apiVersion: v1 のように。
  • 名前付きのグループは、RESTパス /apis/$GROUP_NAME/$VERSION にあり、以下のように使用します。 apiVersion: $GROUP_NAME/$VERSIONを使用します(例:apiVersion: batch/v1)。 サポートされているAPIグループの完全なリストは以下にあります。 Kubernetes API reference

APIグループの有効化と無効化

一部のリソースやAPIグループはデフォルトで有効になっています。 APIサーバー上で--runtime-configを設定することで、有効にしたり無効にしたりすることができます。 またruntime-configフラグには、APIサーバーのランタイム構成を記述したコンマ区切りの<key>[=<value>]ペアを指定します。 もし=<value>の部分が省略された場合には、=trueが指定されたものとして扱われます。

例えば:

  • batch/v1を無効するには、--runtime-config=batch/v1=falseを設定する
  • batch/v2alpha1を有効するには、--runtime-config=batch/v2alpha1を設定する

永続化

Kubernetesはシリアライズされた状態を、APIリソースとしてetcdに書き込んで保存します。

次の項目

3 - 認証

このページでは、認証の概要について説明します。

Kubernetesにおけるユーザー

すべてのKubernetesクラスターには、2種類のユーザーがあります。Kubernetesによって管理されるサービスアカウントと、通常のユーザーです。

クラスターから独立したサービスは通常のユーザーを以下の方法で管理することを想定されています。

  • 秘密鍵を配布する管理者
  • KeystoneやGoogle Accountsのようなユーザーストア
  • ユーザー名とパスワードのリストを持つファイル

これを考慮すると、 Kubernetesは通常のユーザーアカウントを表すオブジェクトを持ちません。 APIコールを介して、通常のユーザーをクラスターに追加することはできません。

APIコールを介して通常のユーザーを追加できませんが、クラスターの認証局(CA)に署名された有効な証明書で表すユーザーは認証済みと判断されます。この構成では、Kubernetesは証明書の‘subject’内にある一般的な名前フィールド(例えば、“/CN=bob”)からユーザー名を特定します。そこから、ロールベースアクセス制御(RBAC)サブシステムは、ユーザーがあるリソースにおける特定の操作を実行するために認証済みかどうか特定します。詳細は、 証明書要求内の通常のユーザーの題目を参照してください。

対照的に、サービスアカウントはKubernetes APIによって管理されるユーザーです。サービスアカウントは特定の名前空間にバインドされており、APIサーバーによって自動的に作成されるか、APIコールによって手動で作成されます。サービスアカウントは、Secretsとして保存された資格情報の集合に紐付けられています。これをPodにマウントすることで、クラスター内のプロセスがKubernetes APIと通信できるようにします。

APIリクエストは、通常のユーザーかサービスアカウントに紐付けられているか、匿名リクエストとして扱われます。つまり、ワークステーションでkubectlを入力する人間のユーザーから、ノード上のkubeletsやコントロールプレーンのメンバーまで、クラスター内外の全てのプロセスは、APIサーバーへのリクエストを行う際に認証を行うか匿名ユーザーとして扱われる必要があります。

認証戦略

Kubernetesは、クライアント証明書、Bearerトークン、認証プロキシー、HTTP Basic認証を使い、認証プラグインを通してAPIリクエストを認証します。APIサーバーにHTTPリクエストが送信されると、プラグインは以下の属性をリクエストに関連付けようとします。

  • ユーザー名: エンドユーザーを識別する文字列です。一般的にな値は、kube-adminjane@example.comです。
  • UID: エンドユーザーを識別する文字列であり、ユーザー名よりも一貫性と一意性を持たせようとするものです。
  • グループ: 各要素がユーザーの役割を示すような意味を持つ文字列の集合です。system:mastersdevops-teamといった値が一般的です。
  • 追加フィールド: 認証者が有用と思われる追加情報を保持する文字列のリストに対する、文字列のマップです。

すべての値は認証システムに対して非透過であり、認可機能が解釈した場合にのみ意味を持ちます。

一度に複数の認証方法を有効にすることができます。通常は、以下のように少なくとも2つの方法を使用するべきです。

  • サービスアカウント用のサービスアカウントトークン
  • ユーザー認証のための、少なくとも1つの他の方法

複数の認証モジュールが有効化されている場合、リクエストの認証に成功した最初のモジュールが、評価が簡略化します。APIサーバーは、認証の実行順序を保証しません。

system:authenticatedグループには、すべての認証済みユーザーのグループのリストが含まれます。

他の認証プロトコル(LDAP、SAML、Kerberos、X509スキームなど)との統合は、認証プロキシー認証Webhookを使用して実施できます。

X509クライアント証明書

クライアント証明書認証は、APIサーバーに--client-ca-file=SOMEFILEオプションを渡すことで有効になります。参照されるファイルには、APIサーバーに提示されたクライアント証明書を検証するために使用する1つ以上の認証局が含まれている必要があります。クライアント証明書が提示され、検証された場合、サブジェクトのCommon Nameがリクエストのユーザー名として使用されます。Kubernetes1.4時点では、クライアント証明書は、証明書のOrganizationフィールドを使用して、ユーザーのグループメンバーシップを示すこともできます。あるユーザーに対して複数のグループメンバーシップを含めるには、証明書に複数のOrganizationフィールドを含めます。

例えば、証明書署名要求を生成するために、opensslコマンドラインツールを使用します。

openssl req -new -key jbeda.pem -out jbeda-csr.pem -subj "/CN=jbeda/O=app1/O=app2"

これにより、"app1"と"app2"の2つのグループに属するユーザー名"jbeda"の証明書署名要求が作成されます。

クライアント証明書の生成方法については、証明書の管理を参照してください。

静的なトークンファイル

コマンドラインで--token-auth-file=SOMEFILEオプションを指定すると、APIサーバーはファイルからBearerトークンを読み込みます。現在のところ、トークンの有効期限は無く、APIサーバーを再起動しない限りトークンのリストを変更することはできません。

トークンファイルは、トークン、ユーザー名、ユーザーUIDの少なくとも3つの列を持つcsvファイルで、その後にオプションでグループ名が付きます。

リクエストにBearerトークンを含める

HTTPクライアントからBearerトークン認証を利用する場合、APIサーバーはBearer THETOKENという値を持つAuthorizationヘッダーを待ち受けます。Bearerトークンは、HTTPのエンコーディングとクォート機能を利用してHTTPヘッダーの値に入れることができる文字列でなければなりません。例えば、Bearerトークンが31ada4fd-adec-460c-809a-9e56ceb75269であれば、HTTPのヘッダを以下のようにします。

Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269

ブートストラップトークン

FEATURE STATE: Kubernetes v1.18 [stable]

新しいクラスタの効率的なブートストラップを可能にするために、Kubernetesにはブートストラップトークンと呼ばれる動的に管理されたBearerトークンタイプが含まれています。これらのトークンは、kube-system名前空間にSecretsとして格納され、動的に管理したり作成したりすることができます。コントローラーマネージャーには、TokenCleanerコントローラーが含まれており、ブートストラップトークンの有効期限が切れると削除します。

トークンの形式は[a-z0-9]{6}.[a-z0-9]{16}です。最初のコンポーネントはトークンIDであり、第2のコンポーネントはToken Secretです。以下のように、トークンをHTTPヘッダーに指定します。

Authorization: Bearer 781292.db7bc3a58fc5f07e

APIサーバーの--enable-bootstrap-token-authフラグで、Bootstrap Token Authenticatorを有効にする必要があります。TokenCleanerコントローラーを有効にするには、コントローラーマネージャーの--controllersフラグを使います。--controllers=*,tokencleanerのようにして行います。クラスターをブートストラップするためにkubeadmを使用している場合は、kubeadmがこれを代行してくれます。

認証機能はsystem:bootstrap:<Token ID>という名前で認証します。これはsystem:bootstrappersグループに含まれます。名前とグループは意図的に制限されており、ユーザーがブートストラップ後にこれらのトークンを使わないようにしています。ユーザー名とグループは、クラスタのブートストラップをサポートする適切な認可ポリシーを作成するために使用され、kubeadmによって使用されます。

ブートストラップトークンの認証機能やコントローラーについての詳細な説明、kubeadmでこれらのトークンを管理する方法については、ブートストラップトークンを参照してください。

サービスアカウントトークン

サービスアカウントは、自動的に有効化される認証機能で、署名されたBearerトークンを使ってリクエストを検証します。このプラグインは、オプションとして2つのフラグを取ります。

  • --service-account-key-file: Bearerトークンに署名するためのPEMエンコードされた鍵を含むファイルです。指定しない場合は、APIサーバーのTLS秘密鍵が使われます。
  • --service-account-lookup: 有効にすると、APIから削除されたトークンは取り消されます。

サービスアカウントは通常、APIサーバーによって自動的に作成され、ServiceAccountAdmission Controllerを介してクラスター内のPodに関連付けられます。Bearerトークンは、Podのよく知られた場所にマウントされ、これによりクラスター内のプロセスがAPIサーバー通信できるようになります。アカウントはPodSpecserviceAccountNameフィールドを使って、明示的にPodに関連付けることができます。

apiVersion: apps/v1 # このapiVersionは、Kubernetes1.9時点で適切です
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: default
spec:
  replicas: 3
  template:
    metadata:
    # ...
    spec:
      serviceAccountName: bob-the-bot
      containers:
      - name: nginx
        image: nginx:1.14.2

サービスアカウントのBearerトークンは、クラスター外で使用するために完全に有効であり、Kubernetes APIと通信したい長期的なジョブのアイデンティティを作成するために使用することができます。サービスアカウントを手動で作成するには、単にkubectl create serviceaccount (NAME)コマンドを使用します。これにより、現在の名前空間にサービスアカウントと関連するSecretが作成されます。

kubectl create serviceaccount jenkins
serviceaccount "jenkins" created

以下のように、関連するSecretを確認できます。

kubectl get serviceaccounts jenkins -o yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  # ...
secrets:
- name: jenkins-token-1yvwg

作成されたSecretは、APIサーバーのパブリック認証局と署名されたJSON Web Token(JWT)を保持します。

kubectl get secret jenkins-token-1yvwg -o yaml
apiVersion: v1
data:
  ca.crt: (base64でエンコードされたAPIサーバーの認証局)
  namespace: ZGVmYXVsdA==
  token: (base64でエンコードされたBearerトークン)
kind: Secret
metadata:
  # ...
type: kubernetes.io/service-account-token

署名されたJWTは、与えられたサービスアカウントとして認証するためのBearerトークンとして使用できます。トークンをリクエストに含める方法については、リクエストにBearerトークンを含めるを参照してください。通常、これらのSecretはAPIサーバーへのクラスタ内アクセス用にPodにマウントされますが、クラスター外からも使用することができます。

サービスアカウントは、ユーザー名system:serviceaccount:(NAMESPACE):(SERVICEACCOUNT)で認証され、グループsystem:serviceaccountssystem:serviceaccounts:(NAMESPACE)に割り当てられます。

警告: サービスアカウントトークンはSecretに保持されているため、Secretにアクセスできるユーザーは誰でもサービスアカウントとして認証することができます。サービスアカウントに権限を付与したり、Secretの読み取り機能を付与したりする際には注意が必要です。

OpenID Connectトークン

OpenID Connectは、Azure Active Directory、Salesforce、Googleなど、いくつかのOAuth2プロバイダーでサポートされているOAuth2の一種です。 このプロトコルのOAuth2の主な拡張機能は、ID Tokenと呼ばれる、アクセストークンとアクセストークンと一緒に返される追加フィールドです。 このトークンは、ユーザーの電子メールなどのよく知られたフィールドを持つJSON Web Token(JWT)であり、サーバーによって署名されています。トークンをリクエストに含める方法については、リクエストにBearerトークンを含めるを参照してください。

Kubernetes OpenID Connect Flow

  1. IDプロバイダーにログインします
  2. IDプロバイダーは、access_tokenid_tokenrefresh_tokenを提供します
  3. kubectlを使う場合は、--tokenフラグでid_tokenを使うか、kubeconfigに直接追加してください
  4. kubectlは、id_tokenをAuthorizationと呼ばれるヘッダーでAPIサーバーに送ります
  5. APIサーバーは、設定で指定された証明書と照合することで、JWT署名が有効であることを確認します
  6. id_tokenの有効期限が切れていないことを確認します
  7. ユーザーが認可されていることを確認します
  8. 認可されると、APIサーバーはkubectlにレスポンスを返します
  9. kubectlはユーザーにフィードバックを提供します

自分が誰であるかを確認するために必要なデータはすべてid_tokenの中にあるので、KubernetesはIDプロバイダーと通信する必要がありません。すべてのリクエストがステートレスであるモデルでは、これは非常に認証のためのスケーラブルなソリューションを提供します。一方で、以下のようにいくつか課題があります。

  1. Kubernetesには、認証プロセスを起動するための"Webインターフェース"がありません。クレデンシャルを収集するためのブラウザやインターフェースがないため、まずIDプロバイダに認証を行う必要があります。
  2. id_tokenは、取り消すことができません。これは証明書のようなもので、有効期限が短い(数分のみ)必要があるので、数分ごとに新しいトークンを取得しなければならないのは非常に面倒です。
  3. Kubernetesダッシュボードへの認証において、kubectl proxyコマンドやid_tokenを注入するリバースプロキシーを使う以外に、簡単な方法はありません。

APIサーバーの設定

プラグインを有効にするには、APIサーバーで以下のフラグを設定します。

パラメーター説明必須か
--oidc-issuer-urlAPIサーバーが公開署名鍵を発見できるようにするプロバイダーのURLです。 https://スキームを使用するURLのみが受け入れられます。これは通常、"https://accounts.google.com"や"https://login.salesforce.com"のようにパスを持たないプロバイダのディスカバリーURLです。このURLは、.well-known/openid-configurationの下のレベルを指す必要があります。ディスカバリーURLがhttps://accounts.google.com/.well-known/openid-configurationである場合、値はhttps://accounts.google.comとします。はい
--oidc-client-idすべてのトークンが発行されなければならないクライアントIDです。kubernetesはい
--oidc-username-claimユーザー名として使用するJWTのクレームを指定します。デフォルトではsubが使用されますが、これはエンドユーザーの一意の識別子であることが期待されます。管理者はプロバイダーに応じてemailnameなどの他のクレームを選択することができます。ただし、他のプラグインとの名前の衝突を防ぐために、email以外のクレームには、プレフィックスとして発行者のURLが付けられます。subいいえ
--oidc-username-prefix既存の名前(system:ユーザーなど)との衝突を防ぐために、ユーザー名の前にプレフィックスを付加します。例えばoidc:という値は、oidc:jane.doeのようなユーザー名を生成します。このフラグが指定されておらず、--oidc-username-claimemail以外の値である場合、プレフィックスのデフォルトは(Issuer URL)#で、(Issuer URL)--oidc-issuer-urlの値です。すべてのプレフィックスを無効にするためには、-という値を使用できます。oidc:いいえ
--oidc-groups-claimユーザーのグループとして使用するJWTのクレームです。クレームがある場合は、文字列の配列である必要があります。groupsいいえ
--oidc-groups-prefix既存の名前(system:グループなど)との衝突を防ぐために、グループ名の前にプレフィックスを付加します。例えばoidc:という値は、oidc:engineeringoidc:infraのようなグループ名を生成します。oidc:いいえ
--oidc-required-claimIDトークンの中の必須クレームを記述するkey=valueのペアです。設定されている場合、クレームが一致する値でIDトークンに存在することが検証されます。このフラグを繰り返して複数のクレームを指定します。claim=valueいいえ
--oidc-ca-fileIDプロバイダーのWeb証明書に署名した認証局の証明書へのパスです。デフォルトはホストのルート認証局が指定されます。/etc/kubernetes/ssl/kc-ca.pemいいえ

重要なのは、APIサーバーはOAuth2クライアントではなく、ある単一の発行者を信頼するようにしか設定できないことです。これにより、サードパーティーに発行されたクレデンシャルを信頼せずに、Googleのようなパブリックプロバイダーを使用することができます。複数のOAuthクライアントを利用したい管理者は、azpクレームをサポートしているプロバイダや、あるクライアントが別のクライアントに代わってトークンを発行できるような仕組みを検討する必要があります。

KubernetesはOpenID Connect IDプロバイダーを提供していません。既存のパブリックなOpenID Connect IDプロバイダー(Googleやその他など)を使用できます。もしくは、CoreOS dexKeycloak、CloudFoundryUAA、Tremolo SecurityのOpenUnisonなど、独自のIDプロバイダーを実行することもできます。

IDプロバイダーがKubernetesと連携するためには、以下のことが必要です。

  1. すべてではないが、[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)をサポートしていること
  2. 廃れていない暗号を用いたTLSで実行されていること
  3. 認証局が署名した証明書を持っていること(認証局が商用ではない場合や、自己署名の場合も可)

上述の要件#3、認証局署名付き証明書を必要とすることについて、注意事項があります。GoogleやMicrosoftなどのクラウドプロバイダーではなく、独自のIDプロバイダーをデプロイする場合は、たとえ自己署名されていても、CAフラグがTRUEに設定されている証明書によって署名されたIDプロバイダーのWebサーバー証明書を持っていなければなりません。これは、Go言語のTLSクライアント実装が、証明書検証に関する標準に対して非常に厳格であるためです。認証局をお持ちでない場合は、CoreOSチームのこのスクリプトを使用して、シンプルな認証局と署名付きの証明書と鍵のペアを作成することができます。 または、この類似のスクリプトを使って、より寿命が長く、よりキーサイズの大きいSHA256証明書を生成できます。

特定のシステム用のセットアップ手順は、以下を参照してください。

kubectlの使用

選択肢1 - OIDC認証機能

最初の選択肢は、kubectlのoidc認証機能を利用することです。これはすべてのリクエストのBearerトークンとしてid_tokenを設定し、有効期限が切れるとトークンを更新します。プロバイダーにログインした後、kubectlを使ってid_tokenrefresh_tokenclient_idclient_secretを追加してプラグインを設定します。

リフレッシュトークンのレスポンスの一部としてid_tokenを返さないプロバイダーは、このプラグインではサポートされていないので、以下の"選択肢2"を使用してください。

kubectl config set-credentials USER_NAME \
   --auth-provider=oidc \
   --auth-provider-arg=idp-issuer-url=( issuer url ) \
   --auth-provider-arg=client-id=( your client id ) \
   --auth-provider-arg=client-secret=( your client secret ) \
   --auth-provider-arg=refresh-token=( your refresh token ) \
   --auth-provider-arg=idp-certificate-authority=( path to your ca certificate ) \
   --auth-provider-arg=id-token=( your id_token )

例として、IDプロバイダーに認証した後に以下のコマンドを実行します。

kubectl config set-credentials mmosley  \
        --auth-provider=oidc  \
        --auth-provider-arg=idp-issuer-url=https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP  \
        --auth-provider-arg=client-id=kubernetes  \
        --auth-provider-arg=client-secret=1db158f6-177d-4d9c-8a8b-d36869918ec5  \
        --auth-provider-arg=refresh-token=q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXqHega4GAXlF+ma+vmYpFcHe5eZR+slBFpZKtQA= \
        --auth-provider-arg=idp-certificate-authority=/root/ca.pem \
        --auth-provider-arg=id-token=eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw

これは以下のような構成になります。

users:
- name: mmosley
  user:
    auth-provider:
      config:
        client-id: kubernetes
        client-secret: 1db158f6-177d-4d9c-8a8b-d36869918ec5
        id-token: eyJraWQiOiJDTj1vaWRjaWRwLnRyZW1vbG8ubGFuLCBPVT1EZW1vLCBPPVRybWVvbG8gU2VjdXJpdHksIEw9QXJsaW5ndG9uLCBTVD1WaXJnaW5pYSwgQz1VUy1DTj1rdWJlLWNhLTEyMDIxNDc5MjEwMzYwNzMyMTUyIiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJodHRwczovL29pZGNpZHAudHJlbW9sby5sYW46ODQ0My9hdXRoL2lkcC9PaWRjSWRQIiwiYXVkIjoia3ViZXJuZXRlcyIsImV4cCI6MTQ4MzU0OTUxMSwianRpIjoiMm96US15TXdFcHV4WDlHZUhQdy1hZyIsImlhdCI6MTQ4MzU0OTQ1MSwibmJmIjoxNDgzNTQ5MzMxLCJzdWIiOiI0YWViMzdiYS1iNjQ1LTQ4ZmQtYWIzMC0xYTAxZWU0MWUyMTgifQ.w6p4J_6qQ1HzTG9nrEOrubxIMb9K5hzcMPxc9IxPx2K4xO9l-oFiUw93daH3m5pluP6K7eOE6txBuRVfEcpJSwlelsOsW8gb8VJcnzMS9EnZpeA0tW_p-mnkFc3VcfyXuhe5R3G7aa5d8uHv70yJ9Y3-UhjiN9EhpMdfPAoEB9fYKKkJRzF7utTTIPGrSaSU6d2pcpfYKaxIwePzEkT4DfcQthoZdy9ucNvvLoi1DIC-UocFD8HLs8LYKEqSxQvOcvnThbObJ9af71EwmuE21fO5KzMW20KtAeget1gnldOosPtz1G5EwvaQ401-RPQzPGMVBld0_zMCAwZttJ4knw
        idp-certificate-authority: /root/ca.pem
        idp-issuer-url: https://oidcidp.tremolo.lan:8443/auth/idp/OidcIdP
        refresh-token: q1bKLFOyUiosTfawzA93TzZIDzH2TNa2SMm0zEiPKTUwME6BkEo6Sql5yUWVBSWpKUGphaWpxSVAfekBOZbBhaEW+VlFUeVRGcluyVF5JT4+haZmPsluFoFu5XkpXk5BXq
      name: oidc

id_tokenの有効期限が切れると、kubectlrefresh_tokenclient_secretを用いてid_tokenの更新しようとします。refresh_tokenid_tokenの新しい値は、.kube/configに格納されます。

選択肢2 - --tokenオプションの使用

kubectlコマンドでは、--tokenオプションを使ってトークンを渡すことができる。以下のように、このオプションにid_tokenをコピーして貼り付けるだけです。

kubectl --token=eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJodHRwczovL21sYi50cmVtb2xvLmxhbjo4MDQzL2F1dGgvaWRwL29pZGMiLCJhdWQiOiJrdWJlcm5ldGVzIiwiZXhwIjoxNDc0NTk2NjY5LCJqdGkiOiI2RDUzNXoxUEpFNjJOR3QxaWVyYm9RIiwiaWF0IjoxNDc0NTk2MzY5LCJuYmYiOjE0NzQ1OTYyNDksInN1YiI6Im13aW5kdSIsInVzZXJfcm9sZSI6WyJ1c2VycyIsIm5ldy1uYW1lc3BhY2Utdmlld2VyIl0sImVtYWlsIjoibXdpbmR1QG5vbW9yZWplZGkuY29tIn0.f2As579n9VNoaKzoF-dOQGmXkFKf1FMyNV0-va_B63jn-_n9LGSCca_6IVMP8pO-Zb4KvRqGyTP0r3HkHxYy5c81AnIh8ijarruczl-TK_yF5akjSTHFZD-0gRzlevBDiH8Q79NAr-ky0P4iIXS8lY9Vnjch5MF74Zx0c3alKJHJUnnpjIACByfF2SCaYzbWFMUNat-K1PaUk5-ujMBG7yYnr95xD-63n8CO8teGUAAEMx6zRjzfhnhbzX-ajwZLGwGUBT4WqjMs70-6a7_8gZmLZb2az1cZynkFRj2BaCkVT3A2RrjeEwZEtGXlMqKJ1_I2ulrOVsYx01_yD35-rw get nodes

Webhookトークン認証

Webhook認証は、Bearerトークンを検証するためのフックです。

  • --authentication-token-webhook-config-file: リモートのWebhookサービスへのアクセス方法を記述した設定ファイルです
  • --authentication-token-webhook-cache-ttl: 認証をキャッシュする時間を決定します。デフォルトは2分です

設定ファイルは、kubeconfigのファイル形式を使用します。 ファイル内で、clustersはリモートサービスを、usersはAPIサーバーのWebhookを指します。例えば、以下のようになります。

# Kubernetes APIのバージョン
apiVersion: v1
# APIオブジェクトの種類
kind: Config
# clustersは、リモートサービスを指します。
clusters:
  - name: name-of-remote-authn-service
    cluster:
      certificate-authority: /path/to/ca.pem         # リモートサービスを検証するためのCA
      server: https://authn.example.com/authenticate # クエリするリモートサービスのURL。'https'を使用する必要があります。

# usersは、APIサーバーのWebhook設定を指します。
users:
  - name: name-of-api-server
    user:
      client-certificate: /path/to/cert.pem # Webhookプラグインを使うための証明書
      client-key: /path/to/key.pem          # 証明書に合致する鍵

# kubeconfigファイルにはコンテキストが必要です。APIサーバー用のものを用意してください。
current-context: webhook
contexts:
- context:
    cluster: name-of-remote-authn-service
    user: name-of-api-sever
  name: webhook

クライアントが上記のようにBearerトークンを使用してAPIサーバーとの認証を試みた場合、認証Webhookはトークンを含むJSONでシリアライズされたauthentication.k8s.io/v1beta1 TokenReviewオブジェクトをリモートサービスにPOSTします。Kubernetesはそのようなヘッダーが不足しているリクエストを作成しようとはしません。

Webhook APIオブジェクトは、他のKubernetes APIオブジェクトと同じように、Versioning Compatibility Ruleに従うことに注意してください。実装者は、ベータオブジェクトで保証される互換性が緩いことに注意し、正しいデシリアライゼーションが使用されるようにリクエストの"apiVersion"フィールドを確認する必要があります。さらにAPIサーバーは、API拡張グループauthentication.k8s.io/v1beta1を有効にしなければなりません(--runtime config=authentication.k8s.io/v1beta1=true)。

POSTボディは、以下の形式になります。

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "spec": {
    "token": "(Bearerトークン)"
  }
}

リモートサービスはログインの成功を示すために、リクエストのstatusフィールドを埋めることが期待されます。レスポンスボディのspecフィールドは無視され、省略することができます。Bearerトークンの検証に成功すると、以下のようにBearerトークンが返されます。

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": true,
    "user": {
      "username": "janedoe@example.com",
      "uid": "42",
      "groups": [
        "developers",
        "qa"
      ],
      "extra": {
        "extrafield1": [
          "extravalue1",
          "extravalue2"
        ]
      }
    }
  }
}

リクエストに失敗した場合は、以下のように返されます。

{
  "apiVersion": "authentication.k8s.io/v1beta1",
  "kind": "TokenReview",
  "status": {
    "authenticated": false
  }
}

HTTPステータスコードは、追加のエラーコンテキストを提供するために使うことができます。

認証プロキシー

APIサーバーは、X-Remote-Userのようにリクエストヘッダの値からユーザーを識別するように設定することができます。 これは、リクエストヘッダの値を設定する認証プロキシーと組み合わせて使用するために設計です。

  • --requestheader-username-headers: 必須であり、大文字小文字を区別しません。ユーザーのIDをチェックするためのヘッダー名を順番に指定します。値を含む最初のヘッダーが、ユーザー名として使われます。
  • --requestheader-group-headers: バージョン1.6以降で任意であり、大文字小文字を区別しません。"X-Remote-Group"を推奨します。ユーザーのグループをチェックするためのヘッダー名を順番に指定します。指定されたヘッダーの全ての値が、グループ名として使われます。
  • --requestheader-extra-headers-prefix バージョン1.6以降で任意であり、大文字小文字を区別しません。"X-Remote-Extra-"を推奨します。ユーザーに関する追加情報を判断するために検索するヘッダーのプレフィックスです。通常、設定された認可プラグインによって使用されます。指定されたプレフィックスのいずれかで始まるヘッダーは、プレフィックスが削除されます。ヘッダー名の残りの部分は小文字化されパーセントデコーディングされて追加のキーとなり、ヘッダーの値が追加の値となります。

例えば、このような設定を行います。

--requestheader-username-headers=X-Remote-User
--requestheader-group-headers=X-Remote-Group
--requestheader-extra-headers-prefix=X-Remote-Extra-

以下のようなリクエストを考えます。

GET / HTTP/1.1
X-Remote-User: fido
X-Remote-Group: dogs
X-Remote-Group: dachshunds
X-Remote-Extra-Acme.com%2Fproject: some-project
X-Remote-Extra-Scopes: openid
X-Remote-Extra-Scopes: profile

このリクエストは、このユーザー情報を取得します。

name: fido
groups:
- dogs
- dachshunds
extra:
  acme.com/project:
  - some-project
  scopes:
  - openid
  - profile

ヘッダーのスプーフィングを防ぐため、認証プロキシーはリクエストヘッダーがチェックされる前に、指定された認証局に対する検証のために有効なクライアント証明書をAPIサーバーへ提示する必要があります。

  • --requestheader-client-ca-file: 必須です。PEMエンコードされた証明書バンドルです。有効なクライアント証明書を提示し、リクエストヘッダーでユーザー名がチェックされる前に、指定されたファイル内の認証局に対して検証する必要があります。
  • --requestheader-allowed-names: 任意です。Common Name(CN)の値のリストです。設定されている場合、リクエストヘッダーでユーザー名がチェックされる前に、指定されたリストのCNを持つ有効なクライアント証明書を提示する必要があります。空の場合は、任意のCNが許可されます。

匿名リクエスト

この機能を有効にすると、他の設定された認証方法で拒否されなかったリクエストは匿名リクエストとして扱われ、 system:anonymousというユーザー名とsystem:unauthenticatedというグループが与えられます。

例えば、トークン認証が設定されており、匿名アクセスが有効になっているサーバー上で、無効なBearerトークンを提供するリクエストは401 Unauthorizedエラーを受け取ります。Bearerトークンを提供しないリクエストは匿名リクエストとして扱われます。

バージョン1.5.1から1.5.xでは、匿名アクセスはデフォルトでは無効になっており、APIサーバーに --anonymous-auth=trueオプションを渡すことで有効にすることができます。

バージョン1.6以降では、AlwaysAllow以外の認証モードが使用されている場合、匿名アクセスがデフォルトで有効であり、--anonymous-auth=falseオプションをAPIサーバーに渡すことで無効にできます。 1.6以降、ABACおよびRBAC認可機能は、system:anonymousユーザーまたはsystem:unauthenticatedグループの明示的な認証を必要とするようになったため、*ユーザーまたは*グループへのアクセスを許可する従来のポリシールールには匿名ユーザーは含まれません。

ユーザーの偽装

ユーザーは偽装ヘッダーを使って別のユーザーとして振る舞うことができます。これにより、リクエストが認証したユーザー情報を手動で上書きすることが可能です。例えば、管理者はこの機能を使って一時的に別のユーザーに偽装、リクエストが拒否されたかどうかを確認することで認可ポリシーをデバッグすることができます。

偽装リクエストは最初にリクエスト中のユーザーとして認証を行い、次に偽装ユーザー情報に切り替えます。

  • ユーザーは、認証情報と偽装ヘッダーを使ってAPIコールを行います。
  • APIサーバーはユーザーを認証します。
  • APIサーバーは、認証されたユーザーが偽装した権限を持っていることを確認します。
  • リクエストされたユーザー情報は、偽装した値に置き換えられます。
  • リクエストが評価され、認可は偽装されたユーザー情報に基づいて実行されます。

偽装リクエストを実行する際には、以下のHTTPヘッダを使用することができます。

  • Impersonate-User: ユーザー名を指定します。このユーザーとして振る舞います。
  • Impersonate-Group: グループ名を指定します。このグループとして振る舞います。複数回指定して複数のグループを設定することができます。任意であり、"Impersonate-User"が必要です。
  • Impersonate-Extra-( extra name ): 追加フィールドをユーザーに関連付けるために使用される動的なヘッダーです。任意であり、"Impersonate-User"が必要です。一貫して保存されるためには、( extra name )は小文字である必要があり、HTTPヘッダーラベルで使用可能な文字以外の文字は、UTF-8であり、パーセントエンコーディングされている必要があります.

以下が、ヘッダーの例です。

Impersonate-User: jane.doe@example.com
Impersonate-Group: developers
Impersonate-Group: admins
Impersonate-Extra-dn: cn=jane,ou=engineers,dc=example,dc=com
Impersonate-Extra-acme.com%2Fproject: some-project
Impersonate-Extra-scopes: view
Impersonate-Extra-scopes: development

kubectlを使う場合は、--asフラグにImpersonate-Userヘッダーを、--as-groupフラグにImpersonate-Groupヘッダーを設定します。

kubectl drain mynode
Error from server (Forbidden): User "clark" cannot get nodes at the cluster scope. (get nodes mynode)

--asフラグと--as-groupフラグを設定します。

kubectl drain mynode --as=superman --as-group=system:masters
node/mynode cordoned
node/mynode drained

ユーザー、グループ、または追加フィールドを偽装するために、偽装ユーザーは偽装される属性の種類("user"、"group"など)に対して、"偽装した"操作を行う能力を持っている必要があります。RBAC認可プラグインが有効なクラスターの場合、以下のClusterRoleは、ユーザーとグループの偽装ヘッダーを設定するために必要なルールを網羅しています。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: impersonator
rules:
- apiGroups: [""]
  resources: ["users", "groups", "serviceaccounts"]
  verbs: ["impersonate"]

追加フィールドは、"userextras"リソースのサブリソースとして評価されます。ユーザーが追加フィールド"scopes"に偽装ヘッダーを使用できるようにするには、ユーザーに以下のようなロールを付与する必要があります。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: scopes-impersonator
rules:
# "Impersonate-Extra-scopes"ヘッダーを設定できます。
- apiGroups: ["authentication.k8s.io"]
  resources: ["userextras/scopes"]
  verbs: ["impersonate"]

偽装ヘッダーの値は、リソースが取り得るresourceNamesの集合を制限することで、管理することもできます。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: limited-impersonator
rules:
# "jane.doe@example.com"というユーザーを偽装できます。
- apiGroups: [""]
  resources: ["users"]
  verbs: ["impersonate"]
  resourceNames: ["jane.doe@example.com"]

# "developers"と"admins"というグループを偽装できます。
- apiGroups: [""]
  resources: ["groups"]
  verbs: ["impersonate"]
  resourceNames: ["developers","admins"]

# "view"と"development"を値に持つ"scopes"という追加フィールドを偽装できます。
- apiGroups: ["authentication.k8s.io"]
  resources: ["userextras/scopes"]
  verbs: ["impersonate"]
  resourceNames: ["view", "development"]

client-goクレデンシャルプラグイン

FEATURE STATE: Kubernetes v1.11 [beta]

k8s.io/client-goと、それを使用するkubectlkubeletのようなツールは、外部コマンドを実行してユーザーの認証情報を受け取ることができます。

この機能はk8s.io/client-goがネイティブにサポートしていない認証プロトコル(LDAP、Kerberos、OAuth2、SAMLなど)とクライアントサイドで統合するためのものです。プラグインはプロトコル固有のロジックを実装し、使用する不透明なクレデンシャルを返します。ほとんどすべてのクレデンシャルプラグインのユースケースでは、クライアントプラグインが生成するクレデンシャルフォーマットを解釈するために、Webhookトークン認証をサポートするサーバーサイドコンポーネントが必要です。

使用例

ある組織は、LDAPクレデンシャルをユーザー固有の署名済みトークンと交換する外部サービスを実行すると仮定します。このサービスは、トークンを検証するためにWebhookトークン認証リクエストに応答することもできます。ユーザーはワークステーションにクレデンシャルプラグインをインストールする必要があります。

以下のようにして、APIに対して認証を行います。

  • ユーザーはkubectlコマンドを発行します。
  • クレデンシャルプラグインは、LDAPクレデンシャルの入力をユーザーに要求し、クレデンシャルを外部サービスとトークンと交換します。
  • クレデンシャルプラグインはトークンをclient-goに返します。これはAPIサーバーに対するBearerトークンとして使用されます。
  • APIサーバーは、Webhookトークン認証を使用して、TokenReviewを外部サービスに送信します。
  • 外部サービスはトークンの署名を検証し、ユーザーのユーザー名とグループを返します。

設定

クレデンシャルプラグインの設定は、userフィールドの一部としてkubectlの設定ファイルで行います。

apiVersion: v1
kind: Config
users:
- name: my-user
  user:
    exec:
      # 実行するコマンドです。必須です。
      command: "example-client-go-exec-plugin"

      # ExecCredentialsリソースをデコードする際に使用するAPIのバージョン。必須です。
      #
      # プラグインが返すAPIのバージョンは、ここに記載されているバージョンと一致しなければなりません
      #
      # 複数のバージョンをサポートするツール(client.authentication.k8s.io/v1alpha1など)と統合するには、
      # 環境変数を設定するか、execプラグインが期待するバージョンを示す引数をツールに渡します。
      apiVersion: "client.authentication.k8s.io/v1beta1"

      # プラグインを実行する際に設定する環境変数です。任意です。
      env:
      - name: "FOO"
        value: "bar"

      # プラグインを実行する際に渡す引数です。任意です。
      args:
      - "arg1"
      - "arg2"
clusters:
- name: my-cluster
  cluster:
    server: "https://172.17.4.100:6443"
    certificate-authority: "/etc/kubernetes/ca.pem"
contexts:
- name: my-cluster
  context:
    cluster: my-cluster
    user: my-user
current-context: my-cluster

相対的なコマンドパスは、設定ファイルのディレクトリーからの相対的なものとして解釈されます。KUBECONFIGが/home/jane/kubeconfigに設定されていて、execコマンドが./bin/example-client-go-exec-pluginの場合、バイナリー/home/jane/bin/example-client-go-exec-pluginが実行されます。

- name: my-user
  user:
    exec:
      # kubeconfigのディレクトリーへの相対パス
      command: "./bin/example-client-go-exec-plugin"
      apiVersion: "client.authentication.k8s.io/v1beta1"

入出力フォーマット

実行されたコマンドはExecCredentialオブジェクトをstdoutに出力します。k8s.io/client-gostatusで返された認証情報を用いて、Kubernetes APIに対して認証を行ういます。

対話的なセッションから実行する場合、stdinはプラグインに直接公開されます。プラグインはTTYチェックを使って、対話的にユーザーにプロンプトを出すことが適切かどうかを判断する必要があります。

Bearerトークンのクレデンシャルを使用するために、プラグインはExecCredentialのステータスにトークンを返します。

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "token": "my-bearer-token"
  }
}

あるいは、PEMエンコードされたクライアント証明書と鍵を返して、TLSクライアント認証を使用することもできます。 プラグインが後続の呼び出しで異なる証明書と鍵を返すと、k8s.io/client-goはサーバーとの既存の接続を閉じて、新しいTLSハンドシェイクを強制します

指定された場合、clientKeyDataclientCertificateData両方が存在しなければなりません。

clientCertificateDataには、サーバーに送信するための中間証明書を含めることができます。

{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
    "clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
  }
}

オプションで、レスポンスにはRFC3339のタイムスタンプとしてフォーマットされたクレデンシャルの有効期限を含めることができます。有効期限の有無には、以下のような影響あります。

  • 有効期限が含まれている場合、BearerトークンとTLSクレデンシャルは有効期限に達するまで、またはサーバーがHTTPステータスコード401で応答したとき、またはプロセスが終了するまでキャッシュされます。
  • 有効期限が省略された場合、BearerトークンとTLSクレデンシャルはサーバーがHTTPステータスコード401で応答したとき、またはプロセスが終了するまでキャッシュされます。
{
  "apiVersion": "client.authentication.k8s.io/v1beta1",
  "kind": "ExecCredential",
  "status": {
    "token": "my-bearer-token",
    "expirationTimestamp": "2018-03-05T17:30:20-08:00"
  }
}

4 - セットアップツールのリファレンス

4.1 - Kubeadm

kubeadmは、kubeadm initkubeadm joinなどのコマンドを提供するツールで、Kubernetesクラスターを構築する上でのベストプラクティスを反映した「近道」を提供するものとして開発されました。

kubeadmは実用最小限のクラスターをセットアップするための処理を実行します。設計上、kubeadmはブートストラップのみを行い、マシンのプロビジョニングは行いません。同様に、Kubernetesダッシュボード、モニタリングソリューション、クラウド向けのアドオンなど、あれば便利でもなくても支障のない各種アドオンのインストールも範囲外です。

その代わりに、高度な特定用途向けのツールはkubeadmをベースに構築されることが期待されています。理想的には、すべてのデプロイのベースとしてkubeadmを使用することで、適合テストに通るクラスターを簡単に作れるようになります。

インストール方法

kubeadmをインストールするには、インストールガイドを参照してください。

次の項目

  • kubeadm initを使用して、Kubernetesのコントロールプレーンノードをブートストラップする
  • kubeadm joinを使用して、Kubernetesのワーカーノードをブートストラップし、クラスターに参加させる
  • kubeadm upgradeで、Kubernetesクラスターを新しいバージョンにアップグレードする
  • kubeadm configを使用して、kubeadm v1.7.x以前で初期化されたクラスターを、kubeadm upgradeを利用できるように設定する
  • kubeadm tokenで、kubeadm joinのためのトークンを管理する
  • kubeadm resetを使用して、kubeadm initまたはkubeadm joinでホストに行われた変更を元に戻す
  • kubeadm versionで、kubeadmのバージョンを表示する
  • kubeadm alphaで、コミュニティからのフィードバックを集めるために有効にされた各種機能を試用する

5 - kubectl CLI

5.1 - kubectlの概要

kubectlコマンドラインツールを使うと、Kubernetesクラスターを制御できます。環境設定のために、kubectlは、$HOME/.kubeディレクトリにあるconfigという名前のファイルを探します。他のkubeconfigファイルは、KUBECONFIG環境変数を設定するか、--kubeconfigフラグを設定することで指定できます。 この概要では、kubectlの構文を扱い、コマンド操作を説明し、一般的な例を示します。サポートされているすべてのフラグやサブコマンドを含め、各コマンドの詳細については、kubectlリファレンスドキュメントを参照してください。インストール方法については、kubectlのインストールおよびセットアップをご覧ください。

構文

ターミナルウィンドウからkubectlコマンドを実行するには、以下の構文を使用します。

kubectl [command] [TYPE] [NAME] [flags]

ここで、commandTYPENAMEflagsは、以下を表します。

  • command: 1つ以上のリソースに対して実行したい操作を指定します。例えば、creategetdescribedeleteです。

  • TYPE: リソースタイプを指定します。リソースタイプは大文字と小文字を区別せず、単数形や複数形、省略形を指定できます。例えば、以下のコマンドは同じ出力を生成します。

    kubectl get pod pod1
    kubectl get pods pod1
    kubectl get po pod1
    
  • NAME: リソースの名前を指定します。名前は大文字と小文字を区別します。kubectl get podsのように名前が省略された場合は、すべてのリソースの詳細が表示されます。

    複数のリソースに対して操作を行う場合は、各リソースをタイプと名前で指定するか、1つまたは複数のファイルを指定することができます。

    • リソースをタイプと名前で指定する場合

      • タイプがすべて同じとき、リソースをグループ化するにはTYPE1 name1 name2 name<#>とします。
        例: kubectl get pod example-pod1 example-pod2

      • 複数のリソースタイプを個別に指定するには、TYPE1/name1 TYPE1/name2 TYPE2/name3 TYPE<#>/name<#>とします。
        例: kubectl get pod/example-pod1 replicationcontroller/example-rc1

    • リソースを1つ以上のファイルで指定する場合は、-f file1 -f file2 -f file<#>とします。

  • flags: オプションのフラグを指定します。例えば、-sまたは--serverフラグを使って、Kubernetes APIサーバーのアドレスやポートを指定できます。

ヘルプが必要な場合は、ターミナルウィンドウからkubectl helpを実行してください。

操作

以下の表に、kubectlのすべての操作の簡単な説明と一般的な構文を示します。

操作                構文説明
alphakubectl alpha SUBCOMMAND [flags]アルファ機能に該当する利用可能なコマンドを一覧表示します。これらの機能は、デフォルトではKubernetesクラスターで有効になっていません。
annotatekubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]1つ以上のリソースのアノテーションを、追加または更新します。
api-resourceskubectl api-resources [flags]利用可能なAPIリソースを一覧表示します。
api-versionskubectl api-versions [flags]利用可能なAPIバージョンを一覧表示します。
applykubectl apply -f FILENAME [flags]ファイルまたは標準出力から、リソースの設定変更を適用します。
attachkubectl attach POD -c CONTAINER [-i] [-t] [flags]実行中のコンテナにアタッチして、出力ストリームを表示するか、コンテナ(標準入力)と対話します。
authkubectl auth [flags] [options]認可を検査します。
autoscalekubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags]ReplicationControllerで管理されているPodのセットを、自動的にスケールします。
certificatekubectl certificate SUBCOMMAND [options]証明書のリソースを変更します。
cluster-infokubectl cluster-info [flags]クラスター内のマスターとサービスに関するエンドポイント情報を表示します。
completionkubectl completion SHELL [options]指定されたシェル(bashまたはzsh)のシェル補完コードを出力します。
configkubectl config SUBCOMMAND [flags]kubeconfigファイルを変更します。詳細は、個々のサブコマンドを参照してください。
convertkubectl convert -f FILENAME [options]異なるAPIバージョン間で設定ファイルを変換します。YAMLとJSONに対応しています。
cordonkubectl cordon NODE [options]Nodeをスケジュール不可に設定します。
cpkubectl cp <file-spec-src> <file-spec-dest> [options]コンテナとの間でファイルやディレクトリをコピーします。
createkubectl create -f FILENAME [flags]ファイルまたは標準出力から、1つ以上のリソースを作成します。
deletekubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags]ファイル、標準出力、またはラベルセレクター、リソースセレクター、リソースを指定して、リソースを削除します。
describekubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags]1つ以上のリソースの詳細な状態を表示します。
diffkubectl diff -f FILENAME [flags]ファイルまたは標準出力と、現在の設定との差分を表示します。
drainkubectl drain NODE [options]メンテナンスの準備のためにNodeをdrainします。
editkubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags]デファルトのエディタを使い、サーバー上の1つ以上のリソースリソースの定義を編集し、更新します。
execkubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]]Pod内のコンテナに対して、コマンドを実行します。
explainkubectl explain [--recursive=false] [flags]様々なリソースのドキュメントを取得します。例えば、Pod、Node、Serviceなどです。
exposekubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags]ReplicationController、Service、Podを、新しいKubernetesサービスとして公開します。
getkubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags]1つ以上のリソースを表示します。
kustomizekubectl kustomize <dir> [flags] [options]kustomization.yamlファイル内の指示から生成されたAPIリソースのセットを一覧表示します。引数はファイルを含むディレクトリのPath,またはリポジトリルートに対して同じ場所を示すパスサフィックス付きのgitリポジトリのURLを指定しなければなりません。
labelkubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags]1つ以上のリソースのラベルを、追加または更新します。
logskubectl logs POD [-c CONTAINER] [--follow] [flags]Pod内のコンテナのログを表示します。
optionskubectl optionsすべてのコマンドに適用されるグローバルコマンドラインオプションを一覧表示します。
patchkubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags]Strategic Merge Patchの処理を使用して、リソースの1つ以上のフィールドを更新します。
pluginkubectl plugin [flags] [options]プラグインと対話するためのユーティリティを提供します。
port-forwardkubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags]1つ以上のローカルポートを、Podに転送します。
proxykubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags]Kubernetes APIサーバーへのプロキシーを実行します。
replacekubectl replace -f FILENAMEファイルや標準出力から、リソースを置き換えます。
rolloutkubectl rollout SUBCOMMAND [options]リソースのロールアウトを管理します。有効なリソースには、Deployment、DaemonSetとStatefulSetが含まれます。
runkubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags]指定したイメージを、クラスタ上で実行します。
scalekubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags]指定したReplicationControllerのサイズを更新します。
setkubectl set SUBCOMMAND [options]アプリケーションリソースを設定します。
taintkubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options]1つ以上のNodeのtaintを更新します。
topkubectl top [flags] [options]リソース(CPU/メモリー/ストレージ)の使用量を表示します。
uncordonkubectl uncordon NODE [options]Nodeをスケジュール可に設定します。
versionkubectl version [--client] [flags]クライアントとサーバーで実行中のKubernetesのバージョンを表示します。
waitkubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options]実験中の機能: 1つ以上のリソースが特定の状態になるまで待ちます。

コマンド操作について詳しく知りたい場合は、kubectlリファレンスドキュメントを参照してください。

リソースタイプ

以下の表に、サポートされているすべてのリソースと、省略されたエイリアスの一覧を示します。

(この出力はkubectl api-resourcesから取得でき、Kubernetes 1.13.3時点で正確でした。)

リソース名短縮名APIグループ名前空間に属するかリソースの種類
bindingstrueBinding
componentstatusescsfalseComponentStatus
configmapscmtrueConfigMap
endpointseptrueEndpoints
limitrangeslimitstrueLimitRange
namespacesnsfalseNamespace
nodesnofalseNode
persistentvolumeclaimspvctruePersistentVolumeClaim
persistentvolumespvfalsePersistentVolume
podspotruePod
podtemplatestruePodTemplate
replicationcontrollersrctrueReplicationController
resourcequotasquotatrueResourceQuota
secretstrueSecret
serviceaccountssatrueServiceAccount
servicessvctrueService
mutatingwebhookconfigurationsadmissionregistration.k8s.iofalseMutatingWebhookConfiguration
validatingwebhookconfigurationsadmissionregistration.k8s.iofalseValidatingWebhookConfiguration
customresourcedefinitionscrd, crdsapiextensions.k8s.iofalseCustomResourceDefinition
apiservicesapiregistration.k8s.iofalseAPIService
controllerrevisionsappstrueControllerRevision
daemonsetsdsappstrueDaemonSet
deploymentsdeployappstrueDeployment
replicasetsrsappstrueReplicaSet
statefulsetsstsappstrueStatefulSet
tokenreviewsauthentication.k8s.iofalseTokenReview
localsubjectaccessreviewsauthorization.k8s.iotrueLocalSubjectAccessReview
selfsubjectaccessreviewsauthorization.k8s.iofalseSelfSubjectAccessReview
selfsubjectrulesreviewsauthorization.k8s.iofalseSelfSubjectRulesReview
subjectaccessreviewsauthorization.k8s.iofalseSubjectAccessReview
horizontalpodautoscalershpaautoscalingtrueHorizontalPodAutoscaler
cronjobscjbatchtrueCronJob
jobsbatchtrueJob
certificatesigningrequestscsrcertificates.k8s.iofalseCertificateSigningRequest
leasescoordination.k8s.iotrueLease
eventsevevents.k8s.iotrueEvent
ingressesingextensionstrueIngress
networkpoliciesnetpolnetworking.k8s.iotrueNetworkPolicy
poddisruptionbudgetspdbpolicytruePodDisruptionBudget
podsecuritypoliciespsppolicyfalsePodSecurityPolicy
clusterrolebindingsrbac.authorization.k8s.iofalseClusterRoleBinding
clusterrolesrbac.authorization.k8s.iofalseClusterRole
rolebindingsrbac.authorization.k8s.iotrueRoleBinding
rolesrbac.authorization.k8s.iotrueRole
priorityclassespcscheduling.k8s.iofalsePriorityClass
csidriversstorage.k8s.iofalseCSIDriver
csinodesstorage.k8s.iofalseCSINode
storageclassesscstorage.k8s.iofalseStorageClass
volumeattachmentsstorage.k8s.iofalseVolumeAttachment

出力オプション

ある特定のコマンドの出力に対してフォーマットやソートを行う方法については、以下の節を参照してください。どのコマンドが様々な出力オプションをサポートしているかについては、kubectlリファレンスドキュメントをご覧ください。

出力のフォーマット

すべてのkubectlコマンドのデフォルトの出力フォーマットは、人間が読みやすいプレーンテキスト形式です。特定のフォーマットで、詳細をターミナルウィンドウに出力するには、サポートされているkubectlコマンドに-oまたは--outputフラグのいずれかを追加します。

構文

kubectl [command] [TYPE] [NAME] -o <output_format>

kubectlの操作に応じて、以下の出力フォーマットがサポートされています。

出力フォーマット説明
-o custom-columns=<spec>カスタムカラムのコンマ区切りのリストを使用して、テーブルを表示します。
-o custom-columns-file=<filename><filename>ファイル内のカスタムカラムのテンプレートを使用して、テーブルを表示します。
-o jsonJSON形式のAPIオブジェクトを出力します。
-o jsonpath=<template>jsonpath式で定義されたフィールドを表示します。
-o jsonpath-file=<filename><filename>ファイル内のjsonpath式で定義されたフィールドを表示します。
-o nameリソース名のみを表示します。
-o wide追加情報を含めて、プレーンテキスト形式で出力します。Podの場合は、Node名が含まれます。
-o yamlYAML形式のAPIオブジェクトを出力します。

この例において、以下のコマンドは1つのPodの詳細を、YAML形式のオブジェクトとして出力します。

kubectl get pod web-pod-13je7 -o yaml

各コマンドでサポートされている出力フォーマットの詳細については、kubectlリファレンスドキュメントを参照してください。

カスタムカラム

カスタムカラムを定義して、必要な詳細のみをテーブルに出力するには、custom-columnsオプションを使います。カスタムカラムをインラインで定義するか、-o custom-columns=<spec>または-o custom-columns-file=<filename>のようにテンプレートファイルを使用するかを選択できます。

インラインで定義する例は、以下の通りです。

kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion

テンプレートファイルを使用して定義する例は、以下の通りです。

kubectl get pods <pod-name> -o custom-columns-file=template.txt

ここで、template.txtには以下の内容が含まれます。

NAME          RSRC
metadata.name metadata.resourceVersion

どちらのコマンドを実行した場合でも、以下の結果を得ます。

NAME           RSRC
submit-queue   610995

サーバーサイドカラム

kubectlは、サーバーからオブジェクトに関する特定のカラム情報を受け取ることをサポートしています。 つまり、与えられた任意のリソースについて、サーバーはそのリソースに関連する列や行を返し、クライアントが表示できるようにします。 これにより、サーバーが表示の詳細をカプセル化することで、同一クラスターに対して使用されているクライアント間で、一貫した人間が読みやすい出力が可能です。

この機能は、デフォルトで有効になっています。無効にするには、kubectl getコマンドに--server-print=falseフラグを追加します。

Podの状態に関する情報を表示するには、以下のようなコマンドを使用します。

kubectl get pods <pod-name> --server-print=false

以下のように出力されます。

NAME       AGE
pod-name   1m

オブジェクトリストのソート

ターミナルウィンドウで、オブジェクトをソートされたリストに出力するには、サポートされているkubectlコマンドに--sort-byフラグを追加します。--sort-byフラグで任意の数値フィールドや文字列フィールドを指定することで、オブジェクトをソートします。フィールドの指定には、jsonpath式を使用します。

構文

kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>

名前でソートしたPodのリストを表示するには、以下のように実行します。

kubectl get pods --sort-by=.metadata.name

例: 一般的な操作

よく使われるkubectlの操作に慣れるために、以下の例を使用してください。

kubectl apply - ファイルや標準出力から、リソースの適用や更新を行います。

# example-service.yaml内の定義を使用して、Serviceを作成します。
kubectl apply -f example-service.yaml

# example-controller.yaml内の定義を使用して、ReplicationControllerを作成します。
kubectl apply -f example-controller.yaml

# <directory>ディレクトリ内の、任意の.yaml、.yml、.jsonファイルで定義されているオブジェクトを作成します。
kubectl apply -f <directory>

kubectl get - 1つ以上のリソースの一覧を表示します。

# すべてのPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods

# すべてのPodの一覧を、ノード名などの追加情報を含めて、プレーンテキスト形式で表示します。
kubectl get pods -o wide

# 指定した名前のReplicationControllerの一覧をプレーンテキスト形式で表示します。'replicationcontroller'リソースタイプを短縮して、エイリアス'rc'で置き換えることもできます。
kubectl get replicationcontroller <rc-name>

# すべてのReplicationControllerとServiceの一覧をまとめてプレーンテキスト形式で表示します。
kubectl get rc,services

# すべてのDaemonSetの一覧をプレーンテキスト形式で表示します。
kubectl get ds

# server01ノードで実行中のPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods --field-selector=spec.nodeName=server01

kubectl describe - 1つ以上のリソースの詳細な状態を、デフォルトでは初期化されないものも含めて表示します。

# Node <node-name>の詳細を表示します。
kubectl describe nodes <node-name>

# Pod <pod-name>の詳細を表示します。
kubectl describe pods/<pod-name>

# ReplicationController <rc-name>が管理しているすべてのPodの詳細を表示します。
# ReplicationControllerによって作成された任意のPodには、ReplicationControllerの名前がプレフィックスとして付与されます。
kubectl describe pods <rc-name>

# すべてのPodの詳細を表示します。
kubectl describe pods

kubectl delete - ファイル、標準出力、または指定したラベルセレクター、名前、リソースセレクター、リソースを指定して、リソースを削除します。

# pod.yamlファイルで指定されたタイプと名前を用いて、Podを削除します。
kubectl delete -f pod.yaml

# '<label-key>=<label-value>'というラベルを持つPodとServiceをすべて削除します。
kubectl delete pods,services -l <label-key>=<label-value>

# 初期化されていないPodを含む、すべてのPodを削除します。
kubectl delete pods --all

kubectl exec - Pod内のコンテナに対してコマンドを実行します。

# Pod <pod-name>から、'date'を実行している時の出力を取得します。デフォルトでは、最初のコンテナから出力されます。
kubectl exec <pod-name> -- date

# Pod <pod-name>のコンテナ <container-name>から、'date'を実行している時の出力を取得します。
kubectl exec <pod-name> -c <container-name> -- date

# インタラクティブな TTY を取得し、Pod <pod-name>から/bin/bashを実行します。デフォルトでは、最初のコンテナから出力されます。
kubectl exec -ti <pod-name> -- /bin/bash

kubectl logs - Pod内のコンテナのログを表示します。

# Pod <pod-name>のログのスナップショットを返します。
kubectl logs <pod-name>

# Pod <pod-name>から、ログのストリーミングを開始します。Linuxの'tail -f'コマンドと似ています。
kubectl logs -f <pod-name>

kubectl diff - 提案されたクラスタに対する更新の差分を表示します。

# pod.jsonに含まれるリソースの差分を表示します。
kubectl diff -f pod.json

# 標準出力から読み込んだファイルの差分を表示します。
cat service.yaml | kubectl diff -f -

例: プラグインの作成と使用

kubectlプラグインの書き方や使い方に慣れるために、以下の例を使用してください。

# 任意の言語でシンプルなプラグインを作成し、生成される実行可能なファイルに
# プレフィックス"kubectl-"で始まる名前を付けます。
cat ./kubectl-hello
#!/bin/sh

# このプラグインは、"hello world"という単語を表示します。
echo "hello world"

プラグインを書いたら、実行可能にします。

chmod a+x ./kubectl-hello

# さらに、PATH内の場所に移動させます。
sudo mv ./kubectl-hello /usr/local/bin
sudo chown root:root /usr/local/bin

# これでkubectlプラグインを作成し、"インストール"できました。
# 通常のコマンドのようにkubectlから呼び出すことで、プラグインを使用できます。
kubectl hello
hello world
# 配置したPATHのフォルダから削除することで、プラグインを"アンインストール"できます。
sudo rm /usr/local/bin/kubectl-hello

kubectlで利用可能なプラグインをすべて表示するには、kubectl plugin listサブコマンドを使用してください。

kubectl plugin list

出力は以下のようになります。

The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
/usr/local/bin/kubectl-bar

kubectl plugin listコマンドは、実行不可能なプラグインや、他のプラグインの影に隠れてしまっているプラグインなどについて、警告することもできます。例えば、以下のようになります。

sudo chmod -x /usr/local/bin/kubectl-foo # 実行権限を削除します。
kubectl plugin list
The following kubectl-compatible plugins are available:

/usr/local/bin/kubectl-hello
/usr/local/bin/kubectl-foo
  - warning: /usr/local/bin/kubectl-foo identified as a plugin, but it is not executable
/usr/local/bin/kubectl-bar

error: one plugin warning was found

プラグインは、既存のkubectlコマンドの上に、より複雑な機能を構築するための手段であると考えることができます。

cat ./kubectl-whoami

次の例では、下記の内容を含んだkubectl-whoamiが既に作成済であることを前提としています。

#!/bin/bash

# このプラグインは、`kubectl config`コマンドを使って
# 現在選択されているコンテキストに基づいて、現在のユーザーに関する情報を提供します。
kubectl config view --template='{{ range .contexts }}{{ if eq .name "'$(kubectl config current-context)'" }}Current user: {{ printf "%s\n" .context.user }}{{ end }}{{ end }}'

上記のコマンドを実行すると、KUBECONFIGファイル内のカレントコンテキストのユーザーを含んだ出力を得られます。

# ファイルを実行可能にします。
sudo chmod +x ./kubectl-whoami

# さらに、ファイルをPATHに移動します。
sudo mv ./kubectl-whoami /usr/local/bin

kubectl whoami
Current user: plugins-user

次の項目

  • kubectlを使い始めてください。

  • プラグインについてより詳しく知りたい場合は, example cli pluginを御覧ください。

5.2 - JSONPathのサポート

kubectlはJSONPathのテンプレートをサポートしています。

JSONPathのテンプレートは、波括弧{}によって囲まれたJSONPathの式によって構成されています。 kubectlでは、JSONPathの式を使うことで、JSONオブジェクトの特定のフィールドをフィルターしたり、出力のフォーマットを変更することができます。 本来のJSONPathのテンプレートの構文に加え、以下の機能と構文が使えます:

  1. JSONPathの式の内部でテキストをクォートするために、ダブルクォーテーションを使用します。
  2. リストを反復するために、rangeendオペレーターを使用します。
  3. リストを末尾側から参照するために、負の数のインデックスを使用します。負の数のインデックスはリストを「周回」せず、-index + listLength >= 0が満たされる限りにおいて有効になります。

以下のようなJSONの入力が与えられたとします。

{
  "kind": "List",
  "items":[
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.1"},
      "status":{
        "capacity":{"cpu":"4"},
        "addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}]
      }
    },
    {
      "kind":"None",
      "metadata":{"name":"127.0.0.2"},
      "status":{
        "capacity":{"cpu":"8"},
        "addresses":[
          {"type": "LegacyHostIP", "address":"127.0.0.2"},
          {"type": "another", "address":"127.0.0.3"}
        ]
      }
    }
  ],
  "users":[
    {
      "name": "myself",
      "user": {}
    },
    {
      "name": "e2e",
      "user": {"username": "admin", "password": "secret"}
    }
  ]
}
機能説明結果
textプレーンテキストkind is {.kind}kind is List
@現在のオブジェクト{@}入力した値と同じ値
. or []子要素{.kind}, {['kind']} or {['name\.type']}List
..子孫要素を再帰的に探す{..name}127.0.0.1 127.0.0.2 myself e2e
*ワイルドカード。すべてのオブジェクトを取得する{.items[*].metadata.name}[127.0.0.1 127.0.0.2]
[start:end:step]添字{.users[0].name}myself
[,]和集合{.items[*]['metadata.name', 'status.capacity']}127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8]
?()フィルター{.users[?(@.name=="e2e")].user.password}secret
range, endリストの反復{range .items[*]}[{.metadata.name}, {.status.capacity}] {end}[127.0.0.1, map[cpu:4]] [127.0.0.2, map[cpu:8]]
''解釈済みの文字列をクォートする{range .items[*]}{.metadata.name}{'\t'}{end}127.0.0.1 127.0.0.2

kubectlとJSONPathの式を使った例:

kubectl get pods -o json
kubectl get pods -o=jsonpath='{@}'
kubectl get pods -o=jsonpath='{.items[0]}'
kubectl get pods -o=jsonpath='{.items[0].metadata.name}'
kubectl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}"
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'

5.3 - kubectlチートシート

このページには、一般的によく使われるkubectlコマンドとフラグのリストが含まれています。

Kubectlコマンドの補完

BASH

source <(kubectl completion bash) # 現在のbashシェルにコマンド補完を設定するには、最初にbash-completionパッケージをインストールする必要があります。
echo "source <(kubectl completion bash)" >> ~/.bashrc # bashシェルでのコマンド補完を永続化するために.bashrcに追記します。

また、エイリアスを使用している場合にもkubectlコマンドを補完できます。

alias k=kubectl
complete -F __start_kubectl k

ZSH

source <(kubectl completion zsh)  # 現在のzshシェルにコマンド補完を設定します
echo "[[ $commands[kubectl] ]] && source <(kubectl completion zsh)" >> ~/.zshrc # zshシェルでのコマンド補完を永続化するために.zshrcに追記します。

Kubectlコンテキストの設定

kubectlがどのKubernetesクラスターと通信するかを設定します。 設定ファイル詳細についてはkubeconfigを使用した複数クラスターとの認証をご覧ください。

kubectl config view # マージされたkubeconfigの設定を表示します。

# 複数のkubeconfigファイルを同時に読み込む場合はこのように記述します。
KUBECONFIG=~/.kube/config:~/.kube/kubconfig2 

kubectl config view

# e2eユーザのパスワードを取得します。
kubectl config view -o jsonpath='{.users[?(@.name == "e2e")].user.password}'

kubectl config view -o jsonpath='{.users[].name}'    # 最初のユーザー名を表示します
kubectl config view -o jsonpath='{.users[*].name}'   # ユーザー名のリストを表示します
kubectl config get-contexts                          # コンテキストのリストを表示します
kubectl config current-context                       # 現在のコンテキストを表示します
kubectl config use-context my-cluster-name           # デフォルトのコンテキストをmy-cluster-nameに設定します

# basic認証をサポートする新たなユーザーをkubeconfigに追加します
kubectl config set-credentials kubeuser/foo.kubernetes.com --username=kubeuser --password=kubepassword

# 現在のコンテキストでkubectlのサブコマンドの名前空間を永続的に変更します
kubectl config set-context --current --namespace=ggckad-s2

# 特定のユーザー名と名前空間を使用してコンテキストを設定します
kubectl config set-context gce --user=cluster-admin --namespace=foo \
  && kubectl config use-context gce
 
kubectl config unset users.foo    # ユーザーfooを削除します

Kubectl Apply

applyはKubernetesリソースを定義するファイルを通じてアプリケーションを管理します。kubectl applyを実行して、クラスター内のリソースを作成および更新します。これは、本番環境でKubernetesアプリケーションを管理する推奨方法です。 詳しくはKubectl Bookをご覧ください。

Objectの作成

Kubernetesのマニフェストファイルは、JSONまたはYAMLで定義できます。ファイル拡張子として、.yaml.yml.jsonが使えます。

kubectl apply -f ./my-manifest.yaml            # リソースを作成します
kubectl apply -f ./my1.yaml -f ./my2.yaml      # 複数のファイルからリソースを作成します
kubectl apply -f ./dir                         # dirディレクトリ内のすべてのマニフェストファイルからリソースを作成します
kubectl apply -f https://git.io/vPieo          # urlで公開されているファイルからリソースを作成します
kubectl create deployment nginx --image=nginx  # 単一のnginx Deploymentを作成します
kubectl explain pods                           # Podマニフェストのドキュメントを取得します

# 標準入力から複数のYAMLオブジェクトを作成します

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000000"
---
apiVersion: v1
kind: Pod
metadata:
  name: busybox-sleep-less
spec:
  containers:
  - name: busybox
    image: busybox
    args:
    - sleep
    - "1000"
EOF

# いくつかの鍵を含むSecretを作成します

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
  name: mysecret
type: Opaque
data:
  password: $(echo -n "s33msi4" | base64 -w0)
  username: $(echo -n "jane" | base64 -w0)
EOF

リソースの検索と閲覧

# Getコマンドで基本的な情報を確認します
kubectl get services                          # 現在の名前空間上にあるすべてのサービスのリストを表示します
kubectl get pods --all-namespaces             # すべての名前空間上にあるすべてのPodのリストを表示します
kubectl get pods -o wide                      # 現在の名前空間上にあるすべてのPodについてより詳細なリストを表示します
kubectl get deployment my-dep                 # 特定のDeploymentを表示します
kubectl get pods                              # 現在の名前空間上にあるすべてのPodのリストを表示します
kubectl get pod my-pod -o yaml                # PodのYAMLを表示します

# Describeコマンドで詳細な情報を確認します
kubectl describe nodes my-node
kubectl describe pods my-pod

# 名前順にソートしたServiceのリストを表示します
kubectl get services --sort-by=.metadata.name

# Restartカウント順にPodのリストを表示します
kubectl get pods --sort-by='.status.containerStatuses[0].restartCount'

# capacity順にソートしたPersistentVolumeのリストを表示します
kubectl get pv --sort-by=.spec.capacity.storage

# app=cassandraラベルのついたすべてのPodのversionラベルを表示します
kubectl get pods --selector=app=cassandra -o \
  jsonpath='{.items[*].metadata.labels.version}'

# 'ca.crt'のようなピリオドが含まれるキーの値を取得します
kubectl get configmap myconfig \
  -o jsonpath='{.data.ca\.crt}'

# すべてのワーカーノードを取得します(セレクターを使用して、
# 「node-role.kubernetes.io/master」という名前のラベルを持つ結果を除外します)
kubectl get node --selector='!node-role.kubernetes.io/master'

# 現在の名前空間でrunning状態のPodのリストを表示します
kubectl get pods --field-selector=status.phase=Running

# すべてのノードのExternal IPのリストを表示します
kubectl get nodes -o jsonpath='{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'

# 特定のRCに属するPodの名前のリストを表示します
# `jq`コマンドは複雑なjsonpathを変換する場合に便利であり、https://stedolan.github.io/jq/で見つけることが可能です
sel=${$(kubectl get rc my-rc --output=json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"')%?}
echo $(kubectl get pods --selector=$sel --output=jsonpath={.items..metadata.name})

# すべてのPod(またはラベル付けをサポートする他のKubernetesオブジェクト)のラベルのリストを表示します
kubectl get pods --show-labels

# どのノードがready状態か確認します
JSONPATH='{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
 && kubectl get nodes -o jsonpath="$JSONPATH" | grep "Ready=True"

# Podで現在使用中のSecretをすべて表示します
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq

# すべてのPodのInitContainerのコンテナIDのリストを表示します
# initContainerの削除を回避しながら、停止したコンテナを削除するときに役立つでしょう
kubectl get pods --all-namespaces -o jsonpath='{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3

# タイムスタンプでソートされたEventのリストを表示します
kubectl get events --sort-by=.metadata.creationTimestamp

# クラスターの現在の状態を、マニフェストが適用された場合のクラスターの状態と比較します。
kubectl diff -f ./my-manifest.yaml

# Nodeから返されるすべてのキーをピリオド区切りの階層表記で生成します。
# 複雑にネストされたJSON構造をもつキーを指定したい時に便利です
kubectl get nodes -o json | jq -c 'paths|join(".")'

# Pod等から返されるすべてのキーをピリオド区切り階層表記で生成します。
kubectl get pods -o json | jq -c 'paths|join(".")'

リソースのアップデート

kubectl set image deployment/frontend www=image:v2               # frontend Deploymentのwwwコンテナイメージをv2にローリングアップデートします
kubectl rollout history deployment/frontend                      # frontend Deploymentの改訂履歴を確認します
kubectl rollout undo deployment/frontend                         # 1つ前のDeploymentにロールバックします
kubectl rollout undo deployment/frontend --to-revision=2         # 特定のバージョンにロールバックします
kubectl rollout status -w deployment/frontend                    # frontend Deploymentのローリングアップデートを状態をwatchします
kubectl rollout restart deployment/frontend                      # frontend Deployment を再起動します


cat pod.json | kubectl replace -f -                              # 標準入力から渡されたJSONに基づいてPodを置き換えます

# リソースを強制的に削除してから再生成し、置き換えます。サービスの停止が発生します
kubectl replace --force -f ./pod.json

# ReplicaSetリソースで作られたnginxについてServiceを作成します。これは、ポート80で提供され、コンテナへはポート8000で接続します
kubectl expose rc nginx --port=80 --target-port=8000

# 単一コンテナのPodイメージのバージョン(タグ)をv4に更新します
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -

kubectl label pods my-pod new-label=awesome                      # ラベルを追加します
kubectl annotate pods my-pod icon-url=http://goo.gl/XXBTWq       # アノテーションを追加します
kubectl autoscale deployment foo --min=2 --max=10                # "foo" Deploymentのオートスケーリングを行います

リソースへのパッチ適用

# ノードを部分的に更新します
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'

# コンテナのイメージを更新します。spec.containers[*].nameはマージキーであるため必須です
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'

# ポテンシャル配列を含むJSONパッチを使用して、コンテナのイメージを更新します
kubectl patch pod valid-pod --type='json' -p='[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'

# ポテンシャル配列のJSONパッチを使用してDeploymentのlivenessProbeを無効にします
kubectl patch deployment valid-deployment  --type json   -p='[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'

# ポテンシャル配列に新たな要素を追加します
kubectl patch sa default --type='json' -p='[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'

リソースの編集

任意のエディターでAPIリソースを編集します。

kubectl edit svc/docker-registry                      # docker-registryという名前のサービスを編集します
KUBE_EDITOR="nano" kubectl edit svc/docker-registry   # エディターを指定します

リソースのスケーリング

kubectl scale --replicas=3 rs/foo                                 # 「foo」という名前のレプリカセットを3にスケーリングします
kubectl scale --replicas=3 -f foo.yaml                            # 「foo.yaml」で指定されたリソースを3にスケーリングします
kubectl scale --current-replicas=2 --replicas=3 deployment/mysql  # mysqlと名付けられたdeploymentの現在のサイズが2であれば、mysqlを3にスケーリングします
kubectl scale --replicas=5 rc/foo rc/bar rc/baz                   # 複数のReplication controllerをスケーリングします

リソースの削除

kubectl delete -f ./pod.json                                              # pod.jsonで指定されたタイプと名前を使用してPodを削除します
kubectl delete pod,service baz foo                                        # 「baz」と「foo」の名前を持つPodとServiceを削除します
kubectl delete pods,services -l name=myLabel                              # name=myLabelラベルを持つのPodとServiceを削除します
kubectl -n my-ns delete pod,svc --all                                     # 名前空間my-ns内のすべてのPodとServiceを削除します
# awkコマンドのpattern1またはpattern2に一致するすべてのPodを削除します。
kubectl get pods  -n mynamespace --no-headers=true | awk '/pattern1|pattern2/{print $1}' | xargs  kubectl delete -n mynamespace pod

実行中のポッドとの対話処理

kubectl logs my-pod                                 # Podのログをダンプします(標準出力)
kubectl logs -l name=myLabel                        # name=myLabelラベルの持つPodのログをダンプします(標準出力)
kubectl logs my-pod --previous                      # 以前に存在したコンテナのPodログをダンプします(標準出力)
kubectl logs my-pod -c my-container                 # 複数コンテナがあるPodで、特定のコンテナのログをダンプします(標準出力)
kubectl logs -l name=myLabel -c my-container        # name=mylabelラベルを持つPodのログをダンプします(標準出力) 
kubectl logs my-pod -c my-container --previous      # 複数コンテナがあるPodで、以前に作成した特定のコンテナのログをダンプします(標準出力)
kubectl logs -f my-pod                              # Podのログをストリームで確認します(標準出力)
kubectl logs -f my-pod -c my-container              # 複数のコンテナがあるPodで、特定のコンテナのログをストリームで確認します(標準出力)
kubectl logs -f -l name=myLabel --all-containers    # name-myLabelラベルを持つすべてのコンテナのログをストリームで確認します(標準出力)
kubectl run -i --tty busybox --image=busybox -- sh  # Podをインタラクティブシェルとして実行します
kubectl run nginx --image=nginx -n 
mynamespace                                         # 特定の名前空間でnginx Podを実行します
kubectl run nginx --image=nginx                     # nginx Podを実行し、マニフェストファイルをpod.yamlという名前で書き込みます
--dry-run=client -o yaml > pod.yaml
kubectl attach my-pod -i                            # 実行中のコンテナに接続します
kubectl port-forward my-pod 5000:6000               # ローカルマシンのポート5000を、my-podのポート6000に転送します
kubectl exec my-pod -- ls /                         # 既存のPodでコマンドを実行(単一コンテナの場合)
kubectl exec my-pod -c my-container -- ls /         # 既存のPodでコマンドを実行(複数コンテナがある場合)
kubectl top pod POD_NAME --containers               # 特定のPodとそのコンテナのメトリクスを表示します

ノードおよびクラスターとの対話処理

kubectl cordon my-node                                                # my-nodeをスケジューリング不能に設定します
kubectl drain my-node                                                 # メンテナンスの準備としてmy-nodeで動作中のPodを空にします
kubectl uncordon my-node                                              # my-nodeをスケジューリング可能に設定します
kubectl top node my-node                                              # 特定のノードのメトリクスを表示します
kubectl cluster-info                                                  # Kubernetesクラスターのマスターとサービスのアドレスを表示します
kubectl cluster-info dump                                             # 現在のクラスター状態を標準出力にダンプします
kubectl cluster-info dump --output-directory=/path/to/cluster-state   # 現在のクラスター状態を/path/to/cluster-stateにダンプします

# special-userキーとNoScheduleエフェクトを持つTaintがすでに存在する場合、その値は指定されたとおりに置き換えられます
kubectl taint nodes foo dedicated=special-user:NoSchedule

リソースタイプ

サポートされているすべてのリソースタイプを、それらがAPI groupNamespacedKindに関わらずその短縮名をリストします。

kubectl api-resources

APIリソースを探索するためのその他の操作:

kubectl api-resources --namespaced=true      # 名前空間付きのすべてのリソースを表示します
kubectl api-resources --namespaced=false     # 名前空間のないすべてのリソースを表示します
kubectl api-resources -o name                # すべてのリソースを単純な出力(リソース名のみ)で表示します
kubectl api-resources -o wide                # すべてのリソースを拡張された形(別名 "wide")で表示します
kubectl api-resources --verbs=list,get       # "list"および"get"操作をサポートするすべてのリソースを表示します
kubectl api-resources --api-group=extensions # "extensions" APIグループのすべてのリソースを表示します

出力のフォーマット

特定の形式で端末ウィンドウに詳細を出力するには、サポートされているkubectlコマンドに-o(または--output)フラグを追加します。

出力フォーマット説明
-o=custom-columns=<spec>コンマ区切りされたカスタムカラムのリストを指定してテーブルを表示します
-o=custom-columns-file=<filename><filename>ファイル内のカスタムカラムテンプレートを使用してテーブルを表示します
-o=jsonJSON形式のAPIオブジェクトを出力します
-o=jsonpath=<template>jsonpath式で定義されたフィールドを出力します
-o=jsonpath-file=<filename><filename>ファイル内のjsonpath式で定義されたフィールドを出力します
-o=nameリソース名のみを出力し、それ以外は何も出力しません。
-o=wide追加の情報を含むプレーンテキスト形式で出力します。Podの場合、Node名が含まれます。
-o=yamlYAML形式のAPIオブジェクトを出力します

-o=custom-columnsを使用したサンプル:

# クラスター内で実行中のすべてのイメージ名を表示する
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'

# "k8s.gcr.io/coredns:1.6.2"を除いたすべてのイメージ名を表示する
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="k8s.gcr.io/coredns:1.6.2")].image'

# 名前に関係なくmetadata以下のすべてのフィールドを表示する
kubectl get pods -A -o=custom-columns='DATA:metadata.*'

kubectlに関するより多くのサンプルはカスタムカラムのリファレンスを参照してください。

Kubectlのログレベルとデバッグ

kubectlのログレベルは、レベルを表す整数が後に続く-vまたは--vフラグで制御されます。一般的なKubernetesのログ記録規則と関連するログレベルについて、こちらで説明します。

ログレベル説明
--v=0これは、クラスターオペレーターにログレベルが0であることを"常に"見えるようにするために役立ちます
--v=1ログレベルが必要ない場合に、妥当なデフォルトのログレベルです
--v=2サービスに関する重要な定常状態情報と、システムの重要な変更に関連する可能性がある重要なログメッセージを表示します。 これは、ほとんどのシステムで推奨されるデフォルトのログレベルです。
--v=3変更に関するより詳細なログレベルを表示します
--v=4デバックにむいたログレベルで表示します
--v=6要求されたリソースを表示します
--v=7HTTPリクエストのヘッダを表示します
--v=8HTTPリクエストのコンテンツを表示します
--v=9HTTPリクエストのコンテンツをtruncationなしで表示します

次の項目

5.4 - kubectlの使用規則

kubectlの推奨される使用規則です。

再利用可能なスクリプトでのkubectlの使用

スクリプトでの安定した出力のために:

  • -o name, -o json, -o yaml, -o go-template, -o jsonpath などの機械指向の出力形式のいずれかを必要します。
  • バージョンを完全に指定します。例えば、jobs.v1.batch/myjobのようにします。これにより、kubectlが時間とともに変化する可能性のあるデフォルトのバージョンを使用しないようにします。
  • コンテキストや設定、その他の暗黙的な状態に頼ってはいけません。

ベストプラクティス

kubectl run

kubectl runがインフラのコード化を満たすために:

  • イメージにバージョン固有のタグを付けて、そのタグを新しいバージョンに移さない。例えば、:latestではなく、:v1234v1.2.3r03062016-1-4を使用してください(詳細は、Best Practices for Configurationを参照してください)。
  • パラメーターが多用されているイメージをスクリプトでチェックします。
  • kubectl run フラグでは表現できない機能を、ソースコントロールでチェックした設定ファイルに切り替えます。

dry-run=client フラグを使用すると、実際に送信することなく、クラスターに送信されるオブジェクトを確認することができます。

Generators

kubectl create --dry-run=client -o yamlというkubectlコマンドで以下のリソースを生成することができます。

  • clusterrole: ClusterRoleを作成します。
  • clusterrolebinding: 特定のClusterRoleに対するClusterRoleBindingを作成します。
  • configmap: ローカルファイル、ディレクトリ、またはリテラル値からConfigMapを作成します。
  • cronjob: 指定された名前のCronJobを作成します。
  • deployment: 指定された名前でDeploymentを作成します。
  • job: 指定された名前でJobを作成します。
  • namespace: 指定された名前でNamespaceを作成します。
  • poddisruptionbudget: 指定された名前でPodDisruptionBudgetを作成します。
  • priorityclass: 指定された名前でPriorityClassを作成します。
  • quota: 指定された名前でQuotaを作成します。
  • role: 1つのルールでRoleを作成します。
  • rolebinding: 特定のロールやClusterRoleに対するRoleBindingを作成します。
  • secret: 指定されたサブコマンドを使用してSecretを作成します。
  • service: 指定されたサブコマンドを使用してServiceを作成します。
  • ServiceAccount: 指定された名前でServiceAccountを作成します。

kubectl apply

  • リソースの作成や更新には kubectl apply を使用できます。kubectl applyを使ったリソースの更新については、Kubectl Bookを参照してください。

6 - コマンドラインツールのリファレンス

6.1 - フィーチャーゲート

このページでは管理者がそれぞれのKubernetesコンポーネントで指定できるさまざまなフィーチャーゲートの概要について説明しています。

各機能におけるステージの説明については、機能のステージを参照してください。

概要

フィーチャーゲートはアルファ機能または実験的機能を記述するkey=valueのペアのセットです。管理者は各コンポーネントで--feature-gatesコマンドラインフラグを使用することで機能をオンまたはオフにできます。

各コンポーネントはそれぞれのコンポーネント固有のフィーチャーゲートの設定をサポートします。すべてのコンポーネントのフィーチャーゲートの全リストを表示するには-hフラグを使用します。kubeletなどのコンポーネントにフィーチャーゲートを設定するには以下のようにリストの機能ペアを--feature-gatesフラグを使用して割り当てます。

--feature-gates="...,DynamicKubeletConfig=true"

次の表は各Kubernetesコンポーネントに設定できるフィーチャーゲートの概要です。

  • 「導入開始バージョン」列は機能が導入されたとき、またはリリース段階が変更されたときのKubernetesリリースバージョンとなります。
  • 「最終利用可能バージョン」列は空ではない場合はフィーチャーゲートを使用できる最後のKubernetesリリースバージョンとなります。
  • アルファまたはベータ状態の機能はAlphaまたはBetaのフィーチャーゲートに載っています。
  • 安定している機能は、graduatedまたはdeprecatedのフィーチャーゲートに載っています。
  • graduatedまたはdeprecatedのフィーチャーゲートには、非推奨および廃止された機能もリストされています。

AlphaまたはBetaのフィーチャーゲート

AlphaまたはBetaのフィーチャーゲート
機能名デフォルト値ステージ導入開始バージョン最終利用可能バージョン
APIListChunkingfalseAlpha1.81.8
APIListChunkingtrueBeta1.9
APIPriorityAndFairnessfalseAlpha1.181.19
APIPriorityAndFairnesstrueBeta1.20
APIResponseCompressionfalseAlpha1.71.15
APIResponseCompressiontrueBeta1.16
APIServerIdentityfalseAlpha1.20
APIServerTracingfalseAlpha1.22
AllowInsecureBackendProxytrueBeta1.17
AnyVolumeDataSourcefalseAlpha1.181.23
AnyVolumeDataSourcetrueBeta1.24
AppArmortrueBeta1.4
CPUManagerfalseAlpha1.81.9
CPUManagertrueBeta1.10
CPUManagerPolicyAlphaOptionsfalseAlpha1.23
CPUManagerPolicyBetaOptionstrueBeta1.23
CPUManagerPolicyOptionsfalseAlpha1.221.22
CPUManagerPolicyOptionstrueBeta1.23
CSIMigrationAzureFilefalseAlpha1.151.20
CSIMigrationAzureFilefalseBeta1.211.23
CSIMigrationAzureFiletrueBeta1.24
CSIMigrationPortworxfalseAlpha1.231.24
CSIMigrationPortworxfalseBeta1.25
CSIMigrationRBDfalseAlpha1.23
CSIMigrationvSpherefalseAlpha1.181.18
CSIMigrationvSpherefalseBeta1.191.24
CSIMigrationvSpheretrueBeta1.25
CSINodeExpandSecretfalseAlpha1.25
CSIVolumeHealthfalseAlpha1.21
ContainerCheckpointfalseAlpha1.25
ContextualLoggingfalseAlpha1.24
CustomCPUCFSQuotaPeriodfalseAlpha1.12
CustomResourceValidationExpressionsfalseAlpha1.231.24
CustomResourceValidationExpressionstrueBeta1.25
DelegateFSGroupToCSIDriverfalseAlpha1.221.22
DelegateFSGroupToCSIDrivertrueBeta1.23
DevicePluginsfalseAlpha1.81.9
DevicePluginstrueBeta1.10
DisableCloudProvidersfalseAlpha1.22
DisableKubeletCloudCredentialProvidersfalseAlpha1.23
DownwardAPIHugePagesfalseAlpha1.201.20
DownwardAPIHugePagesfalseBeta1.211.21
DownwardAPIHugePagestrueBeta1.22
EndpointSliceTerminatingConditionfalseAlpha1.201.21
EndpointSliceTerminatingConditiontrueBeta1.22
ExpandedDNSConfigfalseAlpha1.22
ExperimentalHostUserNamespaceDefaultingfalseBeta1.5
GRPCContainerProbefalseAlpha1.231.23
GRPCContainerProbetrueBeta1.24
GracefulNodeShutdownfalseAlpha1.201.20
GracefulNodeShutdowntrueBeta1.21
GracefulNodeShutdownBasedOnPodPriorityfalseAlpha1.231.23
GracefulNodeShutdownBasedOnPodPrioritytrueBeta1.24
HPAContainerMetricsfalseAlpha1.20
HPAScaleToZerofalseAlpha1.16
HonorPVReclaimPolicyfalseAlpha1.23
InTreePluginAWSUnregisterfalseAlpha1.21
InTreePluginAzureDiskUnregisterfalseAlpha1.21
InTreePluginAzureFileUnregisterfalseAlpha1.21
InTreePluginGCEUnregisterfalseAlpha1.21
InTreePluginOpenStackUnregisterfalseAlpha1.21
InTreePluginPortworxUnregisterfalseAlpha1.23
InTreePluginRBDUnregisterfalseAlpha1.23
InTreePluginvSphereUnregisterfalseAlpha1.21
IPTablesOwnershipCleanupfalseAlpha1.25
JobMutableNodeSchedulingDirectivestrueBeta1.23
JobPodFailurePolicyfalseAlpha1.25-
JobReadyPodsfalseAlpha1.231.23
JobReadyPodstrueBeta1.24
JobTrackingWithFinalizersfalseAlpha1.221.22
JobTrackingWithFinalizersfalseBeta1.231.24
JobTrackingWithFinalizerstrueBeta1.25
KubeletCredentialProvidersfalseAlpha1.201.23
KubeletCredentialProviderstrueBeta1.24
KubeletInUserNamespacefalseAlpha1.22
KubeletPodResourcesfalseAlpha1.131.14
KubeletPodResourcestrueBeta1.15
KubeletPodResourcesGetAllocatablefalseAlpha1.211.22
KubeletPodResourcesGetAllocatabletrueBeta1.23
KubeletTracingfalseAlpha1.25
LegacyServiceAccountTokenNoAutoGenerationtrueBeta1.24
LocalStorageCapacityIsolationFSQuotaMonitoringfalseAlpha1.151.24
LocalStorageCapacityIsolationFSQuotaMonitoringtrueBeta1.25
LogarithmicScaleDownfalseAlpha1.211.21
LogarithmicScaleDowntrueBeta1.22
MatchLabelKeysInPodTopologySpreadfalseAlpha1.25
MaxUnavailableStatefulSetfalseAlpha1.24
MemoryManagerfalseAlpha1.211.21
MemoryManagertrueBeta1.22
MemoryQoSfalseAlpha1.22
MinDomainsInPodTopologySpreadfalseAlpha1.241.24
MinDomainsInPodTopologySpreadfalseBeta1.25
MixedProtocolLBServicefalseAlpha1.201.23
MixedProtocolLBServicetrueBeta1.24
MultiCIDRRangeAllocatorfalseAlpha1.25
NetworkPolicyStatusfalseAlpha1.24
NodeInclusionPolicyInPodTopologySpreadfalseAlpha1.25
NodeOutOfServiceVolumeDetachfalseAlpha1.24
NodeSwapfalseAlpha1.22
OpenAPIEnumsfalseAlpha1.231.23
OpenAPIEnumstrueBeta1.24
OpenAPIV3falseAlpha1.231.23
OpenAPIV3trueBeta1.24
PodAndContainerStatsFromCRIfalseAlpha1.23
PodDeletionCostfalseAlpha1.211.21
PodDeletionCosttrueBeta1.22
PodDisruptionConditionsfalseAlpha1.25-
PodHasNetworkConditionfalseAlpha1.25
ProbeTerminationGracePeriodfalseAlpha1.211.21
ProbeTerminationGracePeriodfalseBeta1.221.24
ProbeTerminationGracePeriodtrueBeta1.25
ProcMountTypefalseAlpha1.12
ProxyTerminatingEndpointsfalseAlpha1.22
QOSReservedfalseAlpha1.11
ReadWriteOncePodfalseAlpha1.22
RecoverVolumeExpansionFailurefalseAlpha1.23
RemainingItemCountfalseAlpha1.151.15
RemainingItemCounttrueBeta1.16
RetroactiveDefaultStorageClassfalseAlpha1.25
RotateKubeletServerCertificatefalseAlpha1.71.11
RotateKubeletServerCertificatetrueBeta1.12
SELinuxMountReadWriteOncePodfalseAlpha1.25
SeccompDefaultfalseAlpha1.221.24
SeccompDefaulttrueBeta1.25
ServerSideFieldValidationfalseAlpha1.231.24
ServerSideFieldValidationtrueBeta1.25
ServiceIPStaticSubrangefalseAlpha1.241.24
ServiceIPStaticSubrangetrueBeta1.25
ServiceInternalTrafficPolicyfalseAlpha1.211.21
ServiceInternalTrafficPolicytrueBeta1.22
SizeMemoryBackedVolumesfalseAlpha1.201.21
SizeMemoryBackedVolumestrueBeta1.22
StatefulSetAutoDeletePVCfalseAlpha1.22
StorageVersionAPIfalseAlpha1.20
StorageVersionHashfalseAlpha1.141.14
StorageVersionHashtrueBeta1.15
TopologyAwareHintsfalseAlpha1.211.22
TopologyAwareHintsfalseBeta1.231.23
TopologyAwareHintstrueBeta1.24
TopologyManagerfalseAlpha1.161.17
TopologyManagertrueBeta1.18
UserNamespacesStatelessPodsSupportfalseAlpha1.25
VolumeCapacityPriorityfalseAlpha1.21-
WinDSRfalseAlpha1.14
WinOverlayfalseAlpha1.141.19
WinOverlaytrueBeta1.20
WindowsHostProcessContainersfalseAlpha1.221.22
WindowsHostProcessContainerstrueBeta1.23

GraduatedまたはDeprecatedのフィーチャーゲート

GraduatedまたはDeprecatedのフィーチャーゲート
機能名デフォルト値ステージ導入開始バージョン最終利用可能バージョン
AcceleratorsfalseAlpha1.61.10
Accelerators-Deprecated1.11-
AdvancedAuditingfalseAlpha1.71.7
AdvancedAuditingtrueBeta1.81.11
AdvancedAuditingtrueGA1.12-
AffinityInAnnotationsfalseAlpha1.61.7
AffinityInAnnotations-Deprecated1.8-
AllowExtTrafficLocalEndpointsfalseBeta1.41.6
AllowExtTrafficLocalEndpointstrueGA1.7-
BlockVolumefalseAlpha1.91.12
BlockVolumetrueBeta1.131.17
BlockVolumetrueGA1.18-
CSIBlockVolumefalseAlpha1.111.13
CSIBlockVolumetrueBeta1.141.17
CSIBlockVolumetrueGA1.18-
CSIDriverRegistryfalseAlpha1.121.13
CSIDriverRegistrytrueBeta1.141.17
CSIDriverRegistrytrueGA1.18
CSINodeInfofalseAlpha1.121.13
CSINodeInfotrueBeta1.141.16
CSINodeInfotrueGA1.17
AttachVolumeLimitfalseAlpha1.111.11
AttachVolumeLimittrueBeta1.121.16
AttachVolumeLimittrueGA1.17-
CSIPersistentVolumefalseAlpha1.91.9
CSIPersistentVolumetrueBeta1.101.12
CSIPersistentVolumetrueGA1.13-
CustomPodDNSfalseAlpha1.91.9
CustomPodDNStrueBeta1.101.13
CustomPodDNStrueGA1.14-
CustomResourcePublishOpenAPIfalseAlpha1.141.14
CustomResourcePublishOpenAPItrueBeta1.151.15
CustomResourcePublishOpenAPItrueGA1.16-
CustomResourceSubresourcesfalseAlpha1.101.10
CustomResourceSubresourcestrueBeta1.111.15
CustomResourceSubresourcestrueGA1.16-
CustomResourceValidationfalseAlpha1.81.8
CustomResourceValidationtrueBeta1.91.15
CustomResourceValidationtrueGA1.16-
CustomResourceWebhookConversionfalseAlpha1.131.14
CustomResourceWebhookConversiontrueBeta1.151.15
CustomResourceWebhookConversiontrueGA1.16-
DynamicProvisioningSchedulingfalseAlpha1.111.11
DynamicProvisioningScheduling-Deprecated1.12-
DynamicVolumeProvisioningtrueAlpha1.31.7
DynamicVolumeProvisioningtrueGA1.8-
EnableAggregatedDiscoveryTimeouttrueDeprecated1.16-
EnableEquivalenceClassCachefalseAlpha1.81.14
EnableEquivalenceClassCache-Deprecated1.15-
ExperimentalCriticalPodAnnotationfalseAlpha1.51.12
ExperimentalCriticalPodAnnotationfalseDeprecated1.13-
GCERegionalPersistentDisktrueBeta1.101.12
GCERegionalPersistentDisktrueGA1.13-
HugePagesfalseAlpha1.81.9
HugePagestrueBeta1.101.13
HugePagestrueGA1.14-
InitializersfalseAlpha1.71.13
Initializers-Deprecated1.14-
KubeletConfigFilefalseAlpha1.81.9
KubeletConfigFile-Deprecated1.10-
KubeletPluginsWatcherfalseAlpha1.111.11
KubeletPluginsWatchertrueBeta1.121.12
KubeletPluginsWatchertrueGA1.13-
MountPropagationfalseAlpha1.81.9
MountPropagationtrueBeta1.101.11
MountPropagationtrueGA1.12-
NodeLeasefalseAlpha1.121.13
NodeLeasetrueBeta1.141.16
NodeLeasetrueGA1.17-
PersistentLocalVolumesfalseAlpha1.71.9
PersistentLocalVolumestrueBeta1.101.13
PersistentLocalVolumestrueGA1.14-
PodPriorityfalseAlpha1.81.10
PodPrioritytrueBeta1.111.13
PodPrioritytrueGA1.14-
PodReadinessGatesfalseAlpha1.111.11
PodReadinessGatestrueBeta1.121.13
PodReadinessGatestrueGA1.14-
PodShareProcessNamespacefalseAlpha1.101.11
PodShareProcessNamespacetrueBeta1.121.16
PodShareProcessNamespacetrueGA1.17-
PVCProtectionfalseAlpha1.91.9
PVCProtection-Deprecated1.10-
RequestManagementfalseAlpha1.151.16
ResourceQuotaScopeSelectorsfalseAlpha1.111.11
ResourceQuotaScopeSelectorstrueBeta1.121.16
ResourceQuotaScopeSelectorstrueGA1.17-
ScheduleDaemonSetPodsfalseAlpha1.111.11
ScheduleDaemonSetPodstrueBeta1.121.16
ScheduleDaemonSetPodstrueGA1.17-
ServiceLoadBalancerFinalizerfalseAlpha1.151.15
ServiceLoadBalancerFinalizertrueBeta1.161.16
ServiceLoadBalancerFinalizertrueGA1.17-
StorageObjectInUseProtectiontrueBeta1.101.10
StorageObjectInUseProtectiontrueGA1.11-
SupportIPVSProxyModefalseAlpha1.81.8
SupportIPVSProxyModefalseBeta1.91.9
SupportIPVSProxyModetrueBeta1.101.10
SupportIPVSProxyModetrueGA1.11-
TaintBasedEvictionsfalseAlpha1.61.12
TaintBasedEvictionstrueBeta1.131.17
TaintBasedEvictionstrueGA1.18-
TaintNodesByConditionfalseAlpha1.81.11
TaintNodesByConditiontrueBeta1.121.16
TaintNodesByConditiontrueGA1.17-
VolumePVCDataSourcefalseAlpha1.151.15
VolumePVCDataSourcetrueBeta1.161.17
VolumePVCDataSourcetrueGA1.18-
VolumeSchedulingfalseAlpha1.91.9
VolumeSchedulingtrueBeta1.101.12
VolumeSchedulingtrueGA1.13-
VolumeSchedulingfalseAlpha1.91.9
VolumeSchedulingtrueBeta1.101.12
VolumeSchedulingtrueGA1.13-
VolumeSubpathtrueGA1.13-
VolumeSubpathEnvExpansionfalseAlpha1.141.14
VolumeSubpathEnvExpansiontrueBeta1.151.16
VolumeSubpathEnvExpansiontrueGA1.17-
WatchBookmarkfalseAlpha1.151.15
WatchBookmarktrueBeta1.161.16
WatchBookmarktrueGA1.17-
WindowsGMSAfalseAlpha1.141.15
WindowsGMSAtrueBeta1.161.17
WindowsGMSAtrueGA1.18-
WindowsRunAsUserNamefalseAlpha1.161.16
WindowsRunAsUserNametrueBeta1.171.17
WindowsRunAsUserNametrueGA1.18-

機能を使用する

機能のステージ

機能にはAlphaBetaGA の段階があります。Alpha 機能とは:

  • デフォルトでは無効になっています。
  • バグがあるかもしれません。機能を有効にするとバグが発生する可能性があります。
  • 機能のサポートは予告無しにいつでも削除される場合があります。
  • APIは今後のソフトウェアリリースで予告なく互換性の無い変更が行われる場合があります。
  • バグが発生するリスクが高く長期的なサポートはないため、短期間のテストクラスターでのみ使用することをお勧めします。

Beta 機能とは:

  • デフォルトで有効になっています。
  • この機能は十分にテストされていて、有効にすることは安全と考えられます。
  • 詳細は変更される可能性がありますが、機能全体のサポートは削除されません。
  • オブジェクトのスキーマやセマンティックは、その後のベータ版または安定版リリースで互換性の無い変更が行われる場合があります。互換性の無い変更が行われた場合には次のバージョンへの移行手順を提供します。これにはAPIオブジェクトの削除、編集、および再作成が必要になる場合があります。バージョンアップにはいくつかの対応が必要な場合があります。これには機能に依存するアプリケーションのダウンタイムが発生する場合があります。
  • 今後のリリースで互換性の無い変更が行われる可能性があるため、ビジネスクリティカルでない使用のみが推奨されます。個別にアップグレードできる複数のクラスターがある場合はこの制限を緩和できる場合があります。

GA 機能とは(GA 機能は安定版 機能とも呼ばれます):

  • 機能は常に有効となり、無効にすることはできません。
  • フィーチャーゲートの設定は不要になります。
  • 機能の安定版は後続バージョンでリリースされたソフトウェアで使用されます。

フィーチャーゲート

各フィーチャーゲートは特定の機能を有効/無効にするように設計されています。

  • Accelerators: DockerでのNvidia GPUのサポートを有効にします。
  • AdvancedAuditing: 高度な監査機能を有効にします。
  • AffinityInAnnotations(非推奨): Podのアフィニティまたはアンチアフィニティを有効にします。
  • AnyVolumeDataSource: PVCDataSourceとしてカスタムリソースの使用を有効にします。
  • AllowExtTrafficLocalEndpoints: サービスが外部へのリクエストをノードのローカルエンドポイントにルーティングできるようにします。
  • APIListChunking: APIクライアントがAPIサーバーからチャンク単位で(LISTGETの)リソースを取得できるようにします。 APIPriorityAndFairness: 各サーバーで優先順位付けと公平性を備えた要求の並行性を管理できるようにします(RequestManagementから名前が変更されました)。
  • APIResponseCompression:LISTGETリクエストのAPIレスポンスを圧縮します。
  • AppArmor: Dockerを使用する場合にLinuxノードでAppArmorによる強制アクセスコントロールを有効にします。詳細はAppArmorチュートリアルで確認できます。
  • AttachVolumeLimit: ボリュームプラグインを有効にすることでノードにアタッチできるボリューム数の制限を設定できます。
  • BalanceAttachedNodeVolumes: スケジューリング中にバランスのとれたリソース割り当てを考慮するノードのボリュームカウントを含めます。判断を行う際に、CPU、メモリー使用率、およびボリュームカウントが近いノードがスケジューラーによって優先されます。
  • BlockVolume: PodでRawブロックデバイスの定義と使用を有効にします。詳細はRawブロックボリュームのサポートで確認できます。
  • BoundServiceAccountTokenVolume: ServiceAccountTokenVolumeProjectionによって構成される計画ボリュームを使用するにはServiceAccountボリュームを移行します。詳細はService Account Token Volumesで確認できます。
  • ConfigurableFSGroupPolicy: Podにボリュームをマウントするときに、ユーザーがfsGroupsのボリューム権限変更ポリシーを設定できるようにします。詳細については、Podのボリューム権限と所有権変更ポリシーの設定をご覧ください。
  • CPUManager: コンテナレベルのCPUアフィニティサポートを有効します。CPUマネジメントポリシーを見てください。
  • CRIContainerLogRotation: criコンテナランタイムのコンテナログローテーションを有効にします。
  • CSIBlockVolume: 外部CSIボリュームドライバーを有効にしてブロックストレージをサポートします。詳細はcsiRawブロックボリュームのサポートで確認できます。
  • CSIDriverRegistry: csi.storage.k8s.ioのCSIDriver APIオブジェクトに関連するすべてのロジックを有効にします。
  • CSIInlineVolume: PodのCSIインラインボリュームサポートを有効にします。
  • CSIMigration: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のプラグインから対応した事前インストール済みのCSIプラグインにルーティングします。
  • CSIMigrationAWS: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のAWS-EBSプラグインからEBS CSIプラグインにルーティングします。ノードにEBS CSIプラグインがインストールおよび設定されていない場合、ツリー内のEBSプラグインへのフォールバックをサポートします。CSIMigration機能フラグを有効にする必要があります。
  • CSIMigrationAWSComplete: EBSツリー内プラグインのkubeletおよびボリュームコントローラーへの登録を停止し、シムと変換ロジックを有効にして、AWS-EBSツリー内プラグインからEBS CSIプラグインにボリューム操作をルーティングします。CSIMigrationおよびCSIMigrationAWS機能フラグを有効にし、クラスター内のすべてのノードにEBS CSIプラグインをインストールおよび設定する必要があります。
  • CSIMigrationAzureDisk: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のAzure-DiskプラグインからAzure Disk CSIプラグインにルーティングします。ノードにAzureDisk CSIプラグインがインストールおよび設定されていない場合、ツリー内のAzureDiskプラグインへのフォールバックをサポートします。CSIMigration機能フラグを有効にする必要があります。
  • CSIMigrationAzureDiskComplete: Azure-Diskツリー内プラグインのkubeletおよびボリュームコントローラーへの登録を停止し、シムと変換ロジックを有効にして、Azure-Diskツリー内プラグインからAzureDisk CSIプラグインにボリューム操作をルーティングします。CSIMigrationおよびCSIMigrationAzureDisk機能フラグを有効にし、クラスター内のすべてのノードにAzureDisk CSIプラグインをインストールおよび設定する必要があります。
  • CSIMigrationAzureFile: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のAzure-FileプラグインからAzure File CSIプラグインにルーティングします。ノードにAzureFile CSIプラグインがインストールおよび設定されていない場合、ツリー内のAzureFileプラグインへのフォールバックをサポートします。CSIMigration機能フラグを有効にする必要があります。
  • CSIMigrationAzureFileComplete: Azure-Fileツリー内プラグインのkubeletおよびボリュームコントローラーへの登録を停止し、シムと変換ロジックを有効にして、Azure-Fileツリー内プラグインからAzureFile CSIプラグインにボリューム操作をルーティングします。CSIMigrationおよびCSIMigrationAzureFile機能フラグを有効にし、クラスター内のすべてのノードにAzureFile CSIプラグインをインストールおよび設定する必要があります。
  • CSIMigrationGCE: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のGCE-PDプラグインからPD CSIプラグインにルーティングします。ノードにPD CSIプラグインがインストールおよび設定されていない場合、ツリー内のGCEプラグインへのフォールバックをサポートします。CSIMigration機能フラグを有効にする必要があります。
  • CSIMigrationGCEComplete: GCE-PDのツリー内プラグインのkubeletおよびボリュームコントローラーへの登録を停止し、シムと変換ロジックがGCE-PDのツリー内プラグインからPD CSIプラグインにボリューム操作をルーティングできるようにします。CSIMigrationおよびCSIMigrationGCE機能フラグを有効にし、クラスター内のすべてのノードにPD CSIプラグインをインストールおよび設定する必要があります。
  • CSIMigrationOpenStack: シムと変換ロジックを有効にしてボリューム操作をKubernetesリポジトリー内のCinderプラグインからCinder CSIプラグインにルーティングします。ノードにCinder CSIプラグインがインストールおよび設定されていない場合、ツリー内のCinderプラグインへのフォールバックをサポートします。CSIMigration機能フラグを有効にする必要があります。
  • CSIMigrationOpenStackComplete: Cinderのツリー内プラグインのkubeletおよびボリュームコントローラーへの登録を停止し、シムと変換ロジックがCinderのツリー内プラグインからCinder CSIプラグインにボリューム操作をルーティングできるようにします。CSIMigrationおよびCSIMigrationOpenStack機能フラグを有効にし、クラスター内のすべてのノードにCinder CSIプラグインをインストールおよび設定する必要があります。
  • CSINodeInfo: csi.storage.k8s.ioのCSINodeInfo APIオブジェクトに関連するすべてのロジックを有効にします。
  • CSIPersistentVolume: CSI(Container Storage Interface)互換のボリュームプラグインを通してプロビジョニングされたボリュームの検出とマウントを有効にします。 詳細についてはcsiボリュームタイプドキュメントを確認してください。
  • CustomCPUCFSQuotaPeriod: ノードがCPUCFSQuotaPeriodを変更できるようにします。
  • CustomPodDNS: dnsConfigプロパティを使用したPodのDNS設定のカスタマイズを有効にします。詳細はPodのDNS構成で確認できます。
  • CustomResourceDefaulting: OpenAPI v3バリデーションスキーマにおいて、デフォルト値のCRDサポートを有効にします。
  • CustomResourcePublishOpenAPI: CRDのOpenAPI仕様での公開を有効にします。
  • CustomResourceSubresources: CustomResourceDefinitionから作成されたリソースの/statusおよび/scaleサブリソースを有効にします。
  • CustomResourceValidation: CustomResourceDefinitionから作成されたリソースのスキーマによる検証を有効にします。
  • CustomResourceWebhookConversion: CustomResourceDefinitionから作成されたリソースのWebhookベースの変換を有効にします。
  • DevicePlugins: device-pluginsによるノードでのリソースプロビジョニングを有効にします。
  • DryRun: サーバーサイドでのdry runリクエストを有効にします。
  • DynamicAuditing: 動的監査を有効にします。
  • DynamicKubeletConfig: kubeletの動的構成を有効にします。kubeletの再設定を参照してください。
  • DynamicProvisioningScheduling: デフォルトのスケジューラーを拡張してボリュームトポロジーを認識しPVプロビジョニングを処理します。この機能は、v1.12のVolumeScheduling機能に完全に置き換えられました。
  • DynamicVolumeProvisioning(非推奨): Podへの永続ボリュームの動的プロビジョニングを有効にします。
  • EnableAggregatedDiscoveryTimeout (非推奨): 集約されたディスカバリーコールで5秒のタイムアウトを有効にします。
  • EnableEquivalenceClassCache: Podをスケジュールするときにスケジューラーがノードの同等をキャッシュできるようにします。
  • EphemeralContainers: 稼働するPodにephemeral containersを追加する機能を有効にします。
  • EvenPodsSpread: Podをトポロジードメイン全体で均等にスケジュールできるようにします。Even Pods Spreadをご覧ください。
  • ExpandInUsePersistentVolumes: 使用中のPVCのボリューム拡張を有効にします。使用中のPersistentVolumeClaimのサイズ変更を参照してください。
  • ExpandPersistentVolumes: 永続ボリュームの拡張を有効にします。永続ボリューム要求の拡張を参照してください。
  • ExperimentalCriticalPodAnnotation: スケジューリングが保証されるように特定のPodへの クリティカル の注釈を加える設定を有効にします。
  • ExperimentalHostUserNamespaceDefaultingGate: ホストするデフォルトのユーザー名前空間を有効にします。これは他のホストの名前空間やホストのマウントを使用しているコンテナ、特権を持つコンテナ、または名前空間のない特定の機能(たとえばMKNODESYS_MODULEなど)を使用しているコンテナ用です。これはDockerデーモンでユーザー名前空間の再マッピングが有効になっている場合にのみ有効にすべきです。
  • EndpointSlice: よりスケーラブルで拡張可能なネットワークエンドポイントのエンドポイントスライスを有効にします。Enabling Endpoint Slicesをご覧ください。
  • EndpointSliceProxying: このフィーチャーゲートを有効にすると、kube-proxyはエンドポイントの代わりにエンドポイントスライスをプライマリデータソースとして使用し、スケーラビリティとパフォーマンスの向上を実現します。Enabling Endpoint Slices.をご覧ください。
  • GCERegionalPersistentDisk: GCEでリージョナルPD機能を有効にします。
  • HugePages: 事前に割り当てられたhuge pagesの割り当てと消費を有効にします。
  • HugePageStorageMediumSize: 事前に割り当てられた複数のサイズのhuge pagesのサポートを有効にします。
  • HyperVContainer: WindowsコンテナのHyper-Vによる分離を有効にします。
  • HPAScaleToZero: カスタムメトリクスまたは外部メトリクスを使用するときに、HorizontalPodAutoscalerリソースのminReplicasを0に設定できるようにします。
  • ImmutableEphemeralVolumes: 安全性とパフォーマンスを向上させるために、個々のSecretとConfigMapが不変となるように指定できるようにします。
  • KubeletConfigFile: 設定ファイルを使用して指定されたファイルからのkubelet設定の読み込みを有効にします。詳細は設定ファイルによるkubeletパラメーターの設定で確認できます。
  • KubeletPluginsWatcher: 調査ベースのプラグイン監視ユーティリティを有効にしてkubeletがCSIボリュームドライバーなどのプラグインを検出できるようにします。
  • KubeletPodResources: kubeletのPodのリソースgrpcエンドポイントを有効にします。詳細はデバイスモニタリングのサポートで確認できます。
  • LegacyNodeRoleBehavior: 無効にすると、サービスロードバランサーの従来の動作とノードの中断により機能固有のラベルが優先され、node-role.kubernetes.io/masterラベルが無視されます。
  • LocalStorageCapacityIsolation: ローカルの一時ストレージの消費を有効にして、emptyDirボリュームsizeLimitプロパティも有効にします。
  • LocalStorageCapacityIsolationFSQuotaMonitoring: LocalStorageCapacityIsolationローカルの一時ストレージで有効になっていて、emptyDirボリュームのbacking filesystemがプロジェクトクォータをサポートし有効になっている場合、プロジェクトクォータを使用して、パフォーマンスと精度を向上させるために、ファイルシステムへのアクセスではなくemptyDirボリュームストレージ消費を監視します。
  • MountContainers: ホスト上のユーティリティコンテナをボリュームマウンターとして使用できるようにします。
  • MountPropagation: あるコンテナによってマウントされたボリュームを他のコンテナまたはPodに共有できるようにします。詳細はマウントの伝播で確認できます。
  • NodeDisruptionExclusion: ノードラベルnode.kubernetes.io/exclude-disruptionの使用を有効にします。これにより、ゾーン障害時にノードが退避するのを防ぎます。
  • NodeLease: 新しいLease APIを有効にしてノードヘルスシグナルとして使用できるノードのハートビートをレポートします。
  • NonPreemptingPriority: PriorityClassとPodのNonPreemptingオプションを有効にします。
  • PersistentLocalVolumes: Podでlocalボリュームタイプの使用を有効にします。localボリュームを要求する場合、Podアフィニティを指定する必要があります。
  • PodOverhead: PodOverhead機能を有効にして、Podのオーバーヘッドを考慮するようにします。
  • PodDisruptionBudget: PodDisruptionBudget機能を有効にします。
  • PodPriority: 優先度に基づいてPodの再スケジューリングとプリエンプションを有効にします。
  • PodReadinessGates: Podのreadinessの評価を拡張するためにPodReadinessGateフィールドの設定を有効にします。詳細はPod readiness gateで確認できます。
  • PodShareProcessNamespace: Podで実行されているコンテナ間で単一のプロセス名前空間を共有するには、PodでshareProcessNamespaceの設定を有効にします。詳細については、Pod内のコンテナ間でプロセス名前空間を共有するをご覧ください。
  • ProcMountType: コンテナのProcMountTypeの制御を有効にします。
  • PVCProtection: 永続ボリューム要求(PVC)がPodでまだ使用されているときに削除されないようにします。詳細はここで確認できます。
  • QOSReserved: QoSレベルでのリソース予約を許可して、低いQoSレベルのポッドが高いQoSレベルで要求されたリソースにバーストするのを防ぎます(現時点ではメモリのみ)。
  • ResourceLimitsPriorityFunction: 入力したPodのCPU制限とメモリ制限の少なくとも1つを満たすノードに対して最低スコアを1に割り当てるスケジューラー優先機能を有効にします。その目的は同じスコアを持つノード間の関係を断つことです。
  • ResourceQuotaScopeSelectors: リソース割当のスコープセレクターを有効にします。
  • RotateKubeletClientCertificate: kubeletでクライアントTLS証明書のローテーションを有効にします。詳細はkubeletの設定で確認できます。
  • RotateKubeletServerCertificate: kubeletでサーバーTLS証明書のローテーションを有効にします。詳細はkubeletの設定で確認できます。
  • RunAsGroup: コンテナの初期化プロセスで設定されたプライマリグループIDの制御を有効にします。
  • RuntimeClass: コンテナのランタイム構成を選択するにはRuntimeClass機能を有効にします。
  • ScheduleDaemonSetPods: DaemonSetのPodをDaemonSetコントローラーではなく、デフォルトのスケジューラーによってスケジュールされるようにします。
  • SCTPSupport: ServiceEndpointsNetworkPolicyPodの定義でprotocolの値としてSCTPを使用できるようにします
  • ServerSideApply: APIサーバーでサーバーサイドApply(SSA)のパスを有効にします。
  • ServiceAccountIssuerDiscovery: APIサーバーにてサービスアカウント発行者のOIDC検出エンドポイント(発行者とJWKS URL)を有効にします。詳細については、Podのサービスアカウント設定をご覧ください。
  • ServiceAppProtocol: サービスとエンドポイントでAppProtocolフィールドを有効にします。
  • ServiceLoadBalancerFinalizer: サービスロードバランサーのファイナライザー保護を有効にします。
  • ServiceNodeExclusion: クラウドプロバイダーによって作成されたロードバランサーからのノードの除外を有効にします。"alpha.service-controller.kubernetes.io/exclude-balancer"キーまたはnode.kubernetes.io/exclude-from-external-load-balancersでラベル付けされている場合ノードは除外の対象となります。
  • ServiceTopology: クラスタのノードトポロジーに基づいてトラフィックをルーティングするサービスを有効にします。詳細については、Serviceトポロジーを参照してください。
  • StartupProbe: kubeletでstartupプローブを有効にします。
  • StorageObjectInUseProtection: PersistentVolumeまたはPersistentVolumeClaimオブジェクトがまだ使用されている場合、それらの削除を延期します。
  • StorageVersionHash: apiserversがディスカバリーでストレージのバージョンハッシュを公開できるようにします。
  • StreamingProxyRedirects: ストリーミングリクエストのバックエンド(kubelet)からのリダイレクトをインターセプト(およびフォロー)するようAPIサーバーに指示します。ストリーミングリクエストの例にはexecattachport-forwardリクエストが含まれます。
  • SupportIPVSProxyMode: IPVSを使用したクラスター内サービスの負荷分散の提供を有効にします。詳細はサービスプロキシーで確認できます。
  • SupportPodPidsLimit: PodのPID制限のサポートを有効にします。
  • Sysctls: 各Podに設定できる名前空間付きのカーネルパラメーター(sysctl)のサポートを有効にします。詳細はsysctlsで確認できます。
  • TaintBasedEvictions: ノードのTaintとPodのTolerationに基づいてノードからPodを排除できるようにします。。詳細はTaintとTolerationで確認できます。
  • TaintNodesByCondition: ノードの条件に基づいてノードの自動Taintを有効にします。
  • TokenRequest: サービスアカウントリソースでTokenRequestエンドポイントを有効にします。
  • TokenRequestProjection: Projectedボリュームを使用したPodへのサービスアカウントのトークンの注入を有効にします。
  • TTLAfterFinished: TTLコントローラーが実行終了後にリソースをクリーンアップできるようにします。
  • VolumePVCDataSource: 既存のPVCをデータソースとして指定するサポートを有効にします。
  • VolumeScheduling: ボリュームトポロジー対応のスケジューリングを有効にし、PersistentVolumeClaim(PVC)バインディングにスケジューリングの決定を認識させます。またPersistentLocalVolumesフィーチャーゲートと一緒に使用するとlocalボリュームタイプの使用が可能になります。
  • VolumeSnapshotDataSource: ボリュームスナップショットのデータソースサポートを有効にします。
  • VolumeSubpathEnvExpansion: 環境変数をsubPathに展開するためのsubPathExprフィールドを有効にします。
  • WatchBookmark: ブックマークイベントの監視サポートを有効にします。
  • WindowsGMSA: GMSA資格仕様をPodからコンテナランタイムに渡せるようにします。
  • WindowsRunAsUserName: デフォルト以外のユーザーでWindowsコンテナアプリケーションを実行するためのサポートを有効にします。詳細については、RunAsUserNameの設定を参照してください。
  • WinDSR: kube-proxyがWindows用のDSRロードバランサーを作成できるようにします。
  • WinOverlay: kube-proxyをWindowsのオーバーレイモードで実行できるようにします。

次の項目

  • Kubernetesの非推奨ポリシーでは、機能とコンポーネントを削除するためのプロジェクトのアプローチを説明しています。

6.2 - Kubelet 認証/認可

概要

kubeletのHTTPSエンドポイントは、さまざまな感度のデータへのアクセスを提供するAPIを公開し、 ノードとコンテナ内のさまざまなレベルの権限でタスクを実行できるようにします。

このドキュメントでは、kubeletのHTTPSエンドポイントへのアクセスを認証および承認する方法について説明します。

Kubelet 認証

デフォルトでは、他の構成済み認証方法によって拒否されないkubeletのHTTPSエンドポイントへのリクエストは 匿名リクエストとして扱われ、ユーザー名はsystem:anonymous、 グループはsystem:unauthenticatedになります。

匿名アクセスを無効にし、認証されていないリクエストに対して401 Unauthorized応答を送信するには:

  • --anonymous-auth=falseフラグでkubeletを開始します。

kubeletのHTTPSエンドポイントに対するX509クライアント証明書認証を有効にするには:

  • --client-ca-fileフラグでkubeletを起動し、クライアント証明書を確認するためのCAバンドルを提供します。
  • --kubelet-client-certificateおよび--kubelet-client-keyフラグを使用してapiserverを起動します。
  • 詳細については、apiserver認証ドキュメントを参照してください。

APIベアラートークン(サービスアカウントトークンを含む)を使用して、kubeletのHTTPSエンドポイントへの認証を行うには:

  • APIサーバーでauthentication.k8s.io/v1beta1グループが有効になっていることを確認します。
  • --authentication-token-webhookおよび--kubeconfigフラグを使用してkubeletを開始します。
  • kubeletは、構成済みのAPIサーバーで TokenReview APIを呼び出して、ベアラートークンからユーザー情報を判別します。

Kubelet 承認

認証に成功した要求(匿名要求を含む)はすべて許可されます。デフォルトの認可モードは、すべての要求を許可するAlwaysAllowです。

kubelet APIへのアクセスを細分化するのは、次のような多くの理由が考えられます:

  • 匿名認証は有効になっていますが、匿名ユーザーがkubeletのAPIを呼び出す機能は制限する必要があります。
  • ベアラートークン認証は有効になっていますが、kubeletのAPIを呼び出す任意のAPIユーザー(サービスアカウントなど)の機能を制限する必要があります。
  • クライアント証明書の認証は有効になっていますが、構成されたCAによって署名されたクライアント証明書の一部のみがkubeletのAPIの使用を許可されている必要があります。

kubeletのAPIへのアクセスを細分化するには、APIサーバーに承認を委任します:

  • APIサーバーでauthorization.k8s.io/v1beta1 APIグループが有効になっていることを確認します。
  • --authorization-mode=Webhook--kubeconfigフラグでkubeletを開始します。
  • kubeletは、構成されたAPIサーバーでSubjectAccessReview APIを呼び出して、各リクエストが承認されているかどうかを判断します。

kubeletは、apiserverと同じリクエスト属性アプローチを使用してAPIリクエストを承認します。

動詞は、受けとったリクエストのHTTP動詞から決定されます:

HTTP動詞要求 動詞
POSTcreate
GET, HEADget
PUTupdate
PATCHpatch
DELETEdelete

リソースとサブリソースは、受けとったリクエストのパスから決定されます:

Kubelet APIリソースサブリソース
/stats/*nodesstats
/metrics/*nodesmetrics
/logs/*nodeslog
/spec/*nodesspec
all othersnodesproxy

名前空間とAPIグループの属性は常に空の文字列であり、 リソース名は常にkubeletのNode APIオブジェクトの名前です。

このモードで実行する場合は、apiserverに渡される--kubelet-client-certificateフラグと--kubelet-client-key フラグで識別されるユーザーが次の属性に対して許可されていることを確認します:

  • verb=*, resource=nodes, subresource=proxy
  • verb=*, resource=nodes, subresource=stats
  • verb=*, resource=nodes, subresource=log
  • verb=*, resource=nodes, subresource=spec
  • verb=*, resource=nodes, subresource=metrics

7 - RBAC認可を使用する

Role Based Access Control(RBAC)は、組織内の個々のユーザーのRoleをベースに、コンピューターまたはネットワークリソースへのアクセスを制御する方法です。

RBAC認可はAPI Group rbac.authorization.k8s.ioを使用して認可の決定を行い、Kubernetes APIを介して動的にポリシーを構成できるようにします。

RBACを有効にするには、以下の例のようにAPI server--authorization-mode フラグをコンマ区切りのRBACを含むリストでスタートします。

kube-apiserver --authorization-mode=Example,RBAC --other-options --more-options

APIオブジェクト

RBAC APIは4種類のKubernetesオブジェクト(RoleClusterRoleRoleBinding そして ClusterRoleBinding)を宣言します。他のKubernetesオブジェクトのようにkubectlのようなツールを使って、オブジェクトを記述、または変更できます。

RoleとClusterRole

RBACの Role または ClusterRole には、一連の権限を表すルールが含まれて言います。 権限は完全な追加方式です(「deny」のルールはありません)。

Roleは常に特定のnamespaceで権限を設定します。 つまり、Roleを作成する時は、Roleが属するNamespaceを指定する必要があります。

対照的にClusterRoleは、Namespaceに属さないリソースです。Kubernetesオブジェクトは常にNamespaceに属するか、属さないかのいずれかである必要があり、リソースは異なる名前(RoleとClusterRole)を持っています。つまり、両方であることは不可能です。

ClusterRolesにはいくつかの用途があります。ClusterRoleを利用して、以下のことができます。

  1. Namespaceに属するリソースに対する権限を定義し、個々のNamespace内で付与する
  2. Namespaceに属するリソースに対する権限を定義し、すべてのNamespaceにわたって付与する
  3. クラスター単位でスコープされているリソースに対するアクセス許可を定義する

NamespaceでRoleを定義する場合は、Roleを使用します。クラスター全体でRoleを定義する場合は、ClusterRoleを使用します

Roleの例

以下はNamespace「default」にあるRoleの例で、 Podへの読み取りアクセス権の付与に使用できます。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-reader
rules:
- apiGroups: [""] # "" はコアのAPIグループを示します
  resources: ["pods"]
  verbs: ["get", "watch", "list"]

ClusterRoleの例

ClusterRoleを使用してRoleと同じ権限を付与できます。 ClusterRolesはクラスター単位でスコープされているため、以下へのアクセスの許可もできます。

  • クラスター単位でスコープされているリソースに(nodeなど)
  • 非リソースエンドポイントに(/healthzなど)
  • すべてのNamespaceに渡ってNamespaceに属するリソースに(Podなど)。 例えば、ClusterRoleを使用して特定のユーザーにkubectl get pods --all-namespacesの実行を許可できます。

以下は特定のNamespace、またはすべてのNamespace(バインド方法によります)でsecretsへの読み取りアクセス権を付与するClusterRoleの例です。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  # 「namespace」はClusterRolesがNamespaceに属していないため、省略されています
  name: secret-reader
rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、Secretにアクセスするリソースの名前
  # オブジェクトは"secrets"
  resources: ["secrets"]
  verbs: ["get", "watch", "list"]

RoleまたはClusterRoleオブジェクトの名前は有効な パスセグメント名である必要があります。

RoleBindingとClusterRoleBinding

RoleBindingはRoleで定義された権限をユーザーまたはユーザのセットに付与します。 RoleBindingはsubjects (ユーザー、グループ、サービスアカウント)のリストと、付与されるRoleへの参照を保持します。 RoleBindingは特定のNamespace内の権限を付与しますが、ClusterRoleBindingはクラスター全体にアクセスする権限を付与します。

RoleBindingは、同じNamespace内の任意のRoleを参照できます。 または、RoleBindingはClusterRoleを参照し、そのClusterRoleをRoleBindingのNamespaceにバインドできます。 ClusterRoleをクラスター内のすべてのNamespaceにバインドする場合は、ClusterRoleBindingを使用します。

RoleBindingまたはClusterRoleBindingオブジェクトは有効な パスセグメント名である必要があります。

RoleBindingの例

以下はNamespace「default」内でユーザー「jane」に「pod-reader」のRoleを付与するRoleBindingの例です。 これにより、「jane」にNamespace「default」のポッドの読み取り許可されます。

apiVersion: rbac.authorization.k8s.io/v1
# このRoleBindingは「jane」にNamespace「default」のポッドの読み取りを許可する
# そのNamespaceでRole「pod-reader」を既に持っている必要があります。
kind: RoleBinding
metadata:
  name: read-pods
  namespace: default
subjects:
# 一つ以上の「subject」を指定する必要があります
- kind: User
  name: jane # 「name」は大文字と小文字が区別されます
  apiGroup: rbac.authorization.k8s.io
roleRef:
  # 「roleRef」はRole/ClusterRoleへのバインドを指定します
  kind: Role #RoleまたはClusterRoleである必要があります
  name: pod-reader # これはバインドしたいRole名またはClusterRole名とマッチする必要があります
  apiGroup: rbac.authorization.k8s.io

RoleBindingはClusterRoleを参照し、ClusterRoleで定義されている権限をRoleBinding内のNamespaceのリソースに権限付与もできます。この種類の参照を利用すると、クラスター全体で共通のRoleのセットを定義して、それらを複数のNamespace内での再利用できます。

例えば、以下のRoleBindingがClusterRoleを参照している場合でも、 「dave」(大文字と小文字が区別されるsubject)はRoleBindingのNamespace(メタデータ内)が「development」のため、Namespace「development」のSecretsのみの読み取りができます。

apiVersion: rbac.authorization.k8s.io/v1
# このRoleBindingは「dave」にNamespace「development」のSecretsの読み取りを許可する
# ClusterRole「secret-reader」を既に持っている必要があります。
kind: RoleBinding
metadata:
  name: read-secrets
  #
  # RoleBindingのNamespaceが、どこの権限が付与されるかを決定する。
  # これはNamespace「development」内の権限のみ付与する。
  namespace: development
subjects:
- kind: User
  name: dave # nameは大文字、小文字を区別する
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

ClusterRoleBindingの例

クラスター全体に権限を付与するには、ClusterRoleBindingを使用できます。 以下のClusterRoleBindingはグループ「manager」のすべてのユーザーに Secretsの読み取りを許可します。

apiVersion: rbac.authorization.k8s.io/v1
# このClusterRoleBindingはグループ「manager」のすべてのユーザーに任意のNamespaceのSecretsの読み取りを許可します。
kind: ClusterRoleBinding
metadata:
  name: read-secrets-global
subjects:
- kind: Group
  name: manager # nameは大文字、小文字を区別します
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

Bindingを作成後は、それが参照するRoleまたはClusterRoleを変更できません。 BindingのroleRefを変更しようとすると、バリデーションエラーが発生します。BindingのroleRefを変更する場合は、Bindingのオブジェクトを削除して、代わりのオブジェクトを作成する必要があります。

この制限には2つの理由があります。

  1. roleRefをイミュータブルにすることで、誰かに既存のオブジェクトに対するupdate権限を付与します。それにより、subjectsに付与されたRoleの変更ができなくても、subjectsのリストを管理できるようになります。
  2. 異なるRoleへのBindingは根本的に異なるBindingです。 roleRefを変更するためにBindingの削除/再作成を要求することによって、(すべての既存のsubjectsを確認せずに、roleRefだけを誤って変更できるようにするのとは対照的に)Binding内のsubjectsのリストのすべてが意図された新しいRoleが付与されることを担保します。

kubectl auth reconcile コマンドラインユーティリティーはRBACオブジェクトを含んだマニフェストファイルを作成または更新します。また、それらが参照しているRoleへの変更を要求されると、Bindingオブジェクトの削除と再作成を取り扱います。 詳細はcommand usage and examplesを確認してください。

リソースを参照する

KubernetesのAPIでは、ほとんどのリソースはPodであればpodsのように、オブジェクト名の文字列表現を使用して表されます。RBACは、関連するAPIエンドポイントのURLに表示されるものとまったく同じ名前を使用するリソースを参照します。 一部のKubernetes APIには、Podのログなどの subresource が含まれます。Podのログのリクエストは次のようになります。

GET /api/v1/namespaces/{namespace}/pods/{name}/log

この場合、pods はPodリソースのNamespaceに属するリソースであり、logpodsのサブリソースです。これをRBACRoleで表すには、スラッシュ(/)を使用してリソースとサブリソースを区切ります。サブジェクトへのpodsの読み込みと各Podのlogサブリソースへのアクセスを許可するには、次のように記述します。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: pod-and-pod-logs-reader
rules:
- apiGroups: [""]
  resources: ["pods", "pods/log"]
  verbs: ["get", "list"]

resourceNamesリストを通じて、特定のリクエストのリソースを名前で参照することもできます。 指定すると、リクエストをリソースの個々のインスタンスに制限できます。 以下は対象をgetまたはmy-configmapと名付けられた ConfigMapupdateのみに制限する例です。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: default
  name: configmap-updater
rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、ConfigMapにアクセスするリソースの名前
  # オブジェクトは"configmaps"
  resources: ["configmaps"]
  resourceNames: ["my-configmap"]
  verbs: ["update", "get"]

集約ClusterRole

複数のClusterRoleを一つのClusterRoleに 集約 できます。 クラスターコントロールプレーンの一部として実行されるコントローラーは、aggregationRuleセットを持つClusterRoleオブジェクトを監視します。aggregationRuleはコントローラーが、このオブジェクトのrulesフィールドに結合する必要のある他のClusterRoleオブジェクトを一致させるために使用するラベルselectorを定義します。

以下に、集約されたClusterRoleの例を示します。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring
aggregationRule:
  clusterRoleSelectors:
  - matchLabels:
      rbac.example.com/aggregate-to-monitoring: "true"
rules: [] # コントロールプレーンは自動的にルールを入力します

既存の集約されたClusterRoleのラベルセレクターと一致する新しいClusterRoleを作成すると、その変更をトリガーに、集約されたClusterRoleに新しいルールが追加されます。 rbac.example.com/aggregate-to-monitoring: trueラベルが付けられた別のClusterRoleを作成して、ClusterRole「monitoring」にルールを追加する例を以下に示します。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: monitoring-endpoints
  labels:
    rbac.example.com/aggregate-to-monitoring: "true"
# ClusterRole「monitoring-endpoints」を作成すると、
# 以下のルールがClusterRole「monitoring」に追加されます
rules:
- apiGroups: [""]
  resources: ["services", "endpoints", "pods"]
  verbs: ["get", "list", "watch"]

デフォルトのユーザー向けRoleはClusterRoleの集約を使用します。これによりクラスター管理者として、 デフォルトroleを拡張するため、CustomResourceDefinitionsまたは集約されたAPIサーバーなどによって提供されたルールをカスタムリソースに含めることができます。

例えば、次のClusterRoleでは、「admin」と「edit」のデフォルトのRoleでCronTabという名前のカスタムリソースを管理できますが、「view」のRoleではCronTabリソースに対して読み取りアクションのみを実行できます。CronTabオブジェクトは、APIサーバーから見たURLで"crontabs"と名前が付けられていると想定できます。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: aggregate-cron-tabs-edit
  labels:
    # デフォルトRoleの「admin」と「edit」にこれらの権限を追加する。
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
rules:
- apiGroups: ["stable.example.com"]
  resources: ["crontabs"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]
---
kind: ClusterRole
apiVersion: rbac.authorization.k8s.io/v1
metadata:
  name: aggregate-cron-tabs-view
  labels:
    # デフォルトRoleの「view」にこれらの権限を追加します。
    rbac.authorization.k8s.io/aggregate-to-view: "true"
rules:
- apiGroups: ["stable.example.com"]
  resources: ["crontabs"]
  verbs: ["get", "list", "watch"]

Roleの例

次の例は、RoleオブジェクトまたはClusterRoleオブジェクトからの抜粋であり、rulesセクションのみを示しています。

"pods"の読み取りを許可する API Group

rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、Podにアクセスするリソースの名前
  # オブジェクトは"pods"
  resources: ["pods"]
  verbs: ["get", "list", "watch"]

APIグループ" extensions "" apps " の両方で、Deploymentsへの読み取り/書き込みを許可します。 (HTTPレベルでURLのリソース部分に"deployments"を持つオブジェクトで)

rules:
- apiGroups: ["extensions", "apps"]
  #
  # HTTPレベルでの、Deploymentにアクセスするリソースの名前
  # オブジェクトは"deployments"
  resources: ["deployments"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

コアAPIグループのPodの読み取り、および"batch"または"extensions"APIグループのJobリソースの読み取りまたは書き込みを許可します。

rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、Podにアクセスするリソースの名前
  # オブジェクトは"pods"
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["batch", "extensions"]
  #
  # HTTPレベルでの、Jobにアクセスするリソースの名前
  # オブジェクトは"jobs"
  resources: ["jobs"]
  verbs: ["get", "list", "watch", "create", "update", "patch", "delete"]

「my-config」という名前のConfigMapの読み取りを許可します( 単一のNamespace内の単一のConfigMapに制限するRoleBinding)

rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、ConfigMapにアクセスするリソースの名前
  # オブジェクトは"configmaps"
  resources: ["configmaps"]
  resourceNames: ["my-config"]
  verbs: ["get"]

コアグループ内のリソース "nodes"の読み取りを許可します(Nodeはクラスタースコープであり、ClusterRoleBindingが効果的であるため、ClusterRoleにバインドされている必要があります)。

rules:
- apiGroups: [""]
  #
  # HTTPレベルでの、Nodeにアクセスするリソースの名前
  # オブジェクトは"nodes"
  resources: ["nodes"]
  verbs: ["get", "list", "watch"]

非リソースエンドポイント / healthzおよびすべてのサブパス(ClusterRoleBindingが効果的であるため、ClusterRoleにバインドされている必要があります)のGETおよびPOSTリクエストを許可します。

rules:
- nonResourceURLs: ["/healthz", "/healthz/*"] # nonResourceURLの「*」はサフィックスグロブマッチです
  verbs: ["get", "post"]

subjectsを参照する

RoleBindingまたはClusterRoleBindingは、Roleをsubjectsにバインドします。subjectsはグループ、ユーザー、またはServiceAccountsにすることができます。

Kubernetesはユーザー名を文字列として表します。 これらは次のようにできます。「alice」などの単純な名前。「bob@example.com」のような電子メール形式の名前。または文字列として表される数値のユーザーID。 認証が必要な形式のユーザー名を生成するように認証モジュールを構成するかどうかは、クラスター管理者が決定します。

Kubernetesでは、Authenticatorモジュールがグループ情報を提供します。 ユーザーと同様に、グループは文字列として表され、その文字列には、プレフィックスsystem:が予約されていることを除いて、フォーマット要件はありません。

ServiceAccountの名前はプレフィックスsystem:serviceaccount:が付いており、名前のプレフィックスsystem:serviceaccounts:が付いているグループに属しています。

RoleBindingの例

次の例はRoleBindingsubjectsセクションのみを示す抜粋です。

alice@example.comという名前のユーザーの場合。

subjects:
- kind: User
  name: "alice@example.com"
  apiGroup: rbac.authorization.k8s.io

frontend-adminsという名前のグループの場合。

subjects:
- kind: Group
  name: "frontend-admins"
  apiGroup: rbac.authorization.k8s.io

Namespace「kube-system」のデフォルトのサービスアカウントの場合。

subjects:
- kind: ServiceAccount
  name: default
  namespace: kube-system

Namespace「qa」の全てのサービスアカウントの場合。

subjects:
- kind: Group
  name: system:serviceaccounts:qa
  apiGroup: rbac.authorization.k8s.io

任意のNamespaceの全てのサービスアカウントの場合。

subjects:
- kind: Group
  name: system:serviceaccounts
  apiGroup: rbac.authorization.k8s.io

すべての認証済みユーザーの場合。

subjects:
- kind: Group
  name: system:authenticated
  apiGroup: rbac.authorization.k8s.io

認証されていないすべてのユーザーの場合。

subjects:
- kind: Group
  name: system:unauthenticated
  apiGroup: rbac.authorization.k8s.io

すべてのユーザーの場合。

subjects:
- kind: Group
  name: system:authenticated
  apiGroup: rbac.authorization.k8s.io
- kind: Group
  name: system:unauthenticated
  apiGroup: rbac.authorization.k8s.io

デフォルトRoleとClusterRoleBinding

APIサーバーは、デフォルトのClusterRoleオブジェクトとClusterRoleBindingオブジェクトのセットを作成します。 これらの多くにはプレフィックスsystem:が付いています。これは、リソースがクラスターコントロールプレーンによって直接管理されることを示しています。 デフォルトのすべてのClusterRoleおよびClusterRoleBindingには、ラベルkubernetes.io/bootstrapping=rbac-defaultsが付いています。

自動調整

起動するたびに、APIサーバーはデフォルトのClusterRoleを不足している権限で更新し、 デフォルトのClusterRoleBindingを不足しているsubjectsで更新します。 これにより、誤った変更をクラスタが修復できるようになり、新しいKubernetesリリースで権限とsubjectsが変更されても、 RoleとRoleBindingを最新の状態に保つことができます。

この調整を無効化するにはrbac.authorization.kubernetes.io/autoupdateをデフォルトのClusterRoleまたはRoleBindingのアノテーションをfalseに設定します。 デフォルトの権限と subjectsがないと、クラスターが機能しなくなる可能性があることに注意してください。

RBAC authorizerが有効な場合、自動調整はデフォルトで有効になっています。

APIディスカバリーRole

デフォルトのRoleBindingでは、認証されていないユーザーと認証されたユーザーが、パブリックアクセスが安全であると見なされるAPI情報(CustomResourceDefinitionを含む)の読み取りを認可しています。匿名の非認証アクセスを無効にするには、APIサーバー構成に--anonymous-auth=false 追加します。

kubectlの実行によってこれらのRoleの構成を表示するには。

kubectl get clusterroles system:discovery -o yaml
Kubernetes RBAC APIディスカバリーRole
デフォルトのClusterRoleデフォルトのClusterRoleBinding説明
system:basic-usersystem:authenticated groupユーザーに、自身に関する基本情報への読み取り専用アクセスを許可します。v1.14より前は、このRoleはデフォルトでsystem:unauthenticatedにもバインドされていました。
system:discoverysystem:authenticated groupAPIレベルのディスカバリーとネゴシエーションに必要なAPIディスカバリーエンドポイントへの読み取り専用アクセスを許可します。v1.14より前は、このRoleはデフォルトでsystem:unauthenticatedにもバインドされていました。
system:public-info-viewersystem:authenticated and system:unauthenticated groupsクラスターに関する機密情報以外への読み取り専用アクセスを許可します。Kubernetes v1.14で導入されました。

ユーザー向けRole

一部のデフォルトClusterRolesにはプレフィックスsystem:が付いていません。これらは、ユーザー向けのroleを想定しています。それらは、スーパーユーザのRole(cluster-admin)、ClusterRoleBindingsを使用してクラスタ全体に付与されることを意図しているRole、そしてRoleBindings(admin, edit, view)を使用して、特定のNamespace内に付与されることを意図しているRoleを含んでいます。

ユーザー向けのClusterRolesはClusterRoleの集約を使用して、管理者がこれらのClusterRolesにカスタムリソースのルールを含めることができるようにします。ルールをadminedit、またはview Roleに追加するには、次のラベルの一つ以上でClusterRoleを作成します。

metadata:
  labels:
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-view: "true"

デフォルトのClusterRoleデフォルトのClusterRoleBinding説明
cluster-adminsystem:masters groupスーパーユーザーが任意のリソースで任意のアクションを実行できるようにします。 ClusterRoleBindingで使用すると、クラスター内およびすべてのNamespace内のすべてのリソースを完全に制御できます。 RoleBindingで使用すると、Namespace自体を含む、RoleBindingのNamespace内のすべてのリソースを完全に制御できます。
adminNoneRoleBindingを使用してNamespace内で付与することを想定した、管理者アクセスを許可します。 RoleBindingで使用した場合、Namespace内にRoleとRoleBindingを作成する機能を含め、Namespaceのほとんどのリソースへの読み取り/書き込みアクセスを許可します。 このRoleは、リソースクォータまたはNamespace自体への書き込みアクセスを許可しません。
editNoneNamespace内のほとんどのオブジェクトへの読み取り/書き込みアクセスを許可します。

このRoleは、RoleまたはRoleBindingの表示または変更を許可しません。 ただし、このRoleでは、Secretsにアクセスして、Namespace内の任意のServiceAccountとしてPodsを実行できるため、Namespace内の任意のServiceAccountのAPIアクセスレベルを取得するために使用できます。

viewNoneNamespace内のほとんどのオブジェクトを表示するための読み取り専用アクセスを許可します。 RoleまたはRoleBindingは表示できません。

Secretsの内容を読み取るとNamespaceのServiceAccountのクレデンシャルにアクセスできるため、このRoleではSecretsの表示は許可されません。これにより、Namespace内の任意のServiceAccountとしてAPIアクセスが許可されます(特権昇格の形式)。

コアコンポーネントのRole

デフォルトのClusterRoleデフォルトのClusterRoleBinding説明
system:kube-schedulersystem:kube-scheduler userschedulerコンポーネントが必要とするリソースへのアクセスを許可します。
system:volume-schedulersystem:kube-scheduler userkube-scheduleコンポーネントが必要とするリソースへのアクセスを許可します。
system:kube-controller-managersystem:kube-controller-manager usercontroller managerコンポーネントが必要とするリソースへのアクセスを許可します。 個々のコントローラーに必要な権限については、組み込みコントローラーのRoleで詳しく説明しています
system:nodeNoneすべてのsecretへの読み取りアクセス、すべてのポッドステータスオブジェクトへの書き込みアクセスなど、kubeletが必要とするリソースへのアクセスを許可します。

system:nodeRoleの代わりにNode authorizerNodeRestriction admission pluginを使用し、それらで実行するようにスケジュールされたPodに基づいてkubeletへのAPIアクセスを許可する必要があります。

system:nodeのRoleは、V1.8より前のバージョンからアップグレードしたKubernetesクラスターとの互換性のためだけに存在します。

system:node-proxiersystem:kube-proxy userkube-proxyコンポーネントが必要とするリソースへのアクセスを許可します。

他のコンポーネントのRole

デフォルトのClusterRoleデフォルトのClusterRoleBinding説明
system:auth-delegatorNone委任された認証と認可のチェックを許可します。 これは一般に、認証と認可を統合するためにアドオンAPIサーバーで使用されます。
system:heapsterNoneHeapsterコンポーネントのRole(非推奨)。
system:kube-aggregatorNonekube-aggregatorコンポーネントのRole。
system:kube-dnskube-systemNamespaceのサービスアカウントkube-dnskube-dnsコンポーネントのRole。
system:kubelet-api-adminNonekubelet APIへのフルアクセスを許可します。
system:node-bootstrapperNonekubelet TLS bootstrappingの実行に必要なリソースへのアクセスを許可します。
system:node-problem-detectorNonenode-problem-detectorコンポーネントのRole。
system:persistent-volume-provisionerNoneほとんどのdynamic volume provisionersが必要とするリソースへのアクセスを許可します。

組み込みコントローラーのRole

Kubernetes controller managerは、Kubernetesコントロールプレーンに組み込まれているcontrollersを実行します。 --use-service-account-credentialsを指定して呼び出すと、kube-controller-manager個別のサービスアカウントを使用して各コントローラーを起動します。 組み込みコントローラーごとに、プレフィックスsystem:controller:付きの対応するRoleが存在します。 コントローラーマネージャーが--use-service-account-credentialsで開始されていない場合、コントローラーマネージャーは、関連するすべてのRoleを付与する必要がある自身のクレデンシャルを使用して、すべてのコントロールループを実行します。 これらのRoleは次のとおりです。

  • system:controller:attachdetach-controller
  • system:controller:certificate-controller
  • system:controller:clusterrole-aggregation-controller
  • system:controller:cronjob-controller
  • system:controller:daemon-set-controller
  • system:controller:deployment-controller
  • system:controller:disruption-controller
  • system:controller:endpoint-controller
  • system:controller:expand-controller
  • system:controller:generic-garbage-collector
  • system:controller:horizontal-pod-autoscaler
  • system:controller:job-controller
  • system:controller:namespace-controller
  • system:controller:node-controller
  • system:controller:persistent-volume-binder
  • system:controller:pod-garbage-collector
  • system:controller:pv-protection-controller
  • system:controller:pvc-protection-controller
  • system:controller:replicaset-controller
  • system:controller:replication-controller
  • system:controller:resourcequota-controller
  • system:controller:root-ca-cert-publisher
  • system:controller:route-controller
  • system:controller:service-account-controller
  • system:controller:service-controller
  • system:controller:statefulset-controller
  • system:controller:ttl-controller

特権昇格の防止とブートストラップ

RBAC APIは、RoleまたはRoleBindingを編集することにより、ユーザーが特権を昇格するのを防ぎます。 これはAPIレベルで適用されるため、RBAC authorizerが使用されていない場合でも適用されます。

Roleの作成または更新に関する制限

次の項目1つ以上が当てはまる場合にのみ、Roleを作成/更新できます。

  1. 変更対象のオブジェクトと同じスコープで、Roleに含まれるすべての権限を既に持っている(ClusterRoleの場合はクラスター全体。Roleの場合は、同じNamespace内またはクラスター全体)。
  2. rbac.authorization.k8s.ioAPIグループの rolesまたはclusterrolesリソースで escalate verbを実行する明示的な権限が付与されている。

たとえば、 user-1にクラスター全体でSecretsを一覧表示する権限がない場合、それらにその権限を含むClusterRoleを作成できません。 ユーザーがRoleを作成/更新できるようにするには、以下のいずれかを実施します。

  1. 必要に応じて、RoleオブジェクトまたはClusterRoleオブジェクトを作成/更新できるRoleを付与する。
  2. 作成/更新するRoleに特定の権限を含む権限を付与する。
    • 暗黙的に、これらの権限を付与することにより(自分自身が付与されていない権限でRoleまたはClusterRoleを作成または変更しようとすると、APIリクエストは禁止されます)。
    • または、rbac.authorization.k8s.ioAPIグループの rolesまたは clusterrolesリソースで escalate verbを実行する権限を与えることにより、 Roleまたは ClusterRoleで権限を指定することを明示的に許可する

RoleBindingの作成または更新に関する制限

参照されるRoleに含まれるすべての権限を(RoleBindingと同じスコープで)すでに持っている場合、 または参照されたRoleでbind verbを実行する認可されている場合のみ、RoleBindingを作成/更新できます。 たとえば、 user-1にクラスター全体でSecretsを一覧表示する権限がない場合、ClusterRoleBindingを作成してもRoleにその権限を付与できません。 ユーザーがRoleBindingを作成/更新できるようにするには、以下のいずれかを実施します。

  1. 必要に応じて、RoleBindingまたはClusterRoleBindingオブジェクトを作成/更新できるようにする役割を付与する。
  2. 特定の役割をバインドするために必要なアクセス許可を付与する。
    • 暗黙的に、Roleに含まれる権限を付与することによって。
    • 明示的に、特定のRole(またはClusterRole)で bind verbを実行する許可を与えることによって。

たとえば、このClusterRoleとRoleBindingを使用すると、 user-1は他のユーザーにNamespace user-1-namespaceadmin edit、および viewRoleを付与します。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: role-grantor
rules:
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["rolebindings"]
  verbs: ["create"]
- apiGroups: ["rbac.authorization.k8s.io"]
  resources: ["clusterroles"]
  verbs: ["bind"]
  resourceNames: ["admin","edit","view"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: role-grantor-binding
  namespace: user-1-namespace
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: role-grantor
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: user-1

最初のRoleとRoleBindingをブートストラップするときは、最初のユーザーがまだ持っていない権限を付与する必要があります。 初期RoleとRoleBindingをブートストラップするには、以下のいずれかを実施します。

  • 「system:masters」グループのクレデンシャルを使用します。このグループは、デフォルトのBindingによって「cluster-admin」スーパーユーザーRoleにバインドされています。
  • APIサーバーが安全でないポート(--insecure-port)を有効にして実行されている場合、そのポートを介してのAPI呼び出しもできます。これにより、認証や認可が実行されません。

コマンドラインユーティリティー

kubectl create role

以下に、単一のNamespace内で権限を定義するRoleオブジェクトをいくつか例として作成します。

  • ユーザーがポッドで get watch、および listを実行できるように「pod-reader」という名前のRoleを作成します。

    kubectl create role pod-reader --verb=get --verb=list --verb=watch --resource=pods
    
  • resourceNamesを指定して、「pod-reader」という名前のRoleを作成します。

    kubectl create role pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
    
  • apiGroupsを指定して「foo」という名前のRoleを作成します。

    kubectl create role foo --verb=get,list,watch --resource=replicasets.apps
    
  • サブリソースの権限を持つ「foo」という名前のRoleを作成します。

  • Create a Role named "foo" with subresource permissions:

    kubectl create role foo --verb=get,list,watch --resource=pods,pods/status
    
  • 特定の名前のリソースを取得/更新する権限を持つ「my-component-lease-holder」という名前のRoleを作成します。

    kubectl create role my-component-lease-holder --verb=get,list,watch,update --resource=lease --resource-name=my-component
    

kubectl create clusterrole

以下にClusterRoleをいくつか例として作成します。

  • ユーザーがポッドに対してget watch、および listを実行できるようにする「pod-reader」という名前のClusterRoleを作成します。

    kubectl create clusterrole pod-reader --verb=get,list,watch --resource=pods
    
  • resourceNamesを指定して、「pod-reader」という名前のClusterRoleを作成します。

    kubectl create clusterrole pod-reader --verb=get --resource=pods --resource-name=readablepod --resource-name=anotherpod
    
  • apiGroupsを指定して「foo」という名前のClusterRoleを作成します。

    kubectl create clusterrole foo --verb=get,list,watch --resource=replicasets.apps
    
  • サブリソースの権限を持つ「foo」という名前のClusterRoleを作成します。

    kubectl create clusterrole foo --verb=get,list,watch --resource=pods,pods/status
    
  • nonResourceURLを指定して「foo」という名前のClusterRoleを作成します。

    kubectl create clusterrole "foo" --verb=get --non-resource-url=/logs/*
    
  • aggregationRuleを指定して、「monitoring」という名前のClusterRoleを作成します。

    kubectl create clusterrole monitoring --aggregation-rule="rbac.example.com/aggregate-to-monitoring=true"
    

kubectl create rolebinding

以下に、特定のNamespace内でRoleまたはClusterRoleをいくつか例として付与します。

  • Namespace「acme」内で、「admin」ClusterRoleの権限を「bob」という名前のユーザーに付与します。

    kubectl create rolebinding bob-admin-binding --clusterrole=admin --user=bob --namespace=acme
    
  • Namespace「acme」内で、ClusterRole「view」へのアクセス許可を「myapp」というNamespace「acme」のサービスアカウントに付与します。

    kubectl create rolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp --namespace=acme
    
  • Namespace「acme」内で、ClusterRole「view」へのアクセス許可を「myapp」というNamespace「myappnamespace」のサービスアカウントに付与します。

    kubectl create rolebinding myappnamespace-myapp-view-binding --clusterrole=view --serviceaccount=myappnamespace:myapp --namespace=acme
    

kubectl create clusterrolebinding

以下に、クラスタ全体(すべてのNamespace)にClusterRoleをいくつか例として付与します。

  • クラスター全体で、ClusterRole「cluster-admin」へのアクセス許可を「root」という名前のユーザーに付与します。

    kubectl create clusterrolebinding root-cluster-admin-binding --clusterrole=cluster-admin --user=root
    
  • クラスター全体で、ClusterRole「system:node-proxier」へのアクセス許可を「system:kube-proxy」という名前のユーザーに付与します。

    kubectl create clusterrolebinding kube-proxy-binding --clusterrole=system:node-proxier --user=system:kube-proxy
    
  • クラスター全体で、ClusterRole「view」へのアクセス許可を、Namespace「acme」の「myapp」という名前のサービスアカウントに付与します。

    kubectl create clusterrolebinding myapp-view-binding --clusterrole=view --serviceaccount=acme:myapp
    

kubectl auth reconcile

マニフェストファイルから rbac.authorization.k8s.io/v1APIオブジェクトを作成または更新します。

欠落しているオブジェクトが作成され、必要に応じて、Namespaceに属するオブジェクト用にオブジェクトを含むNamespaceが作成されます。

既存のRoleが更新され、入力オブジェクトに権限が含まれるようになります。 --remove-extra-permissionsが指定されている場合は、余分な権限を削除します。

既存のBindingが更新され、入力オブジェクトにsubjectsが含まれるようになります。 --remove-extra-subjectsが指定されている場合は、余分な件名を削除します。

以下、例として。

  • RBACオブジェクトのマニフェストファイルをテストとして適用し、行われる変更を表示します。

    kubectl auth reconcile -f my-rbac-rules.yaml --dry-run=client
    
  • RBACオブジェクトのマニフェストファイルを適用し、(Role内の)追加のアクセス許可と(Binding内の)追加のsubjectsを保持します。

    kubectl auth reconcile -f my-rbac-rules.yaml
    
  • RBACオブジェクトのマニフェストファイルを適用し、(Role内の)余分なアクセス許可と(Binding内の)余分なsubjectsを削除します。

ServiceAccount権限

デフォルトのRBACポリシーは、コントロールプレーンコンポーネント、ノード、 およびコントローラーをスコープとして権限を付与しますが、 Namespacekube-system外のサービスアカウントにはno permissionsで付与します (すべての認証されたユーザーに与えられたディスカバリー権限に関わらず)。

これにより、必要に応じて特定のServiceAccountに特定のRoleを付与できます。 きめ細かいRoleBindingはセキュリティを強化しますが、管理にはより多くの労力が必要です。 より広範な権限は、不必要な(そして潜在的にエスカレートする)APIアクセスをServiceAccountsに与える可能性がありますが、管理が簡単です。

アプローチを最も安全なものから最も安全でないものの順に並べると、次のとおりです。

  1. アプリケーション固有のサービスアカウントにRoleを付与する(ベストプラクティス) これには、アプリケーションがpodのspec、そして作成するサービスアカウント(API、アプリケーションマニフェスト、 kubectl create serviceaccountなどを介して)でserviceAccountNameを指定する必要があります。 たとえば、「my-namespace」内の読み取り専用権限を「my-sa」サービスアカウントに付与します。

    kubectl create rolebinding my-sa-view \
      --clusterrole=view \
      --serviceaccount=my-namespace:my-sa \
      --namespace=my-namespace
    
  2. あるNamespaceのサービスアカウント「default」にRoleを付与します

    アプリケーションが serviceAccountNameを指定しない場合、サービスアカウント「default」を使用します。

    たとえば、「my-namespace」内の読み取り専用権限をサービスアカウント「default」に付与します。

    kubectl create rolebinding default-view \
      --clusterrole=view \
      --serviceaccount=my-namespace:default \
      --namespace=my-namespace
    

    多くのアドオンは、 Namespacekube-systemのサービスアカウント「default」として実行されます。 これらのアドオンをスーパーユーザーアクセスでの実行を許可するには、Namespacekube-systemのサービスアカウント「default」のcluster-admin権限を付与します。

    kubectl create clusterrolebinding add-on-cluster-admin \
      --clusterrole=cluster-admin \
      --serviceaccount=kube-system:default
    
  3. Namespace内のすべてのサービスアカウントにRoleを付与します

    Namespace内のすべてのアプリケーションにRoleを持たせたい場合は、使用するサービスアカウントに関係なく、 そのNamespaceのサービスアカウントグループにRoleを付与できます。

    たとえば、「my-namespace」内の読み取り専用アクセス許可を、そのNamespace内のすべてのサービスアカウントに付与します。

    kubectl create rolebinding serviceaccounts-view \
      --clusterrole=view \
      --group=system:serviceaccounts:my-namespace \
      --namespace=my-namespace
    
  4. クラスター全体のすべてのサービスアカウントに制限されたRoleを付与します(お勧めしません)

    Namespaceごとのアクセス許可を管理したくない場合は、すべてのサービスアカウントにクラスター全体の役割を付与できます。

    たとえば、クラスター内のすべてのサービスアカウントに、すべてのNamespaceで読み取り専用のアクセス許可を付与します。

    kubectl create clusterrolebinding serviceaccounts-view \
      --clusterrole=view \
     --group=system:serviceaccounts
    
  5. クラスター全体のすべてのサービスアカウントへのスーパーユーザーアクセスを許可します。(強くお勧めしません)

    権限の分割をまったく考慮しない場合は、すべてのサービスアカウントにスーパーユーザーアクセスを許可できます。

    kubectl create clusterrolebinding serviceaccounts-cluster-admin \
      --clusterrole=cluster-admin \
      --group=system:serviceaccounts
    

ABACからアップグレードする

以前は古いバージョンのKubernetesを実行していたクラスターは、すべてのサービスアカウントに完全なAPIアクセスを許可するなど、permissiveなABACポリシーを使用することがよくありました。

デフォルトのRBACポリシーは、コントロールプレーンコンポーネント、ノード、 およびコントローラーをスコープとして権限を付与しますが、 Namespacekube-system外のサービスアカウントにはno permissionsで付与します (すべての認証されたユーザーに与えられたディスカバリー権限に関わらず)。

これははるかに安全ですが、API権限を自動的に受け取ることを期待している既存のワークロードを混乱させる可能性があります。 この移行を管理するための2つのアプローチは次のとおりです。

並行認可

RBACとABACの両方のauthorizerを実行し、legacy ABAC policyを含むポリシーファイルを指定します。

--authorization-mode=...,RBAC,ABAC --authorization-policy-file=mypolicy.json

最初のコマンドラインオプションを詳細に説明すると、Nodeなどの以前のauthorizerが 要求を拒否すると、RBAC authorizerはAPI要求を認可しようとします。 RBACの場合 また、そのAPI要求を拒否すると、ABAC authorizerが実行されます。これにより、すべてのリクエストが RBACまたはABACポリシーのいずれかで許可されます。

RBACコンポーネントのログレベルが5以上でkube-apiserverを実行した場合(--vmodule = rbac * = 5または --v = 5)、APIサーバーログでRBACの拒否を確認できます(プレフィックスは「RBAC」)。 その情報を使用して、どのRoleをどのユーザー、グループ、またはサービスアカウントに付与する必要があるかを判断できます。

サービスアカウントに付与されたRoleを取得し、 ワークロードがサーバーログにRBACの拒否メッセージがない状態で実行されている場合は、ABAC authorizerを削除できます。

Permissive RBAC権限

RBACRoleBindingを使用して、permissive ABACポリシーを複製できます。

RBACの使用に移行後、クラスターが情報セキュリティのニーズを確実に満たすように、アクセスコントロールを調整する必要があります。

8 - Scheduling

8.1 - スケジューラーの設定

FEATURE STATE: Kubernetes v1.19 [beta]

設定ファイルを作成し、そのパスをコマンドライン引数として渡すことでkube-schedulerの振る舞いをカスタマイズすることができます。

スケジューリングプロファイルは、kube-schedulerでスケジューリングの異なるステージを設定することができます。 各ステージは、拡張点に公開されています。プラグインをそれらの拡張点に1つ以上実装することで、スケジューリングの振る舞いを変更できます。

KubeSchedulerConfiguration(v1beta2v1beta3)構造体を使用して、kube-scheduler --config <filename>を実行することで、スケジューリングプロファイルを指定することができます。

最小限の設定は次の通りです。

apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
clientConnection:
  kubeconfig: /etc/srv/kubernetes/kube-scheduler/kubeconfig

プロファイル

スケジューリングプロファイルは、kube-schedulerでスケジューリングの異なるステージを設定することができます。 各ステージは拡張点に公開されています。 プラグインをそれらの拡張点に1つ以上実装することで、スケジューリングの振る舞いを変更できます。

単一のkube-schedulerインスタンスで複数のプロファイルを実行するように設定することも可能です。

拡張点

スケジューリングは一連のステージで行われ、以下の拡張点に公開されています。

  1. queueSort: これらのプラグインは、スケジューリングキューにあるpending状態のPodをソートするための順序付け関数を提供します。同時に有効化できるプラグインは1つだけです。
  2. preFilter: これらのプラグインは、フィルタリングをする前にPodやクラスターの情報のチェックや前処理のために使用されます。これらのプラグインは、設定された順序で呼び出されます。
  3. filter: これらのプラグインは、スケジューリングポリシーにおけるPredicatesに相当するもので、Podの実行不可能なNodeをフィルターするために使用されます。もし全てのNodeがフィルターされてしまった場合、Podはunschedulableとしてマークされます。
  4. postFilter:これらのプラグインは、Podの実行可能なNodeが見つからなかった場合、設定された順序で呼び出されます。もしpostFilterプラグインのいずれかが、Podを スケジュール可能 とマークした場合、残りのpostFilterプラグインは呼び出されません。
  5. preScore: これは、スコアリング前の作業を行う際に使用できる情報提供のための拡張点です。
  6. score: これらのプラグインはフィルタリングフェーズを通過してきたそれぞれのNodeに対してスコア付けを行います。その後スケジューラーは、最も高い重み付きスコアの合計を持つノードを選択します。
  7. reserve: これは、指定されたPodのためにリソースが予約された際に、プラグインに通知する、情報提供のための拡張点です。また、プラグインはReserve中に失敗した際、またはReserveの後に呼び出されるUnreserveも実装しています。
  8. permit: これらのプラグインではPodのバインディングを拒む、または遅延させることができます。
  9. preBind: これらのプラグインは、Podがバインドされる前に必要な処理を実行できます。
  10. bind: これらのプラグインはPodをNodeにバインドします。bindプラグインは順番に呼び出され、1つのプラグインがバインドを完了すると、残りのプラグインはスキップされます。bindプラグインは少なくとも1つは必要です。
  11. postBind: これは、Podがバインドされた後に呼び出される情報提供のための拡張点です。
  12. multiPoint: このフィールドは設定のみ可能で、プラグインが適用されるすべての拡張点に対して同時に有効化または無効化することができます。

次の例のように、それぞれの拡張点に対して、特定のデフォルトプラグインを無効化、または自作のプラグインを有効化することができます。

apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
profiles:
  - plugins:
      score:
        disabled:
        - name: PodTopologySpread
        enabled:
        - name: MyCustomPluginA
          weight: 2
        - name: MyCustomPluginB
          weight: 1

disabled配列のnameフィールドに*を使用することで、その拡張点の全てのデフォルトプラグインを無効化できます。また、必要に応じてプラグインの順序を入れ替える場合にも使用されます。

Scheduling plugins

以下のプラグインはデフォルトで有効化されており、1つ以上の拡張点に実装されています。

  • ImageLocality:Podが実行するコンテナイメージを既に持っているNodeを優先します。 拡張点:score
  • TaintToleration:TaintsとTolerationsを実行します。 実装する拡張点:filterpreScorescore
  • NodeName: PodのSpecのNode名が、現在のNodeと一致するかをチェックします。 拡張点:filter
  • NodePorts:要求されたPodのポートに対して、Nodeが空きポートを持っているかチェックします。 拡張点:preFilterfilter
  • NodeAffinity:nodeselectorsNodeアフィニティを実行します。 拡張点:filterscore
  • PodTopologySpread:Podトポロジーの分散制約を実行します。 拡張点:preFilterfilterpreScorescore
  • NodeUnschedulable:.spec.unschedulableがtrueに設定されているNodeをフィルタリングします。 拡張点:filter.
  • NodeResourcesFit:Podが要求しているすべてのリソースがNodeにあるかをチェックします。スコアは3つのストラテジのうちの1つを使用します:LeastAllocated(デフォルト)、MostAllocated、 とRequestedToCapacityRatio 拡張点:preFilterfilterscore
  • NodeResourcesBalancedAllocation:Podがスケジュールされた場合に、よりバランスの取れたリソース使用量となるNodeを優先します。 拡張点:score
  • VolumeBinding:Nodeが、要求されたボリュームを持っている、もしくはバインドしているかチェックします。 拡張点:preFilterfilterreservepreBindscore
  • VolumeRestrictions:Nodeにマウントされたボリュームが、ボリュームプロバイダ固有の制限を満たしているかを確認します。 拡張点:filter
  • VolumeZone:要求されたボリュームがゾーン要件を満たしているかどうかを確認します。 拡張点:filter
  • NodeVolumeLimits:NodeのCSIボリューム制限を満たすかどうかをチェックします。 拡張点:filter
  • EBSLimits:NodeのAWSのEBSボリューム制限を満たすかどうかをチェックします。 拡張点:filter
  • GCEPDLimits:NodeのGCP-PDボリューム制限を満たすかどうかをチェックします。 拡張点:filter
  • AzureDiskLimits:NodeのAzureディスクボリューム制限を満たすかどうかをチェックします。 拡張点:filter
  • InterPodAffinity:Pod間のaffinityとanti-affinityを実行します。 拡張点:preFilterfilterpreScorescore
  • PrioritySort:デフォルトの優先順位に基づくソートを提供します。 拡張点:queueSort.
  • DefaultBinder:デフォルトのバインディングメカニズムを提供します。 拡張点:bind
  • DefaultPreemption:デフォルトのプリエンプションメカニズムを提供します。 拡張点:postFilter

また、コンポーネント設定のAPIにより、以下のプラグインを有効にすることができます。 デフォルトでは有効になっていません。

複数のプロファイル

kube-schedulerは複数のプロファイルを実行するように設定することができます。 各プロファイルは関連するスケジューラー名を持ち、その拡張点に異なるプラグインを設定することが可能です。

以下のサンプル設定では、スケジューラーは2つのプロファイルで実行されます。1つはデフォルトプラグインで、もう1つはすべてのスコアリングプラグインを無効にしたものです。

apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: default-scheduler
  - schedulerName: no-scoring-scheduler
    plugins:
      preScore:
        disabled:
        - name: '*'
      score:
        disabled:
        - name: '*'

特定のプロファイルに従ってスケジュールさせたいPodは、その.spec.schedulerNameに、対応するスケジューラー名を含めることができます。

デフォルトでは、スケジューラー名default-schedulerとしてプロファイルが生成されます。 このプロファイルは、上記のデフォルトプラグインを含みます。複数のプロファイルを宣言する場合は、それぞれユニークなスケジューラー名にする必要があります。

もしPodがスケジューラー名を指定しない場合、kube-apiserverはdefault-schedulerを設定します。 従って、これらのPodをスケジュールするために、このスケジューラー名を持つプロファイルが存在する必要があります。

複数の拡張点に適用されるプラグイン

kubescheduler.config.k8s.io/v1beta3からは、プロファイル設定にmultiPointというフィールドが追加され、複数の拡張点でプラグインを簡単に有効・無効化できるようになりました。 multiPoint設定の目的は、カスタムプロファイルを使用する際に、ユーザーや管理者が必要とする設定を簡素化することです。

MyPluginというプラグインがあり、preScorescorepreFilterfilter拡張点を実装しているとします。 すべての利用可能な拡張点でMyPluginを有効化するためには、プロファイル設定は次のようにします。

apiVersion: kubescheduler.config.k8s.io/v1beta3
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: multipoint-scheduler
    plugins:
      multiPoint:
        enabled:
        - name: MyPlugin

これは以下のように、MyPluginを手動ですべての拡張ポイントに対して有効にすることと同じです。

apiVersion: kubescheduler.config.k8s.io/v1beta3
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: non-multipoint-scheduler
    plugins:
      preScore:
        enabled:
        - name: MyPlugin
      score:
        enabled:
        - name: MyPlugin
      preFilter:
        enabled:
        - name: MyPlugin
      filter:
        enabled:
        - name: MyPlugin

multiPointを使用する利点の一つは、将来的にMyPluginが別の拡張点を実装した場合に、multiPoint設定が自動的に新しい拡張点に対しても有効化されることです。

特定の拡張点は、その拡張点のdisabledフィールドを使用して、MultiPointの展開から除外することができます。 これは、デフォルトのプラグインを無効にしたり、デフォルト以外のプラグインを無効にしたり、ワイルドカード('*')を使ってすべてのプラグインを無効にしたりする場合に有効です。 ScorePreScoreを無効にするためには、次の例のようにします。

apiVersion: kubescheduler.config.k8s.io/v1beta3
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: non-multipoint-scheduler
    plugins:
      multiPoint:
        enabled:
        - name: 'MyPlugin'
      preScore:
        disabled:
        - name: '*'
      score:
        disabled:
        - name: '*'

v1beta3では、MultiPointを通じて、内部的に全てのデフォルトプラグインが有効化されています。 しかしながら、デフォルト値(並び順やスコアの重みなど)を柔軟に設定し直せるように、個別の拡張点は用意されています。 例えば、2つのスコアプラグインDefaultScore1DefaultScore2に、重み1が設定されているとします。 その場合、次のように重さを変更し、並べ替えることができます。

apiVersion: kubescheduler.config.k8s.io/v1beta3
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: multipoint-scheduler
    plugins:
      score:
        enabled:
        - name: 'DefaultScore2'
          weight: 5

この例では、MultiPointはデフォルトプラグインであるため、明示的にプラグイン名を指定する必要はありません。 そして、Scoreに指定されているプラグインはDefaultScore2のみです。 これは、特定の拡張点を通じて設定されたプラグインは、常にMultiPointプラグインよりも優先されるためです。つまり、この設定例では、結果的に2つのプラグインを両方指定することなく、並び替えが行えます。

MultiPointプラグインを設定する際の一般的な優先順位は、以下の通りです。

  1. 特定の拡張点が最初に実行され、その設定は他の場所で設定されたものよりも優先される
  2. MultiPointを使用して、手動で設定したプラグインとその設定内容
  3. デフォルトプラグインとそのデフォルト設定

上記の優先順位を示すために、次の例はこれらのプラグインをベースにします。

プラグイン拡張点
DefaultQueueSortQueueSort
CustomQueueSortQueueSort
DefaultPlugin1Score, Filter
DefaultPlugin2Score
CustomPlugin1Score, Filter
CustomPlugin2Score, Filter

これらのプラグインの有効な設定例は次の通りです。

apiVersion: kubescheduler.config.k8s.io/v1beta3
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: multipoint-scheduler
    plugins:
      multiPoint:
        enabled:
        - name: 'CustomQueueSort'
        - name: 'CustomPlugin1'
          weight: 3
        - name: 'CustomPlugin2'
        disabled:
        - name: 'DefaultQueueSort'
      filter:
        disabled:
        - name: 'DefaultPlugin1'
      score:
        enabled:
        - name: 'DefaultPlugin2'

なお、特定の拡張点にMultiPointプラグインを再宣言しても、エラーにはなりません。 特定の拡張点が優先されるため、再宣言は無視されます(ログは記録されます)。

このサンプルは、ほとんどのコンフィグを一箇所にまとめるだけでなく、いくつかの工夫をしています。

  • カスタムのqueueSortプラグインを有効にし、デフォルトのプラグインを無効にする。
  • CustomPlugin1CustomPlugin2を有効にし、この拡張点のプラグイン内で、最初に実行されるようにする。
  • filter拡張点でのみ、DefaultPlugin1を無効にする。
  • score拡張点でDefaultPlugin2が最初に実行されるように並べ替える(カスタムプラグインより先に)。

v1beta3以前のバージョンで、multiPointがない場合、上記の設定例は、次のものと同等になります。

apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
profiles:
  - schedulerName: multipoint-scheduler
    plugins:

      # デフォルトQueueSortプラグインを無効化
      queueSort:
        enabled:
        - name: 'CustomQueueSort'
        disabled:
        - name: 'DefaultQueueSort'

      # カスタムFilterプラグインを有効化
      filter:
        enabled:
        - name: 'CustomPlugin1'
        - name: 'CustomPlugin2'
        - name: 'DefaultPlugin2'
        disabled:
        - name: 'DefaultPlugin1'

      # カスタムScoreプラグインを有効化し、実行順を並べ替える
      score:
        enabled:
        - name: 'DefaultPlugin2'
          weight: 1
        - name: 'DefaultPlugin1'
          weight: 3

これは複雑な例ですが、MultiPoint設定の柔軟性と、拡張点を設定する既存の方法とのシームレスな統合を実証しています。

スケジューラー設定の移行

  • v1beta2のバージョンの設定では、新しいNodeResourcesFitプラグインをスコア拡張点で使用できます。 この新しい拡張機能は、NodeResourcesLeastAllocatedNodeResourcesMostAllocatedRequestedToCapacityRatioプラグインの機能を組み合わせたものです。 例えば、以前はNodeResourcesMostAllocatedプラグインを使っていたなら、代わりにNodeResourcesFitプラグインを使用し(デフォルトで有効)、pluginConfigに次のようなscoreStrategy`を追加することになるでしょう。

    apiVersion: kubescheduler.config.k8s.io/v1beta2
    kind: KubeSchedulerConfiguration
    profiles:
    - pluginConfig:
      - args:
          scoringStrategy:
            resources:
            - name: cpu
              weight: 1
            type: MostAllocated
        name: NodeResourcesFit
    
  • スケジューラープラグインのNodeLabelは廃止されました。代わりにNodeAffinityプラグイン(デフォルトで有効)を使用することで同様の振る舞いを実現できます。

  • スケジューラープラグインのServiceAffinityは廃止されました。代わりにInterPodAffinityプラグイン(デフォルトで有効)を使用することで同様の振る舞いを実現できます。

  • スケジューラープラグインのNodePreferAvoidPodsは廃止されました。代わりにNode taintsを使用することで同様の振る舞いを実現できます。

  • v1beta2で有効化されたプラグインは、そのプラグインのデフォルトの設定より優先されます。

  • スケジューラーのヘルスとメトリクスのバインドアドレスに設定されているhostportが無効な場合、バリデーションに失敗します。

  • デフォルトで3つのプラグインの重みが増加しました。
    • InterPodAffinity:1から2
    • NodeAffinity:1から2
    • TaintToleration:1から3

次の項目

8.2 - スケジューリングポリシー

バージョンv1.23より前のKubernetesでは、スケジューリングポリシーを使用して、predicatesprioritiesの処理を指定することができました。例えば、kube-scheduler --policy-config-file <filename>またはkube-scheduler --policy-configmap <ConfigMap>を実行すると、スケジューリングポリシーを設定することが可能です。

このスケジューリングポリシーは、バージョンv1.23以降のKubernetesではサポートされていません。関連するフラグである、policy-config-filepolicy-configmappolicy-configmap-namespaceuse-legacy-policy-configも同様にサポートされていません。 代わりに、スケジューラー設定を使用してください。

次の項目

9 - ツール

Kubernetesには、Kubernetesシステムの操作に役立ついくつかの組み込みツールが含まれています。

Kubectl

kubectlは、Kubernetesのためのコマンドラインツールです。このコマンドはKubernetes cluster managerを操作します。

Kubeadm

kubeadmは、物理サーバやクラウドサーバ、仮想マシン上にKubernetesクラスタを容易にプロビジョニングするためのコマンドラインツールです(現在はアルファ版です)。

Minikube

minikubeは、開発やテストのためにワークステーション上でシングルノードのKubernetesクラスタをローカルで実行するツールです。

Dashboard

Dashboardは、KubernetesのWebベースのユーザインタフェースで、コンテナ化されたアプリケーションをKubernetesクラスタにデプロイしたり、トラブルシューティングしたり、クラスタとそのリソース自体を管理したりすることが出来ます。

Helm

Kubernetes Helmは、事前に設定されたKubernetesリソースのパッケージ、別名Kubernetes chartsを管理するためのツールです。

Helmを用いて以下のことを行います。

  • Kubernetes chartsとしてパッケージ化された人気のあるソフトウェアの検索と利用

  • Kubernetes chartsとして所有するアプリケーションを共有すること

  • Kubernetesアプリケーションの再現性のあるビルドの作成

  • Kubernetesマニフェストファイルを知的な方法で管理

  • Helmパッケージのリリース管理

Kompose

Komposeは、Docker ComposeユーザがKubernetesに移行する手助けをするツールです。

Komposeを用いて以下のことを行います。

  • Docker ComposeファイルのKubernetesオブジェクトへの変換

  • ローカルのDocker開発からKubernetesを経由したアプリケーション管理への移行

  • v1またはv2のDocker Compose用 yaml ファイルならびに分散されたアプリケーションバンドルの変換