Merge branch 'master' into release-1.9

2017-11-30 13:34:41 -06:00
parent 31de9f07a3 a49d85186a
commit 8f7d297c96
2991 changed files with 1107 additions and 443386 deletions
@@ -23,7 +23,7 @@ Setting up an extension API server to work the aggregation layer allows the Kube

 ## Setup an extension api-server to work with the aggregation layer

-The following steps describe how to set up an extension-apiserver *at a high level*. For a concrete example of how they can be implemented, you can look at the [sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md) in the Kubernetes repo.
+The following steps describe how to set up an extension-apiserver *at a high level*. These steps apply regardless if you're using YAML configs or using APIs. An attempt is made to specifically identify any differences between the two. For a concrete example of how they can be implemented using YAML configs, you can look at the [sample-apiserver](https://github.com/kubernetes/sample-apiserver/blob/master/README.md) in the Kubernetes repo.

 Alternatively, you can use an existing 3rd party solution, such as [apiserver-builder](https://github.com/Kubernetes-incubator/apiserver-builder/blob/master/README.md), which should generate a skeleton and automate all of the following steps for you.

@@ -38,7 +38,7 @@ Alternatively, you can use an existing 3rd party solution, such as [apiserver-bu
 1. Create a Kubernetes service account in your namespace.
 1. Create a Kubernetes cluster role for the operations you want to allow on your resources.
 1. Create a Kubernetes cluster role binding from the default service account in your namespace to the cluster role you just created.
-1. Create a Kubernetes apiservice. The CA cert above should be base 64 encoded, stripped of new lines and used as the spec.caBundle in the apiservice.  This should not be namespaced.
+1. Create a Kubernetes apiservice. The CA cert above should be base64 encoded, stripped of new lines and used as the spec.caBundle in the apiservice. This should not be namespaced. If using the [kube-aggregator API](https://github.com/kubernetes/kube-aggregator/), only pass in the PEM encoded CA bundle because the base 64 encoding is done for you.
 1. Use kubectl to get your resource. It should return "No resources found." Which means that everything worked but you currently have no objects of that resource type created yet.

 {% endcapture %}
@@ -46,7 +46,7 @@ Alternatively, you can use an existing 3rd party solution, such as [apiserver-bu
 {% capture whatsnext %}

 * If you haven't already, [configure the aggregation layer](/docs/tasks/access-kubernetes-api/configure-aggregation-layer/) and enable the apiserver flags.
-* For a high level overview, see [Extending the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation/).
+* For a high level overview, see [Extending the Kubernetes API with the aggregation layer](/docs/concepts/api-extension/apiserver-aggregation).
 * Learn how to [Extend the Kubernetes API Using Custom Resource Definitions](/docs/tasks/access-kubernetes-api/extend-api-custom-resource-definitions/).

 {% endcapture %}
@@ -21,7 +21,7 @@ When accessing the Kubernetes API for the first time, use the
 Kubernetes command-line tool, `kubectl`.

 To access a cluster, you need to know the location of the cluster and have credentials
-to access it.  Typically, this is automatically set-up when you work through
+to access it. Typically, this is automatically set-up when you work through
 a [Getting started guide](/docs/setup/),
 or someone else setup the cluster and provided you with credentials and a location.

@@ -32,21 +32,21 @@ $ kubectl config view
 ```

 Many of the [examples](https://github.com/kubernetes/examples/tree/{{page.githubbranch}}/) provide an introduction to using
-kubectl.  Complete documentation is found in the [kubectl manual](/docs/user-guide/kubectl/index).
+kubectl. Complete documentation is found in the [kubectl manual](/docs/user-guide/kubectl/index).

 ### Directly accessing the REST API

 kubectl handles locating and authenticating to the API server. If you want to directly access the REST API with an http client like
 `curl` or `wget`, or a browser, there are multiple ways you can locate and authenticate against the API server:

- 1. Run kubectl in proxy mode (recommended).  This method is recommended, since it uses the stored apiserver location and verifies the identity of the API server using a self-signed cert.  No man-in-the-middle (MITM) attack is possible using this method.
- 1. Alternatively, you can provide the location and credentials directly to the http client. This works with for client code that is confused by proxies.  To protect against man in the middle attacks, you'll need to import a root cert into your browser.
+ 1. Run kubectl in proxy mode (recommended). This method is recommended, since it uses the stored apiserver location and verifies the identity of the API server using a self-signed cert. No man-in-the-middle (MITM) attack is possible using this method.
+ 1. Alternatively, you can provide the location and credentials directly to the http client. This works with client code that is confused by proxies. To protect against man in the middle attacks, you'll need to import a root cert into your browser.

 Using the Go or Python client libraries provides accessing kubectl in proxy mode.

 #### Using kubectl proxy

-The following command runs kubectl in a mode where it acts as a reverse proxy.  It handles
+The following command runs kubectl in a mode where it acts as a reverse proxy. It handles
 locating the API server and authenticating.

 Run it like this:
@@ -97,17 +97,17 @@ $ curl $APISERVER/api --header "Authorization: Bearer $TOKEN" --insecure
 }
 ```

-The above example uses the `--insecure` flag.  This leaves it subject to MITM
-attacks.  When kubectl accesses the cluster it uses a stored root certificate
-and client certificates to access the server.  (These are installed in the
-`~/.kube` directory).  Since cluster certificates are typically self-signed, it
+The above example uses the `--insecure` flag. This leaves it subject to MITM
+attacks. When kubectl accesses the cluster it uses a stored root certificate
+and client certificates to access the server. (These are installed in the
+`~/.kube` directory). Since cluster certificates are typically self-signed, it
 may take special configuration to get your http client to use root
 certificate.

 On some clusters, the API server does not require authentication; it may serve
-on localhost, or be protected by a firewall.  There is not a standard
-for this.  [Configuring Access to the API](/docs/admin/accessing-the-api)
-describes how a cluster admin can configure this.  Such approaches may conflict
+on localhost, or be protected by a firewall. There is not a standard
+for this. [Configuring Access to the API](/docs/admin/accessing-the-api)
+describes how a cluster admin can configure this. Such approaches may conflict
 with future high-availability support.

 ### Programmatic access to the API
@@ -136,7 +136,7 @@ import (
   // creates the clientset
   clientset, _:= kubernetes.NewForConfig(config)
   // access the API to list pods
-   pods, _:= clientset.Core().Pods("").List(v1.ListOptions{})
+   pods, _:= clientset.CoreV1().Pods("").List(v1.ListOptions{})
   fmt.Printf("There are %d pods in the cluster\n", len(pods.Items))
 ...
 ```
@@ -32,7 +32,7 @@ You have several options for connecting to nodes, pods and services from outside
      or it may expose it to the internet.  Think about whether the service being exposed is secure.
      Does it do its own authentication?
    - Place pods behind services.  To access one specific pod from a set of replicas, such as for debugging,
-      place a unique label on the pod it and create a new service which selects this label.
+      place a unique label on the pod and create a new service which selects this label.
    - In most cases, it should not be necessary for application developer to directly access
      nodes via their nodeIPs.
  - Access services, nodes, or pods using the Proxy Verb.
@@ -45,9 +45,9 @@ You have several options for connecting to nodes, pods and services from outside
  - Access from a node or pod in the cluster.
    - Run a pod, and then connect to a shell in it using [kubectl exec](/docs/user-guide/kubectl/{{page.version}}/#exec).
      Connect to other nodes, pods, and services from that shell.
-    - Some clusters may allow you to ssh to a node in the cluster.  From there you may be able to
-      access cluster services.  This is a non-standard method, and will work on some clusters but
-      not others.  Browsers and other tools may or may not be installed.  Cluster DNS may not work.
+    - Some clusters may allow you to ssh to a node in the cluster. From there you may be able to
+      access cluster services. This is a non-standard method, and will work on some clusters but
+      not others. Browsers and other tools may or may not be installed. Cluster DNS may not work.

 ### Discovering builtin services

@@ -102,7 +102,7 @@ If you haven't specified a name for your port, you don't have to specify *port_n

 You may be able to put an apiserver proxy URL into the address bar of a browser. However:

-  - Web browsers cannot usually pass tokens, so you may need to use basic (password) auth.  Apiserver can be configured to accept basic auth,
+  - Web browsers cannot usually pass tokens, so you may need to use basic (password) auth. Apiserver can be configured to accept basic auth,
    but your cluster may not be configured to accept basic auth.
  - Some web apps may not work, particularly those with client side javascript that construct URLs in a
    way that is unaware of the proxy path prefix.
@@ -184,7 +184,7 @@ Before starting the restore operation, a snapshot file must be present. It can e

 If the access URLs of the restored cluster is changed from the previous cluster, the Kubernetes API server must be reconfigured accordingly. In this case, restart Kubernetes API server with the flag `--etcd-servers=$NEW_ETCD_CLUSTER` instead of the flag `--etcd-servers=$OLD_ETCD_CLUSTER`. Replace `$NEW_ETCD_CLUSTER` and `$OLD_ETCD_CLUSTER` with the respective IP addresses. If a load balancer is used in front of an etcd cluster, you might need to update the load balancer instead.

-If the majority of etcd members have permanently failed, the etcd cluster is considered failed. In this scenario, Kubernetes cannot make any changes to its current state. Although the scheduled pods might  continue to run, no new pods can be scheduled. In such cases, recover the etcd cluster and potentially reconfigure Kubernetes API server to fix the issue.
+If the majority of etcd members have permanently failed, the etcd cluster is considered failed. In this scenario, Kubernetes cannot make any changes to its current state. Although the scheduled pods might continue to run, no new pods can be scheduled. In such cases, recover the etcd cluster and potentially reconfigure Kubernetes API server to fix the issue.

 ## Upgrading and rolling back etcd clusters

@@ -212,7 +212,7 @@ Note that we need to migrate both the etcd versions that we are using (from 2.2.
 to at least 3.0.x) as well as the version of the etcd API that Kubernetes talks to. The etcd 3.0.x
 binaries support both the v2 and v3 API.

-This document describes how to do this migration.  If you want to skip the
+This document describes how to do this migration. If you want to skip the
 background and cut right to the procedure, see [Upgrade
 Procedure](#upgrade-procedure).

@@ -227,7 +227,7 @@ There are requirements on how an etcd cluster upgrade can be performed. The prim
 Upgrade only one minor release at a time. For example, we cannot upgrade directly from 2.1.x to 2.3.x.
 Within patch releases it is possible to upgrade and downgrade between arbitrary versions. Starting a cluster for
 any intermediate minor release, waiting until the cluster is healthy, and then
-shutting down the cluster down will perform the migration. For example, to upgrade from version 2.1.x to 2.3.y,
+shutting down the cluster will perform the migration. For example, to upgrade from version 2.1.x to 2.3.y,
 it is enough to start etcd in 2.2.z version, wait until it is healthy, stop it, and then start the
 2.3.y version.

@@ -239,7 +239,7 @@ The etcd team has provided a [custom rollback tool](https://git.k8s.io/kubernete
 but the rollback tool has these limitations:

 * This custom rollback tool is not part of the etcd repo and does not receive the same
-  testing as the rest of etcd.  We are testing it in a couple of end-to-end tests.
+  testing as the rest of etcd. We are testing it in a couple of end-to-end tests.
  There is only community support here.

 * The rollback can be done only from the 3.0.x version (that is using the v3 API) to the
@@ -263,13 +263,13 @@ rollback might require restarting all Kubernetes components on all nodes.
 **Note**: At the time of writing, both Kubelet and KubeProxy are using “resource
 version” only for watching (i.e. are not using resource versions for anything
 else). And both are using reflector and/or informer frameworks for watching
-(i.e.  they don’t send watch requests themselves). Both those frameworks if they
+(i.e. they don’t send watch requests themselves). Both those frameworks if they
 can’t renew watch, they will start from “current version” by doing “list + watch
 from the resource version returned by list”. That means that if the apiserver
 will be down for the period of rollback, all of node components should basically
 restart their watches and start from “now” when apiserver is back. And it will
 be back with new resource version. That would mean that restarting node
-components is not needed.  But the assumptions here may not hold forever.
+components is not needed. But the assumptions here may not hold forever.
 {: .note}

 ### Design
@@ -284,7 +284,7 @@ focus on them at all. We focus only on the upgrade/rollback here.
 ### New etcd Docker image

 We decided to completely change the content of the etcd image and the way it works.
-So far, the Docker image for etcd  in version X has contained only the etcd and
+So far, the Docker image for etcd in version X has contained only the etcd and
 etcdctl binaries.

 Going forward, the Docker image for etcd in version X will contain multiple
@@ -337,7 +337,7 @@ script works as follows:
 1. Verify that the detected version is 3.0.x with the v3 API, and the
   desired version is 2.2.1 with the v2 API. We don’t support any other rollback.
 1. If so, we run the custom tool provided by etcd team to do the offline
-   rollback.  This tool reads the v3 formatted data and writes it back to disk
+   rollback. This tool reads the v3 formatted data and writes it back to disk
   in v2 format.
 1. Finally update the contents of the version file.

@@ -350,7 +350,7 @@ Simply modify the command line in the etcd manifest to:

 Starting in Kubernetes version 1.6, this has been done in the manifests for new
 Google Compute Engine clusters. You should also specify these environment
-variables.  In particular,you must keep `STORAGE_MEDIA_TYPE` set to
+variables. In particular, you must keep `STORAGE_MEDIA_TYPE` set to
 `application/json` if you wish to preserve the option to roll back.

 ```
@@ -8,7 +8,7 @@ title: Control CPU Management Policies on the Node
 Kubernetes keeps many aspects of how pods execute on nodes abstracted
 from the user. This is by design.  However, some workloads require
 stronger guarantees in terms of latency and/or performance in order to operate
-acceptably.  The kubelet provides methods to enable more complex workload
+acceptably. The kubelet provides methods to enable more complex workload
 placement policies while keeping the abstraction free from explicit placement
 directives.

@@ -188,5 +188,5 @@ spec:
 This pod runs in the `Guaranteed` QoS class because only `limits` are specified
 and `requests` are set equal to `limits` when not explicitly specified. And the 
 container's resource limit for the CPU resource is an integer greater than or 
-equal to one.The `nginx` container is granted 2 exclusive CPUs.
+equal to one. The `nginx` container is granted 2 exclusive CPUs.

@@ -19,7 +19,7 @@ can consume huge pages and the current limitations.
   its huge page capacity. A node may only pre-allocate huge pages for a single
   size.
 1. A special **alpha** feature gate `HugePages` has to be set to true across the
-   system: `--feature-gates="HugePages=true"`.
+   system: `--feature-gates=HugePages=true`.

 The nodes will automatically discover and report all huge page resources as a
 schedulable resource.