Merge branch 'master' into chrismarino-patch

_data/guides.yml

@@ -14,6 +14,8 @@ toc:
     path: /docs/getting-started-guides/kops/
   - title: Hello World on Google Container Engine
     path: /docs/hellonode/
+  - title: Installing kubectl
+    path: /docs/getting-started-guides/kubectl/
   - title: Downloading or Building Kubernetes
     path: /docs/getting-started-guides/binary_release/
   - title: Online Training Course

_data/tasks.yml

@@ -15,6 +15,14 @@ toc:
   section:
   - title: Using Port Forwarding to Access Applications in a Cluster
     path: /docs/tasks/access-application-cluster/port-forward-access-application-cluster/
+
+
+- title: Debugging Applications in a Cluster
+  section:
+  - title: Determining the Reason for Pod Failure
+    path: /docs/tasks/debug-application-cluster/determine-reason-pod-failure/
+
+
 - title: Accessing the Kubernetes API
   section:
   - title: Using an HTTP Proxy to Access the Kubernetes API

_includes/footer.html

@@ -20,6 +20,8 @@
 				<a href="https://calendar.google.com/calendar/embed?src=nt2tcnbtbied3l6gi2h29slvc0%40group.calendar.google.com" class="calendar"><span>Events Calendar</span></a>
 			</div>
 			<div>
+				<a href="//get.k8s.io" class="button">Download K8s</a>
+				<a href="https://github.com/kubernetes/kubernetes" class="button">Contribute to the K8s codebase</a>
 			</div>
 		</div>
 		<div id="miceType" class="center">&copy; {{ 'now' | date: "%Y" }} Kubernetes</div>

_layouts/docwithnav.html

@@ -80,6 +80,34 @@
   })(window,document,'script','//www.google-analytics.com/analytics.js','ga');
   ga('create', 'UA-36037335-10', 'auto');
   ga('send', 'pageview');
+	
+  // hide docs nav area if no nav is present, or if nav only contains a link to the current page
+  (function () {
+	  window.addEventListener('DOMContentLoaded', init)
+	  
+	  // play nice with our neighbors
+	  function init() {
+		  window.removeEventListener('DOMContentLoaded', init)
+		  hideNav()
+	  }
+	  
+	  function hideNav(toc){
+		  if (!toc) toc = document.querySelector('#docsToc')
+		  var container = toc.querySelector('.container')
+		  
+		  // container is built dynamically, so it may not be present on the first runloop
+		  if (container) {
+			  if (container.childElementCount === 0 || toc.querySelectorAll('a.item').length === 1) {
+				  toc.style.display = 'none'
+				  document.getElementById('docsContent').style.width = '100%'
+			  }
+		  } else {
+			  requestAnimationFrame(function () {
+				  hideNav(toc)
+			  })
+		  }
+	  }
+  })();
 </script>
 <!-- Commenting out AnswerDash for now; we need to work on our list of questions/answers/design first
 <!-- Start of AnswerDash script <script>var AnswerDash;!function(e,t,n,s,a){if(!t.getElementById(s)){var i,r=t.createElement(n),c=t.getElementsByTagName(n)[0];e[a]||(i=e[a]=function(){i.__oninit.push(arguments)},i.__oninit=[]),r.type="text/javascript",r.async=!0,r.src="https://p1.answerdash.com/answerdash.min.js?siteid=756",r.setAttribute("id",s),c.parentNode.insertBefore(r,c)}}(window,document,"script","answerdash-script","AnswerDash");</script> <!-- End of AnswerDash script -->

_sass/_base.sass

@@ -390,6 +390,14 @@ footer
 		height: 0
 		overflow: hidden
 		
+	&.button
+		background-image: none
+		width: auto
+		height: auto
+		
+		&:hover
+			color: $blue
+
 a.twitter
 	background-position: 0 0
 
@@ -874,8 +882,19 @@ dd
 	img
 		max-width: 100%
 
+	a
+		//font-weight: 700
+		text-decoration: underline
+
+	a:visited
+		color: blueviolet
+
 	a.button
 		border-radius: 2px
+		text-decoration: none
+		
+		&:visited
+			color: white
 
 	a.issue
 		margin-left: 20px

docs/getting-started-guides/kubectl.md

@@ -0,0 +1,110 @@
+---
+---
+
+<style>
+li>.highlighter-rouge {position:relative; top:3px;}
+</style>
+
+## Overview
+
+kubectl is the command line tool you use to interact with Kubernetes clusters.
+
+You should use a version of kubectl that is at least as new as your server.
+`kubectl version` will print the server and client versions.  Using the same version of kubectl
+as your server naturally works; using a newer kubectl than your server also works; but if you use
+an older kubectl with a newer server you may see odd validation errors .
+
+## Download a release
+
+Download kubectl from the [official Kubernetes releases](https://console.cloud.google.com/storage/browser/kubernetes-release/release/):
+
+On MacOS:
+
+```shell
+wget https://storage.googleapis.com/kubernetes-release/release/v1.4.4/bin/darwin/amd64/kubectl
+chmod +x kubectl
+mv kubectl /usr/local/bin/kubectl
+```
+
+On Linux:
+
+```shell
+wget https://storage.googleapis.com/kubernetes-release/release/v1.4.4/bin/linux/amd64/kubectl
+chmod +x kubectl
+mv kubectl /usr/local/bin/kubectl
+```
+
+
+You may need to `sudo` the `mv`; you can put it anywhere in your `PATH` - some people prefer to install to `~/bin`.
+
+
+## Alternatives
+
+### Download as part of the Google Cloud SDK
+
+kubectl can be installed as part of the Google Cloud SDK:
+
+First install the [Google Cloud SDK](https://cloud.google.com/sdk/).
+
+After Google Cloud SDK installs, run the following command to install `kubectl`:
+
+```shell
+gcloud components install kubectl
+```
+
+Do check that the version is sufficiently up-to-date using `kubectl version`.
+
+### Install with brew
+
+If you are on MacOS and using brew, you can install with:
+
+```shell
+brew install kubectl
+```
+
+The homebrew project is independent from kubernetes, so do check that the version is
+sufficiently up-to-date using `kubectl version`.
+
+
+# Enabling shell autocompletion
+
+kubectl includes autocompletion support, which can save a lot of typing!
+
+The completion script itself is generated by kubectl, so you typically just need to invoke it from your profile.
+
+Common examples are provided here, but for more details please consult `kubectl completion -h`
+
+## On Linux, using bash
+
+To add it to your current shell: `source <(kubectl completion bash)`
+
+To add kubectl autocompletion to your profile (so it is automatically loaded in future shells):
+
+```shell
+echo "source <(kubectl completion bash)" >> ~/.bashrc
+```
+
+## On MacOS, using bash
+
+On MacOS, you will need to install the bash-completion support first:
+
+```shell
+brew install bash-completion
+```
+
+To add it to your current shell:
+
+```shell
+source $(brew --prefix)/etc/bash_completion
+source <(kubectl completion bash)
+```
+
+To add kubectl autocompletion to your profile (so it is automatically loaded in future shells):
+
+```shell
+echo "source $(brew --prefix)/etc/bash_completion" >> ~/.bash_profile
+echo "source <(kubectl completion bash)" >> ~/.bash_profile
+```
+
+Please note that this only appears to work currently if you install using `brew install kubectl`,
+and not if you downloaded kubectl directly.

docs/tasks/debug-application-cluster/determine-reason-pod-failure.md

@@ -0,0 +1,110 @@
+---
+---
+
+{% capture overview %}
+
+This page shows how to write and read a Container
+termination message.
+
+Termination messages provide a way for containers to write
+information about fatal events to a location where it can
+be easily retrieved and surfaced by tools like dashboards
+and monitoring software. In most cases, information that you
+put in a termination message should also be written to
+the general
+[Kubernetes logs](/docs/user-guide/logging/).
+
+{% endcapture %}
+
+
+{% capture prerequisites %}
+
+{% include task-tutorial-prereqs.md %}
+
+{% endcapture %}
+
+
+{% capture steps %}
+
+### Writing and reading a termination message
+
+In this exercise, you create a Pod that runs one container.
+The configuration file specifies a command that runs when
+the container starts.
+
+{% include code.html language="yaml" file="termination.yaml" ghlink="/docs/tasks/debug-pod-container/termination.yaml" %}
+
+1. Create a Pod based on the YAML configuration file:
+
+        export REPO=https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master
+        kubectl create -f $REPO/docs/tasks/debug-pod-container/termination.yaml
+
+    In the YAML file, in the `cmd` and `args` fields, you can see that the
+    container sleeps for 10 seconds and then writes "Sleep expired" to
+    the `/dev/termination-log` file. After the container writes
+    the "Sleep expired" message, it terminates.
+
+1. Display information about the Pod:
+
+        kubectl get pod termination-demo
+
+    Repeat the preceding command until the Pod is no longer running.
+
+1. Display detailed information about the Pod:
+
+        kubectl get pod --output=yaml
+
+    The output includes the "Sleep expired" message:
+
+        apiVersion: v1
+        kind: Pod
+        ...
+            lastState:
+              terminated:
+                containerID: ...
+                exitCode: 0
+                finishedAt: ...
+                message: |
+                  Sleep expired
+                ...
+
+1. Use a Go template to filter the output so that it includes
+only the termination message:
+        
+```
+{% raw %}    kubectl get pod termination-demo -o go-template="{{range .status.containerStatuses}}{{.lastState.terminated.message}}{{end}}"{% endraw %}
+```
+
+### Setting the termination log file
+
+By default Kubernetes retrieves termination messages from
+`/dev/termination-log`. To change this to a different file,
+specify a `terminationMessagePath` field for your Container.
+
+For example, suppose your Container writes termination messages to
+`/tmp/my-log`, and you want Kubernetes to retrieve those messages.
+Set `terminationMessagePath` as shown here:
+
+    apiVersion: v1
+    kind: Pod
+    metadata:
+      name: msg-path-demo
+    spec:
+      containers:
+      - name: msg-path-demo-container
+        image: debian
+        terminationMessagePath: "/tmp/my-log"
+
+{% endcapture %}
+
+{% capture whatsnext %}
+
+* See the `terminationMessagePath` field in 
+  [Container](/docs/api-reference/v1/definitions#_v1_container).
+* Learn about [retrieving logs](/docs/user-guide/logging/).
+* Learn about [Go templates](https://golang.org/pkg/text/template/).
+
+{% endcapture %}
+
+
+{% include templates/task.md %}

docs/tasks/debug-application-cluster/termination.yaml

@@ -0,0 +1,10 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: termination-demo
+spec:
+  containers:
+  - name: termination-demo-container
+    image: debian
+    command: ["/bin/sh"]
+    args: ["-c", "sleep 10 && echo Sleep expired > /dev/termination-log"]

docs/user-guide/accessing-the-cluster.md

@@ -129,7 +129,7 @@ To use it,
 * Write an application atop of the client-go clients. Note that client-go defines its own API objects, so if needed, please import API definitions from client-go rather than from the main repository, e.g., `import "k8s.io/client-go/1.4/pkg/api/v1"` is correct.
 
 The Go client can use the same [kubeconfig file](/docs/user-guide/kubeconfig-file)
-as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/examples/out-of-cluster.go):
+as the kubectl CLI does to locate and authenticate to the apiserver. See this [example](https://github.com/kubernetes/client-go/blob/master/examples/out-of-cluster/main.go):
 
 ```golang
 import (
@@ -183,7 +183,8 @@ From within a pod the recommended ways to connect to API are:
     in any container of the pod can access it.  See this [example of using kubectl proxy
     in a pod](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/kubectl-container/).
   - use the Go client library, and create a client using the `client.NewInCluster()` factory.
-    This handles locating and authenticating to the apiserver. [example](https://github.com/kubernetes/client-go/examples/in-cluster.go)
+    This handles locating and authenticating to the apiserver. See this [example of using Go client
+    library in a pod](https://github.com/kubernetes/client-go/blob/master/examples/in-cluster/main.go).
 
 In each case, the credentials of the pod are used to communicate securely with the apiserver.