リファレンス

• 1: 標準化用語集
• 2: KubeletチェックポイントAPI
• 3: 認証
• 4: API概要
• 4.1: Kubernetes非推奨ポリシー
• 5: RBAC認可を使用する
• 6: ネットワーキングのリファレンス
• 6.1: ポートとプロトコル
• 7: セットアップツールのリファレンス
• 7.1: Kubeadm
• 7.1.1: Kubeadm Generated
• 7.1.1.1:
• 7.1.1.2:
• 7.1.1.3:
• 7.1.1.4:
• 7.1.1.5:
• 7.1.1.6:
• 7.1.1.7:
• 7.1.2: kubeadm config
• 8: コマンドラインツール(kubectl)
• 8.1: kubectlチートシート
• 8.2: JSONPathのサポート
• 8.3: kubectlの使用規則
• 9: コマンドラインツールのリファレンス
• 9.1: フィーチャーゲート
• 9.2: Kubelet 認証/認可
• 10: Scheduling
• 10.1: スケジューラーの設定
• 10.2: スケジューリングポリシー
• 11: ツール

1 - 標準化用語集

2 - KubeletチェックポイントAPI

コンテナのチェックポイントは実行中のコンテナのステートフルコピーを作成するための機能です。 コンテナのステートフルコピーがあると、デバックや類似の目的のために別のコンピューターに移動させることができます。

チェックポイントコンテナデータを復元可能なコンピューターに移動させる場合、その復元したコンテナは、チェックポイントが作成された正確に同じ地点で実行が再開されます。 保存したデータを検査することも可能です。 ただし、検査を行うための適したツールを保持している必要があります。

コンテナのチェックポイントを作成することで、セキュリティ影響が発生する場合があります。 通常、チェックポイントはチェックポイントされたコンテナ内のすべてのプロセスのすべてのメモリーページを含んでいます。 メモリー内で使用された全てがローカルディスク上で利用できるようになることを意味しています。 これはすべてのプライベートデータを含んでおり、もしかしたら暗号化に使用した鍵も含まれているかもしれません。 基礎となるCRI実装(そのノード上のコンテナランタイム)は、rootユーザーのみがアクセス可能なチェックポイントアーカイブを作成するべきです。 チェックポイントアーカイブが他のシステムに転送された場合、全てのメモリーページがチェックポイントアーカイブのオーナーによって読み取れるようになることを覚えておくことが重要です。

操作方法

post 指定したコンテナのチェックポイント

指定したPodから指定したコンテナのチェックポイントを作成するようにkubeletに指示します。

kubeletチェックポイントインターフェースへのアクセスの制御方法についての詳細な情報は、Kubelet authentication/authorization referenceを参照してください。

kubeletは基礎となるCRI実装にチェックポイントをリクエストします。 チェックポイントリクエストでは、kubeletがcheckpoint-<podFullName>-<containerName>-<timestamp>.tarのようなチェックポイントアーカイブの名前を指定します。 併せて、(--root-dirで定義される)rootディレクトリ配下のcheckpointsディレクトリに、チェックポイントアーカイブを保存することをリクエストします。 デフォルトは/var/lib/kubelet/checkpointsです。

チェックポイントアーカイブは tar フォーマットであり、tarの実装を使用して一覧表示できます。 アーカイブの内容は、基礎となるCRI実装(ノード上のコンテナランタイム)に依存します。

HTTPリクエスト

POST /checkpoint/{namespace}/{pod}/{container}

パラメーター

• namespace (パス内): string, 必須項目

  Namespace

• pod (パス内): string, 必須項目

  Pod

• container (パス内): string, 必須項目

  コンテナ

• timeout (クエリ内): integer

  チェックポイントの作成が終了するまで待機する秒単位のタイムアウト。 ゼロまたはタイムアウトが指定されていない場合、デフォルトはCRIタイムアウトの値が使用されます。 チェックポイント作成時間はコンテナの使用メモリーに直接依存します。 コンテナの使用メモリーが多いほど、対応するチェックポイントを作成するために必要な時間が長くなります。

レスポンス

200: OK

401: Unauthorized

404: Not Found (ContainerCheckpointフィーチャーゲートが無効の場合)

404: Not Found (指定したnamespaceやpod、containerが見つからない場合)

500: Internal Server Error (CRI実装でチェックポイント中にエラーが発生した場合(詳細はエラーメッセージを参照))

500: Internal Server Error (CRI実装がチェックポイントCRI APIを実装していない場合(詳細はエラーメッセージを参照))

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-adminやjane@example.comです。
• UID: エンドユーザーを識別する文字列であり、ユーザー名よりも一貫性と一意性を持たせようとするものです。
• グループ: 各要素がユーザーの役割を示すような意味を持つ文字列の集合です。system:mastersやdevops-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ファイルで、その後にオプションでグループ名が付きます。

token,user,uid,"group1,group2,group3"

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

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

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

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

新しいクラスターの効率的なブートストラップを可能にするために、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サーバー通信できるようになります。アカウントはPodSpecのserviceAccountNameフィールドを使って、明示的に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:serviceaccountsとsystem:serviceaccounts:(NAMESPACE)に割り当てられます。

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

OpenID Connectトークン

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

1. IDプロバイダーにログインします
2. IDプロバイダーは、access_token、id_token、refresh_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サーバーで以下のフラグを設定します。

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

KubernetesはOpenID Connect IDプロバイダーを提供していません。既存のパブリックなOpenID Connect IDプロバイダー(Googleやその他など)を使用できます。もしくは、CoreOS dex、Keycloak、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証明書を生成できます。

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

• UAA
• Dex
• OpenUnison

kubectlの使用

選択肢1 - OIDC認証機能

最初の選択肢は、kubectlのoidc認証機能を利用することです。これはすべてのリクエストのBearerトークンとしてid_tokenを設定し、有効期限が切れるとトークンを更新します。プロバイダーにログインした後、kubectlを使ってid_token、refresh_token、client_id、client_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の有効期限が切れると、kubectlはrefresh_tokenとclient_secretを用いてid_tokenの更新しようとします。refresh_tokenとid_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クレデンシャルプラグイン

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

この機能は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-goはstatusで返された認証情報を用いて、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ハンドシェイクを強制します

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

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 - API概要

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

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

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

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

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

APIバージョニング

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

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

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

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

• Alpha:

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

• Beta:

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

  • 組み込みのbeta APIバージョンはデフォルトで無効化されており、使用するためにはkube-apiserverの設定で明示的に有効にする必要があります。 (例外としてKubernetes 1.22以前に導入されたAPIのbetaバージョンはデフォルトで有効化されています)

  • 組み込みのbeta APIバージョンは、導入から非推奨となるまでが9ヶ月または3マイナーリリース(どちらかの長い期間)、そして非推奨から削除まで9ヶ月または3マイナーリリース(どちらかの長い期間)の最大存続期間を持ちます。

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

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

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

  • 本番環境での使用は推奨しません。 後続のリリースは、互換性のない変更を導入する可能性があります。 beta APIを使用する場合、そのbeta APIが非推奨となり提供されなくなった際には、後続のbetaまたはstable APIバージョンに移行する必要があります。

  備考:

  ベータ版の機能をお試しいただき、ご意見をお寄せください。 ベータ版の機能が終了した後はこれ以上の変更ができない場合があります。

• Stable:

  • バージョン名は vX であり、X は整数である。
  • stable APIバージョンはKubernetesのメジャーバージョン内の全てのリリースで利用可能であり、stable APIを削除するようなKubernetesのメジャーバージョンの修正は、現在計画されていません。

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に書き込んで保存します。

次の項目

• API conventionsをもっと知る
• aggregatorの設計ドキュメントを読む

4.1 - Kubernetes非推奨ポリシー

このドキュメントではシステムのさまざまな側面に関する非推奨ポリシーについて詳しく説明します。

Kubernetesは多くのコンポーネントと多くのコントリビュータを持つ大規模なシステムです。 このようなソフトウェアでは、機能セットは時間の経過とともに自然に進化し、時には機能を削除する必要がある場合があります。 これにはAPI、フラグ、または機能全体が含まれることもあります。 既存のユーザーへの影響を避けるため、Kubernetesは削除される予定のシステムの側面については非推奨ポリシーに従っています。

API

KubernetesはAPI駆動型のシステムであるため、問題領域の理解の進化を反映して時間の経過とともに進化してきました。 Kubernetes APIは実際は「APIグループ」と呼ばれる一連のAPIであり、各APIグループは個別にバージョン管理されています。 APIバージョンは主に3つのトラックに分類され、それぞれに異なる非推奨ポリシーがあります:

Kubernetesの特定のリリースでは任意の数のAPIグループと任意の数のそれぞれのバージョンをサポートすることができます。

次のルールはAPIの要素の非推奨を管理します。これには以下が含まれます:

• RESTリソース (別名 APIオブジェクト)
• RESTリソースのフィールド
• RESTリソースのアノテーション、"beta"アノテーションは含まれますが"alpha"アノテーションは含まれません
• 列挙された値や定数値
• コンポーネントの設定構造

これらのルールは、masterまたはリリースブランチへの任意のコミット間ではなく、公式リリース間に適用されます。

ルール #1: APIの要素はAPIグループのバージョンをインクリメントすることでもに削除することができます。

APIの要素が特定バージョンのAPIグループに追加されると、 トラックに関係なくそのバージョンから削除されたり、 大幅に挙動が変更されることはありません。

ルール #2: APIオブジェクトはいくつかのバージョンに存在しないRESTリソース全体を除き、 任意のリリース内のAPIバージョン間で情報を失うことなくラウンドトリップできる必要があります

例えば、あるオブジェクトがv1として書き込まれその後v2として読み取られv1に変換された場合、 結果として得られるv1リソースは元のリソースと同一である必要があります。 v2における表現はv1とは異なるかもしれませんが、システムは両方向にそれらを変換する方法を知っています。 さらに、v2で追加された新しいフィールドはv1にラウンドトリップできる必要があります。 つまりv1では同等のフィールドを追加するかアノテーションとして表現する必要があるかもしれません。

ルール #3: 特定のトラックのAPIバージョンは安定性の低いAPIバージョンを優先して非推奨になることはありません。

• GA APIバージョンは、betaおよびalpha APIバージョンに置き換えることができます。
• Beta APIバージョンは以前のbetaおよびalpha APIバージョンに置き換えることはできますが、GA APIバージョンに置き換えることはできません。
• Alpha APIバージョンは以前のalpha APIバージョンに置き換えることはできますが、GAまたはbeta APIバージョンに置き換えることはできません。

ルール #4a: APIの有効期間はAPIの安定性レベルによって決まります

• GA APIバージョンは非推奨としてマークされることがありますが、Kubernetesのメジャーバージョン内で削除されることはありません。
• Beta APIバージョンは導入後9ヶ月または3つのマイナーリリース(いずれか長い方)以内に非推奨にされ、 非推奨後9ヶ月または3つのマイナーリリース(いずれか長い方)以内に提供されなくなります。
• Alpha APIバージョンは事前の非推奨通知なしにリリースから削除される場合があります。

これによりbeta APIバージョンのサポートは 最大2つのリリースのバージョンの差異をカバーし、 APIが不安定なbetaバージョンで停滞し、beta APIのサポートが終了したときに本番稼働が中断されることはありません。

ルール #4b: 特定のグループの「優先」APIバージョンと「ストレージバージョン」は、 新しいバージョンと以前のバージョンの両方をサポートするリリースが行われるまで更新されない場合があります。

ユーザーはKubernetesの新しいリリースにアップグレードした後、 (新しいバージョンでのみ利用可能な機能を明示的に使用していない限り) 何も新しいAPIバージョンに変換することなく、また破損が発生することなく、 以前のリリースにロールバックできる必要があります。 これはオブジェクトの保存された表現において特に顕著です。

これらはすべて例を挙げて説明するのが最も適切です。新しいAPIグループを導入する Kubernetesリリース、バージョンXを想像してください。 新しいKubernetesリリースは約4ヶ月ごと(1年に3回)に行われます。 以下の表は一連の後続リリースでサポートされるAPIバージョンを示しています。

REST resources (別名APIオブジェクト)

上記のタイムラインではAPI v1に存在し、非推奨化される必要があるWidgetという仮想のRESTリソースを考えてみましょう。 私たちはリリースX+1と同期して非推奨をドキュメント化とアナウンスを行います。 WidgetリソースはAPIバージョンv1(非推奨)にはまだ存在しますがv2alpha1には存在しません。 WidgetリソースはX+8までのリリースに引き続き存在して機能します。 API v1が期限切れになるX+9でのみ、Widgetリソースは存在しなくなり、その動作が削除されます。

Kubernetes v1.19以降は、非推奨のREST APIエンドポイントへのAPIリクエストを行うと、以下のようになります:

1. APIレスポンスにおいてWarningヘッダー(RFC7234, Section 5.5で定義)を返します。

2. リクエストに対して記録された監査イベントに"k8s.io/deprecated":"true"というアノテーションを追加します。

3. kube-apiserverプロセスでapiserver_requested_deprecated_apisゲージメトリクスに1を設定します。 このメトリクスにはapiserver_request_totalメトリクスに結合することができる group、version、resource、subresourceラベルと、APIが提供されなくなるKubernetesリリースを表すremoved_releaseがあります。 次のPrometheusクエリはv1.22で削除される非推奨APIへのリクエストに関する情報を返します:

   apiserver_requested_deprecated_apis{removed_release="1.22"} * on(group,version,resource,subresource) group_right() apiserver_request_total
   

RESTリソースのフィールド

すべてのRESTリソースと同様に、API v1に存在していた個々のフィールドはAPI v1が削除されるまで存在して機能する必要があります。 リソース全体と異なり、v2 APIはフィールドをラウンドトリップできる限り、異なる表現を選択することができます。 例えば非推奨になった「magnitude」という名前のv1フィールドは、API v2では「deprecatedMagnitude」という名前になる可能性があります。 最終的にv1が削除されると、v2から非推奨のフィールドも削除することができます。

列挙された値や定数値

すべてのRESTリソースとそのフィールドと同様にAPI v1でサポートされていた定数値はAPI v0が削除されるまで存在して機能する必要があります。

コンポーネント設定の構造

コンポーネント設定はRESTリソースと同様にバージョン付けされて管理されています。

今後の取り組み

時間の経過とともに、Kubernetesはよりきめ細かいAPIバージョンを導入し、これらのルールは必要に応じて調整されます。

フラグまたはCLIの非推奨化

Kubernetesシステムは複数の異なるプログラムが連携して構成されています。 KubernetesリリースではこれらのプログラムのフラグやCLIコマンド(総称して「CLI要素」)が削除されることがしばしばあります。 個々のプログラムは、非推奨ポリシーが若干異なる、ユーザー向けプログラムと管理者向けプログラムの2つの主要グループに分類されます。 フラグに明示的に接頭辞が付けられていないか、「alpha」または「beta」としてドキュメント化されない限り、そのフラグはGAとみなされます。

CLI要素は事実上システムに対するAPIの一部ですが、REST APIと同じ方法ではバージョン管理されておらず、非推奨のルールは次のようになっています:

ルール #5a: ユーザー向けのコンポーネントのCLI要素(例: kubectl)は 非推奨がアナウンスされてから以下の期間は機能しなければなりません:

• GA: 12ヶ月または2リリース(いずれか長い方)
• Beta: 3ヶ月または1リリース(いずれか長い方)
• Alpha: 0リリース

ルール #5b: 管理者向けのコンポーネントのCLI要素(例: kubelet)は 非推奨がアナウンスされてから以下の期間は機能しなければなりません:

• GA: 6ヶ月または1リリース(いずれか長い方)
• Beta: 3ヶ月または1リリース(いずれか長い方)
• Alpha: 0リリース

ルール #5c: コマンドラインインターフェース(CLI)の要素は より不安定なCLI要素の代わりに廃止されることはありません

APIに関するルール#3と同様、コマンドラインインターフェースの要素が代替実装にリプレイスされる、 例えば既存の要素名の変更やコマンドライン引数の代わりにファイルから取得した設定を使用するように切り替える場合、 推奨される代替案は同じかそれ以上の安定性レベルでなければなりません。

ルール #6: 非推奨のCLI要素は使用時に警告を表示しなければなりません(オプションで無効化可能)

機能や動作の非推奨化

時には、KubernetesリリースではAPIやCLIによって制御されないシステムの機能や動作を非推奨にする必要があります。 その場合、非推奨に関するルールは以下の通りです:

ルール #7: 非推奨となる動作はアナウンスされてから最低1年間は機能しなければなりません。

機能や動作が、変更を取り込む作業が必要な代替実装に置き換えられる場合、 可能な限り移行を簡素化する努力が必要です。 代替実装がKubernetes organizationの管理下にある場合、以下のルールが適用されます:

ルール #8: 安定性の低い代替実装を優先して、動作の機能を非推奨にしてはなりません

例えば、一般提供されている機能がBeta版にリプレイスために非推奨にされることはありません。 ただし、Kubernetesプロジェクトは同じ成熟度に達する前であっても、ユーザーが代替実装を採用して移行することを推奨しています。 これは、機能の新しいユースケースを検討したり、リプレイスについての早期フィードバックを得るために特に重要です。

代替実装は、外部のツールや製品である場合があります。 例えば、機能がkubeletからKubernetesプロジェクト管理外のコンテナランタイムに移行することがあります。 このような場合、ルールを適用することはできませんが、コンポーネントの成熟度を損なわない移行方法を確保するための努力が必要です。 コンテナランタイムを例に挙げると、一般的なコンテナランタイムが、リプレイスする動作を実装しながら同等の安定性を提供するバージョンを持つように取り組む必要があるかもしれません。

機能と動作の非推奨ルールは、システムに対するすべての変更がこのポリシーによって管理されることを意味するものではありません。 これらのルールはKubernetes上で実行されているアプリケーションの正確性やKubernetesクラスターの管理に影響する、また完全に削除されるものにのみ適用されます。

上記のルールの例外は フィーチャーゲート です。 フィーチャーゲートはユーザーが実験的な機能を有効/無効にできるようにするキー=バリューのペアです。

フィーチャーゲートは機能の開発ライフサイクルをカバーすることを目的としており、 長期的なAPIを目的としたものではありません。 そのため、機能がGAになるが削除された後は、非推奨となり削除されることが期待されます。

機能が段階を踏むにつれて、関連するフィーチャーゲートも進化します。 機能のライフサイクルと対応するフィーチャーゲートの関係は以下の通りです:

• Alpha: フィーチャーゲートはデフォルトで無効化されており、ユーザーによって有効化できます。
• Beta: フィーチャーゲートはデフォルトで有効化されており、ユーザーによって無効化できます。
• GA: フィーチャーゲートは非推奨となり("非推奨"を参照)動作しなくなります。
• GA、非推奨期間終了後: フィーチャーゲートは削除され、呼び出しは受け付けられなくなります。

非推奨

機能はGA前のライフサイクルのどの時点でも削除できます。 GA前に機能が削除されると、それに関連するフィーチャーゲートも非推奨になります。

動作しないフィーチャーゲートを無効化するために呼び出そうとすると、 サイレントに実行される可能性あるサポートされていないシナリオを避けるため呼び出しは失敗します。

場合によっては、GA前の機能を削除にかなりの時間がかかることがあります。 フィーチャーゲートは、関連する機能が完全に削除されるまで機能し続け、 その時点でフィーチャーゲート自体が非推奨になる可能性があります。

GAされた機能のフィーチャーゲートの削除にも時間がかかる場合、 フィーチャーゲートが機能に影響を与えず、エラーも引き起こさない場合、 フィーチャーゲートへの呼び出しは動作し続けることがあります。

ユーザーによって無効化されることを意図した機能には、関連するフィーチャーゲートで その機能を無効化するためにメカニズムが含まれている必要があります。

フィーチャーゲートのバージョニングは、前述のコンポーネントとは異なるため、 非推奨に関するルールは次のとおりです:

ルール #9: フィーチャーゲートは、対応する機能が次のようにライフサイクルステージを移行する際に非推奨にする必要があります。 フィーチャーゲートは以下の期間は機能しなければなりません:

• Beta機能からGA: 6ヶ月または2リリース(どちらか長い方)
• Beta機能からEOL: 3ヶ月または1リリース(どちらか長い方)
• Alpha機能からEOL: 0リリース

ルール #10: 非推奨となったフィーチャーゲートは使用時に警告を返す必要があります。 フィーチャーゲートが非推奨になる場合には、リリースノートと対応するCLIヘルプの両方にドキュメント化される必要があります。 警告とドキュメントの両方には、フィーチャーゲートが動作しないかどうかを明記する必要があります。

メトリクスの非推奨化

Kubernetesコントロールプレーンの各コンポーネントはメトリクス(通常は/metricsエンドポイント)を公開しており、 通常はクラスター管理者によって収集されます。 すべてのメトリクスが同じというわけではありません。一部のメトリクスは一般的にSLIとして使用されたり、 SLOを決定するために使用されるため、より重要な役割を持つ傾向があります。 他のメトリクスは、事実上実験的なものであるか、主にKubernetesの開発プロセスで使用されます。

そのため、メトリクスは3つの安定性クラス(ALPHA、BETA、STABLE)に分類され、 Kubernetesリリース間のメトリクスの削除に影響します。 これらのクラスは、メトリクスの重要性に基づいて決定されます。 メトリクスの非推奨と削除に関するルールは次のとおりです:

ルール #11a: メトリクスは、対応する安定性クラスに応じて、以下の期間は機能しなければなりません:

• STABLE: 4リリースまたは12ヶ月(いずれか長い方)
• BETA: 2リリースまたは8ヶ月(いずれか長い方)
• ALPHA: 0リリース

ルール #11b: メトリクスは、非推奨がアナウンスされた後も、以下の期間は機能しなければなりません:

• STABLE: 3リリースまたは9ヶ月(いずれか長い方)
• BETA: 1リリースまたは4ヶ月(いずれか長い方)
• ALPHA: 0リリース

非推奨となったメトリクスの説明テキストには、先頭に非推奨を通知する文字列「(Deprecated from x.y)」が付けられ、 メトリクスの登録時に警告ログが出力されます。 非推奨でない安定版のメトリクスと同様に、非推奨となったメトリクスも自動的にメトリクスエンドポイントに登録されるため、表示されます。

後続のリリース(メトリクスのdeprecatedVersionが current_kubernetes_version - 3 に等しい場合)で、 非推奨となったメトリクスは 非表示 になります。 非推奨となったメトリクス とは異なり 、非表示のメトリクスは自動的にメトリクスエンドポイントに登録されなくなります(それゆえに非表示になります)。 ただし、バイナリのコマンドラインフラグ(--show-hidden-metrics-for-version=)を使用して明示的に有効化することができます。 これによりクラスター管理者は、以前の非推奨の警告に対応できなかった場合でも、 非推奨となったメトリクスから適切に移行するための回避策を取ることができます。 非表示のメトリクスは、1リリース後に削除される必要があります。

例外

想定し得るすべての状況を網羅するポリシーはありません。 このポリシーは生きたドキュメントであり、時間の経過とともに改善されます。 実際には、このポリシーにうまく適合しない状況や、このポリシーが重大な障害となる状況が発生する可能性があります。 そのような状況では、特定のケースに対して最適な解決策を見つけるためにSIGやプロジェクトリーダーと協議するべきであり、 Kubernetesが可能な限りユーザーに影響を与えない安定したシステムであることを常に念頭に置いておくべきです。 例外は、関連するすべてのリリースノートで常にアナウンスされます。

5 - RBAC認可を使用する

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

RBAC認可はAPIグループ 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オブジェクト(Role、 ClusterRole、 RoleBinding そして 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のオブジェクトを削除して、代わりのオブジェクトを作成する必要があります。

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

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に属するリソースであり、logはpodsのサブリソースです。これを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と名付けられた ConfigMapをupdateのみに制限する例です。

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の例

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

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

ユーザー向けRole

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

ユーザー向けのClusterRolesはClusterRoleの集約を使用して、管理者がこれらのClusterRolesにカスタムリソースのルールを含めることができるようにします。ルールをadmin、edit、または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"

コアコンポーネントのRole

他のコンポーネントのRole

組み込みコントローラーの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-namespaceの admin、 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」を使用します。

   備考:

   サービスアカウント「default」に付与された権限は、serviceAccountNameを指定しないNamespace内のすべてのポッドで利用できます。

   たとえば、「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権限を付与します。

   注意:

   これを有効にすると、 Namespace`kube-systemにクラスターのAPIへのスーパーユーザーアクセス許可するSecretsが含まれます。
   

   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. クラスター全体のすべてのサービスアカウントへのスーパーユーザーアクセスを許可します。(強くお勧めしません)

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

   警告:

   これにより、すべてのアプリケーションにクラスターへのフルアクセスが許可され、Secretsの読み取りアクセス権(または任意のポッドを作成する機能)を持つユーザーに、クラスターへのフルアクセスが許可されます。
   

   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ポリシーを複製できます。

kubectl create clusterrolebinding permissive-binding \
  --clusterrole=cluster-admin \
  --user=admin \
  --user=kubelet \
  --group=system:serviceaccounts

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

6 - ネットワーキングのリファレンス

このセクションでは、Kubernetesネットワーキングの詳細を提供します。

6.1 - ポートとプロトコル

パブリッククラウドにおける仮想ネットワークや、物理ネットワークファイアウォールを持つオンプレミスのデータセンターのような、ネットワークの境界が厳格な環境でKubernetesを実行する場合、Kubernetesのコンポーネントが使用するポートやプロトコルを認識しておくと便利です。

コントロールプレーン

etcdポートはコントロールプレーンノードに含まれていますが、独自のetcdクラスターを外部またはカスタムポートでホストすることもできます。

ワーカーノード

† NodePort Servicesのデフォルトのポート範囲。

すべてのデフォルトのポート番号が書き換え可能です。 カスタムポートを使用する場合、ここに記載されているデフォルトではなく、それらのポートを開く必要があります。

よくある例としては、API Serverのポートを443に変更することがあります。 または、デフォルトポートをそのままにし、API Serverを443でリッスンしているロードバランサーの後ろに置き、APIサーバのデフォルトポートにリクエストをルーティングする方法もあります。

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

7.1 - Kubeadm

kubeadmは、kubeadm initやkubeadm 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で、コミュニティからのフィードバックを集めるために有効にされた各種機能を試用する

7.1.1 - Kubeadm Generated

7.1.1.1 -

kubeadmが使用するイメージの一覧を出力します。 設定ファイルはイメージやイメージリポジトリをカスタマイズする際に使用されます。

概要

kubeadmが使用するイメージの一覧を出力します。 設定ファイルはイメージやイメージリポジトリをカスタマイズする際に使用されます。

kubeadm config images list [flags]

オプション

親コマンドから継承されたオプション

7.1.1.2 -

kubeadmによって使用されるイメージをプルします。

概要

kubeadmによって使用されるイメージをプルします。

kubeadm config images pull [flags]

オプション

親コマンドから継承されたオプション

7.1.1.3 -

ファイルから古いバージョンのAPIタイプのkubeadmの設定を読み込み、新しいバージョンの同等の設定オブジェクトを出力します。

概要

このコマンドは、古いバージョンの設定オブジェクトを、サポートされている最新のバージョンに変換します。 これはクラスターを何も触ることなく、CLIツール内に閉じています。 kubeadmのこのバージョンでは、次のAPIバージョンがサポートされています:

• kubeadm.k8s.io/v1beta3

さらに、kubeadmはバージョン"kubeadm.k8s.io/v1beta3"の設定しか出力できませんが、両方の種類を読むことができます。 このため、どのバージョンを--old-configパラメーターに渡したとしても、APIオブジェクトは読み込まれ、デシリアライズ、デフォルト化、変換、検証、再シリアライズされて、標準出力または--new-configで指定されたファイルに出力されます。

言い換えると、このコマンドの出力は、そのファイルを"kubeadm init"に渡した時にkubeadmが実際に内部で読むものとなります。

kubeadm config migrate [flags]

オプション

親コマンドから継承されたオプション

7.1.1.4 -

設定を出力します。

概要

このコマンドは、指定されたサブコマンドに対する設定を出力します。 詳細については次を参照してください: https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm#section-directories

kubeadm config print [flags]

オプション

親コマンドから継承されたオプション

7.1.1.5 -

kubeadm initで使用できるデフォルトのInitConfigurationを出力します。

概要

このコマンドは、'kubeadm init'で使用されるデフォルトのInitConfigurationオブジェクトを出力します。

Bootstrap Tokenフィールドのような機密性が高い値は、実際にトークンを生成する計算は実行しませんが、検証をパスするために"abcdef.0123456789abcdef"のようなプレースホルダーの値に置き換えられることに注意してください。

kubeadm config print init-defaults [flags]

オプション

親コマンドから継承されたオプション

7.1.1.6 -

kubeadm joinで使用できるデフォルトのJoinConfigurationを出力します。

概要

このコマンドはkubeadm joinで使用されるデフォルトのJoinConfigurationオブジェクトを出力します

Bootstrap Tokenフィールドのような機密性が高い値は、実際にトークンを生成する計算は実行しませんが、検証をパスするために"abcdef.0123456789abcdef"のようなプレースホルダーの値に置き換えられることに注意してください。

kubeadm config print join-defaults [flags]

オプション

親コマンドから継承されたオプション

7.1.1.7 -

kubeadm設定APIを含むファイルを読み込み、検証に問題があれば報告します。

概要

このコマンドはkubeadm設定APIファイルを検証して、警告やエラーがあれば報告します。 エラーが無い場合は終了ステータスはゼロ、それ以外の場合はゼロ以外の値となります。 不明なAPIフィールドのようなデータ変換できない問題については、エラーが発生します。 不明なAPIバージョンや不正な値を持つフィールドについてもエラーとなります。 入力ファイルの内容によっては、その他のエラーや警告が報告されることもあります。

このバージョンのkubeadmでは、次のAPIバージョンがサポートされています:

• kubeadm.k8s.io/v1beta3

kubeadm config validate [flags]

オプション

親コマンドから継承されたオプション

7.1.2 - kubeadm config

kubeadm initの実行中、kubeadmはクラスターに対して、kube-system名前空間内のkubeadm-configという名前のConfigMapにClusterConfigurationオブジェクトをアップロードします。 この設定はkubeadm join、kubeadm resetおよびkubeadm upgradeの実行中に読み込まれます。

kubeadm config printによって、kubeadmがkubeadm initやkubeadm joinで使用する、デフォルトの静的な設定を表示することができます。

initとjoinのより詳細な情報については、設定ファイルを使ったkubeadm initの利用、または設定ファイルを使ったkubeadm joinの利用を参照してください。

kubeadmの設定APIの使用法に関するより詳細な情報については、kubeadm APIを使ったコンポーネントのカスタマイズを参照してください。

非推奨のAPIバージョンを含んだ古い設定ファイルを、サポートされた新しいAPIバージョンに変換する際には、kubeadm config migrateコマンドを使用することができます。

設定ファイルを検証するためには、kubeadm config validateを使用することができます。

kubeadmが必要とするイメージを表示、取得するために、kbueadm config images listやkubeadm config images pullを使用することができます。

kubeadm config print

設定を出力します。

概要

このコマンドは、指定されたサブコマンドに対する設定を出力します。 詳細については次を参照してください: https://pkg.go.dev/k8s.io/kubernetes/cmd/kubeadm/app/apis/kubeadm#section-directories

kubeadm config print [flags]

オプション

親コマンドから継承されたオプション

kubeadm config print init-defaults

kubeadm initで使用できるデフォルトのInitConfigurationを出力します。

概要

このコマンドは、'kubeadm init'で使用されるデフォルトのInitConfigurationオブジェクトを出力します。

Bootstrap Tokenフィールドのような機密性が高い値は、実際にトークンを生成する計算は実行しませんが、検証をパスするために"abcdef.0123456789abcdef"のようなプレースホルダーの値に置き換えられることに注意してください。

kubeadm config print init-defaults [flags]

オプション

親コマンドから継承されたオプション

kubeadm config print join-defaults

kubeadm joinで使用できるデフォルトのJoinConfigurationを出力します。

概要

このコマンドはkubeadm joinで使用されるデフォルトのJoinConfigurationオブジェクトを出力します

Bootstrap Tokenフィールドのような機密性が高い値は、実際にトークンを生成する計算は実行しませんが、検証をパスするために"abcdef.0123456789abcdef"のようなプレースホルダーの値に置き換えられることに注意してください。

kubeadm config print join-defaults [flags]

オプション

親コマンドから継承されたオプション

kubeadm config migrate

ファイルから古いバージョンのAPIタイプのkubeadmの設定を読み込み、新しいバージョンの同等の設定オブジェクトを出力します。

概要

このコマンドは、古いバージョンの設定オブジェクトを、サポートされている最新のバージョンに変換します。 これはクラスターを何も触ることなく、CLIツール内に閉じています。 kubeadmのこのバージョンでは、次のAPIバージョンがサポートされています:

• kubeadm.k8s.io/v1beta3

さらに、kubeadmはバージョン"kubeadm.k8s.io/v1beta3"の設定しか出力できませんが、両方の種類を読むことができます。 このため、どのバージョンを--old-configパラメーターに渡したとしても、APIオブジェクトは読み込まれ、デシリアライズ、デフォルト化、変換、検証、再シリアライズされて、標準出力または--new-configで指定されたファイルに出力されます。

言い換えると、このコマンドの出力は、そのファイルを"kubeadm init"に渡した時にkubeadmが実際に内部で読むものとなります。

kubeadm config migrate [flags]

オプション

親コマンドから継承されたオプション

kubeadm config validate

kubeadm設定APIを含むファイルを読み込み、検証に問題があれば報告します。

概要

このコマンドはkubeadm設定APIファイルを検証して、警告やエラーがあれば報告します。 エラーが無い場合は終了ステータスはゼロ、それ以外の場合はゼロ以外の値となります。 不明なAPIフィールドのようなデータ変換できない問題については、エラーが発生します。 不明なAPIバージョンや不正な値を持つフィールドについてもエラーとなります。 入力ファイルの内容によっては、その他のエラーや警告が報告されることもあります。

このバージョンのkubeadmでは、次のAPIバージョンがサポートされています:

• kubeadm.k8s.io/v1beta3

kubeadm config validate [flags]

オプション

親コマンドから継承されたオプション

kubeadm config images list

kubeadmが使用するイメージの一覧を出力します。 設定ファイルはイメージやイメージリポジトリをカスタマイズする際に使用されます。

概要

kubeadmが使用するイメージの一覧を出力します。 設定ファイルはイメージやイメージリポジトリをカスタマイズする際に使用されます。

kubeadm config images list [flags]

オプション

親コマンドから継承されたオプション

kubeadm config images pull

kubeadmによって使用されるイメージをプルします。

概要

kubeadmによって使用されるイメージをプルします。

kubeadm config images pull [flags]

オプション

親コマンドから継承されたオプション

次の項目

• kubeadm upgradeを使用すると、Kubernetesクラスターを最新のバージョンにアップグレードすることができます

8 - コマンドラインツール(kubectl)

Kubernetesが提供する、 kubernetes APIを使用してKubernetesクラスターのコントロールプレーンと通信するためのコマンドラインツールです。

このツールの名前は、kubectl です。

kubectlコマンドラインツールを使うと、Kubernetesクラスターを制御できます。環境設定のために、kubectlは、$HOME/.kubeディレクトリにあるconfigという名前のファイルを探します。他のkubeconfigファイルは、KUBECONFIG環境変数を設定するか、--kubeconfigフラグを設定することで指定できます。

この概要では、kubectlの構文を扱い、コマンド操作を説明し、一般的な例を示します。サポートされているすべてのフラグやサブコマンドを含め、各コマンドの詳細については、kubectlリファレンスドキュメントを参照してください。

インストール方法については、kubectlのインストールおよびセットアップをご覧ください。クイックガイドは、チートシートをご覧ください。dockerコマンドラインツールに慣れている方は、kubectl for Docker UsersでKubernetesの同等のコマンドを説明しています。

構文

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

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

ここで、command、TYPE、NAME、flagsは、以下を表します。

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

• 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<#>とします。

    • 特に設定ファイルについては、YAMLの方がより使いやすいため、JSONではなくYAMLを使用してください。
      例: kubectl get pod -f ./pod.yaml

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

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

クラスター内認証と名前空間のオーバーライド

デフォルトでは、kubectlは最初にPod内で動作しているか、つまりクラスター内で動作しているかどうかを判断します。まず、KUBERNETES_SERVICE_HOSTとKUBERNETES_SERVICE_PORTの環境変数を確認し、サービスアカウントのトークンファイルが/var/run/secrets/kubernetes.io/serviceaccount/tokenに存在するかどうかを確認します。3つともクラスター内で見つかった場合、クラスター内認証とみなされます。

後方互換性を保つため、クラスター内認証時にPOD_NAMESPACE環境変数が設定されている場合には、サービスアカウントトークンのデフォルトの名前空間が上書きされます。名前空間のデフォルトに依存しているすべてのマニフェストやツールは、この影響を受けます。

POD_NAMESPACE環境変数

POD_NAMESPACE環境変数が設定されている場合、名前空間に属するリソースのCLI操作は、デフォルトで環境変数の値になります。例えば、変数にseattleが設定されている場合、kubectl get podsは、seattle名前空間のPodを返します。これは、Podが名前空間に属するリソースであり、コマンドで名前空間が指定されていないためです。kubectl api-resourcesの出力を見て、リソースが名前空間に属するかどうかを判断してください。

明示的に--namespace <value>を使用すると、この動作は上書きされます。

kubectlによるServiceAccountトークンの処理方法

以下の条件がすべて成立した場合、

• /var/run/secrets/kubernetes.io/serviceaccount/tokenにマウントされたKubernetesサービスアカウントのトークンファイルがある
• KUBERNETES_SERVICE_HOST環境変数が設定されている
• KUBERNETES_SERVICE_PORT環境変数が設定されている
• kubectlコマンドラインで名前空間を明示的に指定しない

kubectlはクラスター内で実行されているとみなして、そのServiceAccountの名前空間(これはPodの名前空間と同じです)を検索し、その名前空間に対して機能します。これは、クラスターの外の動作とは異なります。kubectlがクラスターの外で実行され、名前空間を指定しない場合、kubectlコマンドは、クライアント構成の現在のコンテキストに設定されている名前空間に対して動作します。kubectlのデフォルトの名前空間を変更するには、次のコマンドを使用できます。

kubectl config set-context --current --namespace=<namespace-name>

操作

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

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

リソースタイプ

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

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

出力オプション

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

出力のフォーマット

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

構文

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

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

例

この例において、以下のコマンドは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リファレンスドキュメントをお読みください。
  • kubectlコマンドリファレンス
  • コマンドライン引数リファレンス
• kubectlの使用規則について学習してください。
• kubectlのJSONPathのサポートについてお読みください。
• プラグインを使用して kubectl を拡張する方法についてお読みください。
  • プラグインについてより詳しく知りたい場合は、example CLI pluginをご覧ください。

8.1 - 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とそのコンテナのメトリクスを表示します