scottk/kubernetes
1
0
Fork 0
mirror of https://github.com/optim-enterprises-bv/kubernetes.git synced 2025-11-03 19:58:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update kubeconfig-file doc.

Browse Source 
Remove the '.' in references to '.kubeconfig file' to avoid confusion as
default location is now ~/.kube/config. Also remove auth-path examples,
as that option is deprecated and should not be used.
This commit is contained in:
Jeff Lowdermilk
2015-05-05 11:36:22 -07:00
parent 20ea35105d
commit d8b970e8cf
1 changed files with 20 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files

55
docs/kubeconfig-file.md
View File

@@ -1,12 +1,12 @@
# .kubeconfig files # kubeconfig files
In order to easily switch between multiple clusters, a .kubeconfig file was defined. This file contains a series of authentication mechanisms and cluster connection information associated with nicknames. It also introduces the concept of a tuple of authentication information (user) and cluster connection information called a context that is also associated with a nickname. In order to easily switch between multiple clusters, a kubeconfig file was defined. This file contains a series of authentication mechanisms and cluster connection information associated with nicknames. It also introduces the concept of a tuple of authentication information (user) and cluster connection information called a context that is also associated with a nickname.
Multiple files are .kubeconfig files are allowed. At runtime they are loaded and merged together along with override options specified from the command line (see rules below). Multiple files are kubeconfig files are allowed. At runtime they are loaded and merged together along with override options specified from the command line (see rules below).
## Related discussion ## Related discussion
https://github.com/GoogleCloudPlatform/kubernetes/issues/1755 https://github.com/GoogleCloudPlatform/kubernetes/issues/1755
## Example .kubeconfig file ## Example kubeconfig file
``` ```
apiVersion: v1 apiVersion: v1
clusters: clusters:
@@ -38,9 +38,6 @@ kind: Config
preferences: preferences:
colors: true colors: true
users: users:
- name: black-user
user:
auth-path: path/to/my/existing/.kubernetes_auth_file
- name: blue-user - name: blue-user
user: user:
token: blue-token token: blue-token
@@ -54,9 +51,9 @@ users:
## .kubernetes_auth files ## .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. **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: 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: users:
- name: black-user - name: black-user
@@ -80,10 +77,10 @@ The entries in a file loaded via auth-path will be applied to both the user and
``` ```
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). 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. 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 ## 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: 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. Get the kubeconfig from disk. This is done with the following hierarchy and merge rules: 1. Get the kubeconfig from disk. This is done with the following hierarchy and merge rules:
@@ -111,35 +108,18 @@ The rules for loading and merging the .kubeconfig files are straightforward, but
1. If cluster info is present and a value for the attribute is present, use it. 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. If you don't have a server location, error.
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. 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. 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. The command line flags are: `auth-path`, `client-certificate`, `client-key`, `username`, `password`, and `token`.
1. If there are two conflicting techniques, fail. 1. If there are two conflicting techniques, fail.
1. For any information still missing, use default values and potentially prompt for authentication information 1. For any information still missing, use default values and potentially prompt for authentication information
## Manipulation of .kubeconfig via `kubectl config <subcommand>` ## Manipulation of kubeconfig via `kubectl config <subcommand>`
In order to more easily manipulate .kubeconfig files, there are a series of subcommands to `kubectl config` to help. In order to more easily manipulate kubeconfig files, there are a series of subcommands to `kubectl config` to help.
``` See [docs/kubectl_config.md](kubectl_config.md) for help.
kubectl config set-credentials name --auth-path=path/to/authfile --client-certificate=path/to/cert --client-key=path/to/key --token=string
Sets a user entry in .kubeconfig. If the referenced name already exists, it will be overwritten.
kubectl config set-cluster name --server=server --skip-tls=bool --certificate-authority=path/to/ca --api-version=string
Sets a cluster entry in .kubeconfig. If the referenced name already exists, it will be overwritten.
kubectl config set-context name --user=string --cluster=string --namespace=string
Sets a config entry in .kubeconfig. If the referenced name already exists, it will be overwritten.
kubectl config use-context name
Sets current-context to name
kubectl config set property-name property-value
Sets arbitrary value in .kubeconfig
kubectl config unset property-name
Unsets arbitrary value in .kubeconfig
kubectl config view --local=true --global=false --kubeconfig=specific/filename --merged
Displays the merged (or not) result of the specified .kubeconfig file
--local, --global, and --kubeconfig are valid flags for all of these operations.
```
### Example ### Example
``` ```
$kubectl config set-credentials myself --auth-path=path/to/my/existing/auth-file $kubectl config set-credentials myself --username=admin --password=secret
$kubectl config set-cluster local-server --server=http://localhost:8080 $kubectl config set-cluster local-server --server=http://localhost:8080
$kubectl config set-context default-context --cluster=local-server --user=myself $kubectl config set-context default-context --cluster=local-server --user=myself
$kubectl config use-context default-context $kubectl config use-context default-context
@@ -160,10 +140,11 @@ current-context: default-context
preferences: {} preferences: {}
users: users:
myself: myself:
auth-path: path/to/my/existing/auth-file username: admin
password: secret
``` ```
and a .kubeconfig file that looks like this and a kubeconfig file that looks like this
``` ```
apiVersion: v1 apiVersion: v1
clusters: clusters:
@@ -182,7 +163,8 @@ preferences: {}
users: users:
- name: myself - name: myself
user: user:
auth-path: path/to/my/existing/auth-file username: admin
password: secret
``` ```
#### Commands for the example file #### Commands for the example file
@@ -191,7 +173,6 @@ $kubectl config set preferences.colors true
$kubectl config set-cluster cow-cluster --server=http://cow.org:8080 --api-version=v1beta1 $kubectl config set-cluster cow-cluster --server=http://cow.org:8080 --api-version=v1beta1
$kubectl config set-cluster horse-cluster --server=https://horse.org:4443 --certificate-authority=path/to/my/cafile $kubectl config set-cluster horse-cluster --server=https://horse.org:4443 --certificate-authority=path/to/my/cafile
$kubectl config set-cluster pig-cluster --server=https://pig.org:443 --insecure-skip-tls-verify=true $kubectl config set-cluster pig-cluster --server=https://pig.org:443 --insecure-skip-tls-verify=true
$kubectl config set-credentials black-user --auth-path=path/to/my/existing/.kubernetes_auth_file
$kubectl config set-credentials blue-user --token=blue-token $kubectl config set-credentials blue-user --token=blue-token
$kubectl config set-credentials green-user --client-certificate=path/to/my/client/cert --client-key=path/to/my/client/key $kubectl config set-credentials green-user --client-certificate=path/to/my/client/cert --client-key=path/to/my/client/key
$kubectl config set-context queen-anne-context --cluster=pig-cluster --user=black-user --namespace=saw-ns $kubectl config set-context queen-anne-context --cluster=pig-cluster --user=black-user --namespace=saw-ns