Kubernetes 1.33: SIG-CLI (kubectl) の変更内容

ここでは、Kubernetes 1.33 の CHANGELOG から SIG-CLI (kubectl) の取り組みについてまとめています。:memo: は筆者によるコメントです。

- https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.33.md
- [Kubernetes v1\.33: Octarine \| Kubernetes](https://kubernetes.io/blog/2025/04/23/kubernetes-v1-33-release/k8s-1.33.svg)

**新たに追加されたコマンドとフラグ**

なし

**変更があったコマンドとフラグ**

- `kubectl wait --for=create`: ラベルセレクタとの使用で実行が直ちに終了してしまっていたのが修正されました

**廃止予定のコマンドとフラグ**

なし

**削除されたコマンドとフラグ**

- `kubectl explain -o`: `--output` の短縮フラグが削除されました？
    - :memo: https://github.com/kubernetes/kubernetes/pull/129784 で誤って落とされてしまったようにみえる
    - :memo: もとに戻す修正の PR を作成しておきました https://github.com/kubernetes/kubernetes/pull/131962

そのほか、細かい変更は、 https://github.com/superbrothers/kubernetes-docs/compare/kubernetes-1.32...kubernetes-1.33 で参照できます。

## 所感

久々に大きな変更として `kubectl` のユーザ設定を分離した `kuberc` の追加がありました。今後の機能拡張も期待できそうです。ページ下部で詳細を紹介しています。

## What's New (Major Themes)

なし

## Urgent Upgrade Notes

なし

## Changes by Kind

### Deprecation

なし

### API Change

- kubectl: `kubeconfig` とは別の `kuberc` ファイルからの環境設定を使用して kubectl の動作をカスタマイズできるアルファ版のサポートが追加されました ([#125230](https://github.com/kubernetes/kubernetes/pull/125230), [ardaguclu](https://github.com/ardaguclu)) [SIG API Machinery, CLI and Testing]
    - :memo: 期待の新機能です。下で詳しく機能を紹介します。

### Feature

- kubectl debug コマンドでリソースの補完が追加されました ([#130033](https://github.com/kubernetes/kubernetes/pull/130033), [ardaguclu](https://github.com/ardaguclu)) [SIG CLI]
- kubectl `--subresource` フラグが安定版に昇格しました ([#130238](https://github.com/kubernetes/kubernetes/pull/130238), [soltysh](https://github.com/soltysh))
- `kubectl autoscale` サブコマンドで `autoscaling/v1` API ではなく `autoscaling/v2` を使用するように変更されました。このコマンドはまず最初に `autoscaling/v2` API の使用を試みます。もし `autoscaling/v2` API を使用できない、またはエラーが発生した場合は `autoscaling/v1` API にフォールバックします ([#128950](https://github.com/kubernetes/kubernetes/pull/128950), [googs1025](https://github.com/googs1025)) [SIG Autoscaling and CLI]

### Documentation

- `kubectl` の `-l` / `--selector` コマンドラインオプションに集合ベース (set-based) 要件の例が追加されました ([#129106](https://github.com/kubernetes/kubernetes/pull/129106), [rotsix](https://github.com/rotsix))
    - :memo: 集合ベースの要件とは `in/notin/exists` のオペレータを使用したラベルセレクタです (e.g. `environment in (production, qa)`
        - https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement
    - :memo: `=/==/!=` のオペレータを使用したラベルセレクタは等価ベース (equality-based) の要件といいます
        - https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#equality-based-requirement

### Bug or Regression

- ラベルセレクタでの `kubectl wait --for=create` の動作を修正し、ラベルが一致するリソースが表示されるのを適切に待つようになりました ([#128662](https://github.com/kubernetes/kubernetes/pull/128662), [omerap12](https://github.com/omerap12)) [SIG CLI and Testing]
    - :memo: `error: no matching resources found` で実行が直ちに終了してしまっていたのが修正されました
- WebSockets HTTPS サポートが入りました ([#129872](https://github.com/kubernetes/kubernetes/pull/129872), [seans3](https://github.com/seans3)) [SIG API Machinery, Architecture, Auth, CLI, Cloud Provider, Instrumentation, Network and Node]
    - :memo: クラスタへの接続に HTTPS プロキシを使用していた場合に正しく機能してしなかったようです ([Organizing Cluster Access Using kubeconfig Files \| Kubernetes](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/#proxy))
- [kubectl] projected volume sources の describe 出力を改善し、Secret と ConfigMap のエントリがオプショナルかどうかを明示的に示すようになりました ([#129457](https://github.com/kubernetes/kubernetes/pull/129457), [gshaibi](https://github.com/gshaibi)) [SIG CLI]

### Other (Cleanup or Flake)

- 対象 Pod の `.Spec.SecurityContext.RunAsUser` フィールドに非 root ユーザが指定されている場合にデバッグプロファイルによって付与されたデバッグコンテナの能力 (capabilities) が期待どおりに動作しない可能性があることをユーザに通知する警告メッセージが表示されるようになりました ([#127696](https://github.com/kubernetes/kubernetes/pull/127696), [mochizuki875](https://github.com/mochizuki875)) [SIG CLI and Testing]
    - :memo: 条件を満たす場合に次のメッセージが表示されます  
        ```
        Warning: Non-root user is configured for the entire target Pod, and some capabilities granted by debug profile may not work. Please consider using "--custom" with a custom profile that specifies "securityContext.runAsUser: 0".
        ```
    - :memo: 例えばデバッグプロファイルに `sysadmin` を指定していた場合にはコンテナレベルで `securityContext.privileged=true` のエフェメラルコンテナが追加されますが、Pod レベルで非 root での実行が指定されていると期待した権限が付与されずに期待したデバッグコマンドが実行できない事態になります

## ⚡ kubectl の動作をカスタマイズできる `kuberc` ファイル (アルファ機能)

Kubernetes 1.33 で kubectl の動作をカスタマイズできる新しい設定ファイルである `kuberc` がアルファレベルで追加されました。
クラスタの接続情報を持つ `kubeconfig` ファイルにはすでにユーザ設定機能が実はあります[^1]。しかし、`kubeconfig` ファイルは接続するクラスタを切り替えるために `--kubeconfig` オプションで別のものを指定したりするため、ここにユーザ設定を入れておくことは適切ではありませんでした。クラスタ接続に必要なクレデンシャルデータが含まれるため、ユーザ設定を他の人と共有しにくい問題もあります。

[^1]: https://kubernetes.io/docs/reference/config-api/kubeconfig.v1/#Preferences

そこで、ユーザ設定のみを持つ新しい設定ファイルとして `kuberc` ファイルが導入されました。加えてユーザ設定の分離のみならず新たに kubectl の動作をカスタマイズできる機能が追加されています。

### `kuberc` ファイルの使い方

#### kubectl の設定

`kuberc` は Kubernetes 1.33 でアルファレベルで導入されました。そのため v1.33.0 以上の `kubectl` ツールとアルファレベルのため明示的に機能を有効にするために環境変数 `KUBECTL_KUBERC=true` の設定が必要です。

```
$ kubectl version --client
Client Version: v1.33.1
Kustomize Version: v5.6.0
$ export KUBECTL_KUBERC=true
```

環境変数は `.bashrc` や  `.zshrc` など、使用するシェル設定で起動時に設定されるようにしましょう。

#### kuberc ファイル

`kuberc` ファイルはデフォルトでは `~/.kube/kuberc` が使われます。`KUBERC` 環境変数または `kubectl --kuberc` フラグで明示的に指定もできます。

```
$ kubectl options | grep -A 1 -- --kuberc
    --kuberc='':
        Path to the kuberc file to use for preferences. This can be disabled by exporting KUBECTL_KUBERC=false.
```

### kuberc の機能: コマンドエイリアスとデフォルトフラグの上書き

`kuberc` ファイルでは下記の2つの新機能が使用できます。

- `aliases`: コマンドと引数、フラグを指定したエイリアスコマンドの定義
    - ビルドイン、エイリアス、プラグインの順で優先される
- `overrides`: コマンドのデフォルトのフラグの上書き
    - 上書きしたフラグはインライン指定で上書きされる

`kuberc` ファイルの構造は次のとおりです（KEP にあるサンプルです）。

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
kind: Preference

aliases:
- name: getdbprod
  command: get
  # 引数の先頭に追加するオプションです。後ろに追加する appendArgs フィールドもあります
  prependArgs:
  - pods
  flags:
  - name: selector
    default: what=database
  - name: namespace
    default: us-2-production

overrides:
- command: apply
  flags:
  - name: server-side
    default: "true"
- command: delete
  flags:
  - name: interactive
    default: "true"
```

---

`kubectl apply` でデフォルトで Server Side Apply (SSA) を有効にするのは便利ですね。こういった形でフラグのデフォルト値を上書きできます。

drain で必ず追加するオプションもデフォルトになっていてもよさそうです。

```yaml
overrides:
- command: drain
  flags:
  - name: ignore-daemonsets
    default: "true"
  - name: delete-emptydir-data
  - default: "true"
```

一方でオペレーションのログを記録することを考えると前提が人によって変わってしまうのは問題にもなりえそうです。コマンド実行時にどのフラグが上書きされているか表示してくれてもよいかもしれません。
好みがありそうですが、これ自体も `kuberc` で挙動を変更できるので、新しい機能もより気軽に追加できるようになりそうです。

そのほかにも GitOps ツールの Flux を使用している場合、[SSA managedFields 問題](https://speakerdeck.com/superbrothers/wakaru-metadata-dot-managedfields)も下記のようにデフォルトで Flux が適用したと思わせるようにしておくとハッピーになれます。

```yaml
overrides:
- command: apply
  flags:
  - name: server-side
    default: "true"
  - name: field-manager
    default: kustomize-controller
```

エイリアスコマンドはオプションの値に追加の引数を使えるようになると便利そうな予感があります。
例えば次のように特定のノード上の pods をリストするなどできるとうれしそうです。

```yaml
- name: gpn
  command: get
  prependArgs:
  - pods
  flags:
  - name: --all-namespaces
    default: "true"
  - name: --field-selector
    default: spec.nodeName=$1 # v1.33 時点では追加引数をフラグの値の一部としては使用できず
```

今後の機能追加に期待です。

### 参考

- [KEP-3104: Introduce kuberc](https://github.com/kubernetes/enhancements/blob/master/keps/sig-cli/3104-introduce-kuberc/README.md)