From de76486aa04509a341526bd54395366c28ee38bb Mon Sep 17 00:00:00 2001 From: Jeff Lowdermilk Date: Wed, 4 Mar 2015 14:16:04 -0800 Subject: [PATCH] Add documentation on legacy kubernetes_auth file to kubeconfig-file.md --- docs/kubeconfig-file.md | 43 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 38 insertions(+), 5 deletions(-) diff --git a/docs/kubeconfig-file.md b/docs/kubeconfig-file.md index 21fba261fb254..63496216b640b 100644 --- a/docs/kubeconfig-file.md +++ b/docs/kubeconfig-file.md @@ -46,14 +46,46 @@ users: token: blue-token - name: green-user user: + username: admin + password: secret client-certificate: path/to/my/client/cert client-key: path/to/my/client/key ``` +## .kubernetes_auth files + +**WARNING**: merging auth from a mixture of kubernetes_auth file entries and .kubeconfig user entries is hard to debug and should be avoided. kubernetes_auth file support exists mostly for tests and is being deprecated. + +The kubernetes_auth file is a legacy config file that can contain a mix of server and client auth info. It is supported in .kubeconfig via `auth-path` for a user: +``` +users: +- name: black-user + user: + auth-path: path/to/my/existing/.kubernetes_auth_file +``` + +The entries in a file loaded via auth-path will be applied to both the user and cluster of the current context. + +### Example .kubernetes_auth file +``` +{ + "User": "admin", + "Password": "secret", + "CertFile": "/path/to/my/client/cert", + "KeyFile": "/path/to/my/client/key", + "CAFile": "/path/to/my/server/cafile", + "BearerToken": "secrettoken", + "Insecure": false +} +``` +All entries are optional. `User`, `Password`, `CertFile`, `KeyFile`, and `BearerToken` are applied to the kubectl user. `CAFile` and `Insecure` apply to the cluster. Note that it is invalid to set both `CAFile` and `Insecure`, or both `BearerToken` and `User,Password` (see loading and merging rules below). + +If the contents of the kubernetes_auth file conflict with entries in .kubeconfig, they are ignored. E.g, if the .kubeconfig cluster specifies a `certificate-authority`, and the user specifies an `auth-path` to a kubernetes_file that contains a `CAFile` entry, the former will be used and the latter ignored. + ## Loading and merging rules The rules for loading and merging the .kubeconfig files are straightforward, but there are a lot of them. The final config is built in this order: 1. Merge together the kubeconfig itself. This is done with the following hierarchy and merge rules: - + Empty filenames are ignored. Files with non-deserializable content produced errors. The first file to set a particular value or map key wins and the value or map key is never changed. This means that the first file to set CurrentContext will have its context preserved. It also means that if two files specify a "red-user", only values from the first file's red-user are used. Even non-conflicting entries from the second file's "red-user" are discarded. @@ -73,9 +105,10 @@ The rules for loading and merging the .kubeconfig files are straightforward, but 1. command line arguments - `server`, `api-version`, `certificate-authority`, and `insecure-skip-tls-verify` 1. If cluster info is present and a value for the attribute is present, use it. 1. If you don't have a server location, error. - 1. User is build using the same rules as cluster info, EXCEPT that you can only have one authentication technique per user. - - The command line flags are: `auth-path`, `client-certificate`, `client-key`, and `token`. If there are two conflicting techniques, fail. + 1. Determine the actual user info to use. User is built using the same rules as cluster info, EXCEPT that you can only have one authentication technique per user. + 1. Load precedence is 1) command line flag, 2) user fields from .kubeconfig, 3) kubernetes_auth file fields (if user has a `auth-path` or the `--auth-path` was provided) + 1. The command line flags are: `auth-path`, `client-certificate`, `client-key`, `username`, `password`, and `token`. + 1. If there are two conflicting techniques, fail. 1. For any information still missing, use default values and potentially prompt for authentication information ## Manipulation of .kubeconfig via `kubectl config ` @@ -159,4 +192,4 @@ $kubectl config set-credentials green-user --client-certificate=path/to/my/clien $kubectl config set-context queen-anne-context --cluster=pig-cluster --user=black-user --namespace=saw-ns $kubectl config set-context federal-context --cluster=horse-cluster --user=green-user --namespace=chisel-ns $kubectl config use-context federal-context -``` \ No newline at end of file +```