LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@superbrothers(Kazuki Suda)

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

Last updated at Posted at 2025-09-22

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

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

  • kubectl autoscale --memory フラグ: すべての pods におけるターゲットのメモリ使用率。パーセント指定と MiB での指定が可能で、単位を省略した場合には MiB 単位として扱われる。
  • kubectl autoscale --cpu フラグ: --cpu-percent フラグの代替として追加。--memory フラグと同様にパーセントと milliCPU (Mi) での指定が可能で、単位を省略した場合には Mi 単位として扱われる。
  • kubectl top node/pod --show-swap フラグ: スワップメモリの情報を表示

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

  • --kuberc フラグ: kuberc ファイルのパス。KUBECTL_KUBERC=false か KUBERC=off の環境変数の設定で無効化できる

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

  • kubectl autoscale --cpu-percent フラグ: --cpu フラグが新たに追加され廃止予定になった

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

なし

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

所感

1.34 では .kuberc ファイルのベータ昇格と Kubernetes 向けの新しい YAML 方言である KYAML の提案という大きな変更があります。

.kuberc はベータに昇格しデフォルトで使用可能になりました。今後の機能提供でより便利になっていくことが期待できます。

KYAML は YAML 形式の微妙なところの使用を封印しつつ 100% 互換性ある新しい YAML 方言です。YAML 形式と 100% 互換性があることが重要で、既存の YAML 向けのツールやライブラリで引き続き処理できます。今後プロジェクトのドキュメントとサンプルコードをすべて置き換える計画もあり、KYAML 形式への変換ツールやリンタの提供を通じて今後 Kubernetes でのデファクトスタンダートになっていけるとよさそうです。

What's New (Major Themes)

アルファ: Kubernetes 用の YAML 方言である KYAML のサポートを追加しました

KYAML は、より安全性が高く曖昧性の少ない YAML サブセットとして設計されており、特に Kubernetes 向けに最適化されています。Kubernetes のどのバージョンを使用していても、Kubernetes v1.34 以降では kubectl の新しい出力形式として KYAML を利用できます。

KYAML は、YAML と JSON の両方が持つ特定の課題に対処しています。YAML の重要な特徴であるインデントとネスト構造の厳密な管理が必要な点や、オプションの文字列クォート機能によって予期しない型変換が発生する可能性（いわゆる「ノルウェーバグ」）などが挙げられます。一方、JSON にはコメント機能がなく、末尾のカンマやクォートされたキー名に関して厳格なルールが存在します。

KYAML で記述された設定ファイルは、どのバージョンの kubectl に対しても入力として渡すことが可能です。なぜなら、すべての KYAML ファイルは有効な YAML 形式としても解釈できるからです。kubectl v1.34 以降では、環境変数 KUBECTL_KYAML を true に設定することで、KYAML 形式の出力を直接要求できます（例：kubectl get -o kyaml ...）。必要に応じて、従来通り JSON 形式や YAML 形式での出力も指定可能です。

本プロジェクトは、SIG CLI が主導する KEP#5295 の一環として実施されました。

:pencil: KYAML の詳細は、ページ下部で解説しています。

kubectl ユーザ設定用 .kuberc ファイル

.kuberc 設定ファイルを使用すると、kubectl のデフォルトオプションやコマンドエイリアスなど、ユーザの好みを定義できます。kubeconfig ファイルとは異なり、.kuberc 設定ファイルにはクラスタの詳細やユーザ名、パスワードなどの情報は含まれません。
この機能は v1.33 でアルファ版として導入され、環境変数 KUBECTL_KUBERC によって制御されていました。v1.34 でベータ版に移行し、現在はデフォルトで有効化されています。

この機能の実装は、SIG CLI が主導する KEP #3104 の一環として行われました。

:pencil: kuberc の詳細は Kubernetes 1.33: SIG-CLI (kubectl) の変更内容 #kubernetes - Qiita で解説しています。

Urgent Upgrade Notes

なし

Changes by Kind

Deprecation

なし

API Change

  • kubeconfig 内の preferences フィールドを非推奨とし、代わりに kuberc を使用するように変更しました (#131741, soltysh) [SIG API Machinery, CLI, Cluster Lifecycle and Testing]
  • kubectl: kuberc サポートをベータ版として正式リリースしました。kuberc 設定ファイルを使用することで、kubectl の動作をカスタマイズできるようになりました（これはクラスタアクセスを設定する kubeconfig とは機能が異なります） (#131818, soltysh) [SIG CLI and Testing]

Feature

  • kubectl describe service の出力に Trafic Distribution の情報を表示するフィールドを追加しました (#131491, tchap) [SIG CLI]
  • kubectl top サブコマンドに --show-swap オプションを追加しました (#129458, iholder101) [SIG CLI]
    • :pencil: pod と node の両方で追加されてます
  • kubectl version コマンドにクライアント/サーバのバージョン不一致が公式サポート範囲外かどうかを判定するフラグを追加しました (#127365, omerap12)
    • :pencil: 実際にはフラグは追加されておらず既存の --warnings-as-errors フラグを流用しています
  • kubectl api-resources コマンドに機械可読な出力形式オプション（JSON および YAML）を追加しました (#132604, dharmit) [SIG Apps, CLI and Network]
    • :pencil: --output フラグのサポートに k8s.io/cli-runtime/pkg/printers を使っているので --show-managed-fields フラグも追加されてしまっているが、managed-fields は存在しないのでこれは除いたほうがよさそう
    • :pencil: 実際の出力は下記の感じ 
      apiVersion: v1
groupVersion: ""
kind: APIResourceList
resources:
- kind: ConfigMap
name: configmaps
namespaced: true
shortNames:
- cm
singularName: configmap
verbs:
- create
- delete
- deletecollection
- get
- list
- patch
- update
- watch
version: v1
...
  • kubectl autoscale コマンドに --cpu および --memory フラグのサポートを追加し、--cpu-precent オプションの使用を非推奨としました (#129373, googs1025)
    • :pencil: 下記のように指定できるようになった 
      # Auto scale a deployment "bar", with the number of pods between 3 and 6, target average CPU of 500m and memory of 200Mi
kubectl autoscale deployment bar --min=3 --max=6 --cpu=500m --memory=200Mi

# Auto scale a deployment "bar", with the number of pods between 2 and 8, target CPU utilization 60% and memory utilization 70%
kubectl autoscale deployment bar --min=3 --max=6 --cpu=60% --memory=70%`))
  • 新しい kubectl 出力形式 kyaml をサポートしました。KYAML は YAML の厳密なサブセットであり、あらゆる YAML 処理ツールで正しく解釈可能です。KYAML のフォーマットは JSON と YAML の中間的なスタイルで、デフォルトの YAML スタイルよりも明示的であるため、エラーが発生しにくいという特徴があります (#132942, thockin) [SIG API Machinery, Architecture, Auth, CLI, Cloud Provider, Cluster Lifecycle, Contributor Experience, Instrumentation, Network, Node, Scheduling, Storage and Testing]
    • :pencil: KYAML の詳細はページ下部で説明しています
  • サービスの作成時やポートの用途を解析する際の処理負荷を軽減しました。特に Helm チャートを使用してデプロイされた外部リソースに対して有効です (#133018, rushmash91)
    • :pencil: kubectl describe po コマンドで port 名が含まれるようになってます（例: Ports: 80/TCP (http), 443/TCP (https)
  • kuberc ファイルで定義されたエイリアスに対する補完機能を有効にしました (#131586, ardaguclu)
  • kubectl delete コマンドの出力に名前空間情報を含めるようにし、リソースの識別性を向上させました (#126619, totegamma)
    • :pencil: kubectl delete -f で複数の namespace のオブジェクトを削除するときにとくに便利そう
    • :pencil: 実際の出力 
      $ kubectl delete svc kubernetes -n default
service "kubernetes" deleted from default namespace

Bug or Regression

  • --ignore-not-found フラグのヘルプメッセージを明確化しました。watch 操作において --ignore-not-found オプションをサポートしました (#132542, gemmahou)
    • :pencil: kubectl get コマンドのフラグで、指定のオブジェクトが存在していない場合も終了コードを0にするものですが、リストに対しては機能しないことが明確になるようにヘルプメッセージが変更されてます
    • :pencil: 
      # before
If the requested object does not exist the command will return exit code 0.

# after
If set to true, suppresses NotFound error for object(s) that do not exist and returns exit code 0. Using this flag with commands that query for collections of resources has no effect on the exit code.
  • kubectl のリビジョン履歴に関連するパニック問題を修正しました (#130503, tahacodes) [SIG CLI]
    • :pencil: kubectl rollout history コマンドで --revision フラグで指定されたリビジョンが存在しないときに nil に対して処理してしまい panic になっていたようです

Other (Cleanup or Flake)

  • kubectl attach コマンドに警告を追加しました。この Pod の log サブリソースを通じてコマンド実行結果を確認できることをユーザーに通知するものです。 (#127183, mochizuki875) [SIG Auth, CLI, Node and Security]
    • :pencil: kubectl attach/exec コマンドを通じて pod で実行されたコマンドは kubectl logs コマンドで確認できる。これはログが集約されている場合に記録されてしまうので、それに対して警告したいという要望から
    • :pencil: 追加されたメッセージ 
      All commands and output from this session will be recorded in container logs, including credentials and sensitive information passed through the command prompt.
  • Kubectl interactive delete: 空の改行入力を「N」（拒否）として扱うようにしました (#132251, ardaguclu) [SIG CLI]
  • kubectl kustomize の機能を https://github.com/kubernetes-sigs/kustomize/releases/tag/kustomize%2Fv5.7.0 で説明されている内容に沿ってアップグレードしました (#132593, koba1t)
    • :pencil: 最終的に kustomize 5.7.1 に更新されたようです

新しい kubectl 出力形式 kyaml をサポートしました

KEP: KEP-5295: Introducing KYAML, a safer, less ambiguous YAML subset / encoding

マニフェストの記述には通常 YAML 形式が使用されますが、Kubernetes を利用されている多くの方は、YAML 特有の落とし穴に遭遇したことがあるのではないでしょうか。

  • インデントの問題: YAML では空白文字に意味があるため、ネストの深さを正確に管理する必要があります。これが非常に難しく、インデントが不適切だと正しく動作しません。特に Helm のようなテンプレートシステムでは、YAML の文脈外でインデントを正確に調整する必要があり、これが大きな課題となっています。
  • 型推論の問題: YAML では文字列の引用符を省略可能ですが、これが原因となって予期しない型に変換されてしまうケースがあります。例えば、「NO」や「YES」が bool 値として解釈されたり、特定の数字や時刻を表す文字列が数値として扱われるといった問題が発生します。
  • JSON の代替としての欠点: Kubernetes では JSON もサポートされていますが、JSON にはコメントを記述できないという重大な欠点があります。設定ファイルにおいてコメントは非常に有用であるため、この点が大きなデメリットとなります。
  • YAML 自体の複雑さ: YAML は非常に広範な仕様を持っており、その中でエラーを起こしやすい書き方が広く用いられています。よりシンプルでエラーの少ない書き方（方言）をツールやドキュメントで推進することで、これらの問題を軽減できる可能性があります。

この KEP では、上記の課題を解決するため、既存のパーサやツールと 100% 互換性を保ちつつ、YAML のサブセットである "KYAML" が提案されています。1.34 リリースでは、--output フラグを使用してオブジェクトを KYAML 形式で出力するオプションが追加されました。1.34 時点ではアルファサポート段階であり、使用には環境変数 KUBECTL_KYAML=true の設定が必要です。

最終的な目標として、プロジェクト全体のサンプルコードとドキュメントを KYAML に置き換えることが計画されています。また、KYAML へのエンコードおよび変換を行うライブラリやツールの提供も予定されています。

KYAML のサンプル

$ kubectl get -o kyaml svc hostnames
---
{
  apiVersion: "v1",
  kind: "Service",
  metadata: {
    creationTimestamp: "2025-05-09T21:14:40Z",
    labels: {
      app: "hostnames",
    },
    name: "hostnames",
    namespace: "default",
    resourceVersion: "37697",
    uid: "7aad616c-1686-4231-b32e-5ec68a738bba",
  },
  spec: {
    clusterIP: "10.0.162.160",
    clusterIPs: [
      "10.0.162.160",
    ],
    internalTrafficPolicy: "Cluster",
    ipFamilies: [
      "IPv4",
    ],
    ipFamilyPolicy: "SingleStack",
    ports: [{
      port: 80,
      protocol: "TCP",
      targetPort: 9376,
    }],
    selector: {
      app: "hostnames",
    },
    sessionAffinity: "None",
    type: "ClusterIP",
  },
  status: {
    loadBalancer: {},
  },
}

KYAML の主な仕様

  • 値文字列は常に二重引用符で囲みます（「NO」のような曖昧さを排除するため）
  • 引用符で囲まれていないキー（安全でない場合は引用符で囲まれる。no など）
  • 構造体とマップは必ず {} を使用する（マッピング値に関する曖昧なエラーを避ける）
  • リストには [] を常に使用します（ハイフンが意味を変えるかどうかを判断する必要がなくなる）

この仕様は JSON 形式と非常によく似ていますが、実際その通りで、JSON は有効な YAML 形式でもあります。JSON とは異なり、KYAML には以下のような特徴があります。

  • コメント記述を許可
  • リストや構造体/マップの最後の項目に末尾カンマを許可
  • キーの引用符が不要
  • 複数ドキュメント

詳細な仕様については、KEP のドキュメントを参照してください。

Q. なぜ HJSON や JSONC、JSON5 を採用しないのか

すでに存在する優れた形式を採用することも可能でしたが、KEP では以下の問題点が指摘されています。

  1. いずれかの1つを選択する必要がある
  2. 新しい依存関係が生まれる
    • KYAML は sigs.k8s.io/yaml の新しいパッケージとして追加される
  3. 異なる文法を学ぶ必要がある

重要な要件の1つであるエコシステムとのシームレスな互換性において、KYAML は既存のツールで問題なく解析可能であり（完全な有効な YAML 形式であるため）、新しいパーサや更新されたパーサに切り替える必要がありません。つまり、YAML 向けの yq ツールで KYAML 形式の操作が問題なく行えるということです。

$ KUBECTL_KYAML=true kubectl get -n default svc kubernetes -o kyaml | yq '.spec'
{clusterIP: "10.96.0.1", clusterIPs: ["10.96.0.1"], internalTrafficPolicy: "Cluster", ipFamilies: ["IPv4"], ipFamilyPolicy: "SingleStack", ports: [{name: "https", port: 443, protocol: "TCP", targetPort: 6443}], sessionAffinity: "None", type: "ClusterIP"}
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?