kubectl-config

Get all contexts in the default kubeconfig file

$ kubectl config get-contexts

$ kubectl config [get-clusters|get-contexts|get-users] --kubeconfig [path/to/kubeconfig.yaml]

$ kubectl config current-context

$ kubectl config set-context --current --namespace [namespace]

$ kubectl config [use|use-context] [context_name]

$ kubectl config [delete-cluster|delete-context|delete-user] [cluster|context|user]

$ export KUBECONFIG="[$HOME.kube/config:path/to/custom/kubeconfig.yaml]" kubectl config get-contexts

kubectl config <subcommand> [options]

Common kubectl config subcommands include:
  kubectl config view [options]
  kubectl config get-contexts [options]
  kubectl config use-context <name>
  kubectl config set-context <name> --cluster=<cluster> --user=<user> [--namespace=<namespace>]
  kubectl config delete-context <name>

view
    Displays the merged kubeconfig settings, showing configured clusters, users, and contexts. Can be filtered and formatted.

get-contexts
    Lists all available contexts defined in the kubeconfig, indicating the currently active one and their associated cluster/user/namespace.

use-context
    Sets the current context to the specified name, thereby switching the active Kubernetes cluster and user for subsequent kubectl commands.

current-context
    Prints the name of the currently active context from the kubeconfig file.

set-context
    Creates a new context or modifies an existing one, associating it with a specified cluster, user, and optionally a default namespace.

set-cluster
    Modifies or creates a cluster entry in the kubeconfig, defining its API server address and certificate authority data.

set-credentials
    Modifies or creates a user entry in the kubeconfig, specifying authentication methods like client certificates, client keys, or tokens.

rename-context
    Changes the name of an existing context to a new specified name.

set
    Sets a specific key-value pair directly within the kubeconfig file, allowing granular control over configuration properties.

unset
    Removes a specified key-value pair from the kubeconfig file.

delete-cluster
    Removes a cluster entry and its associated data from the kubeconfig file.

delete-context
    Removes a context entry from the kubeconfig file.

delete-user
    Removes a user entry from the kubeconfig file.

--kubeconfig=
    (Global Flag) Specifies an alternative path to the kubeconfig file to be used instead of the default location (`~/.kube/config`).

--output=
    (Applicable to view, get-contexts) Specifies the output format, such as `yaml`, `json`, `name`, or `wide`.

--flatten
    (Applicable to view) Prints the kubeconfig in a single file by merging and embedding certificate data directly into the output.

The kubectl config command group allows users to manage their kubeconfig files, which are essential for configuring access to Kubernetes clusters. These files encapsulate details about clusters (API server addresses, CA certificates), users (authentication credentials), and contexts. A context is a convenient combination of a cluster, a user, and an optional namespace, defining how kubectl interacts with a specific Kubernetes cluster. This command is fundamental for users who need to switch between multiple Kubernetes environments, such as development, staging, and production, from a single workstation. It provides functionalities to view, create, modify, and delete cluster, user, and context entries, enabling seamless and secure management of diverse Kubernetes interactions. Proper handling of kubeconfig files through this command ensures efficient and secure cluster access.

• Security Risk: Kubeconfig files contain sensitive authentication data. Always protect them with appropriate file permissions and avoid sharing them carelessly.
• Default Location Override: While flexible, consistently overriding the default kubeconfig location (`~/.kube/config`) via the KUBECONFIG environment variable or the --kubeconfig flag can sometimes lead to confusion if not meticulously managed.
• Context Verification: When working with multiple clusters, always verify the current context using `kubectl config current-context` to prevent accidental operations on the wrong cluster.
• Manual Editing: Kubeconfig files are YAML. Manual edits require strict adherence to YAML syntax; errors can corrupt the configuration and prevent kubectl from functioning correctly.

The `KUBECONFIG` environment variable allows specifying a list of kubeconfig files (colon-separated on Linux/macOS, semicolon-separated on Windows). When set, kubectl merges the configurations from all listed files. The first definition encountered for a given cluster, user, or context name takes precedence. This powerful feature enables users to organize their kubeconfig files across different projects or environments, but requires careful management to avoid unexpected overrides.

When multiple kubeconfig files are merged, either implicitly via the `KUBECONFIG` environment variable or explicitly, entries (clusters, users, contexts) are merged based on their names. If there are conflicts for the same named entry, the last-read file's entry typically takes precedence. This merging logic is critical for understanding how your effective Kubernetes configuration is composed.

By default, kubectl looks for your kubeconfig file at `$HOME/.kube/config`. If this file doesn't exist, kubectl may create it upon certain configuration operations. This default location can always be overridden using the `KUBECONFIG` environment variable or the `--kubeconfig` command-line flag.

The kubectl config command has been a foundational component of the kubectl command-line tool since the early stages of Kubernetes development. Its necessity grew as users began managing multiple Kubernetes clusters across different environments (e.g., development, staging, production). Initially, users might have manually edited the `~/.kube/config` file. However, as Kubernetes adoption expanded, the need for a programmatic and safer way to manage kubeconfig entries became evident. Over time, subcommands like `use-context`, `set-context`, and `delete-context` were introduced and refined, significantly enhancing usability and reducing the risk of errors compared to direct file manipulation. This evolution reflects the increasing complexity and widespread use of Kubernetes clusters, making robust configuration management a critical feature.

kubectl(1), kubectl create secret(1), env(1), chmod(1)