リファレンス
本セクションには、Kubernetesのドキュメントのリファレンスが含まれています。
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 - 可用性、パフォーマンス、およびキャパシティを管理するスケジューラーです。
コントロールプレーンとワーカーノードで開いておくべきポートとプロトコル の一覧
設定APIリファレンス
このセクションでは、Kubernetesのコンポーネントやツールを設定するのに使われている「未公開」のAPIのドキュメントをまとめています。
クラスターを使ったり管理したりするユーザーやオペレーターにとって必要不可欠ではありますが、これらのAPIの大半はRESTful方式のAPIサーバーでは提供されません。
kubeadmの設定APIリファレンス
設計のドキュメント
Kubernetesの機能に関する設計ドキュメントのアーカイブです。Kubernetesアーキテクチャ とKubernetesデザイン概要 から読み始めると良いでしょう。
2 - KubeletチェックポイントAPI
FEATURE STATE: Kubernetes v1.25 [alpha]
コンテナのチェックポイントは実行中のコンテナのステートフルコピーを作成するための機能です。
コンテナのステートフルコピーがあると、デバックや類似の目的のために別のコンピューターに移動させることができます。
チェックポイントコンテナデータを復元可能なコンピューターに移動させる場合、その復元したコンテナは、チェックポイントが作成された正確に同じ地点で実行が再開されます。
保存したデータを検査することも可能です。
ただし、検査を行うための適したツールを保持している必要があります。
コンテナのチェックポイントを作成することで、セキュリティ影響が発生する場合があります。
通常、チェックポイントはチェックポイントされたコンテナ内のすべてのプロセスのすべてのメモリーページを含んでいます。
メモリー内で使用された全てがローカルディスク上で利用できるようになることを意味しています。
これはすべてのプライベートデータを含んでおり、もしかしたら暗号化に使用した鍵も含まれているかもしれません。
基礎となるCRI実装(そのノード上のコンテナランタイム)は、root
ユーザーのみがアクセス可能なチェックポイントアーカイブを作成するべきです。
チェックポイントアーカイブが他のシステムに転送された場合、全てのメモリーページがチェックポイントアーカイブのオーナーによって読み取れるようになることを覚えておくことが重要です。
操作方法
post
指定したコンテナのチェックポイント
指定したPodから指定したコンテナのチェックポイントを作成するようにkubeletに指示します。
kubeletチェックポイントインターフェイスへのアクセスの制御方法についての詳細な情報は、Kubelet authentication/authorization reference を参照してください。
kubeletは基礎となるCRI 実装にチェックポイントをリクエストします。
チェックポイントリクエストでは、kubeletがcheckpoint-<podFullName>-<containerName>-<timestamp>.tar
のようなチェックポイントアーカイブの名前を指定します。
併せて、(--root-dir
で定義される)rootディレクトリ配下のcheckpoints
ディレクトリに、チェックポイントアーカイブを保存することをリクエストします。
デフォルトは/var/lib/kubelet/checkpoints
です。
チェックポイントアーカイブは tar フォーマットであり、tar
の実装を使用して一覧表示できます。
アーカイブの内容は、基礎となるCRI実装(ノード上のコンテナランタイム)に依存します。
HTTPリクエスト
POST /checkpoint/{namespace}/{pod}/{container}
パラメーター
namespace (パス内 ): string, 必須項目
Namespace
pod (パス内 ): string, 必須項目
Pod
container (パス内 ): string, 必須項目
コンテナ
timeout (クエリ内 ): integer
チェックポイントの作成が終了するまで待機する秒単位のタイムアウト。
ゼロまたはタイムアウトが指定されていない場合、デフォルトはCRI タイムアウトの値が使用されます。
チェックポイント作成時間はコンテナの使用メモリーに直接依存します。
コンテナの使用メモリーが多いほど、対応するチェックポイントを作成するために必要な時間が長くなります。
レスポンス
200: OK
401: Unauthorized
404: Not Found (ContainerCheckpoint
フィーチャーゲートが無効の場合)
404: Not Found (指定したnamespace
やpod
、container
が見つからない場合)
500: Internal Server Error (CRI実装でチェックポイント中にエラーが発生した場合(詳細はエラーメッセージを参照))
500: Internal Server Error (CRI実装がチェックポイントCRI APIを実装していない場合(詳細はエラーメッセージを参照))
3 - 認証
このページでは、認証の概要について説明します。
Kubernetesにおけるユーザー
すべてのKubernetesクラスターには、2種類のユーザーがあります。Kubernetesによって管理されるサービスアカウントと、通常のユーザーです。
クラスターから独立したサービスは通常のユーザーを以下の方法で管理することを想定されています。
秘密鍵を配布する管理者
KeystoneやGoogle Accountsのようなユーザーストア
ユーザー名とパスワードのリストを持つファイル
これを考慮すると、 Kubernetesは通常のユーザーアカウントを表すオブジェクトを持ちません。 APIコールを介して、通常のユーザーをクラスターに追加することはできません。
APIコールを介して通常のユーザーを追加できませんが、クラスターの認証局(CA)に署名された有効な証明書で表すユーザーは認証済みと判断されます。この構成では、Kubernetesは証明書の‘subject’内にある一般的な名前フィールド(例えば、“/CN=bob”)からユーザー名を特定します。そこから、ロールベースアクセス制御(RBAC)サブシステムは、ユーザーがあるリソースにおける特定の操作を実行するために認証済みかどうか特定します。詳細は、 証明書要求 内の通常のユーザーの題目を参照してください。
対照的に、サービスアカウントはKubernetes APIによって管理されるユーザーです。サービスアカウントは特定の名前空間にバインドされており、APIサーバーによって自動的に作成されるか、APIコールによって手動で作成されます。サービスアカウントは、Secrets
として保存された資格情報の集合に紐付けられています。これをPodにマウントすることで、クラスター内のプロセスがKubernetes APIと通信できるようにします。
APIリクエストは、通常のユーザーかサービスアカウントに紐付けられているか、匿名リクエスト として扱われます。つまり、ワークステーションでkubectl
を入力する人間のユーザーから、ノード上のkubelets
やコントロールプレーンのメンバーまで、クラスター内外の全てのプロセスは、APIサーバーへのリクエストを行う際に認証を行うか匿名ユーザーとして扱われる必要があります。
認証戦略
Kubernetesは、クライアント証明書、Bearerトークン、認証プロキシー、HTTP Basic認証を使い、認証プラグインを通してAPIリクエストを認証します。APIサーバーにHTTPリクエストが送信されると、プラグインは以下の属性をリクエストに関連付けようとします。
ユーザー名: エンドユーザーを識別する文字列です。一般的にな値は、kube-admin
やjane@example.com
です。
UID: エンドユーザーを識別する文字列であり、ユーザー名よりも一貫性と一意性を持たせようとするものです。
グループ: 各要素がユーザーの役割を示すような意味を持つ文字列の集合です。system:masters
やdevops-team
といった値が一般的です。
追加フィールド: 認証者が有用と思われる追加情報を保持する文字列のリストに対する、文字列のマップです。
すべての値は認証システムに対して非透過であり、認可機能 が解釈した場合にのみ意味を持ちます。
一度に複数の認証方法を有効にすることができます。通常は、以下のように少なくとも2つの方法を使用するべきです。
サービスアカウント用のサービスアカウントトークン
ユーザー認証のための、少なくとも1つの他の方法
複数の認証モジュールが有効化されている場合、リクエストの認証に成功した最初のモジュールが、評価が簡略化します。APIサーバーは、認証の実行順序を保証しません。
system:authenticated
グループには、すべての認証済みユーザーのグループのリストが含まれます。
他の認証プロトコル(LDAP、SAML、Kerberos、X509スキームなど)との統合は、認証プロキシー や認証Webhook を使用して実施できます。
X509クライアント証明書
クライアント証明書認証は、APIサーバーに--client-ca-file=SOMEFILE
オプションを渡すことで有効になります。参照されるファイルには、APIサーバーに提示されたクライアント証明書を検証するために使用する1つ以上の認証局が含まれている必要があります。クライアント証明書が提示され、検証された場合、サブジェクトのCommon Nameがリクエストのユーザー名として使用されます。Kubernetes1.4時点では、クライアント証明書は、証明書のOrganizationフィールドを使用して、ユーザーのグループメンバーシップを示すこともできます。あるユーザーに対して複数のグループメンバーシップを含めるには、証明書に複数のOrganizationフィールドを含めます。
例えば、証明書署名要求を生成するために、openssl
コマンドラインツールを使用します。
openssl req -new -key jbeda.pem -out jbeda-csr.pem -subj "/CN=jbeda/O=app1/O=app2"
これにより、"app1"と"app2"の2つのグループに属するユーザー名"jbeda"の証明書署名要求が作成されます。
クライアント証明書の生成方法については、証明書の管理 を参照してください。
静的なトークンファイル
コマンドラインで--token-auth-file=SOMEFILE
オプションを指定すると、APIサーバーはファイルからBearerトークンを読み込みます。現在のところ、トークンの有効期限は無く、APIサーバーを再起動しない限りトークンのリストを変更することはできません。
トークンファイルは、トークン、ユーザー名、ユーザーUIDの少なくとも3つの列を持つcsvファイルで、その後にオプションでグループ名が付きます。
備考: 複数のグループがある場合はダブルクォートで囲む必要があります。
token,user,uid,"group1,group2,group3"
リクエストにBearerトークンを含める
HTTPクライアントからBearerトークン認証を利用する場合、APIサーバーはBearer THETOKEN
という値を持つAuthorization
ヘッダーを待ち受けます。Bearerトークンは、HTTPのエンコーディングとクォート機能を利用してHTTPヘッダーの値に入れることができる文字列でなければなりません。例えば、Bearerトークンが31ada4fd-adec-460c-809a-9e56ceb75269
であれば、HTTPのヘッダを以下のようにします。
Authorization: Bearer 31ada4fd-adec-460c-809a-9e56ceb75269
ブートストラップトークン
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" : "janedoe@example.com" ,
"uid" : "42" ,
"groups" : [
"developers" ,
"qa"
],
"extra" : {
"extrafield1" : [
"extravalue1" ,
"extravalue2"
]
}
}
}
}
リクエストに失敗した場合は、以下のように返されます。
{
"apiVersion" : "authentication.k8s.io/v1beta1" ,
"kind" : "TokenReview" ,
"status" : {
"authenticated" : false
}
}
HTTPステータスコードは、追加のエラーコンテキストを提供するために使うことができます。
認証プロキシー
APIサーバーは、X-Remote-User
のようにリクエストヘッダの値からユーザーを識別するように設定することができます。
これは、リクエストヘッダの値を設定する認証プロキシーと組み合わせて使用するために設計です。
--requestheader-username-headers
: 必須であり、大文字小文字を区別しません。ユーザーのIDをチェックするためのヘッダー名を順番に指定します。値を含む最初のヘッダーが、ユーザー名として使われます。
--requestheader-group-headers
: バージョン1.6以降で任意であり、大文字小文字を区別しません。"X-Remote-Group"を推奨します。ユーザーのグループをチェックするためのヘッダー名を順番に指定します。指定されたヘッダーの全ての値が、グループ名として使われます。
--requestheader-extra-headers-prefix
バージョン1.6以降で任意であり、大文字小文字を区別しません。"X-Remote-Extra-"を推奨します。ユーザーに関する追加情報を判断するために検索するヘッダーのプレフィックスです。通常、設定された認可プラグインによって使用されます。指定されたプレフィックスのいずれかで始まるヘッダーは、プレフィックスが削除されます。ヘッダー名の残りの部分は小文字化されパーセントデコーディング されて追加のキーとなり、ヘッダーの値が追加の値となります。
例えば、このような設定を行います。
--requestheader-username-headers=X-Remote-User
--requestheader-group-headers=X-Remote-Group
--requestheader-extra-headers-prefix=X-Remote-Extra-
以下のようなリクエストを考えます。
GET / HTTP / 1.1
X-Remote-User: fido
X-Remote-Group: dogs
X-Remote-Group: dachshunds
X-Remote-Extra-Acme.com%2Fproject: some-project
X-Remote-Extra-Scopes: openid
X-Remote-Extra-Scopes: profile
このリクエストは、このユーザー情報を取得します。
name : fido
groups :
- dogs
- dachshunds
extra :
acme.com/project :
- some-project
scopes :
- openid
- profile
ヘッダーのスプーフィングを防ぐため、認証プロキシーはリクエストヘッダーがチェックされる前に、指定された認証局に対する検証のために有効なクライアント証明書をAPIサーバーへ提示する必要があります。
--requestheader-client-ca-file
: 必須です。PEMエンコードされた証明書バンドルです。有効なクライアント証明書を提示し、リクエストヘッダーでユーザー名がチェックされる前に、指定されたファイル内の認証局に対して検証する必要があります。
--requestheader-allowed-names
: 任意です。Common Name(CN)の値のリストです。設定されている場合、リクエストヘッダーでユーザー名がチェックされる前に、指定されたリストのCNを持つ有効なクライアント証明書を提示する必要があります。空の場合は、任意のCNが許可されます。
匿名リクエスト
この機能を有効にすると、他の設定された認証方法で拒否されなかったリクエストは匿名リクエストとして扱われ、 system:anonymous
というユーザー名とsystem:unauthenticated
というグループが与えられます。
例えば、トークン認証が設定されており、匿名アクセスが有効になっているサーバー上で、無効なBearerトークンを提供するリクエストは401 Unauthorized
エラーを受け取ります。Bearerトークンを提供しないリクエストは匿名リクエストとして扱われます。
バージョン1.5.1から1.5.xでは、匿名アクセスはデフォルトでは無効になっており、APIサーバーに --anonymous-auth=true
オプションを渡すことで有効にすることができます。
バージョン1.6以降では、AlwaysAllow
以外の認証モードが使用されている場合、匿名アクセスがデフォルトで有効であり、--anonymous-auth=false
オプションをAPIサーバーに渡すことで無効にできます。
1.6以降、ABACおよびRBAC認可機能は、system:anonymous
ユーザーまたはsystem:unauthenticated
グループの明示的な認証を必要とするようになったため、*
ユーザーまたは*
グループへのアクセスを許可する従来のポリシールールには匿名ユーザーは含まれません。
ユーザーの偽装
ユーザーは偽装ヘッダーを使って別のユーザーとして振る舞うことができます。これにより、リクエストが認証したユーザー情報を手動で上書きすることが可能です。例えば、管理者はこの機能を使って一時的に別のユーザーに偽装、リクエストが拒否されたかどうかを確認することで認可ポリシーをデバッグすることができます。
偽装リクエストは最初にリクエスト中のユーザーとして認証を行い、次に偽装ユーザー情報に切り替えます。
ユーザーは、認証情報と偽装ヘッダーを使ってAPIコールを行います。
APIサーバーはユーザーを認証します。
APIサーバーは、認証されたユーザーが偽装した権限を持っていることを確認します。
リクエストされたユーザー情報は、偽装した値に置き換えられます。
リクエストが評価され、認可は偽装されたユーザー情報に基づいて実行されます。
偽装リクエストを実行する際には、以下のHTTPヘッダを使用することができます。
Impersonate-User
: ユーザー名を指定します。このユーザーとして振る舞います。
Impersonate-Group
: グループ名を指定します。このグループとして振る舞います。複数回指定して複数のグループを設定することができます。任意であり、"Impersonate-User"が必要です。
Impersonate-Extra-( extra name )
: 追加フィールドをユーザーに関連付けるために使用される動的なヘッダーです。任意であり、"Impersonate-User"が必要です。一貫して保存されるためには、( extra name )
は小文字である必要があり、HTTPヘッダーラベルで使用可能な文字 以外の文字は、UTF-8であり、パーセントエンコーディング されている必要があります.
以下が、ヘッダーの例です。
Impersonate-User: jane.doe@example.com
Impersonate-Group: developers
Impersonate-Group: admins
Impersonate-Extra-dn: cn=jane,ou=engineers,dc=example,dc=com
Impersonate-Extra-acme.com%2Fproject: some-project
Impersonate-Extra-scopes: view
Impersonate-Extra-scopes: development
kubectl
を使う場合は、--as
フラグにImpersonate-User
ヘッダーを、--as-group
フラグにImpersonate-Group
ヘッダーを設定します。
Error from server (Forbidden): User "clark" cannot get nodes at the cluster scope. (get nodes mynode)
--as
フラグと--as-group
フラグを設定します。
kubectl drain mynode --as= superman --as-group= system:masters
node/mynode cordoned
node/mynode drained
ユーザー、グループ、または追加フィールドを偽装するために、偽装ユーザーは偽装される属性の種類("user"、"group"など)に対して、"偽装した"操作を行う能力を持っている必要があります。RBAC認可プラグインが有効なクラスターの場合、以下のClusterRoleは、ユーザーとグループの偽装ヘッダーを設定するために必要なルールを網羅しています。
apiVersion : rbac.authorization.k8s.io/v1
kind : ClusterRole
metadata :
name : impersonator
rules :
- apiGroups : ["" ]
resources : ["users" , "groups" , "serviceaccounts" ]
verbs : ["impersonate" ]
追加フィールドは、"userextras"リソースのサブリソースとして評価されます。ユーザーが追加フィールド"scopes"に偽装ヘッダーを使用できるようにするには、ユーザーに以下のようなロールを付与する必要があります。
apiVersion : rbac.authorization.k8s.io/v1
kind : ClusterRole
metadata :
name : scopes-impersonator
rules :
# "Impersonate-Extra-scopes"ヘッダーを設定できます。
- apiGroups : ["authentication.k8s.io" ]
resources : ["userextras/scopes" ]
verbs : ["impersonate" ]
偽装ヘッダーの値は、リソースが取り得るresourceNames
の集合を制限することで、管理することもできます。
apiVersion : rbac.authorization.k8s.io/v1
kind : ClusterRole
metadata :
name : limited-impersonator
rules :
# "jane.doe@example.com"というユーザーを偽装できます。
- apiGroups : ["" ]
resources : ["users" ]
verbs : ["impersonate" ]
resourceNames : ["jane.doe@example.com" ]
# "developers"と"admins"というグループを偽装できます。
- apiGroups : ["" ]
resources : ["groups" ]
verbs : ["impersonate" ]
resourceNames : ["developers" ,"admins" ]
# "view"と"development"を値に持つ"scopes"という追加フィールドを偽装できます。
- apiGroups : ["authentication.k8s.io" ]
resources : ["userextras/scopes" ]
verbs : ["impersonate" ]
resourceNames : ["view" , "development" ]
client-goクレデンシャルプラグイン
FEATURE STATE: Kubernetes v1.11 [beta]
k8s.io/client-go
と、それを使用するkubectl
やkubelet
のようなツールは、外部コマンドを実行してユーザーの認証情報を受け取ることができます。
この機能はk8s.io/client-go
がネイティブにサポートしていない認証プロトコル(LDAP、Kerberos、OAuth2、SAMLなど)とクライアントサイドで統合するためのものです。プラグインはプロトコル固有のロジックを実装し、使用する不透明なクレデンシャルを返します。ほとんどすべてのクレデンシャルプラグインのユースケースでは、クライアントプラグインが生成するクレデンシャルフォーマットを解釈するために、Webhookトークン認証 をサポートするサーバーサイドコンポーネントが必要です。
使用例
ある組織は、LDAPクレデンシャルをユーザー固有の署名済みトークンと交換する外部サービスを実行すると仮定します。このサービスは、トークンを検証するためにWebhookトークン認証 リクエストに応答することもできます。ユーザーはワークステーションにクレデンシャルプラグインをインストールする必要があります。
以下のようにして、APIに対して認証を行います。
ユーザーはkubectl
コマンドを発行します。
クレデンシャルプラグインは、LDAPクレデンシャルの入力をユーザーに要求し、クレデンシャルを外部サービスとトークンと交換します。
クレデンシャルプラグインはトークンをclient-go
に返します。これはAPIサーバーに対するBearerトークンとして使用されます。
APIサーバーは、Webhookトークン認証 を使用して、TokenReview
を外部サービスに送信します。
外部サービスはトークンの署名を検証し、ユーザーのユーザー名とグループを返します。
設定
クレデンシャルプラグインの設定は、userフィールドの一部としてkubectlの設定ファイル で行います。
apiVersion : v1
kind : Config
users :
- name : my-user
user :
exec :
# 実行するコマンドです。必須です。
command : "example-client-go-exec-plugin"
# ExecCredentialsリソースをデコードする際に使用するAPIのバージョン。必須です。
#
# プラグインが返すAPIのバージョンは、ここに記載されているバージョンと一致しなければなりません
#
# 複数のバージョンをサポートするツール(client.authentication.k8s.io/v1alpha1など)と統合するには、
# 環境変数を設定するか、execプラグインが期待するバージョンを示す引数をツールに渡します。
apiVersion : "client.authentication.k8s.io/v1beta1"
# プラグインを実行する際に設定する環境変数です。任意です。
env :
- name : "FOO"
value : "bar"
# プラグインを実行する際に渡す引数です。任意です。
args :
- "arg1"
- "arg2"
clusters :
- name : my-cluster
cluster :
server : "https://172.17.4.100:6443"
certificate-authority : "/etc/kubernetes/ca.pem"
contexts :
- name : my-cluster
context :
cluster : my-cluster
user : my-user
current-context : my-cluster
相対的なコマンドパスは、設定ファイルのディレクトリーからの相対的なものとして解釈されます。KUBECONFIGが/home/jane/kubeconfig
に設定されていて、execコマンドが./bin/example-client-go-exec-plugin
の場合、バイナリ/home/jane/bin/example-client-go-exec-plugin
が実行されます。
- name : my-user
user :
exec :
# kubeconfigのディレクトリーへの相対パス
command : "./bin/example-client-go-exec-plugin"
apiVersion : "client.authentication.k8s.io/v1beta1"
入出力フォーマット
実行されたコマンドはExecCredential
オブジェクトをstdout
に出力します。k8s.io/client-go
はstatus
で返された認証情報を用いて、Kubernetes APIに対して認証を行ういます。
対話的なセッションから実行する場合、stdin
はプラグインに直接公開されます。プラグインはTTYチェック を使って、対話的にユーザーにプロンプトを出すことが適切かどうかを判断する必要があります。
Bearerトークンのクレデンシャルを使用するために、プラグインはExecCredential
のステータスにトークンを返します。
{
"apiVersion" : "client.authentication.k8s.io/v1beta1" ,
"kind" : "ExecCredential" ,
"status" : {
"token" : "my-bearer-token"
}
}
あるいは、PEMエンコードされたクライアント証明書と鍵を返して、TLSクライアント認証を使用することもできます。
プラグインが後続の呼び出しで異なる証明書と鍵を返すと、k8s.io/client-go
はサーバーとの既存の接続を閉じて、新しいTLSハンドシェイクを強制します
指定された場合、clientKeyData
とclientCertificateData
両方が存在しなければなりません。
clientCertificateData
には、サーバーに送信するための中間証明書を含めることができます。
{
"apiVersion" : "client.authentication.k8s.io/v1beta1" ,
"kind" : "ExecCredential" ,
"status" : {
"clientCertificateData" : "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----" ,
"clientKeyData" : "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
}
}
オプションで、レスポンスにはRFC3339のタイムスタンプとしてフォーマットされたクレデンシャルの有効期限を含めることができます。有効期限の有無には、以下のような影響あります。
有効期限が含まれている場合、BearerトークンとTLSクレデンシャルは有効期限に達するまで、またはサーバーがHTTPステータスコード401で応答したとき、またはプロセスが終了するまでキャッシュされます。
有効期限が省略された場合、BearerトークンとTLSクレデンシャルはサーバーがHTTPステータスコード401で応答したとき、またはプロセスが終了するまでキャッシュされます。
{
"apiVersion" : "client.authentication.k8s.io/v1beta1" ,
"kind" : "ExecCredential" ,
"status" : {
"token" : "my-bearer-token" ,
"expirationTimestamp" : "2018-03-05T17:30:20-08:00"
}
}
4 - API概要
このセクションでは、Kubernetes APIのリファレンス情報を提供します。
REST APIはKubernetesの基本的な構造です。
すべての操作とコンポーネント間の通信、および外部ユーザーのコマンドは、REST API呼び出しでありAPIサーバーが処理します。
その結果、Kubernetesプラットフォーム内のすべてのものは、APIオブジェクトとして扱われ、API に対応するエントリーがあります。
Kubernetes APIリファレンス は、Kubernetesバージョンv1.28のAPI一覧を提供します。
一般的な背景情報を知るには、The Kubernetes API 、
Controlling Access to the Kubernetes API を読んでください。
それらはKubernetes APIサーバーがクライアントを認証する方法とリクエストを認可する方法を説明します。
APIバージョニング
JSONとProtobufなどのシリアル化スキーマの変更については同じガイドラインに従います。
以下の説明は、両方のフォーマットをカバーしています。
APIのバージョニングとソフトウェアのバージョニングは間接的に関係しています。
API and release versioning proposal は、APIバージョニングとソフトウェアバージョニングの関係を説明しています。
APIのバージョンが異なると、安定性やサポートのレベルも異なります。
各レベルの基準については、API Changes documentation で詳しく説明しています。
各レベルの概要は以下の通りです:
APIグループ
API groups で、KubernetesのAPIを簡単に拡張することができます。
APIグループは、RESTパスとシリアル化されたオブジェクトのapiVersion
フィールドで指定されます。
KubernetesにはいくつかのAPIグループがあります:
core (legacy とも呼ばれる)グループは、RESTパス /api/v1
にあります。
コアグループは apiVersion
フィールドの一部としては指定されません。
例えば、apiVersion: v1
のように。
名前付きのグループは、RESTパス /apis/$GROUP_NAME/$VERSION
にあり、以下のように使用します。
apiVersion: $GROUP_NAME/$VERSION
を使用します(例:apiVersion: batch/v1
)。
サポートされているAPIグループの完全なリストは以下にあります。
Kubernetes API reference 。
APIグループの有効化と無効化
一部のリソースやAPIグループはデフォルトで有効になっています。
APIサーバー上で--runtime-config
を設定することで、有効にしたり無効にしたりすることができます。
またruntime-config
フラグには、APIサーバーのランタイム構成を記述したコンマ区切りの<key>[=<value>]
ペアを指定します。
もし=<value>
の部分が省略された場合には、=true
が指定されたものとして扱われます。
例えば:
batch/v1
を無効するには、--runtime-config=batch/v1=false
を設定する
batch/v2alpha1
を有効するには、--runtime-config=batch/v2alpha1
を設定する
備考: グループやリソースを有効または無効にした場合、
APIサーバーとコントローラーマネージャーを再起動して、--runtime-config
の変更を反映させる必要があります。
永続化
Kubernetesはシリアライズされた状態を、APIリソースとしてetcd に書き込んで保存します。
次の項目
5 - 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」などの単純な名前。「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を手動で編集しないか、自動調整を無効にします。
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:node Roleの代わりに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-system Namespaceのサービスアカウント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の使用に移行後、クラスターが情報セキュリティのニーズを確実に満たすように、アクセスコントロールを調整する必要があります。
6 - ネットワーキングのリファレンス
このセクションでは、Kubernetesネットワーキングの詳細を提供します。
6.1 - ポートとプロトコル
パブリッククラウドにおける仮想ネットワークや、物理ネットワークファイアウォールを持つオンプレミスのデータセンターのような、ネットワークの境界が厳格な環境でKubernetesを実行する場合、Kubernetesのコンポーネントが使用するポートやプロトコルを認識しておくと便利です。
コントロールプレーン
プロトコル
通信の向き
ポート範囲
目的
使用者
TCP
Inbound
6443
Kubernetes API server
全て
TCP
Inbound
2379-2380
etcd server client API
kube-apiserver, etcd
TCP
Inbound
10250
Kubelet API
自身, コントロールプレーン
TCP
Inbound
10259
kube-scheduler
自身
TCP
Inbound
10257
kube-controller-manager
自身
etcdポートはコントロールプレーンノードに含まれていますが、独自のetcdクラスターを外部またはカスタムポートでホストすることもできます。
ワーカーノード
プロトコル
通信の向き
ポート範囲
目的
使用者
TCP
Inbound
10250
Kubelet API
自身, コントロールプレーン
TCP
Inbound
30000-32767
NodePort Services†
全て
† NodePort Services のデフォルトのポート範囲。
すべてのデフォルトのポート番号が書き換え可能です。
カスタムポートを使用する場合、ここに記載されているデフォルトではなく、それらのポートを開く必要があります。
よくある例としては、API Serverのポートを443に変更することがあります。
または、デフォルトポートをそのままにし、API Serverを443でリッスンしているロードバランサーの後ろに置き、APIサーバのデフォルトポートにリクエストをルーティングする方法もあります。
7.1 - Kubeadm
kubeadmは、kubeadm init
やkubeadm join
などのコマンドを提供するツールで、Kubernetesクラスターを構築する上でのベストプラクティスを反映した「近道」を提供するものとして開発されました。
kubeadmは実用最小限のクラスターをセットアップするための処理を実行します。設計上、kubeadmはブートストラップのみを行い、マシンのプロビジョニングは行いません。同様に、Kubernetesダッシュボード、モニタリングソリューション、クラウド向けのアドオンなど、あれば便利でもなくても支障のない各種アドオンのインストールも範囲外です。
その代わりに、高度な特定用途向けのツールはkubeadmをベースに構築されることが期待されています。理想的には、すべてのデプロイのベースとしてkubeadmを使用することで、適合テストに通るクラスターを簡単に作れるようになります。
インストール方法
kubeadmをインストールするには、インストールガイド を参照してください。
次の項目
8 - コマンドラインツール(kubectl)
Kubernetesが提供する、 kubernetes APIを使用してKubernetesクラスターのコントロールプレーン と通信するためのコマンドラインツールです。
このツールの名前は、kubectl
です。
kubectl
コマンドラインツールを使うと、Kubernetesクラスターを制御できます。環境設定のために、kubectl
は、$HOME/.kube
ディレクトリにあるconfig
という名前のファイルを探します。他のkubeconfig ファイルは、KUBECONFIG
環境変数を設定するか、--kubeconfig
フラグを設定することで指定できます。
この概要では、kubectl
の構文を扱い、コマンド操作を説明し、一般的な例を示します。サポートされているすべてのフラグやサブコマンドを含め、各コマンドの詳細については、kubectl リファレンスドキュメントを参照してください。
インストール方法については、kubectlのインストールおよびセットアップ をご覧ください。クイックガイドは、チートシート をご覧ください。docker
コマンドラインツールに慣れている方は、kubectl
for Docker Users でKubernetesの同等のコマンドを説明しています。
構文
ターミナルウィンドウからkubectl
コマンドを実行するには、以下の構文を使用します。
kubectl [ command] [ TYPE] [ NAME] [ flags]
ここで、command
、TYPE
、NAME
、flags
は、以下を表します。
command
: 1つ以上のリソースに対して実行したい操作を指定します。例えば、create
、get
、describe
、delete
です。
TYPE
: リソースタイプ を指定します。リソースタイプは大文字と小文字を区別せず、単数形や複数形、省略形を指定できます。例えば、以下のコマンドは同じ出力を生成します。
kubectl get pod pod1
kubectl get pods pod1
kubectl get po pod1
NAME
: リソースの名前を指定します。名前は大文字と小文字を区別します。kubectl get pods
のように名前が省略された場合は、すべてのリソースの詳細が表示されます。
複数のリソースに対して操作を行う場合は、各リソースをタイプと名前で指定するか、1つまたは複数のファイルを指定することができます。
flags
: オプションのフラグを指定します。例えば、-s
または--server
フラグを使って、Kubernetes APIサーバーのアドレスやポートを指定できます。
注意: コマンドラインから指定したフラグは、デフォルト値および対応する任意の環境変数を上書きします。
ヘルプが必要な場合は、ターミナルウィンドウからkubectl help
を実行してください。
クラスター内認証と名前空間のオーバーライド
デフォルトでは、kubectl
は最初にPod内で動作しているか、つまりクラスター内で動作しているかどうかを判断します。まず、KUBERNETES_SERVICE_HOST
とKUBERNETES_SERVICE_PORT
の環境変数を確認し、サービスアカウントのトークンファイルが/var/run/secrets/kubernetes.io/serviceaccount/token
に存在するかどうかを確認します。3つともクラスター内で見つかった場合、クラスター内認証とみなされます。
後方互換性を保つため、クラスター内認証時にPOD_NAMESPACE
環境変数が設定されている場合には、サービスアカウントトークンのデフォルトの名前空間が上書きされます。名前空間のデフォルトに依存しているすべてのマニフェストやツールは、この影響を受けます。
POD_NAMESPACE
環境変数
POD_NAMESPACE
環境変数が設定されている場合、名前空間に属するリソースのCLI操作は、デフォルトで環境変数の値になります。例えば、変数にseattle
が設定されている場合、kubectl get pods
は、seattle
名前空間のPodを返します。これは、Podが名前空間に属するリソースであり、コマンドで名前空間が指定されていないためです。kubectl api-resources
の出力を見て、リソースが名前空間に属するかどうかを判断してください。
明示的に--namespace <value>
を使用すると、この動作は上書きされます。
kubectlによるServiceAccountトークンの処理方法
以下の条件がすべて成立した場合、
/var/run/secrets/kubernetes.io/serviceaccount/token
にマウントされたKubernetesサービスアカウントのトークンファイルがある
KUBERNETES_SERVICE_HOST
環境変数が設定されている
KUBERNETES_SERVICE_PORT
環境変数が設定されている
kubectlコマンドラインで名前空間を明示的に指定しない
kubectlはクラスター内で実行されているとみなして、そのServiceAccountの名前空間(これはPodの名前空間と同じです)を検索し、その名前空間に対して機能します。これは、クラスターの外の動作とは異なります。kubectlがクラスターの外で実行され、名前空間を指定しない場合、kubectlコマンドは、クライアント構成の現在のコンテキストに設定されている名前空間に対して動作します。kubectlのデフォルトの名前空間を変更するには、次のコマンドを使用できます。
kubectl config set-context --current --namespace= <namespace-name>
操作
以下の表に、kubectl
のすべての操作の簡単な説明と一般的な構文を示します。
操作
構文
説明
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つ以上のリソースリソースの定義を編集し、更新します。
events
kubectl events
イベントを一覧表示します。
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.25.0時点で正確でした。)
リソース名
短縮名
APIバージョン
名前空間に属するか
リソースの種類
bindings
v1
true
Binding
componentstatuses
cs
v1
false
ComponentStatus
configmaps
cm
v1
true
ConfigMap
endpoints
ep
v1
true
Endpoints
events
ev
v1
true
Event
limitranges
limits
v1
true
LimitRange
namespaces
ns
v1
false
Namespace
nodes
no
v1
false
Node
persistentvolumeclaims
pvc
v1
true
PersistentVolumeClaim
persistentvolumes
pv
v1
false
PersistentVolume
pods
po
v1
true
Pod
podtemplates
v1
true
PodTemplate
replicationcontrollers
rc
v1
true
ReplicationController
resourcequotas
quota
v1
true
ResourceQuota
secrets
v1
true
Secret
serviceaccounts
sa
v1
true
ServiceAccount
services
svc
v1
true
Service
mutatingwebhookconfigurations
admissionregistration.k8s.io/v1
false
MutatingWebhookConfiguration
validatingwebhookconfigurations
admissionregistration.k8s.io/v1
false
ValidatingWebhookConfiguration
customresourcedefinitions
crd,crds
apiextensions.k8s.io/v1
false
CustomResourceDefinition
apiservices
apiregistration.k8s.io/v1
false
APIService
controllerrevisions
apps/v1
true
ControllerRevision
daemonsets
ds
apps/v1
true
DaemonSet
deployments
deploy
apps/v1
true
Deployment
replicasets
rs
apps/v1
true
ReplicaSet
statefulsets
sts
apps/v1
true
StatefulSet
tokenreviews
authentication.k8s.io/v1
false
TokenReview
localsubjectaccessreviews
authorization.k8s.io/v1
true
LocalSubjectAccessReview
selfsubjectaccessreviews
authorization.k8s.io/v1
false
SelfSubjectAccessReview
selfsubjectrulesreviews
authorization.k8s.io/v1
false
SelfSubjectRulesReview
subjectaccessreviews
authorization.k8s.io/v1
false
SubjectAccessReview
horizontalpodautoscalers
hpa
autoscaling/v2
true
HorizontalPodAutoscaler
cronjobs
cj
batch/v1
true
CronJob
jobs
batch/v1
true
Job
certificatesigningrequests
csr
certificates.k8s.io/v1
false
CertificateSigningRequest
leases
coordination.k8s.io/v1
true
Lease
endpointslices
discovery.k8s.io/v1
true
EndpointSlice
events
ev
events.k8s.io/v1
true
Event
flowschemas
flowcontrol.apiserver.k8s.io/v1beta2
false
FlowSchema
prioritylevelconfigurations
flowcontrol.apiserver.k8s.io/v1beta2
false
PriorityLevelConfiguration
ingressclasses
networking.k8s.io/v1
false
IngressClass
ingresses
ing
networking.k8s.io/v1
true
Ingress
networkpolicies
netpol
networking.k8s.io/v1
true
NetworkPolicy
runtimeclasses
node.k8s.io/v1
false
RuntimeClass
poddisruptionbudgets
pdb
policy/v1
true
PodDisruptionBudget
podsecuritypolicies
psp
policy/v1beta1
false
PodSecurityPolicy
clusterrolebindings
rbac.authorization.k8s.io/v1
false
ClusterRoleBinding
clusterroles
rbac.authorization.k8s.io/v1
false
ClusterRole
rolebindings
rbac.authorization.k8s.io/v1
true
RoleBinding
roles
rbac.authorization.k8s.io/v1
true
Role
priorityclasses
pc
scheduling.k8s.io/v1
false
PriorityClass
csidrivers
storage.k8s.io/v1
false
CSIDriver
csinodes
storage.k8s.io/v1
false
CSINode
csistoragecapacities
storage.k8s.io/v1
true
CSIStorageCapacity
storageclasses
sc
storage.k8s.io/v1
false
StorageClass
volumeattachments
storage.k8s.io/v1
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
次の項目
8.1 - kubectlチートシート
このページには、一般的によく使われるkubectl
コマンドとフラグのリストが含まれています。
Kubectlコマンドの補完
BASH
source <( kubectl completion bash) # 現在のbashシェルにコマンド補完を設定するには、最初にbash-completionパッケージをインストールする必要があります。
echo "source <(kubectl completion bash)" >> ~/.bashrc # bashシェルでのコマンド補完を永続化するために.bashrcに追記します。
また、エイリアスを使用している場合にもkubectl
コマンドを補完できます。
alias k = kubectl
complete -F __start_kubectl k
ZSH
source <( kubectl completion zsh) # 現在のzshシェルにコマンド補完を設定します
echo "[[ $commands [kubectl] ]] && source <(kubectl completion zsh)" >> ~/.zshrc # zshシェルでのコマンド補完を永続化するために.zshrcに追記します。
Kubectlコンテキストの設定
kubectl
がどのKubernetesクラスターと通信するかを設定します。
設定ファイル詳細についてはkubeconfigを使用した複数クラスターとの認証 をご覧ください。
kubectl config view # マージされたkubeconfigの設定を表示します。
# 複数のkubeconfigファイルを同時に読み込む場合はこのように記述します。
KUBECONFIG = ~/.kube/config:~/.kube/kubconfig2
kubectl config view
# e2eユーザのパスワードを取得します。
kubectl config view -o jsonpath = '{.users[?(@.name == "e2e")].user.password}'
kubectl config view -o jsonpath = '{.users[].name}' # 最初のユーザー名を表示します
kubectl config view -o jsonpath = '{.users[*].name}' # ユーザー名のリストを表示します
kubectl config get-contexts # コンテキストのリストを表示します
kubectl config current-context # 現在のコンテキストを表示します
kubectl config use-context my-cluster-name # デフォルトのコンテキストをmy-cluster-nameに設定します
# basic認証をサポートする新たなユーザーをkubeconfigに追加します
kubectl config set-credentials kubeuser/foo.kubernetes.com --username= kubeuser --password= kubepassword
# 現在のコンテキストでkubectlのサブコマンドの名前空間を永続的に変更します
kubectl config set-context --current --namespace= ggckad-s2
# 特定のユーザー名と名前空間を使用してコンテキストを設定します
kubectl config set-context gce --user= cluster-admin --namespace= foo \
&& kubectl config use-context gce
kubectl config unset users.foo # ユーザーfooを削除します
Kubectl Apply
apply
はKubernetesリソースを定義するファイルを通じてアプリケーションを管理します。kubectl apply
を実行して、クラスター内のリソースを作成および更新します。これは、本番環境でKubernetesアプリケーションを管理する推奨方法です。
詳しくはKubectl Book をご覧ください。
Objectの作成
Kubernetesのマニフェストファイルは、JSONまたはYAMLで定義できます。ファイル拡張子として、.yaml
や.yml
、.json
が使えます。
kubectl apply -f ./my-manifest.yaml # リソースを作成します
kubectl apply -f ./my1.yaml -f ./my2.yaml # 複数のファイルからリソースを作成します
kubectl apply -f ./dir # dirディレクトリ内のすべてのマニフェストファイルからリソースを作成します
kubectl apply -f https://git.io/vPieo # urlで公開されているファイルからリソースを作成します
kubectl create deployment nginx --image= nginx # 単一のnginx Deploymentを作成します
kubectl explain pods # Podマニフェストのドキュメントを取得します
# 標準入力から複数のYAMLオブジェクトを作成します
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
name: busybox-sleep
spec:
containers:
- name: busybox
image: busybox
args:
- sleep
- "1000000"
---
apiVersion: v1
kind: Pod
metadata:
name: busybox-sleep-less
spec:
containers:
- name: busybox
image: busybox
args:
- sleep
- "1000"
EOF
# いくつかの鍵を含むSecretを作成します
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Secret
metadata:
name: mysecret
type: Opaque
data:
password: $(echo -n "s33msi4" | base64 -w0)
username: $(echo -n "jane" | base64 -w0)
EOF
リソースの検索と閲覧
# Getコマンドで基本的な情報を確認します
kubectl get services # 現在の名前空間上にあるすべてのサービスのリストを表示します
kubectl get pods --all-namespaces # すべての名前空間上にあるすべてのPodのリストを表示します
kubectl get pods -o wide # 現在の名前空間上にあるすべてのPodについてより詳細なリストを表示します
kubectl get deployment my-dep # 特定のDeploymentを表示します
kubectl get pods # 現在の名前空間上にあるすべてのPodのリストを表示します
kubectl get pod my-pod -o yaml # PodのYAMLを表示します
# Describeコマンドで詳細な情報を確認します
kubectl describe nodes my-node
kubectl describe pods my-pod
# 名前順にソートしたServiceのリストを表示します
kubectl get services --sort-by= .metadata.name
# Restartカウント順にPodのリストを表示します
kubectl get pods --sort-by= '.status.containerStatuses[0].restartCount'
# capacity順にソートしたPersistentVolumeのリストを表示します
kubectl get pv --sort-by= .spec.capacity.storage
# app=cassandraラベルのついたすべてのPodのversionラベルを表示します
kubectl get pods --selector= app = cassandra -o \
jsonpath = '{.items[*].metadata.labels.version}'
# 'ca.crt'のようなピリオドが含まれるキーの値を取得します
kubectl get configmap myconfig \
-o jsonpath = '{.data.ca\.crt}'
# すべてのワーカーノードを取得します(セレクターを使用して、
# 「node-role.kubernetes.io/master」という名前のラベルを持つ結果を除外します)
kubectl get node --selector= '!node-role.kubernetes.io/master'
# 現在の名前空間でrunning状態のPodのリストを表示します
kubectl get pods --field-selector= status.phase= Running
# すべてのノードのExternal IPのリストを表示します
kubectl get nodes -o jsonpath = '{.items[*].status.addresses[?(@.type=="ExternalIP")].address}'
# 特定のRCに属するPodの名前のリストを表示します
# `jq`コマンドは複雑なjsonpathを変換する場合に便利であり、https://stedolan.github.io/jq/で見つけることが可能です
sel = ${ $( kubectl get rc my-rc --output= json | jq -j '.spec.selector | to_entries | .[] | "\(.key)=\(.value),"' ) %?}
echo $( kubectl get pods --selector= $sel --output= jsonpath ={ .items..metadata.name} )
# すべてのPod(またはラベル付けをサポートする他のKubernetesオブジェクト)のラベルのリストを表示します
kubectl get pods --show-labels
# どのノードがready状態か確認します
JSONPATH = '{range .items[*]}{@.metadata.name}:{range @.status.conditions[*]}{@.type}={@.status};{end}{end}' \
&& kubectl get nodes -o jsonpath = " $JSONPATH " | grep "Ready=True"
# Podで現在使用中のSecretをすべて表示します
kubectl get pods -o json | jq '.items[].spec.containers[].env[]?.valueFrom.secretKeyRef.name' | grep -v null | sort | uniq
# すべてのPodのInitContainerのコンテナIDのリストを表示します
# initContainerの削除を回避しながら、停止したコンテナを削除するときに役立つでしょう
kubectl get pods --all-namespaces -o jsonpath = '{range .items[*].status.initContainerStatuses[*]}{.containerID}{"\n"}{end}' | cut -d/ -f3
# タイムスタンプでソートされたEventのリストを表示します
kubectl get events --sort-by= .metadata.creationTimestamp
# クラスターの現在の状態を、マニフェストが適用された場合のクラスターの状態と比較します。
kubectl diff -f ./my-manifest.yaml
# Nodeから返されるすべてのキーをピリオド区切りの階層表記で生成します。
# 複雑にネストされたJSON構造をもつキーを指定したい時に便利です
kubectl get nodes -o json | jq -c 'paths|join(".")'
# Pod等から返されるすべてのキーをピリオド区切り階層表記で生成します。
kubectl get pods -o json | jq -c 'paths|join(".")'
リソースのアップデート
kubectl set image deployment/frontend www = image:v2 # frontend Deploymentのwwwコンテナイメージをv2にローリングアップデートします
kubectl rollout history deployment/frontend # frontend Deploymentの改訂履歴を確認します
kubectl rollout undo deployment/frontend # 1つ前のDeploymentにロールバックします
kubectl rollout undo deployment/frontend --to-revision= 2 # 特定のバージョンにロールバックします
kubectl rollout status -w deployment/frontend # frontend Deploymentのローリングアップデートを状態をwatchします
kubectl rollout restart deployment/frontend # frontend Deployment を再起動します
cat pod.json | kubectl replace -f - # 標準入力から渡されたJSONに基づいてPodを置き換えます
# リソースを強制的に削除してから再生成し、置き換えます。サービスの停止が発生します
kubectl replace --force -f ./pod.json
# ReplicaSetリソースで作られたnginxについてServiceを作成します。これは、ポート80で提供され、コンテナへはポート8000で接続します
kubectl expose rc nginx --port= 80 --target-port= 8000
# 単一コンテナのPodイメージのバージョン(タグ)をv4に更新します
kubectl get pod mypod -o yaml | sed 's/\(image: myimage\):.*$/\1:v4/' | kubectl replace -f -
kubectl label pods my-pod new-label= awesome # ラベルを追加します
kubectl annotate pods my-pod icon-url= http://goo.gl/XXBTWq # アノテーションを追加します
kubectl autoscale deployment foo --min= 2 --max= 10 # "foo" Deploymentのオートスケーリングを行います
リソースへのパッチ適用
# ノードを部分的に更新します
kubectl patch node k8s-node-1 -p '{"spec":{"unschedulable":true}}'
# コンテナのイメージを更新します。spec.containers[*].nameはマージキーであるため必須です
kubectl patch pod valid-pod -p '{"spec":{"containers":[{"name":"kubernetes-serve-hostname","image":"new image"}]}}'
# ポテンシャル配列を含むJSONパッチを使用して、コンテナのイメージを更新します
kubectl patch pod valid-pod --type= 'json' -p= '[{"op": "replace", "path": "/spec/containers/0/image", "value":"new image"}]'
# ポテンシャル配列のJSONパッチを使用してDeploymentのlivenessProbeを無効にします
kubectl patch deployment valid-deployment --type json -p= '[{"op": "remove", "path": "/spec/template/spec/containers/0/livenessProbe"}]'
# ポテンシャル配列に新たな要素を追加します
kubectl patch sa default --type= 'json' -p= '[{"op": "add", "path": "/secrets/1", "value": {"name": "whatever" } }]'
リソースの編集
任意のエディターでAPIリソースを編集します。
kubectl edit svc/docker-registry # docker-registryという名前のサービスを編集します
KUBE_EDITOR = "nano" kubectl edit svc/docker-registry # エディターを指定します
リソースのスケーリング
kubectl scale --replicas= 3 rs/foo # 「foo」という名前のレプリカセットを3にスケーリングします
kubectl scale --replicas= 3 -f foo.yaml # 「foo.yaml」で指定されたリソースを3にスケーリングします
kubectl scale --current-replicas= 2 --replicas= 3 deployment/mysql # mysqlと名付けられたdeploymentの現在のサイズが2であれば、mysqlを3にスケーリングします
kubectl scale --replicas= 5 rc/foo rc/bar rc/baz # 複数のReplication controllerをスケーリングします
リソースの削除
kubectl delete -f ./pod.json # pod.jsonで指定されたタイプと名前を使用してPodを削除します
kubectl delete pod,service baz foo # 「baz」と「foo」の名前を持つPodとServiceを削除します
kubectl delete pods,services -l name = myLabel # name=myLabelラベルを持つのPodとServiceを削除します
kubectl -n my-ns delete pod,svc --all # 名前空間my-ns内のすべてのPodとServiceを削除します
# awkコマンドのpattern1またはpattern2に一致するすべてのPodを削除します。
kubectl get pods -n mynamespace --no-headers= true | awk '/pattern1|pattern2/{print $1}' | xargs kubectl delete -n mynamespace pod
実行中のポッドとの対話処理
kubectl logs my-pod # Podのログをダンプします(標準出力)
kubectl logs -l name = myLabel # name=myLabelラベルの持つPodのログをダンプします(標準出力)
kubectl logs my-pod --previous # 以前に存在したコンテナのPodログをダンプします(標準出力)
kubectl logs my-pod -c my-container # 複数コンテナがあるPodで、特定のコンテナのログをダンプします(標準出力)
kubectl logs -l name = myLabel -c my-container # name=mylabelラベルを持つPodのログをダンプします(標準出力)
kubectl logs my-pod -c my-container --previous # 複数コンテナがあるPodで、以前に作成した特定のコンテナのログをダンプします(標準出力)
kubectl logs -f my-pod # Podのログをストリームで確認します(標準出力)
kubectl logs -f my-pod -c my-container # 複数のコンテナがあるPodで、特定のコンテナのログをストリームで確認します(標準出力)
kubectl logs -f -l name = myLabel --all-containers # name-myLabelラベルを持つすべてのコンテナのログをストリームで確認します(標準出力)
kubectl run -i --tty busybox --image= busybox -- sh # Podをインタラクティブシェルとして実行します
kubectl run nginx --image= nginx -n
mynamespace # 特定の名前空間でnginx Podを実行します
kubectl run nginx --image= nginx # nginx Podを実行し、マニフェストファイルをpod.yamlという名前で書き込みます
--dry-run= client -o yaml > pod.yaml
kubectl attach my-pod -i # 実行中のコンテナに接続します
kubectl port-forward my-pod 5000:6000 # ローカルマシンのポート5000を、my-podのポート6000に転送します
kubectl exec my-pod -- ls / # 既存のPodでコマンドを実行(単一コンテナの場合)
kubectl exec my-pod -c my-container -- ls / # 既存のPodでコマンドを実行(複数コンテナがある場合)
kubectl top pod POD_NAME --containers # 特定のPodとそのコンテナのメトリクスを表示します
ノードおよびクラスターとの対話処理
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'
# "registry.k8s.io/coredns:1.6.2"を除いたすべてのイメージ名を表示する
kubectl get pods -A -o= custom-columns= 'DATA:spec.containers[?(@.image!="registry.k8s.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なしで表示します
次の項目
8.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-")).metadata.name'
8.3 - kubectlの使用規則
kubectl
の推奨される使用規則です。
再利用可能なスクリプトでのkubectl
の使用
スクリプトでの安定した出力のために:
-o name
, -o json
, -o yaml
, -o go-template
, -o jsonpath
などの機械指向の出力形式のいずれかを必要します。
バージョンを完全に指定します。例えば、jobs.v1.batch/myjob
のようにします。これにより、kubectlが時間とともに変化する可能性のあるデフォルトのバージョンを使用しないようにします。
コンテキストや設定、その他の暗黙的な状態に頼ってはいけません。
ベストプラクティス
kubectl run
kubectl run
がインフラのコード化を満たすために:
イメージにバージョン固有のタグを付けて、そのタグを新しいバージョンに移さない。例えば、:latest
ではなく、:v1234
、v1.2.3
、r03062016-1-4
を使用してください(詳細は、Best Practices for Configuration を参照してください)。
パラメーターが多用されているイメージをスクリプトでチェックします。
kubectl run
フラグでは表現できない機能を、ソースコントロールでチェックした設定ファイルに切り替えます。
dry-run=client
フラグを使用すると、実際に送信することなく、クラスターに送信されるオブジェクトを確認することができます。
備考: すべての
kubectl run
ジェネレーターは非推奨です。ジェネレーターの
リスト とその使用方法については、Kubernetes v1.17のドキュメントを参照してください。
Generators
kubectl create --dry-run=client -o yaml
というkubectlコマンドで以下のリソースを生成することができます。
clusterrole
: ClusterRoleを作成します。
clusterrolebinding
: 特定のClusterRoleに対するClusterRoleBindingを作成します。
configmap
: ローカルファイル、ディレクトリ、またはリテラル値からConfigMapを作成します。
cronjob
: 指定された名前のCronJobを作成します。
deployment
: 指定された名前でDeploymentを作成します。
job
: 指定された名前でJobを作成します。
namespace
: 指定された名前でNamespaceを作成します。
poddisruptionbudget
: 指定された名前でPodDisruptionBudgetを作成します。
priorityclass
: 指定された名前でPriorityClassを作成します。
quota
: 指定された名前でQuotaを作成します。
role
: 1つのルールでRoleを作成します。
rolebinding
: 特定のロールやClusterRoleに対するRoleBindingを作成します。
secret
: 指定されたサブコマンドを使用してSecretを作成します。
service
: 指定されたサブコマンドを使用してServiceを作成します。
ServiceAccount
: 指定された名前でServiceAccountを作成します。
kubectl apply
リソースの作成や更新には kubectl apply
を使用できます。kubectl applyを使ったリソースの更新については、Kubectl Book を参照してください。
9.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
10.1 - スケジューラーの設定
FEATURE STATE: Kubernetes v1.19 [beta]
設定ファイルを作成し、そのパスをコマンドライン引数として渡すことでkube-scheduler
の振る舞いをカスタマイズすることができます。
スケジューリングプロファイルは、kube-scheduler でスケジューリングの異なるステージを設定することができます。
各ステージは、拡張点に公開されています。プラグインをそれらの拡張点に1つ以上実装することで、スケジューリングの振る舞いを変更できます。
KubeSchedulerConfiguration(v1beta2
かv1beta3
)構造体を使用して、kube-scheduler --config <filename>
を実行することで、スケジューリングプロファイルを指定することができます。
最小限の設定は次の通りです。
apiVersion : kubescheduler.config.k8s.io/v1beta2
kind : KubeSchedulerConfiguration
clientConnection :
kubeconfig : /etc/srv/kubernetes/kube-scheduler/kubeconfig
プロファイル
スケジューリングプロファイルは、kube-scheduler でスケジューリングの異なるステージを設定することができます。
各ステージは拡張点 に公開されています。
プラグイン をそれらの拡張点に1つ以上実装することで、スケジューリングの振る舞いを変更できます。
単一のkube-scheduler
インスタンスで複数のプロファイル を実行するように設定することも可能です。
拡張点
スケジューリングは一連のステージで行われ、以下の拡張点に公開されています。
queueSort
: これらのプラグインは、スケジューリングキューにあるpending
状態のPodをソートするための順序付け関数を提供します。同時に有効化できるプラグインは1つだけです。
preFilter
: これらのプラグインは、フィルタリングをする前にPodやクラスターの情報のチェックや前処理のために使用されます。これらのプラグインは、設定された順序で呼び出されます。
filter
: これらのプラグインは、スケジューリングポリシーにおけるPredicatesに相当するもので、Podの実行不可能なNodeをフィルターするために使用されます。もし全てのNodeがフィルターされてしまった場合、Podはunschedulableとしてマークされます。
postFilter
:これらのプラグインは、Podの実行可能なNodeが見つからなかった場合、設定された順序で呼び出されます。もしpostFilter
プラグインのいずれかが、Podを スケジュール可能 とマークした場合、残りのpostFilter
プラグインは呼び出されません。
preScore
: これは、スコアリング前の作業を行う際に使用できる情報提供のための拡張点です。
score
: これらのプラグインはフィルタリングフェーズを通過してきたそれぞれのNodeに対してスコア付けを行います。その後スケジューラーは、最も高い重み付きスコアの合計を持つノードを選択します。
reserve
: これは、指定されたPodのためにリソースが予約された際に、プラグインに通知する、情報提供のための拡張点です。また、プラグインはReserve
中に失敗した際、またはReserve
の後に呼び出されるUnreserve
も実装しています。
permit
: これらのプラグインではPodのバインディングを拒む、または遅延させることができます。
preBind
: これらのプラグインは、Podがバインドされる前に必要な処理を実行できます。
bind
: これらのプラグインはPodをNodeにバインドします。bind
プラグインは順番に呼び出され、1つのプラグインがバインドを完了すると、残りのプラグインはスキップされます。bind
プラグインは少なくとも1つは必要です。
postBind
: これは、Podがバインドされた後に呼び出される情報提供のための拡張点です。
multiPoint
: このフィールドは設定のみ可能で、プラグインが適用されるすべての拡張点に対して同時に有効化または無効化することができます。
次の例のように、それぞれの拡張点に対して、特定のデフォルトプラグイン を無効化、または自作のプラグインを有効化することができます。
apiVersion : kubescheduler.config.k8s.io/v1beta2
kind : KubeSchedulerConfiguration
profiles :
- plugins :
score :
disabled :
- name : PodTopologySpread
enabled :
- name : MyCustomPluginA
weight : 2
- name : MyCustomPluginB
weight : 1
disabled
配列のname
フィールドに*
を使用することで、その拡張点の全てのデフォルトプラグインを無効化できます。また、必要に応じてプラグインの順序を入れ替える場合にも使用されます。
Scheduling plugins
以下のプラグインはデフォルトで有効化されており、1つ以上の拡張点に実装されています。
また、コンポーネント設定のAPIにより、以下のプラグインを有効にすることができます。
デフォルトでは有効になっていません。
複数のプロファイル
kube-scheduler
は複数のプロファイルを実行するように設定することができます。
各プロファイルは関連するスケジューラー名を持ち、その拡張点 に異なるプラグインを設定することが可能です。
以下のサンプル設定では、スケジューラーは2つのプロファイルで実行されます。1つはデフォルトプラグインで、もう1つはすべてのスコアリングプラグインを無効にしたものです。
apiVersion : kubescheduler.config.k8s.io/v1beta2
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : default-scheduler
- schedulerName : no -scoring-scheduler
plugins :
preScore :
disabled :
- name : '*'
score :
disabled :
- name : '*'
特定のプロファイルに従ってスケジュールさせたいPodは、その.spec.schedulerName
に、対応するスケジューラー名を含めることができます。
デフォルトでは、スケジューラー名default-scheduler
としてプロファイルが生成されます。
このプロファイルは、上記のデフォルトプラグインを含みます。複数のプロファイルを宣言する場合は、それぞれユニークなスケジューラー名にする必要があります。
もしPodがスケジューラー名を指定しない場合、kube-apiserverはdefault-scheduler
を設定します。
従って、これらのPodをスケジュールするために、このスケジューラー名を持つプロファイルが存在する必要があります。
備考: Podのスケジューリングイベントには、ReportingControllerとして.spec.schedulerName
が設定されています。
リーダー選出のイベントには、リスト先頭のプロファイルのスケジューラー名が使用されます。
備考: すべてのプロファイルは、queueSort
拡張点で同じプラグインを使用し、同じ設定パラメーターを持つ必要があります (該当する場合)。これは、pending状態のPodキューがスケジューラーに1つしかないためです。
複数の拡張点に適用されるプラグイン
kubescheduler.config.k8s.io/v1beta3
からは、プロファイル設定にmultiPoint
というフィールドが追加され、複数の拡張点でプラグインを簡単に有効・無効化できるようになりました。
multiPoint
設定の目的は、カスタムプロファイルを使用する際に、ユーザーや管理者が必要とする設定を簡素化することです。
MyPlugin
というプラグインがあり、preScore
、score
、preFilter
、filter
拡張点を実装しているとします。
すべての利用可能な拡張点でMyPlugin
を有効化するためには、プロファイル設定は次のようにします。
apiVersion : kubescheduler.config.k8s.io/v1beta3
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : multipoint-scheduler
plugins :
multiPoint :
enabled :
- name : MyPlugin
これは以下のように、MyPlugin
を手動ですべての拡張ポイントに対して有効にすることと同じです。
apiVersion : kubescheduler.config.k8s.io/v1beta3
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : non-multipoint-scheduler
plugins :
preScore :
enabled :
- name : MyPlugin
score :
enabled :
- name : MyPlugin
preFilter :
enabled :
- name : MyPlugin
filter :
enabled :
- name : MyPlugin
multiPoint
を使用する利点の一つは、将来的にMyPlugin
が別の拡張点を実装した場合に、multiPoint
設定が自動的に新しい拡張点に対しても有効化されることです。
特定の拡張点は、その拡張点のdisabled
フィールドを使用して、MultiPoint
の展開から除外することができます。
これは、デフォルトのプラグインを無効にしたり、デフォルト以外のプラグインを無効にしたり、ワイルドカード('*'
)を使ってすべてのプラグインを無効にしたりする場合に有効です。
Score
とPreScore
を無効にするためには、次の例のようにします。
apiVersion : kubescheduler.config.k8s.io/v1beta3
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : non-multipoint-scheduler
plugins :
multiPoint :
enabled :
- name : 'MyPlugin'
preScore :
disabled :
- name : '*'
score :
disabled :
- name : '*'
v1beta3
では、MultiPoint
を通じて、内部的に全てのデフォルトプラグイン が有効化されています。
しかしながら、デフォルト値(並び順やスコアの重みなど)を柔軟に設定し直せるように、個別の拡張点は用意されています。
例えば、2つのスコアプラグインDefaultScore1
とDefaultScore2
に、重み1が設定されているとします。
その場合、次のように重さを変更し、並べ替えることができます。
apiVersion : kubescheduler.config.k8s.io/v1beta3
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : multipoint-scheduler
plugins :
score :
enabled :
- name : 'DefaultScore2'
weight : 5
この例では、MultiPoint
はデフォルトプラグインであるため、明示的にプラグイン名を指定する必要はありません。
そして、Score
に指定されているプラグインはDefaultScore2
のみです。
これは、特定の拡張点を通じて設定されたプラグインは、常にMultiPoint
プラグインよりも優先されるためです。つまり、この設定例では、結果的に2つのプラグインを両方指定することなく、並び替えが行えます。
MultiPoint
プラグインを設定する際の一般的な優先順位は、以下の通りです。
特定の拡張点が最初に実行され、その設定は他の場所で設定されたものよりも優先される
MultiPoint
を使用して、手動で設定したプラグインとその設定内容
デフォルトプラグインとそのデフォルト設定
上記の優先順位を示すために、次の例はこれらのプラグインをベースにします。
プラグイン
拡張点
DefaultQueueSort
QueueSort
CustomQueueSort
QueueSort
DefaultPlugin1
Score
, Filter
DefaultPlugin2
Score
CustomPlugin1
Score
, Filter
CustomPlugin2
Score
, Filter
これらのプラグインの有効な設定例は次の通りです。
apiVersion : kubescheduler.config.k8s.io/v1beta3
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : multipoint-scheduler
plugins :
multiPoint :
enabled :
- name : 'CustomQueueSort'
- name : 'CustomPlugin1'
weight : 3
- name : 'CustomPlugin2'
disabled :
- name : 'DefaultQueueSort'
filter :
disabled :
- name : 'DefaultPlugin1'
score :
enabled :
- name : 'DefaultPlugin2'
なお、特定の拡張点にMultiPoint
プラグインを再宣言しても、エラーにはなりません。
特定の拡張点が優先されるため、再宣言は無視されます(ログは記録されます)。
このサンプルは、ほとんどのコンフィグを一箇所にまとめるだけでなく、いくつかの工夫をしています。
カスタムのqueueSort
プラグインを有効にし、デフォルトのプラグインを無効にする。
CustomPlugin1
とCustomPlugin2
を有効にし、この拡張点のプラグイン内で、最初に実行されるようにする。
filter
拡張点でのみ、DefaultPlugin1
を無効にする。
score
拡張点でDefaultPlugin2
が最初に実行されるように並べ替える(カスタムプラグインより先に)。
v1beta3
以前のバージョンで、multiPoint
がない場合、上記の設定例は、次のものと同等になります。
apiVersion : kubescheduler.config.k8s.io/v1beta2
kind : KubeSchedulerConfiguration
profiles :
- schedulerName : multipoint-scheduler
plugins :
# デフォルトQueueSortプラグインを無効化
queueSort :
enabled :
- name : 'CustomQueueSort'
disabled :
- name : 'DefaultQueueSort'
# カスタムFilterプラグインを有効化
filter :
enabled :
- name : 'CustomPlugin1'
- name : 'CustomPlugin2'
- name : 'DefaultPlugin2'
disabled :
- name : 'DefaultPlugin1'
# カスタムScoreプラグインを有効化し、実行順を並べ替える
score :
enabled :
- name : 'DefaultPlugin2'
weight : 1
- name : 'DefaultPlugin1'
weight : 3
これは複雑な例ですが、MultiPoint
設定の柔軟性と、拡張点を設定する既存の方法とのシームレスな統合を実証しています。
スケジューラー設定の移行
v1beta2のバージョン
の設定では、新しいNodeResourcesFit
プラグインをスコア拡張点で使用できます。
この新しい拡張機能は、NodeResourcesLeastAllocated
、NodeResourcesMostAllocated
、 RequestedToCapacityRatio
プラグインの機能を組み合わせたものです。
例えば、以前はNodeResourcesMostAllocated
プラグインを使っていたなら、代わりにNodeResourcesFitプラグインを使用し(デフォルトで有効)、
pluginConfigに次のような
scoreStrategy`を追加することになるでしょう。
apiVersion : kubescheduler.config.k8s.io/v1beta2
kind : KubeSchedulerConfiguration
profiles :
- pluginConfig :
- args :
scoringStrategy :
resources :
- name : cpu
weight : 1
type : MostAllocated
name : NodeResourcesFit
スケジューラープラグインのNodeLabel
は廃止されました。代わりにNodeAffinity
プラグイン(デフォルトで有効)を使用することで同様の振る舞いを実現できます。
スケジューラープラグインのServiceAffinity
は廃止されました。代わりにInterPodAffinity
プラグイン(デフォルトで有効)を使用することで同様の振る舞いを実現できます。
スケジューラープラグインのNodePreferAvoidPods
は廃止されました。代わりにNode taints を使用することで同様の振る舞いを実現できます。
v1beta2で有効化されたプラグインは、そのプラグインのデフォルトの設定より優先されます。
スケジューラーのヘルスとメトリクスのバインドアドレスに設定されているhost
やport
が無効な場合、バリデーションに失敗します。
デフォルトで3つのプラグインの重みが増加しました。
InterPodAffinity
:1から2
NodeAffinity
:1から2
TaintToleration
:1から3
次の項目
10.2 - スケジューリングポリシー
バージョンv1.23より前のKubernetesでは、スケジューリングポリシーを使用して、predicates とpriorities の処理を指定することができました。例えば、kube-scheduler --policy-config-file <filename>
またはkube-scheduler --policy-configmap <ConfigMap>
を実行すると、スケジューリングポリシーを設定することが可能です。
このスケジューリングポリシーは、バージョンv1.23以降のKubernetesではサポートされていません。関連するフラグである、policy-config-file
、policy-configmap
、policy-configmap-namespace
、use-legacy-policy-config
も同様にサポートされていません。
代わりに、スケジューラー設定 を使用してください。
次の項目
11 - ツール
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
ファイルならびに分散されたアプリケーションバンドル の変換