Merge branch 'master' into release-1.8

2017-08-23 10:10:51 -07:00
parent 6c68762cef 74fe1170cc
commit 9403dc361f
35 changed files with 548 additions and 490 deletions
@@ -215,7 +215,7 @@ unschedulable, run this command:
 kubectl cordon $NODENAME
 ```

-Note that pods which are created by a daemonSet controller bypass the Kubernetes scheduler,
+Note that pods which are created by a DaemonSet controller bypass the Kubernetes scheduler,
 and do not respect the unschedulable attribute on a node.  The assumption is that daemons belong on
 the machine even if it is being drained of applications in preparation for a reboot.

@@ -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 %}
+
@@ -39,7 +39,7 @@ These are just examples of commonly used labels; you are free to develop your ow

 ## Syntax and character set

-_Labels_ are key value pairs. Valid label keys have two segments: an optional prefix and name, separated by a slash (`/`).  The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.  The prefix is optional.  If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (`.`), not longer than 253 characters in total, followed by a slash (`/`).
+_Labels_ are key/value pairs. Valid label keys have two segments: an optional prefix and name, separated by a slash (`/`).  The name segment is required and must be 63 characters or less, beginning and ending with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.  The prefix is optional.  If specified, the prefix must be a DNS subdomain: a series of DNS labels separated by dots (`.`), not longer than 253 characters in total, followed by a slash (`/`).
 If the prefix is omitted, the label Key is presumed to be private to the user. Automated system components (e.g. `kube-scheduler`, `kube-controller-manager`, `kube-apiserver`, `kubectl`, or other third-party automation) which add labels to end-user objects must specify a prefix.  The `kubernetes.io/` prefix is reserved for Kubernetes core components.

 Valid label values must be 63 characters or less and must be empty or begin and end with an alphanumeric character (`[a-z0-9A-Z]`) with dashes (`-`), underscores (`_`), dots (`.`), and alphanumerics between.
@@ -219,10 +219,10 @@ automatically give each namespace the ability to consume more resources.

 Sometimes more complex policies may be desired, such as:

-  - proportionally divide total cluster resources among several teams.
-  - allow each tenant to grow resource usage as needed, but have a generous
+  - Proportionally divide total cluster resources among several teams.
+  - Allow each tenant to grow resource usage as needed, but have a generous
    limit to prevent accidental resource exhaustion.
-  - detect demand from one namespace, add nodes, and increase quota.
+  - Detect demand from one namespace, add nodes, and increase quota.

 Such policies could be implemented using ResourceQuota as a building-block, by
 writing a 'controller' which watches the quota usage and adjusts the quota
@@ -67,6 +67,6 @@ As of 1.7, Pods with hostNetwork enabled will not be able to use this feature. T

 ## Why Does Kubelet Manage the Hosts File?

-kubelet [manages](https://github.com/kubernetes/kubernetes/issues/14633) the hosts file for each container of the Pod to prevent Docker from [modifying](https://github.com/moby/moby/issues/17190) the file after the containers have already been started.
+Kubelet [manages](https://github.com/kubernetes/kubernetes/issues/14633) the hosts file for each container of the Pod to prevent Docker from [modifying](https://github.com/moby/moby/issues/17190) the file after the containers have already been started.

 Because of the managed-nature of the file, any user-written content will be overwritten whenever the hosts file is remounted by Kubelet in the event of a container restart or a Pod reschedule. Thus, it is not suggested to modify the contents of the file.
@@ -38,7 +38,7 @@ An Ingress is a collection of rules that allow inbound connections to reach the
   [ Services ]
 ```

-It can be configured to give services externally-reachable urls, load balance traffic, terminate SSL, offer name based virtual hosting etc. Users request ingress by POSTing the Ingress resource to the API server. An [Ingress controller](#ingress-controllers) is responsible for fulfilling the Ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic in an HA manner.
+It can be configured to give services externally-reachable URLs, load balance traffic, terminate SSL, offer name based virtual hosting etc. Users request ingress by POSTing the Ingress resource to the API server. An [Ingress controller](#ingress-controllers) is responsible for fulfilling the Ingress, usually with a loadbalancer, though it may also configure your edge router or additional frontends to help handle the traffic in an HA manner.

 ## Prerequisites

@@ -185,7 +185,7 @@ spec:
          servicePort: 80
 ```

-__Default Backends__: An Ingress with no rules, like the one shown in the previous section, sends all traffic to a single default backend. You can use the same technique to tell a loadbalancer where to find your website's 404 page, by specifying a set of rules *and* a default backend. Traffic is routed to your default backend if none of the Hosts in your Ingress match the Host in the request header, and/or none of the paths match the url of the request.
+__Default Backends__: An Ingress with no rules, like the one shown in the previous section, sends all traffic to a single default backend. You can use the same technique to tell a loadbalancer where to find your website's 404 page, by specifying a set of rules *and* a default backend. Traffic is routed to your default backend if none of the Hosts in your Ingress match the Host in the request header, and/or none of the paths match the URL of the request.

 ### TLS

@@ -65,8 +65,8 @@ __ingress__: Each `NetworkPolicy` includes a list of whitelist `ingress` rules.
 So, the example NetworkPolicy:

 1. isolates "role=db" pods in the "default" namespace (if they weren't already isolated)
-2. allows connections to tcp port 6379 of "role=db" pods in the "default" namespace from any pod in the "default" namespace with the label "role=frontend"
-3. allows connections to tcp port 6379 of "role=db" pods in the "default" namespace from any pod in a namespace with the label "project=myproject"
+2. allows connections to TCP port 6379 of "role=db" pods in the "default" namespace from any pod in the "default" namespace with the label "role=frontend"
+3. allows connections to TCP port 6379 of "role=db" pods in the "default" namespace from any pod in a namespace with the label "project=myproject"

 See the [NetworkPolicy getting started guide](/docs/getting-started-guides/network-policy/walkthrough) for further examples.

@@ -649,6 +649,9 @@ You can see [vSphere example](https://git.k8s.io/kubernetes/examples/volumes/vsp
    pool: kube
    userId: kube
    userSecretName: ceph-secret-user
+    fsType: ext4
+    imageFormat: "2"
+    imageFeatures: "layering"
 ```

 * `monitors`: Ceph monitors, comma delimited. This parameter is required.
@@ -661,6 +664,9 @@ You can see [vSphere example](https://git.k8s.io/kubernetes/examples/volumes/vsp
  ```
  $ kubectl create secret generic ceph-secret --type="kubernetes.io/rbd" --from-literal=key='QVFEQ1pMdFhPUnQrSmhBQUFYaERWNHJsZ3BsMmNjcDR6RFZST0E9PQ==' --namespace=kube-system
  ```
+* `fsType`: fsType that is supported by kubernetes. Default: `"ext4"`.
+* `imageFormat`: Ceph RBD image format, "1" or "2". Default is "1".
+* `imageFeatures`: This parameter is optional and should only be used if you set `imageFormat` to "2". Currently supported features are `layering` only. Default is "", and no features are turned on.

 #### Quobyte

@@ -129,7 +129,7 @@ job "hello-1202039034" deleted

 Once the jobs are deleted, the pods created by them are deleted as well. Note that all jobs created by cron
 job "hello" will be prefixed "hello-". You can delete them at once with `kubectl delete jobs --all`, if you want to
-delete all jobs in the current namespace (not just the ones created by "hello".)
+delete all jobs in the current namespace (not just the ones created by "hello").

 ## Cron Job Limitations

@@ -262,7 +262,7 @@ removed label still exists in any existing Pods and ReplicaSets.

 Sometimes you may want to rollback a Deployment; for example, when the Deployment is not stable, such as crash looping.
 By default, all of the Deployment's rollout history is kept in the system so that you can rollback anytime you want
-(you can change that by modifyingrevision history limit]).
+(you can change that by modifying revision history limit]).

 **Note:** a Deployment's revision is created when a Deployment's rollout is triggered. This means that the
 new revision is created if and only if the Deployment's pod template (`.spec.template`) is changed,
@@ -94,7 +94,7 @@ Before you start deploying applications as PetSets, there are a few limitations

 * PetSet is an *alpha* resource, not available in any Kubernetes release prior to 1.3.
 * As with all alpha/beta resources, it can be disabled through the `--runtime-config` option passed to the apiserver, and in fact most likely will be disabled on hosted offerings of Kubernetes.
-* The only updatable field on a PetSet is `replicas`
+* The only updatable field on a PetSet is `replicas`.
 * The storage for a given pet must either be provisioned by a [persistent volume provisioner](http://releases.k8s.io/{{page.githubbranch}}/examples/persistent-volume-provisioning/README.md) based on the requested `storage class`, or pre-provisioned by an admin. Note that persistent volume provisioning is also currently in alpha.
 * Deleting and/or scaling a PetSet down will *not* delete the volumes associated with the PetSet. This is done to ensure safety first, your data is more valuable than an auto purge of all related PetSet resources. **Deleting the Persistent Volume Claims will result in a deletion of the associated volumes**.
 * All PetSets currently require a "governing service", or a Service responsible for the network identity of the pets. The user is responsible for this Service.
@@ -122,7 +122,7 @@ The "intended" number of pods is computed from the `.spec.replicas` of the pods
 The controller is discovered from the pods using the `.metadata.ownerReferences` of the object.

 PDBs cannot prevent [involuntary disruptions](#voluntary-and-involuntary-disruptions) from
-occuring, but they do count against the budget.
+occurring, but they do count against the budget.

 Pods which are deleted or unavailable due to a rolling upgrade to an application do count
 against the disruption budget, but controllers (like deployment and stateful-set)