Organizing Cluster Access Using kubeconfig Files

    Note: A file that is used to configure access to clusters is called a kubeconfig file. This is a generic way of referring to configuration files. It does not mean that there is a file named kubeconfig.

    Warning: Only use kubeconfig files from trusted sources. Using a specially-crafted kubeconfig file could result in malicious code execution or file exposure. If you must use an untrusted kubeconfig file, inspect it carefully first, much as you would a shell script.

    By default, kubectl looks for a file named config in the $HOME/.kube directory. You can specify other kubeconfig files by setting the KUBECONFIG environment variable or by setting the --kubeconfig flag.

    For step-by-step instructions on creating and specifying kubeconfig files, see .

    Suppose you have several clusters, and your users and components authenticate in a variety of ways. For example:

    • A running kubelet might authenticate using certificates.
    • A user might authenticate using tokens.
    • Administrators might have sets of certificates that they provide to individual users.

    With kubeconfig files, you can organize your clusters, users, and namespaces. You can also define contexts to quickly and easily switch between clusters and namespaces.

    Context

    A context element in a kubeconfig file is used to group access parameters under a convenient name. Each context has three parameters: cluster, namespace, and user. By default, the kubectl command-line tool uses parameters from the current context to communicate with the cluster.

    The KUBECONFIG environment variable holds a list of kubeconfig files. For Linux and Mac, the list is colon-delimited. For Windows, the list is semicolon-delimited. The KUBECONFIG environment variable is not required. If the KUBECONFIG environment variable doesn’t exist, kubectl uses the default kubeconfig file, $HOME/.kube/config.

    If the KUBECONFIG environment variable does exist, uses an effective configuration that is the result of merging the files listed in the KUBECONFIG environment variable.

    Merging kubeconfig files

    To see your configuration, enter this command:

    1. kubectl config view

    As described previously, the output might be from a single kubeconfig file, or it might be the result of merging several kubeconfig files.

    Here are the rules that kubectl uses when it merges kubeconfig files:

    1. Determine the context to use based on the first hit in this chain:

      1. Use the command-line flag if it exists.
      2. Use the current-context from the merged kubeconfig files.

      An empty context is allowed at this point.

    2. Determine the cluster and user. At this point, there might or might not be a context. Determine the cluster and user based on the first hit in this chain, which is run twice: once for user and once for cluster:

      1. Use a command-line flag if it exists: --user or --cluster.
      2. If the context is non-empty, take the user or cluster from the context.

      The user and cluster can be empty at this point.

    3. Determine the actual user information to use. Build user information using the same rules as cluster information, except allow only one authentication technique per user:

      1. Use command line flags if they exist: --client-certificate, --client-key, --username, --password, --token.
      2. Use the user fields from the merged kubeconfig files.
      3. If there are two conflicting techniques, fail.
    4. For any information still missing, use default values and potentially prompt for authentication information.

    What’s next