Skip to content

[KEP-3104] Kuberc beta #51351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 1, 2025
Merged

[KEP-3104] Kuberc beta #51351

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 99 additions & 68 deletions content/en/docs/reference/kubectl/kuberc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,81 +4,101 @@ content_type: concept
weight: 70
---

{{< feature-state state="alpha" for_k8s_version="1.33" >}}
{{< feature-state state="beta" for_k8s_version="1.34" >}}

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
{{<glossary_tooltip text="kubectl" term_id="kubectl">}},
such as default options and command aliases. Unlike the kubeconfig file, a `kuberc`
configuration file does **not** contain cluster details, usernames or passwords.

The default location of this configuration file is `$HOME/.kube/kuberc`.
You can instruct `kubectl` to look at a custom path for this configuration using the `--kuberc` command line argument.
The default location of this configuration file is `$HOME/.kube/kuberc`.
You can instruct `kubectl` to look at a custom path for this configuration using
the `--kuberc` command line argument.

## aliases

Within a `kuberc` configuration, _aliases_ allow you to define custom shortcuts
for kubectl commands, optionally with preset command line arguments.

### name

Alias name must not collide with the built-in commands.
A `kuberc` using the `kubectl.config.k8s.io/v1beta1` format allows you to define
two types of user preferences:

### command
1. [Aliases](#aliases) - allow you to create shorter versions of your favorite
commands, optionally setting options and arguments.
2. [Defaults](#defaults) - allow you to configure default option values for your
favorite commands.

Specify the underlying built-in command that your alias will execute. This includes support for subcommands like `create role`.

### flags
## aliases

Specify default values for command line arguments (which the kuberc format terms _flags_).
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.
Within a `kuberc` configuration, the _aliases_ section allows you to define custom
shortcuts for kubectl commands, optionally with preset command line arguments
and flags.

#### Example {#flags-example}
This next example defines a `kubectl getn` alias for the `kubectl get` subcommand,
additionally specifying JSON output format: `--output=json`.

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
- name: getn
command: get
flags:
options:
- name: output
default: json
```

With this alias, running `kubectl getn pods` will default JSON output. However, if you execute `kubectl getn pods -oyaml`, the output will be in YAML format.
In this example, the following settings were used:

### prependArgs
1. `name` - Alias name must not collide with the built-in commands.
1. `command` - Specify the underlying built-in command that your alias will execute.
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`.

Copy link
Contributor

Choose a reason for hiding this comment

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

Why delete this line?

Insert arbitrary arguments immediately after the kubectl command and its subcommand (if any).
With this alias, running `kubectl getn pods` will default JSON output. However,
if you execute `kubectl getn pods -oyaml`, the output will be in YAML format.

#### Example {#prependArgs-example}
Copy link
Contributor

Choose a reason for hiding this comment

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

Why delete this line?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Too many sections will cause confusion, but I agree with your take and brought back the prependArgs and appendArgs sections.

Full `kuberc` schema is available [here](/docs/reference/config-api/kubelet-config.v1beta1/).

### prependArgs

This next example, will expand the previous one, introducing `prependArgs` section,
which allows inserting arbitrary arguments immediately after the kubectl command
and its subcommand (if any).

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
- name: getn
command: get
prependArgs:
- namespace
flags:
options:
- name: output
default: json
prependArgs:
- namespace
```

`kubectl getn test-ns` will be translated to `kubectl get namespace test-ns --output json`.
In this example, the following settings were used:

### appendArgs
Copy link
Contributor

Choose a reason for hiding this comment

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

Why delete this line?

1. `name` - Alias name must not collide with the built-in commands.
1. `command` - Specify the underlying built-in command that your alias will execute.
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`.
1. `prependArgs` - Specify explicit argument that will be placed right after the
command. Here, this will be translated to `kubectl get namespace test-ns --output json`.

Append arbitrary arguments to the end of the kubectl command.
### appendArgs

#### Example {#appendArgs-example}
Copy link
Contributor

Choose a reason for hiding this comment

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

Why delete this line?

This next example, will introduce a mechanism similar to prepending arguments,
this time, though, we will append arguments to the end of the kubectl command.

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
aliases:
- name: runx
command: run
flags:
options:
- name: image
default: busybox
- name: namespace
Expand All @@ -88,65 +108,76 @@ aliases:
- custom-arg
```

`kubectl runx test-pod` will be translated to `kubectl run test-pod --namespace test-ns --image busybox -- custom-arg`.

## Command overrides

Within a `kuberc` configuration, _command overrides_ let you specify custom values for command line arguments.

### command

Specify the built-in command. This includes support for subcommands like `create role`.

### flags
In this example, the following settings were used:

Within a `kuberc`, configuration, command line arguments are termed _flags_ (even if they do not represent a boolean type).
You can use `flags` to set the default value of a command line argument.
1. `name` - Alias name must not collide with the built-in commands.
1. `command` - Specify the underlying built-in command that your alias will execute.
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`.
1. `appendArgs` - Specify explicit arguments that will be placed at the end of the
command. Here, this will be translated to `kubectl run test-pod --namespace test-ns --image busybox -- custom-arg`.

If you explicitly specify a flag on your terminal, explicit value will always take precedence over
the value you defined in kuberc using `overrides`.
## defaults

{{< note >}}
You cannot use `kuberc` to override the value of a command line argument to take precedence over
what the user specifies on the command line. The term `overrides`
in this context refers to specifying a default value that is different from the
compiled-in default value.
{{< /note >}}
Within a `kuberc` configuration, `defaults` section lets you specify default values
for command line arguments.

#### Example
Copy link
Contributor

Choose a reason for hiding this comment

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

Why delete this line?

This next example makes the interactive removal the default mode for invoking
`kubectl delete`:

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
overrides:
defaults:
- command: delete
flags:
options:
- name: interactive
default: "true"
Copy link
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

@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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

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..🙂

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

```

With this override, running `kubectl delete pod/test-pod` will default to prompting for confirmation.
In this example, the following settings were used:

1. `command` - Built-in command, 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`.

With this setting, running `kubectl delete pod/test-pod` will default to prompting for confirmation.
However, `kubectl delete pod/test-pod --interactive=false` will bypass the confirmation.

The kubectl maintainers encourage you to adopt kuberc with the given defaults:
## Suggested defaults

The kubectl maintainers encourage you to adopt kuberc with the following defaults:

```yaml
apiVersion: kubectl.config.k8s.io/v1alpha1
apiVersion: kubectl.config.k8s.io/v1beta1
kind: Preference
overrides:
defaults:
# (1) default server-side apply
- command: apply
flags:
options:
- name: server-side
default: "true"

# (2) default interactive deletion
- command: delete
flags:
options:
- name: interactive
default: "true"
```

In this example, the following settings are enforced:
1. Defaults to using [Server-Side Apply](/docs/reference/using-api/server-side-apply/).
1. Defaults to interactive removal whenever invoking `kubectl delete` to prevent
accidental removal of resources from the cluster.


## Disable kuberc

To temporarily disable the kuberc functionality, simply export the environment variable `KUBERC` with the value `off`:
To temporarily disable the `kuberc` functionality, set (and export) the environment
variable `KUBERC` with the value `off`:

```shell
export KUBERC=off
Copy link
Contributor

Choose a reason for hiding this comment

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

Does this assume that the path off is invalid?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Contributor

Choose a reason for hiding this comment

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

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

Expand Down