Yasuhiro ABE, The University of Aizu. | 準備作業 (kubectlコマンド)

kubectlコマンドはKubernetesクラスターを操作するための唯一のコマンドです。

このコマンドを使うための準備作業について説明します。

1. kubecamp.u-aizu.ac.jpを利用する場合

1.1. 既に利用したことがある場合

既にファイルを配置している場合にはID Tokenの内容(1行)をコピーし、既存の設定ファイルの下から3行目付近にあるid-token: の右辺と置き換えてください。

そうでない場合には、表示された設定ファイルのテキストを~/.kube/configファイルにコピーしてください。

1.2. 詳細情報

詳細は https://kubecamp.u-aizu.ac.jp/signup/docs/ja/index.html#kubectlを参照してください。

2. inovtst9.u-aizu.ac.jpを利用する場合

AY2024からinovtst9.u-aizu.ac.jpでもKubeCampと同様の方法でユーザーの設定を行っています。

Dashboardは準備していませんので、configファイルのテンプレートを利用してください。

方法については以下から詳しく説明します。

2.1. 既に利用したことがある場合

既に一度準備作業が完了している場合には、次の手順をヒントに準備作業を進めてください。手順の内容がよく分からない場合には、下記の該当するセクションを参照してください。

https://opm00h.u-aizu.ac.jp/dexc にアクセスし、ID Token を取得してください。
次に、emacs, nano, vimなどのエディタを起動し、~/.kube/config ファイルの下記、2行の情報を最新の ID Token の値に更新します。

        id-token:

Note: Token情報をコロン(:)の次には空白が1文字分必要である点に注意すること

ファイルの編集が完了したら、次のコマンドを実行し、稼動確認を行ないます。

$ kubectl get node

なお、kubectl version コマンドでも、サーバーとの接続を確認することは可能です。

成功すると次のように表示されます。

NAME       STATUS   ROLES           AGE      VERSION
u109ls01   Ready    control-plane   2y358d   v1.30.4
u109ls02   Ready    control-plane   2y358d   v1.30.4
u109ls03   Ready    <none>          2y358d   v1.30.4
u109ls04   Ready    <none>          2y358d   v1.30.4

configファイルの設定に失敗する場合のメッセージについては、kubectlコマンド実行時によくあるエラーを参照してください。

Emacs上で、古いid-tokenを削除する作業では、該当箇所を囲んで(先頭での C-Space 実行後、行末まで移動)から、C-w を実行しています。

[ View on the Asciinema Site ]

2.2. 参考情報

以下の説明する内容の背景や詳細を理解したい場合は、次のURL先を確認してください。

Dexを利用したOIDCによるkubectlコマンドの管理 (ID Tokenによってkubectlコマンドを利用可能にする方法の詳細な説明)
kubernetes.io::install kubectl on linux (kubectlコマンドの取得方法)
Wikipedia::Json Web Token (JSON Web Token (JWT)の概要説明)
jwt.io (JWTの公式Web)

2.3. kubectlコマンドを使うための準備

kubectlコマンドはkubernetes(k8s)クラスターを操作するためのクライアントです。このSCCPで操作するk8sは、OIDC認証を有効にしているため、操作にはAINS IDでの認証が必須です。

ここで説明する方法の有効期間は24時間(86400秒)です。 k8sを使う場合には、毎週のSCCPの都度必要になるので、このページを参照して準備をしてください。

2.4. OIDC ProviderからのJWT情報の入手

Json Web Tokenは署名付きのユーザー情報(トークン)の仕様です。

このSCCPの環境では試験的に提供している次のサービスにAINS-IDでログインすることで、JWTを生成します。

https://opm00h.u-aizu.ac.jp/dexc

2.4.1. 最初の画面

まずExtra scopesに groups と入力されていることを確認してください。 Loginボタンを押下し、次ページに進みます。

2.4.2. Login画面

ここではAINSのIDとパスワードを入力します。

2.4.3. Grant Access画面

緑色の"Grant Access"ボタンを押下します。

2.4.4. 最終画面

画面にID Token の情報が出力されます。 groupsの内容から自分がどのようなメーリングリストに登録されているのか分かります。

この ID Token の情報を利用して、~/.kube/configファイルを準備するのでWebブラウザの画面は閉じないでください。

kubecamp.u-aizu.ac.jpにログインする場合には赤枠で囲まれた設定ファイルの内容を~/.kube/configに配置してください。

2.5. 【初回のみ】JWTの情報から~/.kube/configファイルの作成

この手順は ~/.kube/config が存在していない初回のみ行ないます。

configファイルのテンプレートは以下の場所にあります。

configファイル (192.168.100.51クラスタ用)

kubectlコマンドが導入されている作業用ThinkPad等で、ID Token を利用して次のようなファイル~/.kube/configを作成します。

$ mkdir -p ~/.kube
$ cd ~/.kube
$ wget -Oconfig https://web-int.u-aizu.ac.jp/%7Eyasu-abe/ja/sccp/manual/setupk8s.config-192.168.100.51.txt

~/.kube/config ファイルが準備できたら、エディタなどで"s12xxxxxx"となっている部分("user:", "name:"(x2), "current-context:", 計4箇所)を自分のAINS-IDの情報に書き換えて、"id-token"の値に、OIDC Providerから入手した ID Token を入力します。

2.6. 毎回、必要な作業について

既に ~/.kube/config は作成済みのため、改めてダウンロードする必要はありません。しかし、ID Tokenは、JWTの中に含まれる "exp:" の項目にある86400秒(24時間)で期限が切れます。

次回以降も https://opm00h.u-aizu.ac.jp/dexc にアクセスし、ID Token を入手して、書き換えてからkubectlコマンドを利用してください。

3. 稼動確認

kubectlコマンドを以下のように実行します。

$ kubectl -v=8 get node

結果は次のようになります。

I0909 22:01:15.829029   23452 loader.go:395] Config loaded from file:  /home/yasu/.kube/config.inovtst9
I0909 22:01:15.834818   23452 round_trippers.go:463] GET https://inovtst9.u-aizu.ac.jp:6443/api/v1/nodes?limit=500
I0909 22:01:15.834849   23452 round_trippers.go:469] Request Headers:
I0909 22:01:15.834856   23452 round_trippers.go:473]     Accept: application/json;as=Table;v=v1;g=meta.k8s.io,application/json;as=Table;v=v1bet
a1;g=meta.k8s.io,application/json
I0909 22:01:15.834863   23452 round_trippers.go:473]     User-Agent: kubectl/v1.30.4 (linux/amd64) kubernetes/a51b3b7
I0909 22:01:16.104847   23452 round_trippers.go:574] Response Status: 200 OK in 269 milliseconds
I0909 22:01:16.104934   23452 round_trippers.go:577] Response Headers:
I0909 22:01:16.104957   23452 round_trippers.go:580]     Audit-Id: 11adc20d-db06-49c4-aa43-2defab9c63f0
I0909 22:01:16.104979   23452 round_trippers.go:580]     Cache-Control: no-cache, private
I0909 22:01:16.104991   23452 round_trippers.go:580]     Content-Type: application/json
I0909 22:01:16.105005   23452 round_trippers.go:580]     X-Kubernetes-Pf-Flowschema-Uid: f4b25b5a-17c2-4d04-8328-ccdf93bfaa7b
I0909 22:01:16.105024   23452 round_trippers.go:580]     X-Kubernetes-Pf-Prioritylevel-Uid: 4b38613e-0027-4522-8106-69dac0750cfe
I0909 22:01:16.105049   23452 round_trippers.go:580]     Date: Mon, 09 Sep 2024 13:01:18 GMT
I0909 22:01:16.397039   23452 request.go:1212] Response Body: {"kind":"Table","apiVersion":"meta.k8s.io/v1","metadata":{"resourceVersion":"3591
84485"},"columnDefinitions":[{"name":"Name","type":"string","format":"name","description":"Name must be unique within a namespace. Is required
when creating resources, although some resources may allow a client to request the generation of an appropriate name automatically. Name is pri
marily intended for creation idempotence and configuration definition. Cannot be updated. More info: https://kubernetes.io/docs/concepts/overvi
ew/working-with-objects/names#names","priority":0},{"name":"Status","type":"string","format":"","description":"The status of the node","priorit
y":0},{"name":"Roles","type":"string","format":"","description":"The roles of the node","priority":0},{"name":"Age","type":"string","format":""
,"description":"CreationTimestamp is a timestamp representing the server time when this object was created. It is not guaranteed to be set in h
appens-before order across separate operations. Clients may not set this value. It is [truncated 19065 chars]
NAME       STATUS   ROLES           AGE     VERSION
u109ls01   Ready    control-plane   3y11d   v1.30.4
u109ls02   Ready    control-plane   3y11d   v1.30.4
u109ls03   Ready    <none>          3y11d   v1.30.4
u109ls04   Ready    <none>          3y11d   v1.30.4

4台のホスト名が表示されれば正常に稼動しています。

4. apply/create/delete操作で気をつける点

自分のIDと同じnamespace内でだけ、操作が可能です。システム全体や、他の人の設定を変更する心配はないので、自由に試してください。

namespaceを指定しなかったり(※)、他のnamespaceを指定した場合には次のようなエラーが表示されます。

(※: namespaceを指定しない場合は、"-n default" が指定されたものとして動きます)

$ kubectl apply -f https://kubernetes.io/examples/service/load-balancer-example.yaml
Error from server (Forbidden): error when creating "https://kubernetes.io/examples/service/load-balancer-example.yaml": deployments.apps is forbidden: User "yasu-abe@u-aizu.ac.jp" cannot create resource "deployments" in API group "apps" in the namespace "default"

4.1. namespaceの指定を省略するために

毎回、kubectl -n <namespace>とnamespaceを指定するのは面倒です。 bashやzshを利用する場合、aliasやfunctionを設定して手間を削減してください。

k8s.envrc.txt (Download)

## ~/k8s.envrc file
alias kubectl="kubectl -n $(id -un)"
alias kc=kubectl
alias kcg="kc get"
alias kcga="kcg all"
alias kcgns="kcg ns"
alias kcd="kc describe"
alias kcang="kcan get"

function kcan {
  kc "$@" --all-namespaces
}

function chkc {
  alias kubectl="kubectl -n $1"
}

k8s.envrcファイル内では、namespaceの代りに "$(id -un)" を指定しています。
これは、**id -un**コマンドの出力に置き換わります。"id -un"コマンドは、ユーザー名を返します。

例えばホームディレクトリにk8s.envrcファイルを準備した場合は、毎回ログインする度に次の操作で、設定を反映させます。

$ . ~/k8s.envrc

直接、~/.bashrc や ~/.zshrc などの設定ファイルに同じ内容を書き込んでも問題ありません。

5. 【上級者向け解説】許可されている権限と確認方法

権限にはシステム全体レベルでの設定(ClusterRoleBinding)と、個別のNamespace毎の設定(RoleBinding)の2種類があります。

5.1. ClusterRoleBinding

システム全体の権限設定では、このSCCPのメンバーが、k8sシステムの内部を観察できるように、ClusterRole dex-adminを作成しています。

以下の設定では、多くのリソースに対してユーザーにget/list/watchコマンドを許可しています。

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: dex-admin
rules:
- apiGroups:
  - '*'
  resources:
  - clusterroles
  - cronjobs
  - customresourcedefinitions
  - daemonsets
  - deployments
  - horizontalpodautoscalers
  - ingresses
  - jobs
  - namespaces
  - nodes
  - persistentvolumeclaims
  - persistentvolumes
  - pods
  - replicasets
  - replicationcontrollers
  - roles
  - services
  - statefulsets
  - storageclasses
  verbs: ["get", "list", "watch"]
- nonResourceURLs:
  - '*'
  verbs: ["get", "list", "watch"]

次に、このdex-admin権限を、SCCPのメーリングリストに参加しているユーザーに付与する設定を行なっています。

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin:12-4009-OT03-001-sem10
subjects:
- kind: Group
  name: 12-4009-OT03-001-sem10@course
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: dex-admin
  apiGroup: rbac.authorization.k8s.io

kubectlコマンドで確認する場合は、次のようにしてください。

$ kubectl get ClusterRole dex-admin
$ kubectl get ClusterRoleBinding | grep ^admin
## 例： 表示された名前から一つを選択して引数に指定します。
$ kubectl get ClusterRoleBinding admin:12-4009-OT03-001-sem10

5.2. RoleBinding

もう一つの権限は、SCCP参加者のAINS ID名と同じ名称のnamespaceを作成したものについてです。単純にIDと同じ名前のnamespaceを作成しても権限は何も付与されていません。

まずUser名と同じnamespaceを作成して、次にRoleを作成しています。

RoleBindingで、AINS ID(User)とnamespace(Role)を紐付けています。個別に、["create", "patch", "delete", "get", "watch", "list"]の操作を許可しています。

この操作を参加者分、半自動で実行できるよう簡単な仕組みを作成しています。

---
apiVersion: v1
kind: Namespace
metadata:
  name: yasu-abe
  labels:
    name: yasu-abe
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: yasu-abe
  name: sccp-user
rules:
- apiGroups: ["*"] # "" indicates the core API group
  resources: ["*"]
  verbs: ["create", "patch", "delete", "get", "watch", "list"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: sccp-user
  namespace: yasu-abe
subjects:
- kind: User
  name: yasu-abe@u-aizu.ac.jp
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: sccp-user
  apiGroup: rbac.authorization.k8s.io

これらはRoleとRoleBindingから構成されていて、kubectlコマンドからは次のコマンドで確認することができます。

$ kubectl get -n $(id -un) role sccp-user -o yaml
$ kubectl get -n $(id -un) rolebinding sccp-user -o yaml

この設定のとおり、namespace自身を含めてあらゆる要素の削除(delete)を許可しています。自身のnamespaceは削除できますが、作成はシステム管理者権限が必要です。

つまり自分で消すことはできても、再作成することはできません。自身のnamespaceの削除を試しても構いませんが、再作成するので連絡をお願いします。