Merge branch 'master' of https://github.com/kubernetes/kubernetes.github.io into release-1.8

* 'master' of https://github.com/kubernetes/kubernetes.github.io: (23 commits) concepts/configuration/manage-compute-resources-container.md: fix a conversion (#4952) Update authentication.md (#5281) Update static-pod.md for consistency Space needed before list in kramdown. Update downward-api-volume-expose-pod-information.md fix the command output fix the command output fix the command output fix the command output fix the command output Fix CRD page typo fix 404 page Update binary_release.md Update disruptions.md fix the command output fix typo fix the command output Fix curl does not work in zsh use the term 'node' for consistency fix typo ...
2017-09-05 16:10:28 -07:00
parent fc7c06c1e5 6e584be28e
commit 7c999e38b1
23 changed files with 142 additions and 44 deletions
@@ -81,6 +81,7 @@ toc:
 - title: Cluster Administration
  section:
  - docs/concepts/cluster-administration/cluster-administration-overview.md
+  - docs/concepts/cluster-administration/cloud-providers.md
  - docs/concepts/cluster-administration/manage-deployment.md
  - docs/concepts/cluster-administration/networking.md
  - docs/concepts/cluster-administration/network-plugins.md
@@ -228,6 +228,7 @@ $ kubectl get secret jenkins-token-1yvwg -o yaml
 apiVersion: v1
 data:
  ca.crt: (APISERVER'S CA BASE64 ENCODED)
+  namespace: ZGVmYXVsdA==
  token: (BEARER TOKEN BASE64 ENCODED)
 kind: Secret
 metadata:
@@ -290,7 +291,7 @@ To enable the plugin, configure the following flags on the API server:

 | Parameter | Description | Example | Required |
 | --------- | ----------- | ------- | ------- |
-| `--oidc-issuer-url` | URL of the provider which allows the API server to discover public signing keys. Only URLs which use the `https://` scheme are accepted.  This is typically the provider's discovery URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".  This URL should point to the level below .well-known/openid-configuration | If the discovery URL is https://accounts.google.com/.well-known/openid-configuration the value should be https://accounts.google.com | Yes |
+| `--oidc-issuer-url` | URL of the provider which allows the API server to discover public signing keys. Only URLs which use the `https://` scheme are accepted.  This is typically the provider's discovery URL without a path, for example "https://accounts.google.com" or "https://login.salesforce.com".  This URL should point to the level below .well-known/openid-configuration | If the discovery URL is `https://accounts.google.com/.well-known/openid-configuration`, the value should be `https://accounts.google.com` | Yes |
 | `--oidc-client-id` |  A client id that all tokens must be issued for. | kubernetes | Yes |
 | `--oidc-username-claim` | JWT claim to use as the user name. By default `sub`, which is expected to be a unique identifier of the end user. Admins can choose other claims, such as `email` or `name`, depending on their provider. However, claims other than `email` will be prefixed with the issuer URL to prevent naming clashes with other plugins. | sub | No |
 | `--oidc-groups-claim` | JWT claim to use as the user's group. If the claim is present it must be an array of strings. | groups | No |
@@ -323,7 +324,8 @@ For an identity provider to work with Kubernetes it must:
 2.  Run in TLS with non-obsolete ciphers
 3.  Have a CA signed certificate (even if the CA is not a commercial CA or is self signed)

-A note about requirement #3 above, requiring a CA signed certificate.  If you deploy your own identity provider (as opposed to one of the cloud providers like Google or Microsoft) you MUST have your identity provider's web server certificate signed by a certificate with the `CA` flag set to `TRUE`, even if it is self signed.  This is due to GoLang's TLS client implementation being very strict to the standards around certificate validation.  If you don't have a CA handy, you can use this script from the CoreOS team to create a simple CA and a signed certificate and key pair - https://github.com/coreos/dex/blob/1ee5920c54f5926d6468d2607c728b71cfe98092/examples/k8s/gencert.sh or this script based on it that will generate SHA256 certs with a longer life and larger key size https://raw.githubusercontent.com/TremoloSecurity/openunison-qs-kubernetes/master/makecerts.sh.
+A note about requirement #3 above, requiring a CA signed certificate.  If you deploy your own identity provider (as opposed to one of the cloud providers like Google or Microsoft) you MUST have your identity provider's web server certificate signed by a certificate with the `CA` flag set to `TRUE`, even if it is self signed.  This is due to GoLang's TLS client implementation being very strict to the standards around certificate validation.  If you don't have a CA handy, you can use [this script](https://github.com/coreos/dex/blob/1ee5920c54f5926d6468d2607c728b71cfe98092/examples/k8s/gencert.sh) from the CoreOS team to create a simple CA and a signed certificate and key pair.
+Or you can use [this similar script](https://raw.githubusercontent.com/TremoloSecurity/openunison-qs-kubernetes/master/makecerts.sh) that generates SHA256 certs with a longer life and larger key size.

 Setup instructions for specific systems:

@@ -683,6 +683,7 @@ In order from most secure to least secure, the approaches are:
   NOTE: Permissions given to the "default" service account are available to any pod in the namespace that does not specify a `serviceAccountName`.

   For example, grant read-only permission within "my-namespace" to the "default" service account:
+   
   ```shell
   kubectl create rolebinding default-view \
     --clusterrole=view \
@@ -65,6 +65,7 @@ or service through the apiserver's proxy functionality.
 ### apiserver -> kubelet

 The connections from the apiserver to the kubelet are used for:
+
  * Fetching logs for pods.
  * Attaching (through kubectl) to running pods.
  * Providing the kubelet's port-forwarding functionality. 
@@ -0,0 +1,61 @@
+---
+title: Cloud Providers
+---
+
+{% capture overview %}
+This page explains how to manage Kubernetes running on a specific
+cloud provider.
+{% endcapture %}
+
+{% capture body %}
+# AWS
+This section describes all the possible configurations which can
+be used when running Kubernetes on Amazon Web Services.
+
+## Load Balancers
+You can setup [external load balancers](/docs/tasks/access-application-cluster/create-external-load-balancer)
+to use specific features in AWS by configuring the annotations as shown below.
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: example
+  namespace: kube-system
+  labels:
+    run: example
+  annotations:
+     service.beta.kubernetes.io/aws-load-balancer-ssl-cert: arn:aws:acm:xx-xxxx-x:xxxxxxxxx:xxxxxxx/xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx #replace this value
+     service.beta.kubernetes.io/aws-load-balancer-backend-protocol: http
+spec:
+  type: LoadBalancer
+  ports:
+  - port: 443
+    targetPort: 5556
+    protocol: TCP
+  selector:
+    app: example
+```
+Different settings can be applied to a load balancer service in AWS using _annotations_. The following describes the annotations supported on AWS ELBs:
+
+* `service.beta.kubernetes.io/aws-load-balancer-access-log-emit-interval`: Used to specify access log emit interval.
+* `service.beta.kubernetes.io/aws-load-balancer-access-log-enabled`: Used on the service to enable or disable access logs.
+* `service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-name`: Used to specify access log s3 bucket name.
+* `service.beta.kubernetes.io/aws-load-balancer-access-log-s3-bucket-prefix`: Used to specify access log s3 bucket prefix.
+* `service.beta.kubernetes.io/aws-load-balancer-additional-resource-tags`: Used on the service to specify a comma-separated list of key-value pairs which will be recorded as additional tags in the ELB. For example: `"Key1=Val1,Key2=Val2,KeyNoVal1=,KeyNoVal2"`.
+* `service.beta.kubernetes.io/aws-load-balancer-backend-protocol`: Used on the service to specify the protocol spoken by the backend (pod) behind a listener. If `http` (default) or `https`, an HTTPS listener that terminates the connection and parses headers is created. If set to `ssl` or `tcp`, a "raw" SSL listener is used. If set to `http` and `aws-load-balancer-ssl-cert` is not used then a HTTP listener is used.
+* `service.beta.kubernetes.io/aws-load-balancer-ssl-cert`: Used on the service to request a secure listener. Value is a valid certificate ARN. For more, see http://docs.aws.amazon.com/ElasticLoadBalancing/latest/DeveloperGuide/elb-listener-config.html CertARN is an IAM or CM certificate ARN, e.g. `arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012`.
+* `service.beta.kubernetes.io/aws-load-balancer-connection-draining-enabled`: Used on the service to enable or disable connection draining.
+* `service.beta.kubernetes.io/aws-load-balancer-connection-draining-timeout`: Used on the service to specify a connection draining timeout.
+* `service.beta.kubernetes.io/aws-load-balancer-connection-idle-timeout`: Used on the service to specify the idle connection timeout.
+* `service.beta.kubernetes.io/aws-load-balancer-cross-zone-load-balancing-enabled`: Used on the service to enable or disable cross-zone load balancing.
+* `service.beta.kubernetes.io/aws-load-balancer-extra-security-groups`: Used one the service to specify additional security groups to be added to ELB created
+* `service.beta.kubernetes.io/aws-load-balancer-internal`: Used on the service to indicate that we want an internal ELB.
+* `service.beta.kubernetes.io/aws-load-balancer-proxy-protocol`: Used on the service to enable the proxy protocol on an ELB. Right now we only accept the value `*` which means enable the proxy protocol on all ELB backends. In the future we could adjust this to allow setting the proxy protocol only on certain backends.
+* `service.beta.kubernetes.io/aws-load-balancer-ssl-ports`: Used on the service to specify a comma-separated list of ports that will use SSL/HTTPS listeners. Defaults to `*` (all)
+
+The information for the annotations for AWS is taken from the comments on [aws.go](https://github.com/kubernetes/kubernetes/blob/master/pkg/cloudprovider/providers/aws/aws.go)
+
+{% endcapture %}
+
+{% include templates/concept.md %}
@@ -60,7 +60,7 @@ so that logs don't consume all available storage on the node. Kubernetes
 currently is not responsible for rotating logs, but rather a deployment tool
 should set up a solution to address that.
 For example, in Kubernetes clusters, deployed by the `kube-up.sh` script,
-there is a [`logrotate`](http://www.linuxcommand.org/man_pages/logrotate8.html)
+there is a [`logrotate`](https://linux.die.net/man/8/logrotate)
 tool configured to run each hour. You can also set up a container runtime to
 rotate application's logs automatically, e.g. by using Docker's `log-opt`.
 In the `kube-up.sh` script, the latter approach is used for COS image on GCP,
@@ -135,14 +135,12 @@ When using Docker:
  [`--cpu-shares`](https://docs.docker.com/engine/reference/run/#/cpu-share-constraint)
  flag in the `docker run` command.

- The `spec.containers[].resources.limits.cpu` is converted to its millicore value,
-  multiplied by 100000, and then divided by 1000. This number is used as the value
-  of the [`--cpu-quota`](https://docs.docker.com/engine/reference/run/#/cpu-quota-constraint)
-  flag in the `docker run` command.  The [`--cpu-period`] flag is set to 100000,
-   which represents the default 100ms period for measuring quota usage. The
-   kubelet enforces cpu limits if it is started with the
-  [`--cpu-cfs-quota`] flag set to true. As of Kubernetes version 1.2, this flag
-  defaults to true.
+- The `spec.containers[].resources.limits.cpu` is converted to its millicore value and
+  multiplied by 100. The resulting value is the total amount of CPU time that a container can use
+  every 100ms. A container cannot use more than its share of CPU time during this interval.
+
+  **Note**: The default quota period is 100ms. The minimum resolution of CPU quota is 1ms.
+  {: .note}

 - The `spec.containers[].resources.limits.memory` is converted to an integer, and
  used as the value of the
@@ -434,4 +432,3 @@ consistency across providers and platforms.
 {% endcapture %}

 {% include templates/concept.md %}
-
@@ -80,13 +80,14 @@ $ kubectl describe svc my-nginx
 Name:                my-nginx
 Namespace:           default
 Labels:              run=my-nginx
+Annotations:         <none>
 Selector:            run=my-nginx
 Type:                ClusterIP
 IP:                  10.0.162.149
 Port:                <unset> 80/TCP
 Endpoints:           10.244.2.5:80,10.244.3.4:80
 Session Affinity:    None
-No events.
+Events:              <none>

 $ kubectl get ep my-nginx
 NAME       ENDPOINTS                     AGE
@@ -112,11 +112,11 @@ Some uses for an `emptyDir` are:
  container serves the data

 By default, `emptyDir` volumes are stored on whatever medium is backing the
-machine - that might be disk or SSD or network storage, depending on your
+node - that might be disk or SSD or network storage, depending on your
 environment.  However, you can set the `emptyDir.medium` field to `"Memory"`
 to tell Kubernetes to mount a tmpfs (RAM-backed filesystem) for you instead.
 While tmpfs is very fast, be aware that unlike disks, tmpfs is cleared on
-machine reboot and any files you write will count against your container's
+node reboot and any files you write will count against your container's
 memory limit.

 #### Example pod
@@ -41,14 +41,29 @@ Check on the status of the job using this command:
 $ kubectl describe jobs/pi
 Name:             pi
 Namespace:        default
-Image(s):         perl
 Selector:         controller-uid=b1db589a-2c8d-11e6-b324-0209dc45a495
+Labels:           controller-uid=b1db589a-2c8d-11e6-b324-0209dc45a495
+                  job-name=pi
+Annotations:      <none>
 Parallelism:      1
 Completions:      1
 Start Time:       Tue, 07 Jun 2016 10:56:16 +0200
-Labels:           controller-uid=b1db589a-2c8d-11e6-b324-0209dc45a495,job-name=pi
 Pods Statuses:    0 Running / 1 Succeeded / 0 Failed
-No volumes.
+Pod Template:
+  Labels:       controller-uid=b1db589a-2c8d-11e6-b324-0209dc45a495
+                job-name=pi
+  Containers:
+   pi:
+    Image:      perl
+    Port:
+    Command:
+      perl
+      -Mbignum=bpi
+      -wle
+      print bpi(2000)
+    Environment:        <none>
+    Mounts:             <none>
+  Volumes:              <none>
 Events:
  FirstSeen    LastSeen    Count    From            SubobjectPath    Type        Reason            Message
  ---------    --------    -----    ----            -------------    --------    ------            -------
@@ -61,12 +61,25 @@ replicaset "frontend" created
 $ kubectl describe rs/frontend
 Name:          frontend
 Namespace:     default
-Image(s):      gcr.io/google_samples/gb-frontend:v3
 Selector:      tier=frontend,tier in (frontend)
 Labels:        app=guestbook,tier=frontend
+Annotations:   <none>
 Replicas:      3 current / 3 desired
 Pods Status:   3 Running / 0 Waiting / 0 Succeeded / 0 Failed
-No volumes.
+Pod Template:
+  Labels:       app=guestbook
+                tier=frontend
+  Containers:
+   php-redis:
+    Image:      gcr.io/google_samples/gb-frontend:v3
+    Port:       80/TCP
+    Requests:
+      cpu:      100m
+      memory:   100Mi
+    Environment:
+      GET_HOSTS_FROM:   dns
+    Mounts:             <none>
+  Volumes:              <none>
 Events:
  FirstSeen    LastSeen    Count    From                SubobjectPath    Type        Reason            Message
  ---------    --------    -----    ----                -------------    --------    ------            -------
@@ -55,11 +55,20 @@ Check on the status of the ReplicationController using this command:
 $ kubectl describe replicationcontrollers/nginx
 Name:        nginx
 Namespace:   default
-Image(s):    nginx
 Selector:    app=nginx
 Labels:      app=nginx
+Annotations:    <none>
 Replicas:    3 current / 3 desired
 Pods Status: 0 Running / 3 Waiting / 0 Succeeded / 0 Failed
+Pod Template:
+  Labels:       app=nginx
+  Containers:
+   nginx:
+    Image:              nginx
+    Port:               80/TCP
+    Environment:        <none>
+    Mounts:             <none>
+  Volumes:              <none>
 Events:
  FirstSeen       LastSeen     Count    From                        SubobjectPath    Type      Reason              Message
  ---------       --------     -----    ----                        -------------    ----      ------              -------
@@ -128,7 +128,7 @@ Pods which are deleted or unavailable due to a rolling upgrade to an application
 against the disruption budget, but controllers (like deployment and stateful-set)
 are not limited by PDBs when doing rolling upgrades -- the handling of failures
 during application updates is configured in the controller spec.
-(Learn about [updating a deployment](/docs/concepts/cluster-administration/manage-deployment/#updating-your-application-without-a-service-outage).)
+(Learn about [updating a deployment](/docs/concepts/workloads/controllers/deployment/#updating-a-deployment).)

 When a pod is evicted using the eviction API, it is gracefully terminated (see
 `terminationGracePeriodSeconds` in [PodSpec](/docs/resources-reference/{{page.version}}/#podspec-v1-core).)
@@ -37,7 +37,7 @@ For more details on the release process see the [`build`](http://releases.k8s.io

 ### Download Kubernetes and automatically set up a default cluster

-The bash script at `https://get.k8s.io`, which can be run with `wget` or `curl`, automatically downloads Kubernetes, and provisions a cluster based on your desired cloud provider.
+The bash script at [`https://get.k8s.io`](https://get.k8s.io), which can be run with `wget` or `curl`, automatically downloads Kubernetes, and provisions a cluster based on your desired cloud provider.

 ```shell
 # wget version
@@ -327,7 +327,7 @@ Future work will add instructions to this guide to enable support for Kubernetes

 [1]: https://docs.mesosphere.com/latest/usage/service-guides/hdfs/
 [2]: https://docs.mesosphere.com/latest/usage/service-guides/spark/
-[3]: https://docs.mesosphere.com/latest/usage/service-guides/chronos/
+[3]: https://mesos.github.io/chronos/docs/getting-started.html
 [4]: https://releases.k8s.io/{{page.githubbranch}}/cluster/addons/dns/README.md
 [5]: https://dcos.io/docs/latest/administration/installing/cloud/gce/
 [6]: http://mesos.apache.org/
@@ -864,10 +864,10 @@ Example usage and output:
 ```shell
 KUBECTL_PATH=$(which kubectl) NUM_NODES=3 KUBERNETES_PROVIDER=local cluster/validate-cluster.sh
 Found 3 node(s).
-NAME                    STATUS    AGE
-node1.local             Ready     1h
-node2.local             Ready     1h
-node3.local             Ready     1h
+NAME                    STATUS    AGE     VERSION
+node1.local             Ready     1h      v1.6.9+a3d1dfa6f4335
+node2.local             Ready     1h      v1.6.9+a3d1dfa6f4335
+node3.local             Ready     1h      v1.6.9+a3d1dfa6f4335
 Validate output:
 NAME                 STATUS    MESSAGE              ERROR
 controller-manager   Healthy   ok
@@ -112,7 +112,7 @@ Note that resource names are not case-sensitive when using kubectl,
 and you can use either the singular or plural forms defined in the CRD,
 as well as any short names.

-You can also view the raw JSON data:
+You can also view the raw YAML data:

 ```shell
 kubectl get ct -o yaml
@@ -178,7 +178,3 @@ meaning all finalizers are done.
 {% endcapture %}

 {% include templates/task.md %}
-
-
-
-
@@ -29,8 +29,8 @@ For example, this is how to start a simple web server as a static pod:
 2. Choose a directory, say `/etc/kubelet.d` and place a web server pod definition there, e.g. `/etc/kubelet.d/static-web.yaml`:

    ```
-    [root@my-node1 ~] $ mkdir /etc/kubernetes.d/
-    [root@my-node1 ~] $ cat <<EOF >/etc/kubernetes.d/static-web.yaml
+    [root@my-node1 ~] $ mkdir /etc/kubelet.d/
+    [root@my-node1 ~] $ cat <<EOF >/etc/kubelet.d/static-web.yaml
    apiVersion: v1
    kind: Pod
    metadata:
@@ -189,6 +189,7 @@ The following information is available to Containers through environment
 variables and DownwardAPIVolumeFiles:

 * The node’s name
+* The node's IP
 * The Pod’s name
 * The Pod’s namespace
 * The Pod’s IP address
@@ -20,7 +20,7 @@ Here are a few methods to install kubectl.
 {% capture macos %}
 1. Download the latest release with the command:

-       curl -LO https://storage.googleapis.com/kubernetes-release/release/$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)/bin/darwin/amd64/kubectl
+       curl -LO https://storage.googleapis.com/kubernetes-release/release/`curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt`/bin/darwin/amd64/kubectl

    To download a specific version, replace the `$(curl -s https://storage.googleapis.com/kubernetes-release/release/stable.txt)` portion of the command with the specific version.

@@ -24,11 +24,11 @@ The docker is based on `debian:jessie` and includes OpenJDK 8. This image includ
 {% endcapture %}

 {% capture objectives %}
-* Create and Validate a Cassandra headless `Service`.
-* Use a `StatefulSet` to create a Cassandra ring.
-* Validate the `StatefulSet`.
-* Modify the `StatefulSet`.
-* Delete the `StatefulSet` and its `Pods`.
+* Create and Validate a Cassandra headless [Services](/docs/concepts/services-networking/service/).
+* Use a [StatefulSet](/docs/concepts/workloads/controllers/statefulset/) to create a Cassandra ring.
+* Validate the [StatefulSet](/docs/concepts/workloads/controllers/statefulset/).
+* Modify the [StatefulSet](/docs/concepts/workloads/controllers/statefulset/).
+* Delete the [StatefulSet](/docs/concepts/workloads/controllers/statefulset/) and its [Pods](/docs/concepts/workloads/pods/pod/).
 {% endcapture %}

 {% capture prerequisites %}
@@ -367,7 +367,7 @@ statefulset "zk" deleted
 Watch the termination of the Pods in the StatefulSet.

 ```shell
-get pods -w -l app=zk
+kubectl get pods -w -l app=zk
 ```

 When `zk-0` if fully terminated, use `CRTL-C` to terminate kubectl.
@@ -235,8 +235,8 @@ With kubectl:

 ```shell
 $ kubectl version
-Client Version: version.Info{Major:"0", Minor:"20.1", GitVersion:"v0.20.1", GitCommit:"", GitTreeState:"not a git tree"}
-Server Version: version.Info{Major:"0", Minor:"21+", GitVersion:"v0.21.1-411-g32699e873ae1ca-dirty", GitCommit:"32699e873ae1caa01812e41de7eab28df4358ee4", GitTreeState:"dirty"}
+Client Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}
+Server Version: version.Info{Major:"1", Minor:"6", GitVersion:"v1.6.9+a3d1dfa6f4335", GitCommit:"9b77fed11a9843ce3780f70dd251e92901c43072", GitTreeState:"dirty", BuildDate:"2017-08-29T20:32:58Z", OpenPaasKubernetesVersion:"v1.03.02", GoVersion:"go1.7.5", Compiler:"gc", Platform:"linux/amd64"}
 ```

 #### docker info