kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Update kubeconfig topics. (#4439)

reviewable/pr5165/r1
Steve Perry 2017-08-22 22:51:55 -07:00 committed by GitHub
parent 3af984a7aa
commit 74fe1170cc
7 changed files with 499 additions and 449 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
_data/concepts.yml
View File

@ -24,7 +24,7 @@ toc:
- title: Extending the Kubernetes API
section:
- docs/concepts/api-extension/custom-resources.md
- docs/concepts/api-extension/apiserver-aggregation.md
- docs/concepts/api-extension/apiserver-aggregation.md
- title: Containers
section:
@ -59,6 +59,7 @@ toc:
- docs/concepts/configuration/manage-compute-resources-container.md
- docs/concepts/configuration/assign-pod-node.md
- docs/concepts/configuration/secret.md
- docs/concepts/configuration/organize-cluster-access-kubeconfig.md
- title: Services, Load Balancing, and Networking
section:

3
_data/tasks.yml
View File

@ -66,7 +66,7 @@ toc:
section:
- docs/tasks/access-application-cluster/web-ui-dashboard.md
- docs/tasks/access-application-cluster/access-cluster.md
- docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md
- docs/tasks/access-application-cluster/configure-access-multiple-clusters.md
- docs/tasks/access-application-cluster/port-forward-access-application-cluster.md
- docs/tasks/access-application-cluster/load-balance-access-application-cluster.md
- docs/tasks/access-application-cluster/service-access-application-cluster.md
@ -152,7 +152,6 @@ toc:
- docs/tasks/administer-cluster/configure-pod-disruption-budget.md
- docs/tasks/administer-cluster/limit-storage-consumption.md
- docs/tasks/administer-cluster/change-default-storage-class.md
- docs/tasks/administer-cluster/share-configuration.md
- docs/tasks/administer-cluster/running-cloud-controller.md
- docs/tasks/administer-cluster/highly-available-master.md
- docs/tasks/administer-cluster/configure-multiple-schedulers.md

3
_redirects
View File

@ -85,9 +85,11 @@
/docs/hellonode /docs/tutorials/stateless-application/hello-minikube 301
/docs/ /docs/home/ 301
/docs/samples /docs/tutorials/ 301
/docs/tasks/administer-cluster/assign-pods-nodes /docs/tasks/configure-pod-container/assign-pods-nodes 301
/docs/tasks/administer-cluster/overview /docs/concepts/cluster-administration/cluster-administration-overview 301
/docs/tasks/administer-cluster/cpu-memory-limit /docs/tasks/administer-cluster/memory-default-namespace 301
/docs/tasks/administer-cluster/share-configuration/ /docs/tasks/access-application-cluster/configure-access-multiple-clusters 301
/docs/tasks/configure-pod-container/apply-resource-quota-limit /docs/tasks/administer-cluster/apply-resource-quota-limit 301
/docs/tasks/configure-pod-container/calico-network-policy /docs/tasks/administer-cluster/calico-network-policy 301
@ -276,6 +278,7 @@
/docs/stable/user-guide/labels /docs/concepts/overview/working-with-objects/labels 301
/docs/tasks/access-application-cluster/access-cluster.md /docs/tasks/access-application-cluster/access-cluster 301
/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig/ /docs/tasks/access-application-cluster/configure-access-multiple-clusters 301
/docs/tasks/access-kubernetes-api/access-kubernetes-api/http-proxy-access-api /docs/tasks/access-kubernetes-api/http-proxy-access-api 301
/docs/tasks/administer-cluster/reserve-compute-resources/out-of-resource.md /docs/tasks/administer-cluster/out-of-resource 301
/docs/tasks/configure-pod-container/configure-pod-disruption-budget /docs/tasks/run-application/configure-pdb 301

150
docs/concepts/configuration/organize-cluster-access-kubeconfig.md Normal file
View File

@ -0,0 +1,150 @@
---
title: Organizing Cluster Access Using kubeconfig Files
---
{% capture overview %}
Use kubeconfig files to organize information about clusters, users, namespaces, and
authentication mechanisms. The `kubectl` command-line tool uses kubeconfig files to
find the information it needs to choose a cluster and communicate with the API server
of a cluster.
**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`.
{: .note}
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`](/docs/user-guide/kubectl/{{page.version}}/) flag.
For step-by-step instructions on creating and specifying kubeconfig files, see
[Configure Access to Multiple Clusters](/docs/tasks/access-application-cluster/configure-access-multiple-clusters).
{% endcapture %}
{% capture body %}
## Supporting multiple clusters, users, and authentication mechanisms
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.
And you can define contexts that enable users to quickly and easily switch between
clusters and namespaces.
## Context
A kubeconfig file can have *context* elements. Each context is a triple
(cluster, namespace, user). You can use `kubectl config use-context` to set
the current context. The `kubectl` command-line tool communicates with the
cluster and namespace listed in the current context. And it uses the
credentials of the user listed in the current context.
## The KUBECONFIG environment variable
The `KUBECONGIG` 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, `kubectl` uses
an effective configuration that is the result of merging the files
listed in the `KUBECONFIG` evironment variable.
## Merging kubeconfig files
To see your configuration, enter this command:
```shell
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. If the `--kubeconfig` flag is set, use only the specified file. Do not merge.
Only one instance of this flag is allowed.
Otherwise, if the `KUBECONFIG` environment variable is set, use it as a
list of files that should be merged.
Merge the files listed in the `KUBECONFIG` envrionment variable
according to these rules:
* Ignore empty filenames.
* Produce errors for files with content that cannot be deserialized.
* The first file to set a particular value or map key wins.
* Never change the value or map key.
Example: Preserve the context of the first file to set `current-context`.
Example: If two files specify a `red-user`, use only values from the first file's `red-user`.
Even if the second file has non-conflicting entries under `red-user`, discard them.
For an example of setting the `KUBECONFIG` environment variable, see
[Setting the KUBECONFIG environment variable](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/#set-the-kubeconfig-environment-variable).
Otherwise, use the default kubeconfig file, `$HOME/.kube/config`, with no merging.
1. Determine the context to use based on the first hit in this chain:
1. Use the `--context` command-line flag if it exits.
1. Use the `current-context` from the merged kubeconfig files.
An empty context is allowed at this point.
1. 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`.
1. If the context is non-empty, take the user or cluster from the context.
The user and cluster can be empty at this point.
1. Determine the actual cluster information to use. At this point, there might or
might not be cluster information.
Build each piece of the cluster information based on this chain; the first hit wins:
1. Use command line flags if they exist: `--server`, `--certificate-authority`, `--insecure-skip-tls-verify`.
1. If any cluster information attributes exist from the merged kubeconfig files, use them.
1. If there is no server location, fail.
1. 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`.
1. Use the `user` fields from the merged kubeconfig files.
1. If there are two conflicting techniques, fail.
1. For any information still missing, use default values and potentially
prompt for authentication information.
## File references
File and path references in a kubeconfig file are relative to the location of the kubeconfig file.
File references on the command line are relative to the current working directory.
In `$HOME/.kube/config`, relative paths are stored relatively, and absolute paths
are stored absolutely.
{% endcapture %}
{% capture whatsnext %}
* [Configure Access to Multiple Clusters](/docs/tasks/access-application-cluster/configure-access-multiple-clusters/)
* [kubectl config](/docs/user-guide/kubectl/{{page.version}}/)
{% endcapture %}
{% include templates/concept.md %}

321
docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md
View File

@ -1,321 +0,0 @@
---
title: Authenticate across clusters with kubeconfig
---
{% capture overview %}
Authentication in Kubernetes can differ for different individuals.
- A running kubelet might have one way of authenticating (i.e. certificates).
- Users might have a different way of authenticating (i.e. tokens).
- Administrators might have a list of certificates which they provide individual users.
- There may be multiple clusters, and we may want to define them all in one place - giving users the ability to use their own certificates and reusing the same global configuration.
So in order to easily switch between multiple clusters, for multiple users, 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 kubeconfig files are allowed, if specified explicitly. At runtime they are loaded and merged along with override options specified from the command line (see [rules](#loading-and-merging-rules) below).
{% endcapture %}
{% capture prerequisites %}
* {% include task-tutorial-prereqs.md %}
{% endcapture %}
{% capture steps %}
## Components of a kubeconfig file
### Example kubeconfig file
```yaml
current-context: federal-context
apiVersion: v1
clusters:
- cluster:
api-version: v1
server: http://cow.org:8080
name: cow-cluster
- cluster:
certificate-authority: path/to/my/cafile
server: https://horse.org:4443
name: horse-cluster
- cluster:
insecure-skip-tls-verify: true
server: https://pig.org:443
name: pig-cluster
contexts:
- context:
cluster: horse-cluster
namespace: chisel-ns
user: green-user
name: federal-context
- context:
cluster: pig-cluster
namespace: saw-ns
user: black-user
name: queen-anne-context
kind: Config
preferences:
colors: true
users:
- name: blue-user
user:
token: blue-token
- name: green-user
user:
client-certificate: path/to/my/client/cert
client-key: path/to/my/client/key
```
### Breakdown/explanation of components
#### cluster
```yaml
clusters:
- cluster:
certificate-authority: path/to/my/cafile
server: https://horse.org:4443
name: horse-cluster
- cluster:
insecure-skip-tls-verify: true
server: https://pig.org:443
name: pig-cluster
```
A `cluster` contains endpoint data for a kubernetes cluster. This includes the fully
qualified url for the kubernetes apiserver, as well as the cluster's certificate
authority or `insecure-skip-tls-verify: true`, if the cluster's serving
certificate is not signed by a system trusted certificate authority.
A `cluster` has a name (nickname) which acts as a dictionary key for the cluster
within this kubeconfig file. You can add or modify `cluster` entries using
[`kubectl config set-cluster`](/docs/user-guide/kubectl/{{page.version}}/#-em-set-cluster-em-).
#### user
```yaml
users:
- name: blue-user
user:
token: blue-token
- name: green-user
user:
client-certificate: path/to/my/client/cert
client-key: path/to/my/client/key
```
A `user` defines client credentials for authenticating to a kubernetes cluster. A
`user` has a name (nickname) which acts as its key within the list of user entries
after kubeconfig is loaded/merged. Available credentials are `client-certificate`,
`client-key`, `token`, and `username/password`. `username/password` and `token`
are mutually exclusive, but client certs and keys can be combined with them.
You can add or modify `user` entries using
[`kubectl config set-credentials`](/docs/user-guide/kubectl/{{page.version}}/#-em-set-credentials-em-).
#### context
```yaml
contexts:
- context:
cluster: horse-cluster
namespace: chisel-ns
user: green-user
name: federal-context
```
A `context` defines a named [`cluster`](#cluster),[`user`](#user),[`namespace`](/docs/user-guide/namespaces) tuple
which is used to send requests to the specified cluster using the provided authentication info and
namespace. Each of the three is optional; it is valid to specify a context with only one of `cluster`,
`user`,`namespace`, or to specify none. Unspecified values, or named values that don't have corresponding
entries in the loaded kubeconfig (e.g. if the context specified a `pink-user` for the above kubeconfig file)
will be replaced with the default. See [Loading and merging rules](#loading-and-merging) below for override/merge behavior.
You can add or modify `context` entries with [`kubectl config set-context`](/docs/user-guide/kubectl/{{page.version}}/#-em-set-context-em-).
#### current-context
```yaml
current-context: federal-context
```
`current-context` is the nickname or 'key' for the cluster,user,namespace tuple that kubectl
will use by default when loading config from this file. You can override any of the values in kubectl
from the command line, by passing `--context=CONTEXT`, `--cluster=CLUSTER`, `--user=USER`, and/or `--namespace=NAMESPACE` respectively.
You can change the `current-context` with [`kubectl config use-context`](/docs/user-guide/kubectl/{{page.version}}/#-em-use-context-em-).
#### miscellaneous
```yaml
apiVersion: v1
kind: Config
preferences:
colors: true
```
`apiVersion` and `kind` identify the version and schema for the client parser and should not
be edited manually.
`preferences` specify optional (and currently unused) kubectl preferences.
## Viewing kubeconfig files
`kubectl config view` will display the current kubeconfig settings. By default
it will show you all loaded kubeconfig settings; you can filter the view to just
the settings relevant to the `current-context` by passing `--minify`. See
[`kubectl config view`](/docs/user-guide/kubectl/{{page.version}}/#-em-view-em-) for other options.
## Building your own kubeconfig file
You can use the [sample kubeconfig file](#example-kubeconfig-file) above as a template for your own kubeconfig files.
**Note:** If you're deploying Kubernetes with `kube-up.sh`, you don't need to create your own kubeconfig files—the script does it for you.
{: .note}
The sample file corresponds to an [API server](https://kubernetes.io/docs/admin/kube-apiserver/) launched using the `--token-auth-file=tokens.csv` option, where the `tokens.csv` file contains:
```conf
blue-user,blue-user,1
mister-red,mister-red,2
```
**Note:** There are many [options available](https://kubernetes.io/docs/admin/kube-apiserver/) for launching an API server. Make sure you understand the options you include.
{: .note}
The sample kubeconfig file provides client credentials for the user `green-user`. Because the user for `current-context` is `green-user`, any client of the API server using the sample kubeconfig file could log in successfully. Similarly, we can operate as `blue-user` by changing the value of `current-context`.
In the example provided, `green-user` logs in by providing certificates, and `blue-user` provides a token. Login information is specified with the `kubectl config set-credentials` command. For more information, see "[Commands for the example file](#commands-for-the-example-file)".
## 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. Get the kubeconfig from disk. This is done with the following hierarchy and merge rules:
If the `CommandLineLocation` (the value of the `kubeconfig` command line option) is set, use this file only. No merging. Only one instance of this flag is allowed.
Else, if `EnvVarLocation` (the value of `$KUBECONFIG`) is available, use it as a list of files that should be merged.
Merge files together based on the following 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.
Otherwise, use HomeDirectoryLocation (`~/.kube/config`) with no merging.
1. Determine the context to use based on the first hit in this chain
1. Command line argument - the value of the `context` command line option
1. `current-context` from the merged kubeconfig file
1. Empty is allowed at this stage
1. Determine the cluster info and user to use. At this point, we may or may not have a context. They are built based on the first hit in this chain. (run it twice, once for user, once for cluster)
1. Command line argument - `user` for user name and `cluster` for cluster name
1. If context is present, then use the context's value
1. Empty is allowed
1. Determine the actual cluster info to use. At this point, we may or may not have a cluster info. Build each piece of the cluster info based on the chain (first hit wins):
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. 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
1. The command line flags are: `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
1. All file references inside of a kubeconfig file are resolved relative to the location of the kubeconfig file itself. When file references are presented on the command line
they are resolved relative to the current working directory. When paths are saved in the ~/.kube/config, relative paths are stored relatively while absolute paths are stored absolutely.
Any path in a kubeconfig file is resolved relative to the location of the kubeconfig file itself.
## 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.
See [kubectl/kubectl_config](/docs/user-guide/kubectl/{{page.version}}/#config) for help.
### Example
```shell
$ kubectl config set-credentials myself --username=admin --password=secret
$ kubectl config set-cluster local-server --server=http://localhost:8080
$ kubectl config set-context default-context --cluster=local-server --user=myself
$ kubectl config use-context default-context
$ kubectl config set contexts.default-context.namespace the-right-prefix
$ kubectl config view
```
produces this output
```yaml
apiVersion: v1
clusters:
- cluster:
server: http://localhost:8080
name: local-server
contexts:
- context:
cluster: local-server
namespace: the-right-prefix
user: myself
name: default-context
current-context: default-context
kind: Config
preferences: {}
users:
- name: myself
user:
password: secret
username: admin
```
and a kubeconfig file that looks like this
```yaml
apiVersion: v1
clusters:
- cluster:
server: http://localhost:8080
name: local-server
contexts:
- context:
cluster: local-server
namespace: the-right-prefix
user: myself
name: default-context
current-context: default-context
kind: Config
preferences: {}
users:
- name: myself
user:
password: secret
username: admin
```
#### Commands for the example file
```shell
$ kubectl config set preferences.colors true
$ kubectl config set-cluster cow-cluster --server=http://cow.org:8080 --api-version=v1
$ 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-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-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
```
{% endcapture %}
{% capture discussion %}
## Final notes for tying it all together
So, tying this all together, a quick start to create your own kubeconfig file:
- Take a good look and understand how your api-server is being launched: You need to know YOUR security requirements and policies before you can design a kubeconfig file for convenient authentication.
- Replace the snippet above with information for your cluster's api-server endpoint.
- Make sure your api-server provides at least one set of credentials (for example, `green-user`) when launched. You will of course have to look at api-server documentation in order to determine the current state-of-the-art in terms of providing authentication details.
## Related discussion
[https://github.com/kubernetes/kubernetes/issues/1755](https://github.com/kubernetes/kubernetes/issues/1755)
{% endcapture %}
{% include templates/task.md %}

343
docs/tasks/access-application-cluster/configure-access-multiple-clusters.md Normal file
View File

@ -0,0 +1,343 @@
---
title: Configure Access to Multiple Clusters
---
{% capture overview %}
This page shows how to configure access to multiple clusters by using
configuration files. After your clusters, users, and contexts are defined in
one or more configuration files, you can quickly switch between clusters by using the
`kubectl config use-context` command.
**Note:** A file that is used to configure access to a cluster is sometimes 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`.
{: .note}
{% endcapture %}
{% capture prerequisites %}
You need to have the [`kubectl`](/docs/tasks/tools/install-kubectl/) command-line tool installed.
{% endcapture %}
{% capture steps %}
## Define clusters, users, and contexts
Suppose you have two clusters, one for development work and one for scratch work.
In the `development` cluster, your frontend developers work in a namespace called `frontend`,
and your storage developers work in a namespace called `storage`. In your `scratch` cluster,
developers work in the default namespace, or they create auxiliary namespaces as they
see fit. Access to the development cluster requires authentication by certificate. Access
to the scratch cluster requires authentication by username and password.
Create a directory named `config-exercise`. In your
`config-exercise` directory, create a file named `config-demo` with this content:
```shell
apiVersion: v1
kind: Config
preferences: {}
clusters:
- cluster:
name: development
- cluster:
name: scratch
users:
- name: developer
- name: experimenter
contexts:
- context:
name: dev-frontend
- context:
name: dev-storage
- context:
name: exp-scratch
```
A configuration file describes clusters, users, and contexts. Your `config-demo` file
has the framework to describe two clusters, two users, and three contexts.
Go to your `config-exercise` directory. Enter these commands to add cluster details to
your configuration file:
```shell
kubectl config --kubeconfig=config-demo set-cluster development --server=https://1.2.3.4 --certificate-authority=fake-ca-file
kubectl config --kubeconfig=config-demo set-cluster scratch --server=https://5.6.7.8 --insecure-skip-tls-verify
```
Add user details to your configuration file:
```shell
kubectl config --kubeconfig=config-demo set-credentials developer --client-certificate=fake-cert-file --client-key=fake-key-seefile
kubectl config --kubeconfig=config-demo set-credentials experimenter --username=exp --password=some-password
```
Add context details to your configuration file:
```shell
kubectl config --kubeconfig=config-demo set-context dev-frontend --cluster=development --namespace=frontend --user=developer
kubectl config --kubeconfig=config-demo set-context dev-storage --cluster=development --namespace=storage --user=developer
kubectl config --kubeconfig=config-demo set-context exp-scratch --cluster=scratch --namespace=default --user=experimenter
```
Open your `config-demo` file to see the added details. As an alternative to opening the
`config-demo` file, you can use the `config view` command.
```shell
kubectl config --kubeconfig=config-demo view
```
The output shows the two clusters, two users, and three contexts:
```shell
apiVersion: v1
clusters:
- cluster:
certificate-authority: fake-ca-file
server: https://1.2.3.4
name: development
- cluster:
insecure-skip-tls-verify: true
server: https://5.6.7.8
name: scratch
contexts:
- context:
cluster: development
namespace: frontend
user: developer
name: dev-frontend
- context:
cluster: development
namespace: storage
user: developer
name: dev-storage
- context:
cluster: scratch
namespace: default
user: experimenter
name: exp-scratch
current-context: ""
kind: Config
preferences: {}
users:
- name: developer
user:
client-certificate: fake-cert-file
client-key: fake-key-file
- name: experimenter
user:
password: some-password
username: exp
```
Each context is a triple (cluster, user, namespace). For example, the
`dev-frontend` context says, Use the credentials of the `developer`
user to access the `frontend` namespace of the `development` cluster.
Set the current context:
```shell
kubectl config --kubeconfig=config-demo use-context dev-frontend
```
Now whenever you enter a `kubectl` command, the action will apply to the cluster,
and namespace listed in the `dev-frontend` context. And the command will use
the credentials of the user listed in the `dev-frontend` context.
To see only the configuration information associated with
the current context, use the `--minify` flag.
```shell
kubectl config --kubeconfig=config-demo view --minify
```
The output shows configuration information associated with the `dev-frontend` context:
```shell
apiVersion: v1
clusters:
- cluster:
certificate-authority: fake-ca-file
server: https://1.2.3.4
name: development
contexts:
- context:
cluster: development
namespace: frontend
user: developer
name: dev-frontend
current-context: dev-frontend
kind: Config
preferences: {}
users:
- name: developer
user:
client-certificate: fake-cert-file
client-key: fake-key-file
```
Now suppose you want to work for a while in the scratch cluster.
Change the current context to `exp-scratch`:
```shell
kubectl config --kubeconfig=config-demo use-context exp-scratch
```
Now any `kubectl` command you give will apply to the default namespace of
the `scratch` cluster. And the command will use the credentials of the user
listed in the `exa-scratch` context.
View configuration associated with the new current context, `exp-scratch`.
```shell
kubectl config --kubeconfig=config-demo view --minify
```
Finally, suppose you want to work for a while in the `storage` namespace of the
`development` cluster.
Change the current context to `dev-storage`:
```shell
kubectl config --kubeconfig=config-demo use-context dev-storage
```
View configuration associated with the new current context, `dev-storage.
```shell
kubectl config --kubeconfig=config-demo view --minify
```
## Create a second configuration file
In your `config-exercise` directory, create a file named `config-demo-2` with this content:
```shell
apiVersion: v1
kind: Config
preferences: {}
contexts:
- context:
cluster: development
namespace: ramp
user: developer
name: dev-ramp-up
```
The preceding configuration file defines a new context named `dev-ramp-up`.
## Set the KUBECONFIG environment variable
See whether you have an environment variable named `KUBECONFIG`. If so, save the
current value of your `KUBECONFIG` environment variable, so you can restore it later.
For example, on Linux:
```shell
export KUBECONFIG_SAVED=$KUBECONFIG
```
The `KUBECONFIG` environment variable is a list of paths to configuration files. The list is
colon-delimited for Linux and Mac, and semicolon-delimited for Windows. If you have
a `KUBECONFIG` environment variable, familiarize yourself with the configuration files
in the list.
Temporarily append two paths to your `KUBECONFIG` environment variable. For example, on Linux:
```shell
export KUBECONFIG=$KUBECONFIG:config-demo:config-demo-2
```
In your `config-exercise` directory, enter this command:
```shell
kubectl config view
```
The output shows merged information from all the files listed in your `KUBECONFIG`
environnment variable. In particular, notice that the merged information has the
`dev-ramp-up` context from the `config-demo-2` file and the three contexts from
the `config-demo` file:
```shell
contexts:
- context:
cluster: development
namespace: frontend
user: developer
name: dev-frontend
- context:
cluster: development
namespace: ramp
user: developer
name: dev-ramp-up
- context:
cluster: development
namespace: storage
user: developer
name: dev-storage
- context:
cluster: scratch
namespace: default
user: experimenter
name: exp-scratch
```
For more information about how kubeconfig files are merged, see
[Organizing Cluster Access Using kubeconfig Files](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
## Explore the $HOME/.kube directory
If you already have a cluster, and you can use `kubectl` to interact with
the cluster, then you probably have a file named `config` in the `$HOME/.kube`
directory.
Go to `$HOME/.kube`, and see what files are there. Typically, there is a file named
`config`. There might also be other configuration files in this directory. Briefly
familiarize yourself with the contents of these files.
## Append $HOME/.kube/config to your KUBECONFIG environment variable
If you have a `$HOME/.kube/config` file, and it's not already listed in your
`KUBECONFIG` environment variable, append it to your `KUBECONFIG` environment variable now.
For example, on Linux:
```shell
export KUBECONFIG=$KUBECONFIG:$HOME/.kube/config
```
View configuration information merged from all the files that are now listed
in your `KUBECONFIG` environment variable. In your config-exercise directory, enter:
```shell
kubectl config view
```
## Clean up
Return your `KUBECONFIG` environment variable to its original value. For example, on Linux:
```shell
export KUBECONFIG=$KUBECONFIG_SAVED
```
{% endcapture %}
{% capture whatsnext %}
* [Organizing Cluster Access Using kubeconfig Files](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
* [kubectl config](/docs/user-guide/kubectl/{{page.version}}/)
{% endcapture %}
{% include templates/task.md %}

125
docs/tasks/administer-cluster/share-configuration.md
View File

@ -1,125 +0,0 @@
---
approvers:
- mikedanese
- thockin
title: Share Cluster Access with kubeconfig
---
Client access to a running Kubernetes cluster can be shared by copying
the `kubectl` client config bundle ([kubeconfig](/docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig/)).
This config bundle lives in `$HOME/.kube/config`, and is generated
by `cluster/kube-up.sh`. Sample steps for sharing `kubeconfig` below.
**1. Create a cluster**
```shell
$ cluster/kube-up.sh
```
**2. Copy `kubeconfig` to new host**
```shell
$ scp $HOME/.kube/config user@remotehost:/path/to/.kube/config
```
**3. On new host, make copied `config` available to `kubectl`**
* Option A: copy to default location
```shell
$ mv /path/to/.kube/config $HOME/.kube/config
```
* Option B: copy to working directory (from which kubectl is run)
```shell
$ mv /path/to/.kube/config $PWD
```
* Option C: manually pass `kubeconfig` location to `kubectl`
```shell
# via environment variable
$ export KUBECONFIG=/path/to/.kube/config
# via commandline flag
$ kubectl ... --kubeconfig=/path/to/.kube/config
```
## Manually Generating `kubeconfig`
`kubeconfig` is generated by `kube-up` but you can generate your own
using (any desired subset of) the following commands.
```shell
# create kubeconfig entry
$ kubectl config set-cluster $CLUSTER_NICK \
--server=https://1.1.1.1 \
--certificate-authority=/path/to/apiserver/ca_file \
--embed-certs=true \
# Or if tls not needed, replace --certificate-authority and --embed-certs with
--insecure-skip-tls-verify=true \
--kubeconfig=/path/to/standalone/.kube/config
# create user entry
$ kubectl config set-credentials $USER_NICK \
# bearer token credentials, generated on kube master
--token=$token \
# use either username|password or token, not both
--username=$username \
--password=$password \
--client-certificate=/path/to/crt_file \
--client-key=/path/to/key_file \
--embed-certs=true \
--kubeconfig=/path/to/standalone/.kube/config
# create context entry
$ kubectl config set-context $CONTEXT_NAME \
--cluster=$CLUSTER_NICK \
--user=$USER_NICK \
--kubeconfig=/path/to/standalone/.kube/config
```
Notes:
* The `--embed-certs` flag is needed to generate a standalone
`kubeconfig`, that will work as-is on another host.
* `--kubeconfig` is both the preferred file to load config from and the file to
save config too. In the above commands the `--kubeconfig` file could be
omitted if you first run
```shell
$ export KUBECONFIG=/path/to/standalone/.kube/config
```
* The ca_file, key_file, and cert_file referenced above are generated on the
kube master at cluster turnup. They can be found on the master under
`/srv/kubernetes`. Bearer token/basic auth is also generated on the kube master.
For more details on `kubeconfig` see [Authenticating Across Clusters with kubeconfig](/docs/concepts/cluster-administration/authenticate-across-clusters-kubeconfig/),
and/or run `kubectl config -h`.
## Merging `kubeconfig` Example
`kubectl` loads and merges config from the following locations (in order)
1. `--kubeconfig=/path/to/.kube/config` command line flag
2. `KUBECONFIG=/path/to/.kube/config` env variable
3. `$HOME/.kube/config`
If you create clusters A, B on host1, and clusters C, D on host2, you can
make all four clusters available on both hosts by running
```shell
# on host2, copy host1's default kubeconfig, and merge it from env
$ scp host1:/path/to/home1/.kube/config /path/to/other/.kube/config
$ export KUBECONFIG=/path/to/other/.kube/config
# on host1, copy host2's default kubeconfig and merge it from env
$ scp host2:/path/to/home2/.kube/config /path/to/other/.kube/config
$ export KUBECONFIG=/path/to/other/.kube/config
```
Detailed examples and explanation of `kubeconfig` loading/merging rules can be found in [kubeconfig-file](/docs/user-guide/kubeconfig-file).