From 74fe1170ccbbd4cdf4f27fa9d048105ed2b3ed5b Mon Sep 17 00:00:00 2001 From: Steve Perry Date: Tue, 22 Aug 2017 22:51:55 -0700 Subject: [PATCH] Update kubeconfig topics. (#4439) --- _data/concepts.yml | 3 +- _data/tasks.yml | 3 +- _redirects | 3 + .../organize-cluster-access-kubeconfig.md | 150 ++++++++ ...authenticate-across-clusters-kubeconfig.md | 321 ---------------- .../configure-access-multiple-clusters.md | 343 ++++++++++++++++++ .../administer-cluster/share-configuration.md | 125 ------- 7 files changed, 499 insertions(+), 449 deletions(-) create mode 100644 docs/concepts/configuration/organize-cluster-access-kubeconfig.md delete mode 100644 docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md create mode 100644 docs/tasks/access-application-cluster/configure-access-multiple-clusters.md delete mode 100644 docs/tasks/administer-cluster/share-configuration.md diff --git a/_data/concepts.yml b/_data/concepts.yml index 6740057bcfb..f1ba8a6661f 100644 --- a/_data/concepts.yml +++ b/_data/concepts.yml @@ -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: diff --git a/_data/tasks.yml b/_data/tasks.yml index 7272e58b0dd..29fa4723947 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -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 diff --git a/_redirects b/_redirects index d97fcabfb47..42bebb055bf 100644 --- a/_redirects +++ b/_redirects @@ -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 diff --git a/docs/concepts/configuration/organize-cluster-access-kubeconfig.md b/docs/concepts/configuration/organize-cluster-access-kubeconfig.md new file mode 100644 index 00000000000..3fd78f0ac4b --- /dev/null +++ b/docs/concepts/configuration/organize-cluster-access-kubeconfig.md @@ -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 %} + diff --git a/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md b/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md deleted file mode 100644 index 8e34e967807..00000000000 --- a/docs/tasks/access-application-cluster/authenticate-across-clusters-kubeconfig.md +++ /dev/null @@ -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 ` - -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 %} diff --git a/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md b/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md new file mode 100644 index 00000000000..0f88d74b9a2 --- /dev/null +++ b/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md @@ -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 %} + diff --git a/docs/tasks/administer-cluster/share-configuration.md b/docs/tasks/administer-cluster/share-configuration.md deleted file mode 100644 index 949ab53eedd..00000000000 --- a/docs/tasks/administer-cluster/share-configuration.md +++ /dev/null @@ -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).