diff --git a/_data/guides.yml b/_data/guides.yml index 85c5dd4103..f3ed275e9f 100644 --- a/_data/guides.yml +++ b/_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 diff --git a/_data/tasks.yml b/_data/tasks.yml index 4c6cd1b709..9898fae32f 100644 --- a/_data/tasks.yml +++ b/_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 diff --git a/_includes/footer.html b/_includes/footer.html index 15dacb72e0..e7fa36d26a 100644 --- a/_includes/footer.html +++ b/_includes/footer.html @@ -20,6 +20,8 @@ Events Calendar
+ Download K8s + Contribute to the K8s codebase
© {{ 'now' | date: "%Y" }} Kubernetes
diff --git a/_layouts/docwithnav.html b/_layouts/docwithnav.html index 8ca0906065..f3d885d246 100755 --- a/_layouts/docwithnav.html +++ b/_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) + }) + } + } + })(); diff --git a/_sass/_base.sass b/_sass/_base.sass index a8ac4b47c4..1eabc9ac14 100644 --- a/_sass/_base.sass +++ b/_sass/_base.sass @@ -389,6 +389,14 @@ footer display: block 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 diff --git a/_sass/_reset.sass b/_sass/_reset.sass index 9f4a43a68e..2a8bb1b6d2 100755 --- a/_sass/_reset.sass +++ b/_sass/_reset.sass @@ -15,7 +15,7 @@ ul, li ul margin: 0 padding: 0 - + a text-decoration: none diff --git a/docs/getting-started-guides/kubectl.md b/docs/getting-started-guides/kubectl.md new file mode 100644 index 0000000000..bd2512707b --- /dev/null +++ b/docs/getting-started-guides/kubectl.md @@ -0,0 +1,110 @@ +--- +--- + + + +## 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. \ No newline at end of file diff --git a/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md b/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md new file mode 100644 index 0000000000..f0f611e235 --- /dev/null +++ b/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 %} diff --git a/docs/tasks/debug-application-cluster/termination.yaml b/docs/tasks/debug-application-cluster/termination.yaml new file mode 100644 index 0000000000..3f63748f72 --- /dev/null +++ b/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"] diff --git a/docs/user-guide/accessing-the-cluster.md b/docs/user-guide/accessing-the-cluster.md index 6f78ab5293..63134b4909 100644 --- a/docs/user-guide/accessing-the-cluster.md +++ b/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.