リファレンス
本セクションには、Kubernetesのドキュメントのリファレンスが含まれています。
APIリファレンス
APIクライアントライブラリー
プログラミング言語からKubernetesのAPIを呼ぶためには、クライアントライブラリーを使うことができます。公式にサポートしているクライアントライブラリー:
CLIリファレンス
- kubectl - コマンドの実行やKubernetesクラスターの管理に使う主要なCLIツールです。
- kubeadm - セキュアなKubernetesクラスターを簡単にプロビジョニングするためのCLIツールです。
コンポーネントリファレンス
- kubelet - 各ノード上で動作する最も重要なノードエージェントです。kubeletは一通りのPodSpecを受け取り、コンテナーが実行中で正常であることを確認します。
- kube-apiserver - Pod、Service、Replication Controller等、APIオブジェクトのデータを検証・設定するREST APIサーバーです。
- kube-controller-manager - Kubernetesに同梱された、コアのコントロールループを埋め込むデーモンです。
- kube-proxy - 単純なTCP/UDPストリームのフォワーディングや、一連のバックエンド間でTCP/UDPのラウンドロビンでのフォワーディングを実行できます。
- kube-scheduler - 可用性、パフォーマンス、およびキャパシティを管理するスケジューラーです。
設計のドキュメント
Kubernetesの機能に関する設計ドキュメントのアーカイブです。Kubernetesアーキテクチャ とKubernetesデザイン概要から読み始めると良いでしょう。
1 - 標準化用語集
2 - 認証
このページでは、認証の概要について説明します。
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
や[email protected]
です。
- 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
ブートストラップトークン
FEATURE STATE: Kubernetes v1.18 [stable]
新しいクラスタの効率的なブートストラップを可能にするために、Kubernetesにはブートストラップトークンと呼ばれる動的に管理されたBearerトークンタイプが含まれています。これらのトークンは、kube-system
名前空間にSecretsとして格納され、動的に管理したり作成したりすることができます。コントローラーマネージャーには、TokenCleanerコントローラーが含まれており、ブートストラップトークンの有効期限が切れると削除します。
トークンの形式は[a-z0-9]{6}.[a-z0-9]{16}
です。最初のコンポーネントはトークンIDであり、第2のコンポーネントはToken Secretです。以下のように、トークンをHTTPヘッダーに指定します。
Authorization: Bearer 781292.db7bc3a58fc5f07e
APIサーバーの--enable-bootstrap-token-auth
フラグで、Bootstrap Token Authenticatorを有効にする必要があります。TokenCleanerコントローラーを有効にするには、コントローラーマネージャーの--controllers
フラグを使います。--controllers=*,tokencleaner
のようにして行います。クラスターをブートストラップするためにkubeadm
を使用している場合は、kubeadm
がこれを代行してくれます。
認証機能はsystem:bootstrap:<Token ID>
という名前で認証します。これはsystem:bootstrappers
グループに含まれます。名前とグループは意図的に制限されており、ユーザーがブートストラップ後にこれらのトークンを使わないようにしています。ユーザー名とグループは、クラスタのブートストラップをサポートする適切な認可ポリシーを作成するために使用され、kubeadm
によって使用されます。
ブートストラップトークンの認証機能やコントローラーについての詳細な説明、kubeadm
でこれらのトークンを管理する方法については、ブートストラップトークンを参照してください。
サービスアカウントトークン
サービスアカウントは、自動的に有効化される認証機能で、署名されたBearerトークンを使ってリクエストを検証します。このプラグインは、オプションとして2つのフラグを取ります。
--service-account-key-file
: Bearerトークンに署名するためのPEMエンコードされた鍵を含むファイルです。指定しない場合は、APIサーバーのTLS秘密鍵が使われます。
--service-account-lookup
: 有効にすると、APIから削除されたトークンは取り消されます。
サービスアカウントは通常、APIサーバーによって自動的に作成され、ServiceAccount
Admission 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トークンを含めるを参照してください。
- IDプロバイダーにログインします
- IDプロバイダーは、
access_token
、id_token
、refresh_token
を提供します
kubectl
を使う場合は、--token
フラグでid_token
を使うか、kubeconfig
に直接追加してください
kubectl
は、id_token
をAuthorizationと呼ばれるヘッダーでAPIサーバーに送ります
- APIサーバーは、設定で指定された証明書と照合することで、JWT署名が有効であることを確認します
id_token
の有効期限が切れていないことを確認します
- ユーザーが認可されていることを確認します
- 認可されると、APIサーバーは
kubectl
にレスポンスを返します
kubectl
はユーザーにフィードバックを提供します
自分が誰であるかを確認するために必要なデータはすべてid_token
の中にあるので、KubernetesはIDプロバイダーと通信する必要がありません。すべてのリクエストがステートレスであるモデルでは、これは非常に認証のためのスケーラブルなソリューションを提供します。一方で、以下のようにいくつか課題があります。
- Kubernetesには、認証プロセスを起動するための"Webインターフェース"がありません。クレデンシャルを収集するためのブラウザやインターフェースがないため、まずIDプロバイダに認証を行う必要があります。
id_token
は、取り消すことができません。これは証明書のようなもので、有効期限が短い(数分のみ)必要があるので、数分ごとに新しいトークンを取得しなければならないのは非常に面倒です。
- Kubernetesダッシュボードへの認証において、
kubectl proxy
コマンドやid_token
を注入するリバースプロキシーを使う以外に、簡単な方法はありません。
APIサーバーの設定
プラグインを有効にするには、APIサーバーで以下のフラグを設定します。
パラメーター |
説明 |
例 |
必須か |
--oidc-issuer-url |
APIサーバーが公開署名鍵を発見できるようにするプロバイダーのURLです。 https:// スキームを使用するURLのみが受け入れられます。これは通常、"https://accounts.google.com"や"https://login.salesforce.com"のようにパスを持たないプロバイダのディスカバリーURLです。このURLは、.well-known/openid-configuration の下のレベルを指す必要があります。 |
ディスカバリーURLがhttps://accounts.google.com/.well-known/openid-configuration である場合、値はhttps://accounts.google.com とします。 |
はい |
--oidc-client-id |
すべてのトークンが発行されなければならないクライアントIDです。 |
kubernetes |
はい |
--oidc-username-claim |
ユーザー名として使用するJWTのクレームを指定します。デフォルトではsub が使用されますが、これはエンドユーザーの一意の識別子であることが期待されます。管理者はプロバイダーに応じてemail やname などの他のクレームを選択することができます。ただし、他のプラグインとの名前の衝突を防ぐために、email 以外のクレームには、プレフィックスとして発行者のURLが付けられます。 |
sub |
いいえ |
--oidc-username-prefix |
既存の名前(system: ユーザーなど)との衝突を防ぐために、ユーザー名の前にプレフィックスを付加します。例えばoidc: という値は、oidc:jane.doe のようなユーザー名を生成します。このフラグが指定されておらず、--oidc-username-claim がemail 以外の値である場合、プレフィックスのデフォルトは(Issuer URL)# で、(Issuer URL) は--oidc-issuer-url の値です。すべてのプレフィックスを無効にするためには、- という値を使用できます。 |
oidc: |
いいえ |
--oidc-groups-claim |
ユーザーのグループとして使用するJWTのクレームです。クレームがある場合は、文字列の配列である必要があります。 |
groups |
いいえ |
--oidc-groups-prefix |
既存の名前(system: グループなど)との衝突を防ぐために、グループ名の前にプレフィックスを付加します。例えばoidc: という値は、oidc:engineering やoidc:infra のようなグループ名を生成します。 |
oidc: |
いいえ |
--oidc-required-claim |
IDトークンの中の必須クレームを記述するkey=valueのペアです。設定されている場合、クレームが一致する値でIDトークンに存在することが検証されます。このフラグを繰り返して複数のクレームを指定します。 |
claim=value |
いいえ |
--oidc-ca-file |
IDプロバイダーのWeb証明書に署名した認証局の証明書へのパスです。デフォルトはホストのルート認証局が指定されます。 |
/etc/kubernetes/ssl/kc-ca.pem |
いいえ |
重要なのは、APIサーバーはOAuth2クライアントではなく、ある単一の発行者を信頼するようにしか設定できないことです。これにより、サードパーティーに発行されたクレデンシャルを信頼せずに、Googleのようなパブリックプロバイダーを使用することができます。複数のOAuthクライアントを利用したい管理者は、azp
クレームをサポートしているプロバイダや、あるクライアントが別のクライアントに代わってトークンを発行できるような仕組みを検討する必要があります。
KubernetesはOpenID Connect IDプロバイダーを提供していません。既存のパブリックなOpenID Connect IDプロバイダー(Googleやその他など)を使用できます。もしくは、CoreOS dex、Keycloak、CloudFoundryUAA、Tremolo SecurityのOpenUnisonなど、独自のIDプロバイダーを実行することもできます。
IDプロバイダーがKubernetesと連携するためには、以下のことが必要です。
- すべてではないが、[OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html)をサポートしていること
- 廃れていない暗号を用いたTLSで実行されていること
- 認証局が署名した証明書を持っていること(認証局が商用ではない場合や、自己署名の場合も可)
上述の要件#3、認証局署名付き証明書を必要とすることについて、注意事項があります。GoogleやMicrosoftなどのクラウドプロバイダーではなく、独自のIDプロバイダーをデプロイする場合は、たとえ自己署名されていても、CA
フラグがTRUE
に設定されている証明書によって署名されたIDプロバイダーのWebサーバー証明書を持っていなければなりません。これは、Go言語のTLSクライアント実装が、証明書検証に関する標準に対して非常に厳格であるためです。認証局をお持ちでない場合は、CoreOSチームのこのスクリプトを使用して、シンプルな認証局と署名付きの証明書と鍵のペアを作成することができます。
または、この類似のスクリプトを使って、より寿命が長く、よりキーサイズの大きいSHA256証明書を生成できます。
特定のシステム用のセットアップ手順は、以下を参照してください。
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": "[email protected]",
"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: [email protected]
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
ヘッダーを設定します。
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:
# "[email protected]"というユーザーを偽装できます。
- apiGroups: [""]
resources: ["users"]
verbs: ["impersonate"]
resourceNames: ["[email protected]"]
# "developers"と"admins"というグループを偽装できます。
- apiGroups: [""]
resources: ["groups"]
verbs: ["impersonate"]
resourceNames: ["developers","admins"]
# "view"と"development"を値に持つ"scopes"という追加フィールドを偽装できます。
- apiGroups: ["authentication.k8s.io"]
resources: ["userextras/scopes"]
verbs: ["impersonate"]
resourceNames: ["view", "development"]
client-goクレデンシャルプラグイン
FEATURE STATE: Kubernetes v1.11 [beta]
k8s.io/client-go
と、それを使用する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をインストールするには、インストールガイドを参照してください。
次の項目
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つまたは複数のファイルを指定することができます。
-
flags
: オプションのフラグを指定します。例えば、-s
または--server
フラグを使って、Kubernetes APIサーバーのアドレスやポートを指定できます。
注意: コマンドラインから指定したフラグは、デフォルト値および対応する任意の環境変数を上書きします。
ヘルプが必要な場合は、ターミナルウィンドウからkubectl help
を実行してください。
操作
以下の表に、kubectl
のすべての操作の簡単な説明と一般的な構文を示します。
操作 |
構文 |
説明 |
alpha |
kubectl alpha SUBCOMMAND [flags] |
アルファ機能に該当する利用可能なコマンドを一覧表示します。これらの機能は、デフォルトではKubernetesクラスターで有効になっていません。 |
annotate |
kubectl annotate (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] |
1つ以上のリソースのアノテーションを、追加または更新します。 |
api-resources |
kubectl api-resources [flags] |
利用可能なAPIリソースを一覧表示します。 |
api-versions |
kubectl api-versions [flags] |
利用可能なAPIバージョンを一覧表示します。 |
apply |
kubectl apply -f FILENAME [flags] |
ファイルまたは標準出力から、リソースの設定変更を適用します。 |
attach |
kubectl attach POD -c CONTAINER [-i] [-t] [flags] |
実行中のコンテナにアタッチして、出力ストリームを表示するか、コンテナ(標準入力)と対話します。 |
auth |
kubectl auth [flags] [options] |
認可を検査します。 |
autoscale |
kubectl autoscale (-f FILENAME | TYPE NAME | TYPE/NAME) [--min=MINPODS] --max=MAXPODS [--cpu-percent=CPU] [flags] |
ReplicationControllerで管理されているPodのセットを、自動的にスケールします。 |
certificate |
kubectl certificate SUBCOMMAND [options] |
証明書のリソースを変更します。 |
cluster-info |
kubectl cluster-info [flags] |
クラスター内のマスターとサービスに関するエンドポイント情報を表示します。 |
completion |
kubectl completion SHELL [options] |
指定されたシェル(bashまたはzsh)のシェル補完コードを出力します。 |
config |
kubectl config SUBCOMMAND [flags] |
kubeconfigファイルを変更します。詳細は、個々のサブコマンドを参照してください。 |
convert |
kubectl convert -f FILENAME [options] |
異なるAPIバージョン間で設定ファイルを変換します。YAMLとJSONに対応しています。 |
cordon |
kubectl cordon NODE [options] |
Nodeをスケジュール不可に設定します。 |
cp |
kubectl cp <file-spec-src> <file-spec-dest> [options] |
コンテナとの間でファイルやディレクトリをコピーします。 |
create |
kubectl create -f FILENAME [flags] |
ファイルまたは標準出力から、1つ以上のリソースを作成します。 |
delete |
kubectl delete (-f FILENAME | TYPE [NAME | /NAME | -l label | --all]) [flags] |
ファイル、標準出力、またはラベルセレクター、リソースセレクター、リソースを指定して、リソースを削除します。 |
describe |
kubectl describe (-f FILENAME | TYPE [NAME_PREFIX | /NAME | -l label]) [flags] |
1つ以上のリソースの詳細な状態を表示します。 |
diff |
kubectl diff -f FILENAME [flags] |
ファイルまたは標準出力と、現在の設定との差分を表示します。 |
drain |
kubectl drain NODE [options] |
メンテナンスの準備のためにNodeをdrainします。 |
edit |
kubectl edit (-f FILENAME | TYPE NAME | TYPE/NAME) [flags] |
デファルトのエディタを使い、サーバー上の1つ以上のリソースリソースの定義を編集し、更新します。 |
exec |
kubectl exec POD [-c CONTAINER] [-i] [-t] [flags] [-- COMMAND [args...]] |
Pod内のコンテナに対して、コマンドを実行します。 |
explain |
kubectl explain [--recursive=false] [flags] |
様々なリソースのドキュメントを取得します。例えば、Pod、Node、Serviceなどです。 |
expose |
kubectl expose (-f FILENAME | TYPE NAME | TYPE/NAME) [--port=port] [--protocol=TCP|UDP] [--target-port=number-or-name] [--name=name] [--external-ip=external-ip-of-service] [--type=type] [flags] |
ReplicationController、Service、Podを、新しいKubernetesサービスとして公開します。 |
get |
kubectl get (-f FILENAME | TYPE [NAME | /NAME | -l label]) [--watch] [--sort-by=FIELD] [[-o | --output]=OUTPUT_FORMAT] [flags] |
1つ以上のリソースを表示します。 |
kustomize |
kubectl kustomize <dir> [flags] [options] |
kustomization.yamlファイル内の指示から生成されたAPIリソースのセットを一覧表示します。引数はファイルを含むディレクトリのPath,またはリポジトリルートに対して同じ場所を示すパスサフィックス付きのgitリポジトリのURLを指定しなければなりません。 |
label |
kubectl label (-f FILENAME | TYPE NAME | TYPE/NAME) KEY_1=VAL_1 ... KEY_N=VAL_N [--overwrite] [--all] [--resource-version=version] [flags] |
1つ以上のリソースのラベルを、追加または更新します。 |
logs |
kubectl logs POD [-c CONTAINER] [--follow] [flags] |
Pod内のコンテナのログを表示します。 |
options |
kubectl options |
すべてのコマンドに適用されるグローバルコマンドラインオプションを一覧表示します。 |
patch |
kubectl patch (-f FILENAME | TYPE NAME | TYPE/NAME) --patch PATCH [flags] |
Strategic Merge Patchの処理を使用して、リソースの1つ以上のフィールドを更新します。 |
plugin |
kubectl plugin [flags] [options] |
プラグインと対話するためのユーティリティを提供します。 |
port-forward |
kubectl port-forward POD [LOCAL_PORT:]REMOTE_PORT [...[LOCAL_PORT_N:]REMOTE_PORT_N] [flags] |
1つ以上のローカルポートを、Podに転送します。 |
proxy |
kubectl proxy [--port=PORT] [--www=static-dir] [--www-prefix=prefix] [--api-prefix=prefix] [flags] |
Kubernetes APIサーバーへのプロキシーを実行します。 |
replace |
kubectl replace -f FILENAME |
ファイルや標準出力から、リソースを置き換えます。 |
rollout |
kubectl rollout SUBCOMMAND [options] |
リソースのロールアウトを管理します。有効なリソースには、Deployment、DaemonSetとStatefulSetが含まれます。 |
run |
kubectl run NAME --image=image [--env="key=value"] [--port=port] [--dry-run=server|client|none] [--overrides=inline-json] [flags] |
指定したイメージを、クラスタ上で実行します。 |
scale |
kubectl scale (-f FILENAME | TYPE NAME | TYPE/NAME) --replicas=COUNT [--resource-version=version] [--current-replicas=count] [flags] |
指定したReplicationControllerのサイズを更新します。 |
set |
kubectl set SUBCOMMAND [options] |
アプリケーションリソースを設定します。 |
taint |
kubectl taint NODE NAME KEY_1=VAL_1:TAINT_EFFECT_1 ... KEY_N=VAL_N:TAINT_EFFECT_N [options] |
1つ以上のNodeのtaintを更新します。 |
top |
kubectl top [flags] [options] |
リソース(CPU/メモリー/ストレージ)の使用量を表示します。 |
uncordon |
kubectl uncordon NODE [options] |
Nodeをスケジュール可に設定します。 |
version |
kubectl version [--client] [flags] |
クライアントとサーバーで実行中のKubernetesのバージョンを表示します。 |
wait |
kubectl wait ([-f FILENAME] | resource.group/resource.name | resource.group [(-l label | --all)]) [--for=delete|--for condition=available] [options] |
実験中の機能: 1つ以上のリソースが特定の状態になるまで待ちます。 |
コマンド操作について詳しく知りたい場合は、kubectlリファレンスドキュメントを参照してください。
リソースタイプ
以下の表に、サポートされているすべてのリソースと、省略されたエイリアスの一覧を示します。
(この出力はkubectl api-resources
から取得でき、Kubernetes 1.13.3時点で正確でした。)
リソース名 |
短縮名 |
APIグループ |
名前空間に属するか |
リソースの種類 |
bindings |
|
|
true |
Binding |
componentstatuses |
cs |
|
false |
ComponentStatus |
configmaps |
cm |
|
true |
ConfigMap |
endpoints |
ep |
|
true |
Endpoints |
limitranges |
limits |
|
true |
LimitRange |
namespaces |
ns |
|
false |
Namespace |
nodes |
no |
|
false |
Node |
persistentvolumeclaims |
pvc |
|
true |
PersistentVolumeClaim |
persistentvolumes |
pv |
|
false |
PersistentVolume |
pods |
po |
|
true |
Pod |
podtemplates |
|
|
true |
PodTemplate |
replicationcontrollers |
rc |
|
true |
ReplicationController |
resourcequotas |
quota |
|
true |
ResourceQuota |
secrets |
|
|
true |
Secret |
serviceaccounts |
sa |
|
true |
ServiceAccount |
services |
svc |
|
true |
Service |
mutatingwebhookconfigurations |
|
admissionregistration.k8s.io |
false |
MutatingWebhookConfiguration |
validatingwebhookconfigurations |
|
admissionregistration.k8s.io |
false |
ValidatingWebhookConfiguration |
customresourcedefinitions |
crd , crds |
apiextensions.k8s.io |
false |
CustomResourceDefinition |
apiservices |
|
apiregistration.k8s.io |
false |
APIService |
controllerrevisions |
|
apps |
true |
ControllerRevision |
daemonsets |
ds |
apps |
true |
DaemonSet |
deployments |
deploy |
apps |
true |
Deployment |
replicasets |
rs |
apps |
true |
ReplicaSet |
statefulsets |
sts |
apps |
true |
StatefulSet |
tokenreviews |
|
authentication.k8s.io |
false |
TokenReview |
localsubjectaccessreviews |
|
authorization.k8s.io |
true |
LocalSubjectAccessReview |
selfsubjectaccessreviews |
|
authorization.k8s.io |
false |
SelfSubjectAccessReview |
selfsubjectrulesreviews |
|
authorization.k8s.io |
false |
SelfSubjectRulesReview |
subjectaccessreviews |
|
authorization.k8s.io |
false |
SubjectAccessReview |
horizontalpodautoscalers |
hpa |
autoscaling |
true |
HorizontalPodAutoscaler |
cronjobs |
cj |
batch |
true |
CronJob |
jobs |
|
batch |
true |
Job |
certificatesigningrequests |
csr |
certificates.k8s.io |
false |
CertificateSigningRequest |
leases |
|
coordination.k8s.io |
true |
Lease |
events |
ev |
events.k8s.io |
true |
Event |
ingresses |
ing |
extensions |
true |
Ingress |
networkpolicies |
netpol |
networking.k8s.io |
true |
NetworkPolicy |
poddisruptionbudgets |
pdb |
policy |
true |
PodDisruptionBudget |
podsecuritypolicies |
psp |
policy |
false |
PodSecurityPolicy |
clusterrolebindings |
|
rbac.authorization.k8s.io |
false |
ClusterRoleBinding |
clusterroles |
|
rbac.authorization.k8s.io |
false |
ClusterRole |
rolebindings |
|
rbac.authorization.k8s.io |
true |
RoleBinding |
roles |
|
rbac.authorization.k8s.io |
true |
Role |
priorityclasses |
pc |
scheduling.k8s.io |
false |
PriorityClass |
csidrivers |
|
storage.k8s.io |
false |
CSIDriver |
csinodes |
|
storage.k8s.io |
false |
CSINode |
storageclasses |
sc |
storage.k8s.io |
false |
StorageClass |
volumeattachments |
|
storage.k8s.io |
false |
VolumeAttachment |
出力オプション
ある特定のコマンドの出力に対してフォーマットやソートを行う方法については、以下の節を参照してください。どのコマンドが様々な出力オプションをサポートしているかについては、kubectlリファレンスドキュメントをご覧ください。
出力のフォーマット
すべてのkubectl
コマンドのデフォルトの出力フォーマットは、人間が読みやすいプレーンテキスト形式です。特定のフォーマットで、詳細をターミナルウィンドウに出力するには、サポートされているkubectl
コマンドに-o
または--output
フラグのいずれかを追加します。
構文
kubectl [command] [TYPE] [NAME] -o <output_format>
kubectl
の操作に応じて、以下の出力フォーマットがサポートされています。
出力フォーマット |
説明 |
-o custom-columns=<spec> |
カスタムカラムのコンマ区切りのリストを使用して、テーブルを表示します。 |
-o custom-columns-file=<filename> |
<filename> ファイル内のカスタムカラムのテンプレートを使用して、テーブルを表示します。 |
-o json |
JSON形式のAPIオブジェクトを出力します。 |
-o jsonpath=<template> |
jsonpath式で定義されたフィールドを表示します。 |
-o jsonpath-file=<filename> |
<filename> ファイル内のjsonpath式で定義されたフィールドを表示します。 |
-o name |
リソース名のみを表示します。 |
-o wide |
追加情報を含めて、プレーンテキスト形式で出力します。Podの場合は、Node名が含まれます。 |
-o yaml |
YAML形式のAPIオブジェクトを出力します。 |
例
この例において、以下のコマンドは1つのPodの詳細を、YAML形式のオブジェクトとして出力します。
kubectl get pod web-pod-13je7 -o yaml
各コマンドでサポートされている出力フォーマットの詳細については、kubectlリファレンスドキュメントを参照してください。
カスタムカラム
カスタムカラムを定義して、必要な詳細のみをテーブルに出力するには、custom-columns
オプションを使います。カスタムカラムをインラインで定義するか、-o custom-columns=<spec>
または-o custom-columns-file=<filename>
のようにテンプレートファイルを使用するかを選択できます。
例
インラインで定義する例は、以下の通りです。
kubectl get pods <pod-name> -o custom-columns=NAME:.metadata.name,RSRC:.metadata.resourceVersion
テンプレートファイルを使用して定義する例は、以下の通りです。
kubectl get pods <pod-name> -o custom-columns-file=template.txt
ここで、template.txt
には以下の内容が含まれます。
NAME RSRC
metadata.name metadata.resourceVersion
どちらのコマンドを実行した場合でも、以下の結果を得ます。
NAME RSRC
submit-queue 610995
サーバーサイドカラム
kubectl
は、サーバーからオブジェクトに関する特定のカラム情報を受け取ることをサポートしています。
つまり、与えられた任意のリソースについて、サーバーはそのリソースに関連する列や行を返し、クライアントが表示できるようにします。
これにより、サーバーが表示の詳細をカプセル化することで、同一クラスターに対して使用されているクライアント間で、一貫した人間が読みやすい出力が可能です。
この機能は、デフォルトで有効になっています。無効にするには、kubectl get
コマンドに--server-print=false
フラグを追加します。
例
Podの状態に関する情報を表示するには、以下のようなコマンドを使用します。
kubectl get pods <pod-name> --server-print=false
以下のように出力されます。
NAME AGE
pod-name 1m
オブジェクトリストのソート
ターミナルウィンドウで、オブジェクトをソートされたリストに出力するには、サポートされているkubectl
コマンドに--sort-by
フラグを追加します。--sort-by
フラグで任意の数値フィールドや文字列フィールドを指定することで、オブジェクトをソートします。フィールドの指定には、jsonpath式を使用します。
構文
kubectl [command] [TYPE] [NAME] --sort-by=<jsonpath_exp>
例
名前でソートしたPodのリストを表示するには、以下のように実行します。
kubectl get pods --sort-by=.metadata.name
例: 一般的な操作
よく使われるkubectl
の操作に慣れるために、以下の例を使用してください。
kubectl apply
- ファイルや標準出力から、リソースの適用や更新を行います。
# example-service.yaml内の定義を使用して、Serviceを作成します。
kubectl apply -f example-service.yaml
# example-controller.yaml内の定義を使用して、ReplicationControllerを作成します。
kubectl apply -f example-controller.yaml
# <directory>ディレクトリ内の、任意の.yaml、.yml、.jsonファイルで定義されているオブジェクトを作成します。
kubectl apply -f <directory>
kubectl get
- 1つ以上のリソースの一覧を表示します。
# すべてのPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods
# すべてのPodの一覧を、ノード名などの追加情報を含めて、プレーンテキスト形式で表示します。
kubectl get pods -o wide
# 指定した名前のReplicationControllerの一覧をプレーンテキスト形式で表示します。'replicationcontroller'リソースタイプを短縮して、エイリアス'rc'で置き換えることもできます。
kubectl get replicationcontroller <rc-name>
# すべてのReplicationControllerとServiceの一覧をまとめてプレーンテキスト形式で表示します。
kubectl get rc,services
# すべてのDaemonSetの一覧をプレーンテキスト形式で表示します。
kubectl get ds
# server01ノードで実行中のPodの一覧をプレーンテキスト形式で表示します。
kubectl get pods --field-selector=spec.nodeName=server01
kubectl describe
- 1つ以上のリソースの詳細な状態を、デフォルトでは初期化されないものも含めて表示します。
# Node <node-name>の詳細を表示します。
kubectl describe nodes <node-name>
# Pod <pod-name>の詳細を表示します。
kubectl describe pods/<pod-name>
# ReplicationController <rc-name>が管理しているすべてのPodの詳細を表示します。
# ReplicationControllerによって作成された任意のPodには、ReplicationControllerの名前がプレフィックスとして付与されます。
kubectl describe pods <rc-name>
# すべてのPodの詳細を表示します。
kubectl describe pods
備考: kubectl 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
サブコマンドを使用してください。
出力は以下のようになります。
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
コマンドの上に、より複雑な機能を構築するための手段であると考えることができます。
次の例では、下記の内容を含んだ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
次の項目
4.2 - JSONPathのサポート
kubectlはJSONPathのテンプレートをサポートしています。
JSONPathのテンプレートは、波括弧{}
によって囲まれたJSONPathの式によって構成されています。
kubectlでは、JSONPathの式を使うことで、JSONオブジェクトの特定のフィールドをフィルターしたり、出力のフォーマットを変更することができます。
本来のJSONPathのテンプレートの構文に加え、以下の機能と構文が使えます:
- JSONPathの式の内部でテキストをクォートするために、ダブルクォーテーションを使用します。
- リストを反復するために、
range
、end
オペレーターを使用します。
- リストを末尾側から参照するために、負の数のインデックスを使用します。負の数のインデックスはリストを「周回」せず、
-index + listLength >= 0
が満たされる限りにおいて有効になります。
以下のようなJSONの入力が与えられたとします。
{
"kind": "List",
"items":[
{
"kind":"None",
"metadata":{"name":"127.0.0.1"},
"status":{
"capacity":{"cpu":"4"},
"addresses":[{"type": "LegacyHostIP", "address":"127.0.0.1"}]
}
},
{
"kind":"None",
"metadata":{"name":"127.0.0.2"},
"status":{
"capacity":{"cpu":"8"},
"addresses":[
{"type": "LegacyHostIP", "address":"127.0.0.2"},
{"type": "another", "address":"127.0.0.3"}
]
}
}
],
"users":[
{
"name": "myself",
"user": {}
},
{
"name": "e2e",
"user": {"username": "admin", "password": "secret"}
}
]
}
機能 |
説明 |
例 |
結果 |
text |
プレーンテキスト |
kind is {.kind} |
kind is List |
@ |
現在のオブジェクト |
{@} |
入力した値と同じ値 |
. or [] |
子要素 |
{.kind} , {['kind']} or {['name\.type']} |
List |
.. |
子孫要素を再帰的に探す |
{..name} |
127.0.0.1 127.0.0.2 myself e2e |
* |
ワイルドカード。すべてのオブジェクトを取得する |
{.items[*].metadata.name} |
[127.0.0.1 127.0.0.2] |
[start:end:step] |
添字 |
{.users[0].name} |
myself |
[,] |
和集合 |
{.items[*]['metadata.name', 'status.capacity']} |
127.0.0.1 127.0.0.2 map[cpu:4] map[cpu:8] |
?() |
フィルター |
{.users[?(@.name=="e2e")].user.password} |
secret |
range , end |
リストの反復 |
{range .items[*]}[{.metadata.name}, {.status.capacity}] {end} |
[127.0.0.1, map[cpu:4]] [127.0.0.2, map[cpu:8]] |
'' |
解釈済みの文字列をクォートする |
{range .items[*]}{.metadata.name}{'\t'}{end} |
127.0.0.1 127.0.0.2 |
kubectl
とJSONPathの式を使った例:
kubectl get pods -o json
kubectl get pods -o=jsonpath='{@}'
kubectl get pods -o=jsonpath='{.items[0]}'
kubectl get pods -o=jsonpath='{.items[0].metadata.name}'
kubectl get pods -o=jsonpath="{.items[*]['metadata.name', 'status.capacity']}"
kubectl get pods -o=jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.startTime}{"\n"}{end}'
備考: 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に関わらずその短縮名をリストします。
APIリソースを探索するためのその他の操作:
kubectl api-resources --namespaced=true # 名前空間付きのすべてのリソースを表示します
kubectl api-resources --namespaced=false # 名前空間のないすべてのリソースを表示します
kubectl api-resources -o name # すべてのリソースを単純な出力(リソース名のみ)で表示します
kubectl api-resources -o wide # すべてのリソースを拡張された形(別名 "wide")で表示します
kubectl api-resources --verbs=list,get # "list"および"get"操作をサポートするすべてのリソースを表示します
kubectl api-resources --api-group=extensions # "extensions" APIグループのすべてのリソースを表示します
出力のフォーマット
特定の形式で端末ウィンドウに詳細を出力するには、サポートされているkubectl
コマンドに-o
(または--output
)フラグを追加します。
出力フォーマット |
説明 |
-o=custom-columns=<spec> |
コンマ区切りされたカスタムカラムのリストを指定してテーブルを表示します |
-o=custom-columns-file=<filename> |
<filename> ファイル内のカスタムカラムテンプレートを使用してテーブルを表示します |
-o=json |
JSON形式のAPIオブジェクトを出力します |
-o=jsonpath=<template> |
jsonpath式で定義されたフィールドを出力します |
-o=jsonpath-file=<filename> |
<filename> ファイル内のjsonpath式で定義されたフィールドを出力します |
-o=name |
リソース名のみを出力し、それ以外は何も出力しません。 |
-o=wide |
追加の情報を含むプレーンテキスト形式で出力します。Podの場合、Node名が含まれます。 |
-o=yaml |
YAML形式のAPIオブジェクトを出力します |
-o=custom-columns
を使用したサンプル:
# クラスター内で実行中のすべてのイメージ名を表示する
kubectl get pods -A -o=custom-columns='DATA:spec.containers[*].image'
# "k8s.gcr.io/coredns:1.6.2"を除いたすべてのイメージ名を表示する
kubectl get pods -A -o=custom-columns='DATA:spec.containers[?(@.image!="k8s.gcr.io/coredns:1.6.2")].image'
# 名前に関係なくmetadata以下のすべてのフィールドを表示する
kubectl get pods -A -o=custom-columns='DATA:metadata.*'
kubectlに関するより多くのサンプルはカスタムカラムのリファレンスを参照してください。
Kubectlのログレベルとデバッグ
kubectlのログレベルは、レベルを表す整数が後に続く-v
または--v
フラグで制御されます。一般的なKubernetesのログ記録規則と関連するログレベルについて、こちらで説明します。
ログレベル |
説明 |
--v=0 |
これは、クラスターオペレーターにログレベルが0であることを"常に"見えるようにするために役立ちます |
--v=1 |
ログレベルが必要ない場合に、妥当なデフォルトのログレベルです |
--v=2 |
サービスに関する重要な定常状態情報と、システムの重要な変更に関連する可能性がある重要なログメッセージを表示します。 これは、ほとんどのシステムで推奨されるデフォルトのログレベルです。 |
--v=3 |
変更に関するより詳細なログレベルを表示します |
--v=4 |
デバックにむいたログレベルで表示します |
--v=6 |
要求されたリソースを表示します |
--v=7 |
HTTPリクエストのヘッダを表示します |
--v=8 |
HTTPリクエストのコンテンツを表示します |
--v=9 |
HTTPリクエストのコンテンツをtruncationなしで表示します |
次の項目
5 - コマンドラインツールのリファレンス
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動詞から決定されます:
HTTP動詞 |
要求 動詞 |
POST |
create |
GET, HEAD |
get |
PUT |
update |
PATCH |
patch |
DELETE |
delete |
リソースとサブリソースは、受けとったリクエストのパスから決定されます:
Kubelet API |
リソース |
サブリソース |
/stats/* |
nodes |
stats |
/metrics/* |
nodes |
metrics |
/logs/* |
nodes |
log |
/spec/* |
nodes |
spec |
all others |
nodes |
proxy |
名前空間と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を利用して、以下のことができます。
- Namespaceに属するリソースに対する権限を定義し、個々のNamespace内で付与する
- Namespaceに属するリソースに対する権限を定義し、すべてのNamespaceにわたって付与する
- クラスター単位でスコープされているリソースに対するアクセス許可を定義する
NamespaceでRoleを定義する場合は、Roleを使用します。クラスター全体でRoleを定義する場合は、ClusterRoleを使用します
Roleの例
以下はNamespace「default」にあるRoleの例で、
Podへの読み取りアクセス権の付与に使用できます。
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
namespace: default
name: pod-reader
rules:
- apiGroups: [""] # "" はコアのAPIグループを示します
resources: ["pods"]
verbs: ["get", "watch", "list"]
ClusterRoleの例
ClusterRoleを使用してRoleと同じ権限を付与できます。
ClusterRolesはクラスター単位でスコープされているため、以下へのアクセスの許可もできます。
- クラスター単位でスコープされているリソースに(nodeなど)
- 非リソースエンドポイントに(
/healthz
など)
- すべてのNamespaceに渡ってNamespaceに属するリソースに(Podなど)。
例えば、ClusterRoleを使用して特定のユーザーに
kubectl get pods --all-namespaces
の実行を許可できます。
以下は特定のNamespace、またはすべてのNamespace(バインド方法によります)でsecretsへの読み取りアクセス権を付与するClusterRoleの例です。
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
# 「namespace」はClusterRolesがNamespaceに属していないため、省略されています
name: secret-reader
rules:
- apiGroups: [""]
#
# HTTPレベルでの、Secretにアクセスするリソースの名前
# オブジェクトは"secrets"
resources: ["secrets"]
verbs: ["get", "watch", "list"]
RoleまたはClusterRoleオブジェクトの名前は有効な
パスセグメント名である必要があります。
RoleBindingとClusterRoleBinding
RoleBindingはRoleで定義された権限をユーザーまたはユーザのセットに付与します。
RoleBindingはsubjects (ユーザー、グループ、サービスアカウント)のリストと、付与されるRoleへの参照を保持します。
RoleBindingは特定のNamespace内の権限を付与しますが、ClusterRoleBindingはクラスター全体にアクセスする権限を付与します。
RoleBindingは、同じNamespace内の任意のRoleを参照できます。
または、RoleBindingはClusterRoleを参照し、そのClusterRoleをRoleBindingのNamespaceにバインドできます。
ClusterRoleをクラスター内のすべてのNamespaceにバインドする場合は、ClusterRoleBindingを使用します。
RoleBindingまたはClusterRoleBindingオブジェクトは有効な
パスセグメント名である必要があります。
RoleBindingの例
以下はNamespace「default」内でユーザー「jane」に「pod-reader」のRoleを付与するRoleBindingの例です。
これにより、「jane」にNamespace「default」のポッドの読み取り許可されます。
apiVersion: rbac.authorization.k8s.io/v1
# このRoleBindingは「jane」にNamespace「default」のポッドの読み取りを許可する
# そのNamespaceでRole「pod-reader」を既に持っている必要があります。
kind: RoleBinding
metadata:
name: read-pods
namespace: default
subjects:
# 一つ以上の「subject」を指定する必要があります
- kind: User
name: jane # 「name」は大文字と小文字が区別されます
apiGroup: rbac.authorization.k8s.io
roleRef:
# 「roleRef」はRole/ClusterRoleへのバインドを指定します
kind: Role #RoleまたはClusterRoleである必要があります
name: pod-reader # これはバインドしたいRole名またはClusterRole名とマッチする必要があります
apiGroup: rbac.authorization.k8s.io
RoleBindingはClusterRoleを参照し、ClusterRoleで定義されている権限をRoleBinding内のNamespaceのリソースに権限付与もできます。この種類の参照を利用すると、クラスター全体で共通のRoleのセットを定義して、それらを複数のNamespace内での再利用できます。
例えば、以下のRoleBindingがClusterRoleを参照している場合でも、
「dave」(大文字と小文字が区別されるsubject)はRoleBindingのNamespace(メタデータ内)が「development」のため、Namespace「development」のSecretsのみの読み取りができます。
apiVersion: rbac.authorization.k8s.io/v1
# このRoleBindingは「dave」にNamespace「development」のSecretsの読み取りを許可する
# ClusterRole「secret-reader」を既に持っている必要があります。
kind: RoleBinding
metadata:
name: read-secrets
#
# RoleBindingのNamespaceが、どこの権限が付与されるかを決定する。
# これはNamespace「development」内の権限のみ付与する。
namespace: development
subjects:
- kind: User
name: dave # nameは大文字、小文字を区別する
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: secret-reader
apiGroup: rbac.authorization.k8s.io
ClusterRoleBindingの例
クラスター全体に権限を付与するには、ClusterRoleBindingを使用できます。
以下のClusterRoleBindingはグループ「manager」のすべてのユーザーに
Secretsの読み取りを許可します。
apiVersion: rbac.authorization.k8s.io/v1
# このClusterRoleBindingはグループ「manager」のすべてのユーザーに任意のNamespaceのSecretsの読み取りを許可します。
kind: ClusterRoleBinding
metadata:
name: read-secrets-global
subjects:
- kind: Group
name: manager # nameは大文字、小文字を区別します
apiGroup: rbac.authorization.k8s.io
roleRef:
kind: ClusterRole
name: secret-reader
apiGroup: rbac.authorization.k8s.io
Bindingを作成後は、それが参照するRoleまたはClusterRoleを変更できません。
BindingのroleRef
を変更しようとすると、バリデーションエラーが発生します。BindingのroleRef
を変更する場合は、Bindingのオブジェクトを削除して、代わりのオブジェクトを作成する必要があります。
この制限には2つの理由があります。
roleRef
をイミュータブルにすることで、誰かに既存のオブジェクトに対するupdate
権限を付与します。それにより、subjectsに付与されたRoleの変更ができなくても、subjectsのリストを管理できるようになります。
- 異なる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」などの単純な名前。「[email protected]」のような電子メール形式の名前。または文字列として表される数値のユーザーID。 認証が必要な形式のユーザー名を生成するように認証モジュールを構成するかどうかは、クラスター管理者が決定します。
注意: プレフィックスsystem:
はKubernetesシステムで使用するために予約されているため、誤ってsystem:
で始まる名前のユーザーまたはグループが存在しないようにする必要があります。
この特別なプレフィックスを除いて、RBAC承認システムでは、ユーザー名の形式は問いません。
Kubernetesでは、Authenticatorモジュールがグループ情報を提供します。
ユーザーと同様に、グループは文字列として表され、その文字列には、プレフィックスsystem:
が予約されていることを除いて、フォーマット要件はありません。
ServiceAccountの名前はプレフィックスsystem:serviceaccount:
が付いており、名前のプレフィックスsystem:serviceaccounts:
が付いているグループに属しています。
備考:
system:serviceaccount:
(単数)は、サービスアカウントのユーザー名のプレフィックスです。
system:serviceaccounts:
(複数)は、サービスアカウントグループのプレフィックスです。
RoleBindingの例
次の例はRoleBinding
、subjects
セクションのみを示す抜粋です。
[email protected]
という名前のユーザーの場合。
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を手動で編集しないか、自動調整を無効にします。
Kubernetes RBAC APIディスカバリーRole
デフォルトのClusterRole |
デフォルトのClusterRoleBinding |
説明 |
system:basic-user |
system:authenticated group |
ユーザーに、自身に関する基本情報への読み取り専用アクセスを許可します。v1.14より前は、このRoleはデフォルトでsystem:unauthenticatedにもバインドされていました。 |
system:discovery |
system:authenticated group |
APIレベルのディスカバリーとネゴシエーションに必要なAPIディスカバリーエンドポイントへの読み取り専用アクセスを許可します。v1.14より前は、このRoleはデフォルトでsystem:unauthenticatedにもバインドされていました。 |
system:public-info-viewer |
system:authenticated and system:unauthenticated groups |
クラスターに関する機密情報以外への読み取り専用アクセスを許可します。Kubernetes v1.14で導入されました。 |
ユーザー向けRole
一部のデフォルトClusterRolesにはプレフィックスsystem:
が付いていません。これらは、ユーザー向けのroleを想定しています。それらは、スーパーユーザのRole(cluster-admin
)、ClusterRoleBindingsを使用してクラスタ全体に付与されることを意図しているRole、そしてRoleBindings(admin
, edit
, view
)を使用して、特定のNamespace内に付与されることを意図しているRoleを含んでいます。
ユーザー向けのClusterRolesはClusterRoleの集約を使用して、管理者がこれらのClusterRolesにカスタムリソースのルールを含めることができるようにします。ルールを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"
デフォルトのClusterRole |
デフォルトのClusterRoleBinding |
説明 |
cluster-admin |
system:masters group |
スーパーユーザーが任意のリソースで任意のアクションを実行できるようにします。
ClusterRoleBindingで使用すると、クラスター内およびすべてのNamespace内のすべてのリソースを完全に制御できます。
RoleBindingで使用すると、Namespace自体を含む、RoleBindingのNamespace内のすべてのリソースを完全に制御できます。 |
admin |
None |
RoleBindingを使用してNamespace内で付与することを想定した、管理者アクセスを許可します。
RoleBindingで使用した場合、Namespace内にRoleとRoleBindingを作成する機能を含め、Namespaceのほとんどのリソースへの読み取り/書き込みアクセスを許可します。
このRoleは、リソースクォータまたはNamespace自体への書き込みアクセスを許可しません。 |
edit |
None |
Namespace内のほとんどのオブジェクトへの読み取り/書き込みアクセスを許可します。
このRoleは、RoleまたはRoleBindingの表示または変更を許可しません。
ただし、このRoleでは、Secretsにアクセスして、Namespace内の任意のServiceAccountとしてPodsを実行できるため、Namespace内の任意のServiceAccountのAPIアクセスレベルを取得するために使用できます。 |
view |
None |
Namespace内のほとんどのオブジェクトを表示するための読み取り専用アクセスを許可します。
RoleまたはRoleBindingは表示できません。
Secretsの内容を読み取るとNamespaceのServiceAccountのクレデンシャルにアクセスできるため、このRoleではSecretsの表示は許可されません。これにより、Namespace内の任意のServiceAccountとしてAPIアクセスが許可されます(特権昇格の形式)。 |
コアコンポーネントのRole
デフォルトのClusterRole |
デフォルトのClusterRoleBinding |
説明 |
system:kube-scheduler |
system:kube-scheduler user |
schedulerコンポーネントが必要とするリソースへのアクセスを許可します。 |
system:volume-scheduler |
system:kube-scheduler user |
kube-scheduleコンポーネントが必要とするリソースへのアクセスを許可します。 |
system:kube-controller-manager |
system:kube-controller-manager user |
controller managerコンポーネントが必要とするリソースへのアクセスを許可します。
個々のコントローラーに必要な権限については、組み込みコントローラーのRoleで詳しく説明しています。 |
system:node |
None |
すべてのsecretへの読み取りアクセス、すべてのポッドステータスオブジェクトへの書き込みアクセスなど、kubeletが必要とするリソースへのアクセスを許可します。
system:nodeRoleの代わりにNode authorizerと NodeRestriction admission pluginを使用し、それらで実行するようにスケジュールされたPodに基づいてkubeletへのAPIアクセスを許可する必要があります。
system:nodeのRoleは、V1.8より前のバージョンからアップグレードしたKubernetesクラスターとの互換性のためだけに存在します。
|
system:node-proxier |
system:kube-proxy user |
kube-proxyコンポーネントが必要とするリソースへのアクセスを許可します。 |
他のコンポーネントのRole
デフォルトのClusterRole |
デフォルトのClusterRoleBinding |
説明 |
system:auth-delegator |
None |
委任された認証と認可のチェックを許可します。
これは一般に、認証と認可を統合するためにアドオンAPIサーバーで使用されます。 |
system:heapster |
None |
HeapsterコンポーネントのRole(非推奨)。 |
system:kube-aggregator |
None |
kube-aggregatorコンポーネントのRole。 |
system:kube-dns |
kube-systemNamespaceのサービスアカウントkube-dns |
kube-dnsコンポーネントのRole。 |
system:kubelet-api-admin |
None |
kubelet APIへのフルアクセスを許可します。 |
system:node-bootstrapper |
None |
kubelet TLS bootstrappingの実行に必要なリソースへのアクセスを許可します。 |
system:node-problem-detector |
None |
node-problem-detectorコンポーネントのRole。 |
system:persistent-volume-provisioner |
None |
ほとんどのdynamic volume provisionersが必要とするリソースへのアクセスを許可します。 |
組み込みコントローラーのRole
Kubernetes controller managerは、Kubernetesコントロールプレーンに組み込まれているcontrollersを実行します。
--use-service-account-credentials
を指定して呼び出すと、kube-controller-manager個別のサービスアカウントを使用して各コントローラーを起動します。
組み込みコントローラーごとに、プレフィックスsystem:controller:
付きの対応するRoleが存在します。
コントローラーマネージャーが--use-service-account-credentials
で開始されていない場合、コントローラマネージャーは、関連するすべてのRoleを付与する必要がある自身のクレデンシャルを使用して、すべてのコントロールループを実行します。
これらのRoleは次のとおりです。
system:controller:attachdetach-controller
system:controller:certificate-controller
system:controller:clusterrole-aggregation-controller
system:controller:cronjob-controller
system:controller:daemon-set-controller
system:controller:deployment-controller
system:controller:disruption-controller
system:controller:endpoint-controller
system:controller:expand-controller
system:controller:generic-garbage-collector
system:controller:horizontal-pod-autoscaler
system:controller:job-controller
system:controller:namespace-controller
system:controller:node-controller
system:controller:persistent-volume-binder
system:controller:pod-garbage-collector
system:controller:pv-protection-controller
system:controller:pvc-protection-controller
system:controller:replicaset-controller
system:controller:replication-controller
system:controller:resourcequota-controller
system:controller:root-ca-cert-publisher
system:controller:route-controller
system:controller:service-account-controller
system:controller:service-controller
system:controller:statefulset-controller
system:controller:ttl-controller
特権昇格の防止とブートストラップ
RBAC APIは、RoleまたはRoleBindingを編集することにより、ユーザーが特権を昇格するのを防ぎます。
これはAPIレベルで適用されるため、RBAC authorizerが使用されていない場合でも適用されます。
Roleの作成または更新に関する制限
次の項目1つ以上が当てはまる場合にのみ、Roleを作成/更新できます。
- 変更対象のオブジェクトと同じスコープで、Roleに含まれるすべての権限を既に持っている(ClusterRoleの場合はクラスター全体。Roleの場合は、同じNamespace内またはクラスター全体)。
rbac.authorization.k8s.io
APIグループの roles
またはclusterroles
リソースで escalate
verbを実行する明示的な権限が付与されている。
たとえば、 user-1
にクラスター全体でSecretsを一覧表示する権限がない場合、それらにその権限を含むClusterRoleを作成できません。
ユーザーがRoleを作成/更新できるようにするには、以下のいずれかを実施します。
- 必要に応じて、RoleオブジェクトまたはClusterRoleオブジェクトを作成/更新できるRoleを付与する。
- 作成/更新するRoleに特定の権限を含む権限を付与する。
- 暗黙的に、これらの権限を付与することにより(自分自身が付与されていない権限でRoleまたはClusterRoleを作成または変更しようとすると、APIリクエストは禁止されます)。
- または、
rbac.authorization.k8s.io
APIグループの roles
または clusterroles
リソースで escalate
verbを実行する権限を与えることにより、 Role
または ClusterRole
で権限を指定することを明示的に許可する
RoleBindingの作成または更新に関する制限
参照されるRoleに含まれるすべての権限を(RoleBindingと同じスコープで)すでに持っている場合、
または参照されたRoleでbind
verbを実行する認可されている場合のみ、RoleBindingを作成/更新できます。
たとえば、 user-1
にクラスター全体でSecretsを一覧表示する権限がない場合、ClusterRoleBindingを作成してもRoleにその権限を付与できません。
ユーザーがRoleBindingを作成/更新できるようにするには、以下のいずれかを実施します。
- 必要に応じて、RoleBindingまたはClusterRoleBindingオブジェクトを作成/更新できるようにする役割を付与する。
- 特定の役割をバインドするために必要なアクセス許可を付与する。
- 暗黙的に、Roleに含まれる権限を付与することによって。
- 明示的に、特定のRole(またはClusterRole)で
bind
verbを実行する許可を与えることによって。
たとえば、このClusterRoleとRoleBindingを使用すると、 user-1
は他のユーザーにNamespace user-1-namespace
の admin
、 edit
、および view
Roleを付与します。
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/v1
APIオブジェクトを作成または更新します。
欠落しているオブジェクトが作成され、必要に応じて、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に与える可能性がありますが、管理が簡単です。
アプローチを最も安全なものから最も安全でないものの順に並べると、次のとおりです。
-
アプリケーション固有のサービスアカウントに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
-
ある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
-
Namespace内のすべてのサービスアカウントにRoleを付与します
Namespace内のすべてのアプリケーションにRoleを持たせたい場合は、使用するサービスアカウントに関係なく、
そのNamespaceのサービスアカウントグループにRoleを付与できます。
たとえば、「my-namespace」内の読み取り専用アクセス許可を、そのNamespace内のすべてのサービスアカウントに付与します。
kubectl create rolebinding serviceaccounts-view \
--clusterrole=view \
--group=system:serviceaccounts:my-namespace \
--namespace=my-namespace
-
クラスター全体のすべてのサービスアカウントに制限されたRoleを付与します(お勧めしません)
Namespaceごとのアクセス許可を管理したくない場合は、すべてのサービスアカウントにクラスター全体の役割を付与できます。
たとえば、クラスター内のすべてのサービスアカウントに、すべてのNamespaceで読み取り専用のアクセス許可を付与します。
kubectl create clusterrolebinding serviceaccounts-view \
--clusterrole=view \
--group=system:serviceaccounts
-
クラスター全体のすべてのサービスアカウントへのスーパーユーザーアクセスを許可します。(強くお勧めしません)
権限の分割をまったく考慮しない場合は、すべてのサービスアカウントにスーパーユーザーアクセスを許可できます。
警告: これにより、すべてのアプリケーションにクラスターへのフルアクセスが許可され、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
は、物理サーバやクラウドサーバ、仮想マシン上にKubernetesクラスタを容易にプロビジョニングするためのコマンドラインツールです(現在はアルファ版です)。
Minikube
minikube
は、開発やテストのためにワークステーション上でシングルノードのKubernetesクラスタをローカルで実行するツールです。
Dashboard
Dashboard
は、KubernetesのWebベースのユーザインタフェースで、コンテナ化されたアプリケーションをKubernetesクラスタにデプロイしたり、トラブルシューティングしたり、クラスタとそのリソース自体を管理したりすることが出来ます。
Helm
Kubernetes Helm
は、事前に設定されたKubernetesリソースのパッケージ、別名Kubernetes chartsを管理するためのツールです。
Helmを用いて以下のことを行います。
-
Kubernetes chartsとしてパッケージ化された人気のあるソフトウェアの検索と利用
-
Kubernetes chartsとして所有するアプリケーションを共有すること
-
Kubernetesアプリケーションの再現性のあるビルドの作成
-
Kubernetesマニフェストファイルを知的な方法で管理
-
Helmパッケージのリリース管理
Kompose
Kompose
は、Docker ComposeユーザがKubernetesに移行する手助けをするツールです。
Komposeを用いて以下のことを行います。
-
Docker ComposeファイルのKubernetesオブジェクトへの変換
-
ローカルのDocker開発からKubernetesを経由したアプリケーション管理への移行
-
v1またはv2のDocker Compose用 yaml
ファイルならびに分散されたアプリケーションバンドルの変換