[KEP-3104] Kuberc beta #51351

soltysh · 2025-06-23T10:15:06Z

Description

Promote kuberc to beta

Issue

KEP: kubernetes/enhancements#3104

/assign @ardaguclu
for sig-cli review

The generated changes are coming from kubernetes-sigs/reference-docs#396

netlify · 2025-06-23T10:15:12Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`134e80c`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/6888b2d3a7ee230008f36dbe

netlify · 2025-06-23T10:24:50Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`134e80c`
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/6888b2d3bc391900084d55b9
😎 Deploy Preview	https://deploy-preview-51351--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

ardaguclu · 2025-06-30T05:52:36Z

/lgtm
from sig-cli POV

k8s-ci-robot · 2025-06-30T05:52:44Z

LGTM label has been added.

Git tree hash: e21e1f494afc538904a4497edafc7c914d93f0bb

lmktfy · 2025-07-01T11:00:16Z

content/en/docs/reference/_index.md

@@ -89,7 +90,7 @@ operator to use or manage a cluster.
 * [kube-controller-manager configuration (v1alpha1)](/docs/reference/config-api/kube-controller-manager-config.v1alpha1/)
 * [kube-proxy configuration (v1alpha1)](/docs/reference/config-api/kube-proxy-config.v1alpha1/)
 * [`audit.k8s.io/v1` API](/docs/reference/config-api/apiserver-audit.v1/)
-* [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) and 
+* [Client authentication API (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/) and


nit: Avoid changing this line

lmktfy · 2025-07-01T11:01:50Z

content/en/docs/reference/kubectl/kuberc.md

 ## Disable kuberc

-To temporarily disable the kuberc functionality, simply export the environment variable `KUBERC` with the value `off`:
+To temporarily disable the kuberc functionality, simply export the environment


Suggested change

To temporarily disable the kuberc functionality, simply export the environment

To temporarily disable the kuberc functionality, set (and export) the environment

lmktfy · 2025-07-01T11:02:23Z

content/en/docs/reference/kubectl/kuberc.md

 ## Disable kuberc

-To temporarily disable the kuberc functionality, simply export the environment variable `KUBERC` with the value `off`:
+To temporarily disable the kuberc functionality, simply export the environment
+variable `KUBERC` with the value `off`:

 ```shell
 export KUBERC=off


Does this assume that the path off is invalid?

Yes, value off is strictly for disabling kuberc functionality, especially once we graduate fully to stable.

Let's document that mini snag: you can't name your kuberc off

lmktfy · 2025-07-01T11:02:59Z

content/en/docs/reference/kubectl/kuberc.md

-compiled-in default value.
-{{< /note >}}
-
-#### Example


Why delete this line?

lmktfy · 2025-07-01T11:03:14Z

content/en/docs/reference/kubectl/kuberc.md


-Append arbitrary arguments to the end of the kubectl command.
-
-#### Example {#appendArgs-example}


Why delete this line?

content/en/docs/reference/kubectl/kuberc.md

lmktfy

As a reference document, this should retain the terse style of the existing reference (with, of course, the appropriate factual updates).

Please amend it to align more with the existing approach.

lmktfy · 2025-07-01T11:04:20Z

content/en/docs/reference/kubectl/kuberc.md


-Alias name must not collide with the built-in commands. 
+Within a `kuberc` configuration, _aliases_ section allows you to define custom


Suggested change

Within a `kuberc` configuration, _aliases_ section allows you to define custom

Within a `kuberc` configuration, the _aliases_ section allows you to define custom

lmktfy · 2025-07-01T11:05:20Z

content/en/docs/reference/kubectl/kuberc.md


-## aliases
+Currently, this file allows you to define two types of user preferences:


Suggested change

Currently, this file allows you to define two types of user preferences:

A kuberc using the v1beta1 format allows you to define two types of user preferences:

lmktfy · 2025-07-01T11:06:27Z

content/en/docs/reference/kubectl/kuberc.md


-### name
+## Aliases


Suggested change

## Aliases

## aliases

lmktfy · 2025-07-01T11:06:53Z

content/en/docs/reference/kubectl/kuberc.md


-### command
+## Defaults


Suggested change

## Defaults

## defaults

lmktfy · 2025-07-01T11:08:53Z

content/en/docs/reference/kubectl/kuberc.md

+   This includes support for subcommands like `create role`.
+1. `options` - Specify default values for options. If you explicitly specify an option
+   when you run `kubectl`, the value you provide takes precedence over the default
+   one defined in `kuberc`.



Why delete this line?

lmktfy · 2025-07-01T11:11:37Z

content/en/docs/reference/kubectl/kuberc.md

 - command: delete
-  flags:
+  options:
    - name: interactive
      default: "true"


Optionally, use a comment to explain why the value is quoted.

@soltysh is a multi one type command better here?

apiVersion: kubectl.config.k8s.io/v1beta1 kind: Preference aliases: - name: rolloutwatch command: rollout status options: - name: watch default: "true"

With this alias, running kubectl rolloutwatch deployments/nginx will be translated to kubectl rollout status deployments/nginx --watch. This demonstrates how aliases can work with multi-word commands like rollout status.

I think we'll unnecessarily muddy the picture. That's why I went with the simplest possible example.

Sure! I'll defer to you if you think it's not required. I think there can be a section about the non-simple stuff as well. Maybe in the later versions..🙂

We can always expand examples towards promoting this feature to GA.

lmktfy · 2025-07-01T11:12:04Z

content/en/docs/reference/kubectl/kuberc.md

-
-#### Example
+This next example makes the interactive removal the default mode for invoking
+`kubectl delete` command:


Suggested change

`kubectl delete` command:

`kubectl delete`:

lmktfy · 2025-07-01T11:13:14Z

content/en/docs/reference/kubectl/kuberc.md


-A Kubernetes `kuberc` configuration file allows you to define preferences for kubectl, such as default options and command aliases.
-Unlike the kubeconfig file, a `kuberc` configuration file does **not** contain cluster details, usernames or passwords.
+A Kubernetes `kuberc` configuration file allows you to define preferences for kubectl,


Even better: make kubectl a hyperlink or a glossary tooltip.

lmktfy · 2025-07-01T11:15:24Z

content/en/docs/reference/kubectl/kuberc.md

-
-#### Example  {#flags-example}
+This next example defines `kubectl getn` alias for `kubectl get` command, additionally
+setting output flag `--output=json`.


Suggested change

setting output flag `--output=json`.

specifying JSON output format: `--output=json`.

lmktfy · 2025-07-01T11:16:11Z

content/en/docs/reference/kubectl/kuberc.md

-If you explicitly specify a command line argument when you run kubectl, the value you provide takes precedence over the default one defined in kuberc. 
-
-#### Example  {#flags-example}
+This next example defines `kubectl getn` alias for `kubectl get` command, additionally


Suggested change

This next example defines `kubectl getn` alias for `kubectl get` command, additionally

This next example defines a `kubectl getn` alias for the `kubectl get` subcommand, additionally

soltysh · 2025-07-22T12:09:56Z

I've addressed the comments, not quite sure what @lmktfy you mean with:

As a reference document, this should retain the terse style of the existing reference (with, of course, the appropriate factual updates).

Please amend it to align more with the existing approach.

but I hope the new version addresses your concern.

lmktfy · 2025-07-24T14:07:32Z

static/docs/reference/generated/kubectl/navData.js

I wouldn't update this file in this PR. Leave that update for the v1.34 docs team.

I can drop the entire Add generated files commit, most likely. Since that should be performed by the docs team, I believe. WDYT?

Yes please; that's what we recommend in general.

Dropped the 2nd commit with generated changes.

rushmash91

@soltysh this looks good! I minor since there isnt an example with multiple words for the command.

rushmash91 · 2025-07-26T03:52:58Z

content/en/docs/reference/kubectl/kuberc.md

 - command: delete
-  flags:
+  options:
    - name: interactive
      default: "true"


@soltysh is a multi one type command better here?

apiVersion: kubectl.config.k8s.io/v1beta1 kind: Preference aliases: - name: rolloutwatch command: rollout status options: - name: watch default: "true"

With this alias, running kubectl rolloutwatch deployments/nginx will be translated to kubectl rollout status deployments/nginx --watch. This demonstrates how aliases can work with multi-word commands like rollout status.

Signed-off-by: Maciej Szulik <[email protected]>

ardaguclu · 2025-08-01T12:08:02Z

/lgtm
from sig-cli POV

k8s-ci-robot · 2025-08-01T12:08:09Z

LGTM label has been added.

Git tree hash: 8398f59848451b2122020fd8fccd374864f33511

michellengnx · 2025-08-01T15:30:07Z

Hello @soltysh 👋! I'm reaching out from the Docs team.

Just checking in as we approach Docs Freeze on Wednesday August 6, 2025 18:00 PDT. This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs. Thank you!

dipesh-rawat

/approve

k8s-ci-robot · 2025-08-01T16:38:40Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: dipesh-rawat

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/docs/OWNERS~~ [dipesh-rawat]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot assigned ardaguclu Jun 23, 2025

k8s-ci-robot added this to the 1.34 milestone Jun 23, 2025

k8s-ci-robot added language/en Issues or PRs related to English language cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Jun 23, 2025

k8s-ci-robot requested review from dipesh-rawat and tengqm June 23, 2025 10:15

k8s-ci-robot added sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jun 23, 2025

soltysh mentioned this pull request Jun 23, 2025

Separate kubectl user preferences from cluster configs kubernetes/enhancements#3104

Open

8 tasks

soltysh mentioned this pull request Jun 25, 2025

Add config API for kuberc v1beta1 kubernetes-sigs/reference-docs#396

Open

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jun 30, 2025

lmktfy reviewed Jul 1, 2025

View reviewed changes

content/en/docs/reference/kubectl/kuberc.md

compiled-in default value.

{{< /note >}}

#### Example

Copy link

Contributor

lmktfy Jul 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why delete this line?

lmktfy reviewed Jul 1, 2025

View reviewed changes

content/en/docs/reference/kubectl/kuberc.md Show resolved Hide resolved

lmktfy reviewed Jul 1, 2025

View reviewed changes

soltysh force-pushed the kuberc_beta branch from 329325b to e00f1c3 Compare July 22, 2025 12:08

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 22, 2025

k8s-ci-robot requested a review from ardaguclu July 22, 2025 12:08

soltysh mentioned this pull request Jul 24, 2025

Update kuberc documentation for 1.34 beta #51671

Closed

soltysh force-pushed the kuberc_beta branch from e00f1c3 to 0a2aa87 Compare July 24, 2025 14:04

lmktfy reviewed Jul 24, 2025

View reviewed changes

rushmash91 reviewed Jul 26, 2025

View reviewed changes

Promote kuberc to beta

134e80c

Signed-off-by: Maciej Szulik <[email protected]>

soltysh force-pushed the kuberc_beta branch from 0a2aa87 to 134e80c Compare July 29, 2025 11:38

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Jul 29, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 1, 2025

dipesh-rawat reviewed Aug 1, 2025

View reviewed changes

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 1, 2025

k8s-ci-robot merged commit 276116d into kubernetes:dev-1.34 Aug 1, 2025
6 checks passed

soltysh deleted the kuberc_beta branch August 6, 2025 05:54

	To temporarily disable the kuberc functionality, simply export the environment
	To temporarily disable the kuberc functionality, set (and export) the environment


		Append arbitrary arguments to the end of the kubectl command.

		#### Example {#appendArgs-example}


		Alias name must not collide with the built-in commands.
		Within a `kuberc` configuration, _aliases_ section allows you to define custom

	Within a `kuberc` configuration, _aliases_ section allows you to define custom
	Within a `kuberc` configuration, the _aliases_ section allows you to define custom


		## aliases
		Currently, this file allows you to define two types of user preferences:

	Currently, this file allows you to define two types of user preferences:
	A kuberc using the v1beta1 format allows you to define two types of user preferences:

	setting output flag `--output=json`.
	specifying JSON output format: `--output=json`.

	This next example defines `kubectl getn` alias for `kubectl get` command, additionally
	This next example defines a `kubectl getn` alias for the `kubectl get` subcommand, additionally

[KEP-3104] Kuberc beta #51351

[KEP-3104] Kuberc beta #51351

Conversation

soltysh commented Jun 23, 2025

Description

Issue

Uh oh!

netlify bot commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Uh oh!

netlify bot commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull request preview available for checking

Uh oh!

ardaguclu commented Jun 30, 2025

Uh oh!

k8s-ci-robot commented Jun 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lmktfy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soltysh commented Jul 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rushmash91 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netlify bot commented Jun 23, 2025 •

edited

Loading

netlify bot commented Jun 23, 2025 •

edited

Loading