リファレンス

• 1: 標準化用語集
• 2: 認証
• 3: セットアップツールのリファレンス
• 3.1: Kubeadm
• 4: kubectl CLI
• 4.1: kubectlの概要
• 4.2: JSONPathのサポート
• 4.3: kubectlチートシート
• 5: コマンドラインツールのリファレンス
• 5.1: フィーチャーゲート
• 5.2: Kubelet 認証/認可
• 6: RBAC認可を使用する
• 7: ツール

1 - 標準化用語集

2 - 認証

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

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に関連付けることができます。

備考: 自動で行われるため、通常serviceAccountNameは省略します。

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

備考: Secretは常にbase64でエンコードされるため、これらの値もbase64でエンコードされています。

署名された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-"を推奨します。ユーザーに関する追加情報を判断するために検索するヘッダーのプレフィックスです。通常、設定された認可プラグインによって使用されます。指定されたプレフィックスのいずれかで始まるヘッダーは、プレフィックスが削除されます。ヘッダー名の残りの部分は小文字化されパーセントデコーディングされて追加のキーとなり、ヘッダーの値が追加の値となります。

備考: 1.11.3(および1.10.7、1.9.11)よりも前のバージョンでは、追加のキーにはHTTPヘッダーラベルで使用可能な文字のみを含めることができました。

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

--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であり、パーセントエンコーディングされている必要があります.

備考: 1.11.3(および1.10.7、1.9.11)よりも前のバージョンでは、( extra name )にはHTTPヘッダーラベルで使用可能な文字のみを含めることができました。

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

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"
  }
}

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

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

4 - kubectl CLI

4.1 - kubectlの概要

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

構文

ターミナルウィンドウから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のすべての操作の簡単な説明と一般的な構文を示します。

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

リソースタイプ

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

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

出力オプション

ある特定のコマンドの出力に対してフォーマットやソートを行う方法については、以下の節を参照してください。どのコマンドが様々な出力オプションをサポートしているかについては、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 getコマンドは通常、同じリソースタイプの1つ以上のリソースを取得するために使用します。豊富なフラグが用意されており、例えば-oや--outputフラグを使って、出力フォーマットをカスタマイズできます。-wや--watchフラグを指定することで、特定のオブジェクトの更新を監視できます。kubectl describeコマンドは、指定されたリソースに関する多くの側面を説明することに重点を置いています。ユーザーに対してビューを構築するために、APIサーバーへ複数のAPIコールを呼び出すことができます。例えば、kubectl describe nodeコマンドは、Nodeに関する情報だけでなく、その上で動いているPodやNodeで生成されたイベントなどをまとめて表示します。

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が既に作成済であることを前提としています。 The next few examples assume that you already made kubectl-whoami have the following contents:

#!/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を御覧ください。

4.2 - JSONPathのサポート

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

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

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

備考:

• 式は常にルートのオブジェクトから始まるので、$オペレーターの入力は任意になります。

• 結果のオブジェクトはString()関数を適用した形で表示されます。

以下のような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"}
    }
  ]
}

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}'

備考:

Windowsでは、空白が含まれるJSONPathのテンプレートをクォートする場合は(上記のようにシングルクォーテーションを使うのではなく)、ダブルクォーテーションを使わなければなりません。 また、テンプレート内のリテラルをクォートする際には、シングルクォーテーションか、エスケープされたダブルクォーテーションを使わなければなりません。例えば:

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

備考:

JSONPathの正規表現はサポートされていません。正規表現を利用した検索を行いたい場合は、jqのようなツールを使ってください。

# kubectlはJSONpathの出力として正規表現をサポートしていないので、以下のコマンドは動作しない
kubectl get pods -o jsonpath='{.items[?(@.metadata.name=~/^test$/)].metadata.name}'

# 上のコマンドに期待される結果が欲しい場合、以下のコマンドを使うとよい
kubectl get pods -o json | jq -r '.items[] | select(.metadata.name | test("test-")).spec.containers[].image'

4.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 'path(..)|[.[]|tostring]|join(".")'

# Pod等から返されるすべてのキーをピリオド区切り階層表記で生成します。
kubectl get pods -o json | jq -c 'path(..)|[.[]|tostring]|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 groupかNamespaced、Kindに関わらずその短縮名をリストします。

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を使用したサンプル:

# クラスター内で実行中のすべてのイメージ名を表示する
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のログ記録規則と関連するログレベルについて、こちらで説明します。

次の項目

• kubectlについてより深く学びたい方はkubectl概要やJsonPathをご覧ください。

• オプションについてはkubectl optionsをご覧ください。

• またkubectlの利用パターンでは再利用可能なスクリプトでkubectlを利用する方法を学べます。

• コミュニティ版kubectlチートシートもご覧ください。

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

5.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のフィーチャーゲート

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

機能を使用する

機能のステージ

機能にはAlpha 、Beta 、GA の段階があります。Alpha 機能とは：

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

Beta 機能とは：

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

備考: ベータ版 の機能を試してフィードバックをお寄せください！ GAになってからさらなる変更を加えることは現実的ではない場合があります。

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

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

フィーチャーゲート

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

• Accelerators: DockerでのNvidia GPUのサポートを有効にします。
• AdvancedAuditing: 高度な監査機能を有効にします。
• AffinityInAnnotations(非推奨): Podのアフィニティまたはアンチアフィニティを有効にします。
• AnyVolumeDataSource: PVCのDataSourceとしてカスタムリソースの使用を有効にします。
• AllowExtTrafficLocalEndpoints: サービスが外部へのリクエストをノードのローカルエンドポイントにルーティングできるようにします。
• APIListChunking: APIクライアントがAPIサーバーからチャンク単位で（LISTやGETの）リソースを取得できるようにします。 APIPriorityAndFairness: 各サーバーで優先順位付けと公平性を備えた要求の並行性を管理できるようにします(RequestManagementから名前が変更されました)。
• APIResponseCompression:LISTやGETリクエストの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: ホストするデフォルトのユーザー名前空間を有効にします。これは他のホストの名前空間やホストのマウントを使用しているコンテナ、特権を持つコンテナ、または名前空間のない特定の機能（たとえばMKNODE、SYS_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: Service、Endpoints、NetworkPolicy、Podの定義で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サーバーに指示します。ストリーミングリクエストの例にはexec、attach、port-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の非推奨ポリシーでは、機能とコンポーネントを削除するためのプロジェクトのアプローチを説明しています。

5.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動詞から決定されます:

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

名前空間と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

6 - 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オブジェクト(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"]

備考: resourceNamesでcreateまたはdeletecollectionのリクエストを制限することはできません。この制限はcreateの場合、認証時にオブジェクト名がわからないためです。

集約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。 認証が必要な形式のユーザー名を生成するように認証モジュールを構成するかどうかは、クラスター管理者が決定します。

注意: プレフィックスsystem:はKubernetesシステムで使用するために予約されているため、誤ってsystem:で始まる名前のユーザーまたはグループが存在しないようにする必要があります。 この特別なプレフィックスを除いて、RBAC承認システムでは、ユーザー名の形式は問いません。

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

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

備考:

• 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が付いています。

注意: プレフィックスとしてsystem:を含む名前で、ClusterRolesおよびClusterRoleBindingsを変更する場合は注意してください。 これらのリソースを変更すると、クラスターが機能しなくなる可能性があります。

自動調整

起動するたびに、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

備考: ClusterRoleを編集すると、変更が自動調整によるAPIサーバーの再起動時に上書きされます。この上書きを回避するにはRoleを手動で編集しないか、自動調整を無効にします。

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

警告:

次のポリシーでは、すべてのサービスアカウントがクラスター管理者としてふるまうことを許可しています。 コンテナで実行されているアプリケーションは、サービスアカウントのクレデンシャルを自動的に受け取ります。 secretsの表示や権限の変更など、APIに対して任意のアクションを実行できます。 これは推奨されるポリシーではありません。

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

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

7 - ツール

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

Kubectl

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

Kubeadm

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

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 ファイルならびに分散されたアプリケーションバンドルの変換