From 8a484aff51fd0333dfe84a572901914d904eec6a Mon Sep 17 00:00:00 2001 From: gavinB-orange Date: Tue, 4 Oct 2016 19:08:22 +0200 Subject: [PATCH 01/17] Update minikube.md to cover use behind a web proxy In a corporate environment you need to pass proxy information, and just setting the appropriate environment variables does not work. The code snippet here works for me --- docs/getting-started-guides/minikube.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index 020fc5e257..1ad16b6d28 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -99,6 +99,14 @@ Kubectl is now configured to use the cluster. This will build and start a lightweight local cluster, consisting of a master, etcd, Docker and a single node. +If you are behind a web proxy, you will need to pass this information in e.g. via + +``` + +https_proxy= minikube start --docker-env HTTP_PROXY= --docker-env HTTPS_PROXY= --docker-env NO_PROXY=192.168.99.0/24 + +Unfortunately just setting the environment variables will not work. +``` Minikube will also create a "minikube" context, and set it to default in kubectl. To switch back to this context later, run this command: `kubectl config use-context minikube`. From 8048e7d2fcb6f40236a081d7b7750e32dcca56f9 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Wed, 11 Jan 2017 09:24:01 -0800 Subject: [PATCH 02/17] Fix link. --- docs/user-guide/environment-guide/index.md | 184 +++++++++++---------- 1 file changed, 94 insertions(+), 90 deletions(-) diff --git a/docs/user-guide/environment-guide/index.md b/docs/user-guide/environment-guide/index.md index 64f1e4a019..417cf5be33 100644 --- a/docs/user-guide/environment-guide/index.md +++ b/docs/user-guide/environment-guide/index.md @@ -4,93 +4,97 @@ assignees: title: Using Environment Variables --- -This example demonstrates running pods, replication controllers, and -services. It shows two types of pods: frontend and backend, with -services on top of both. Accessing the frontend pod will return -environment information about itself, and a backend pod that it has -accessed through the service. The goal is to illuminate the -environment metadata available to running containers inside the -Kubernetes cluster. The documentation for the Kubernetes environment -is [here](/docs/user-guide/container-environment). - -![Diagram](/images/docs/diagram.png) - -## Prerequisites - -This example assumes that you have a Kubernetes cluster installed and -running, and that you have installed the `kubectl` command line tool -somewhere in your path. Please see the [getting -started](/docs/getting-started-guides/) for installation instructions -for your platform. - -## Optional: Build your own containers - -The code for the containers is under -[containers/](/docs/user-guide/containers/) - -## Get everything running - -```shell -kubectl create -f ./backend-rc.yaml -kubectl create -f ./backend-srv.yaml -kubectl create -f ./show-rc.yaml -kubectl create -f ./show-srv.yaml -``` - -## Query the service - -Use `kubectl describe service show-srv` to determine the public IP of -your service. - -> Note: If your platform does not support external load balancers, - you'll need to open the proper port and direct traffic to the - internal IP shown for the frontend service with the above command - -Run `curl :80` to query the service. You should get -something like this back: - -```shell -Pod Name: show-rc-xxu6i -Pod Namespace: default -USER_VAR: important information - -Kubernetes environment variables -BACKEND_SRV_SERVICE_HOST = 10.147.252.185 -BACKEND_SRV_SERVICE_PORT = 5000 -KUBERNETES_RO_SERVICE_HOST = 10.147.240.1 -KUBERNETES_RO_SERVICE_PORT = 80 -KUBERNETES_SERVICE_HOST = 10.147.240.2 -KUBERNETES_SERVICE_PORT = 443 -KUBE_DNS_SERVICE_HOST = 10.147.240.10 -KUBE_DNS_SERVICE_PORT = 53 - -Found backend ip: 10.147.252.185 port: 5000 -Response from backend -Backend Container -Backend Pod Name: backend-rc-6qiya -Backend Namespace: default -``` - -First the frontend pod's information is printed. The pod name and -[namespace](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md) are retrieved from the -[Downward API](/docs/user-guide/downward-api). Next, `USER_VAR` is the name of -an environment variable set in the [pod -definition](/docs/user-guide/environment-guide/show-rc.yaml). Then, the dynamic Kubernetes environment -variables are scanned and printed. These are used to find the backend -service, named `backend-srv`. Finally, the frontend pod queries the -backend service and prints the information returned. Again the backend -pod returns its own pod name and namespace. - -Try running the `curl` command a few times, and notice what -changes. Ex: `watch -n 1 curl -s ` Firstly, the frontend service -is directing your request to different frontend pods each time. The -frontend pods are always contacting the backend through the backend -service. This results in a different backend pod servicing each -request as well. - -## Cleanup - -```shell -kubectl delete rc,service -l type=show-type -kubectl delete rc,service -l type=backend-type -``` +This example demonstrates running pods, replication controllers, and +services. It shows two types of pods: frontend and backend, with +services on top of both. Accessing the frontend pod will return +environment information about itself, and a backend pod that it has +accessed through the service. The goal is to illuminate the +environment metadata available to running containers inside the +Kubernetes cluster. The documentation for the Kubernetes environment +is [here](/docs/user-guide/container-environment). + +![Diagram](/images/docs/diagram.png) + +## Prerequisites + +This example assumes that you have a Kubernetes cluster installed and +running, and that you have installed the `kubectl` command line tool +somewhere in your path. Please see the [getting +started](/docs/getting-started-guides/) for installation instructions +for your platform. + +## Optional: Build your own containers + +These are the configuration files for the containers: + +* [backend-rc.yaml](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/user-guide/environment-guide/backend-rc.yaml) +* [backend-srv.yaml](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/user-guide/environment-guide/backend-srv.yaml) +* [show-rc.yaml](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/user-guide/environment-guide/show-rc.yaml) +* [show-srv.yaml](https://raw.githubusercontent.com/kubernetes/kubernetes.github.io/master/docs/user-guide/environment-guide/show-srv.yaml) + +## Get everything running + +```shell +kubectl create -f ./backend-rc.yaml +kubectl create -f ./backend-srv.yaml +kubectl create -f ./show-rc.yaml +kubectl create -f ./show-srv.yaml +``` + +## Query the service + +Use `kubectl describe service show-srv` to determine the public IP of +your service. + +> Note: If your platform does not support external load balancers, + you'll need to open the proper port and direct traffic to the + internal IP shown for the frontend service with the above command + +Run `curl :80` to query the service. You should get +something like this back: + +```shell +Pod Name: show-rc-xxu6i +Pod Namespace: default +USER_VAR: important information + +Kubernetes environment variables +BACKEND_SRV_SERVICE_HOST = 10.147.252.185 +BACKEND_SRV_SERVICE_PORT = 5000 +KUBERNETES_RO_SERVICE_HOST = 10.147.240.1 +KUBERNETES_RO_SERVICE_PORT = 80 +KUBERNETES_SERVICE_HOST = 10.147.240.2 +KUBERNETES_SERVICE_PORT = 443 +KUBE_DNS_SERVICE_HOST = 10.147.240.10 +KUBE_DNS_SERVICE_PORT = 53 + +Found backend ip: 10.147.252.185 port: 5000 +Response from backend +Backend Container +Backend Pod Name: backend-rc-6qiya +Backend Namespace: default +``` + +First the frontend pod's information is printed. The pod name and +[namespace](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/namespaces.md) are retrieved from the +[Downward API](/docs/user-guide/downward-api). Next, `USER_VAR` is the name of +an environment variable set in the [pod +definition](/docs/user-guide/environment-guide/show-rc.yaml). Then, the dynamic Kubernetes environment +variables are scanned and printed. These are used to find the backend +service, named `backend-srv`. Finally, the frontend pod queries the +backend service and prints the information returned. Again the backend +pod returns its own pod name and namespace. + +Try running the `curl` command a few times, and notice what +changes. Ex: `watch -n 1 curl -s ` Firstly, the frontend service +is directing your request to different frontend pods each time. The +frontend pods are always contacting the backend through the backend +service. This results in a different backend pod servicing each +request as well. + +## Cleanup + +```shell +kubectl delete rc,service -l type=show-type +kubectl delete rc,service -l type=backend-type +``` From 54519b72f93edfa1d46645a1cdebf9f284e22ccc Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Wed, 11 Jan 2017 14:31:32 -0800 Subject: [PATCH 03/17] Fix code and fix link to code. --- docs/tutorials/stateless-application/hello-minikube.md | 2 +- docs/tutorials/stateless-application/server.js | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/stateless-application/hello-minikube.md b/docs/tutorials/stateless-application/hello-minikube.md index 54697ef9c1..42853a62cc 100644 --- a/docs/tutorials/stateless-application/hello-minikube.md +++ b/docs/tutorials/stateless-application/hello-minikube.md @@ -99,7 +99,7 @@ kubectl cluster-info The next step is to write the application. Save this code in a folder named `hellonode` with the filename `server.js`: -{% include code.html language="js" file="server.js" ghlink="docs/tutorials/stateless-application/server.js" %} +{% include code.html language="js" file="server.js" ghlink="/docs/tutorials/stateless-application/server.js" %} Run your application: diff --git a/docs/tutorials/stateless-application/server.js b/docs/tutorials/stateless-application/server.js index 4a31299886..76345a17d8 100644 --- a/docs/tutorials/stateless-application/server.js +++ b/docs/tutorials/stateless-application/server.js @@ -1,3 +1,5 @@ +var http = require('http'); + var handleRequest = function(request, response) { console.log('Received request for URL: ' + request.url); response.writeHead(200); From 809c3cf9b546cd8284f3c002c45c244cc783ba83 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Thu, 12 Jan 2017 16:29:19 -0800 Subject: [PATCH 04/17] Redirect User Guide topic: Working with Containers in Production. --- _data/guides.yml | 1 - docs/tasks/index.md | 3 + docs/user-guide/production-pods.md | 245 ----------------------------- 3 files changed, 3 insertions(+), 246 deletions(-) delete mode 100644 docs/user-guide/production-pods.md diff --git a/_data/guides.yml b/_data/guides.yml index 9d08a88367..c1bdd99a4e 100644 --- a/_data/guides.yml +++ b/_data/guides.yml @@ -71,7 +71,6 @@ toc: - docs/user-guide/pods/init-container.md - docs/user-guide/configuring-containers.md - docs/user-guide/pod-templates.md - - docs/user-guide/production-pods.md - docs/user-guide/containers.md - docs/user-guide/environment-guide/index.md - docs/user-guide/compute-resources.md diff --git a/docs/tasks/index.md b/docs/tasks/index.md index 2482a13677..92521ad0dd 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -1,5 +1,8 @@ --- title: Tasks +redirect_from: +- "/docs/user-guide/production-pods/" +- "/docs/user-guide/production-pods.html" --- This section of the Kubernetes documentation contains pages that diff --git a/docs/user-guide/production-pods.md b/docs/user-guide/production-pods.md deleted file mode 100644 index 586838f852..0000000000 --- a/docs/user-guide/production-pods.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -assignees: -- bgrant0607 -- janetkuo -- thockin -title: Working with Containers in Production ---- - -You've seen [how to configure and deploy pods and containers](/docs/user-guide/configuring-containers), using some of the most common configuration parameters. This section dives into additional features that are especially useful for running applications in production. - -* TOC -{:toc} - -## Using a Volume for storage - -The container file system only lives as long as the container does, so when a container crashes and restarts, changes to the filesystem will be lost and the container will restart from a clean slate. For more consistent storage that lasts for the life of a Pod, you need a [*volume*](/docs/user-guide/volumes). This is especially important to stateful applications, such as key-value stores and databases. - -For example, [Redis](http://redis.io/) is a key-value cache and store, which we use in the [guestbook](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/examples/guestbook/) and other examples. We can add a volume to it to store data as follows: - -{% include code.html language="yaml" file="redis-deployment.yaml" ghlink="/docs/user-guide/redis-deployment.yaml" %} - -`emptyDir` volumes live for the lifespan of the [pod](/docs/user-guide/pods), which is longer than the lifespan of any one container, so if the container fails and is restarted, our storage will live on. - -In addition to the local disk storage provided by `emptyDir`, Kubernetes supports many different network-attached storage solutions, including PD on GCE and EBS on EC2, which are preferred for critical data, and will handle details such as mounting and unmounting the devices on the nodes. See [the volumes doc](/docs/user-guide/volumes) for more details. - -## Distributing credentials - -Many applications need credentials, such as passwords, OAuth tokens, and TLS keys, to authenticate with other applications, databases, and services. Storing these credentials in container images or environment variables is less than ideal, since the credentials can then be copied by anyone with access to the image, pod/container specification, host file system, or host Docker daemon. - -Kubernetes provides a mechanism, called [*secrets*](/docs/user-guide/secrets), that facilitates delivery of sensitive credentials to applications. A `Secret` is a simple resource containing a map of data. For instance, you can create a simple secret with a username and password as follows: - -```shell -$ kubectl create secret generic mysecret --from-literal=username="admin",password="1234" -secret "mysecret" created -``` - -This is equivalent to `kubectl create -f`: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: mysecret -type: Opaque -data: - username: YWRtaW4= - password: MTIzNA== -``` - -As with other resources, the created secret can be viewed with `get`: - -```shell -$ kubectl get secrets -NAME TYPE DATA AGE -default-token-zirbw kubernetes.io/service-account-token 3 3h -mysecret Opaque 2 2m -``` - -To use the secret, you need to reference it in a pod or pod template. The `secret` volume source enables you to mount it as an in-memory directory into your containers. - -{% include code.html language="yaml" file="redis-secret-deployment.yaml" ghlink="/docs/user-guide/redis-secret-deployment.yaml" %} - -For more details, see the [secrets document](/docs/user-guide/secrets), [example](/docs/user-guide/secrets/) and [design doc](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/docs/design/secrets.md). - -## Authenticating with a private image registry - -Secrets can also be used to pass [image registry credentials](/docs/user-guide/images/#using-a-private-registry). - -The easiest way to create a secret for Docker registry is: - -```shell -$ kubectl create secret docker-registry myregistrykey --docker-username=janedoe --docker-password=●●●●●●●●●●● --docker-email=jdoe@example.com -secret "myregistrykey" created -``` - -Alternatively, you can do the equivalent with the following steps. First, create a `.docker/config.json`, such as by running `docker login `. -Then put the resulting `.docker/config.json` file into a [secret resource](secrets.md). For example: - -```shell -$ docker login -Username: janedoe -Password: ●●●●●●●●●●● -Email: jdoe@example.com -WARNING: login credentials saved in /Users/jdoe/.docker/config.json. -Login Succeeded - -$ echo $(cat ~/.docker/config.json) -{ "https://index.docker.io/v1/": { "auth": "ZmFrZXBhc3N3b3JkMTIK", "email": "jdoe@example.com" } } - -$ cat ~/.docker/config.json | base64 -eyAiaHR0cHM6Ly9pbmRleC5kb2NrZXIuaW8vdjEvIjogeyAiYXV0aCI6ICJabUZyWlhCaGMzTjNiM0prTVRJSyIsICJlbWFpbCI6ICJqZG9lQGV4YW1wbGUuY29tIiB9IH0K - -$ cat > /tmp/image-pull-secret.yaml < Date: Thu, 5 Jan 2017 15:28:50 +0100 Subject: [PATCH 05/17] Refactor stackdriver logging page --- docs/user-guide/logging/overview.md | 56 ++++--- docs/user-guide/logging/stackdriver.md | 214 +++++++++++-------------- 2 files changed, 130 insertions(+), 140 deletions(-) diff --git a/docs/user-guide/logging/overview.md b/docs/user-guide/logging/overview.md index e1ac4885be..61c068a4d9 100644 --- a/docs/user-guide/logging/overview.md +++ b/docs/user-guide/logging/overview.md @@ -7,26 +7,26 @@ title: Logging Overview Application and systems logs can help you understand what is happening inside your cluster. The logs are particularly useful for debugging problems and monitoring cluster activity. Most modern applications have some kind of logging mechanism; as such, most container engines are likewise designed to support some kind of logging. The easiest and most embraced logging method for containerized applications is to write to the standard output and standard error streams. -However, the native functionality provided by a container engine or runtime is usually not enough for a complete logging solution. For example, if a container crashes, a pod is evicted, or a node dies, you'll usually still want to access your application's logs. As such, logs should have a separate storage and lifecycle independent of nodes, pods, or containers; this concept is called __cluster-level-logging__. Cluster-level logging requires a separate back-end to store, analyze, and query logs. Kubernetes provides no native storage solution for logs data, but you can integrate many existing logging solutions into your Kubernetes cluster. +However, the native functionality provided by a container engine or runtime is usually not enough for a complete logging solution. For example, if a container crashes, a pod is evicted, or a node dies, you'll usually still want to access your application's logs. As such, logs should have a separate storage and lifecycle independent of nodes, pods, or containers. This concept is called _cluster-level-logging_. Cluster-level logging requires a separate backend to store, analyze, and query logs. Kubernetes provides no native storage solution for log data, but you can integrate many existing logging solutions into your Kubernetes cluster. -In this document, you can find: +This document includes: * A basic demonstration of logging in Kubernetes using the standard output stream * A detailed description of the node logging architecture in Kubernetes * Guidance for implementing cluster-level logging in Kubernetes -The guidance for cluster-level logging assumes that a logging back-end is present inside or outside of your cluster. If you're not interested in having cluster-level logging, you might still find the description how logs are stored and handled on the node to be useful. +The guidance for cluster-level logging assumes that a logging backend is present inside or outside of your cluster. If you're not interested in having cluster-level logging, you might still find the description of how logs are stored and handled on the node to be useful. ## Basic logging in Kubernetes In this section, you can see an example of basic logging in Kubernetes that outputs data to the standard output stream. This demonstration uses a [pod specification](/docs/user-guide/logging/counter-pod.yaml) with a container that writes some text to standard output once per second. -{% include code.html language="yaml" file="counter-pod.yaml" %} +{% include code.html language="yaml" file="counter-pod.yaml" ghlink="/docs/user-guide/counter-pod.yaml" %} To run this pod, use the following command: ```shell -$ kubectl create -f counter-pod.yaml +$ kubectl create -f http://k8s.io/docs/user-guide/counter-pod.yaml pod "counter" created ``` @@ -43,17 +43,17 @@ $ kubectl logs counter ... ``` -You can use `kubectl logs` to retrieve logs from a previous instantiation of a container with `--previous` flag, in case the container has crashed. If your pod has multiple containers, you should specify which container's logs you want to access by appending a container name to the command. See the [`kubectl logs` documentation](/docs/user-guide/kubectl/kubectl_logs) for more details. +You can use `kubectl logs` to retrieve logs from a previous instantiation of a container with `--previous` flag, in case the container has crashed. If your pod has multiple containers, you should specify which container's logs you want to access by appending a container name to the command. See the [`kubectl logs` documentation](/docs/user-guide/kubectl/kubectl_logs/) for more details. ## Logging at the node level ![Node level logging](/images/docs/user-guide/logging/logging-node-level.png) -Everything a containerized application writes to `stdout` and `stderr` is handled and redirected somewhere by a container engine. For example, Docker container engine redirects those two streams to [a logging driver](https://docs.docker.com/engine/admin/logging/overview), which is configured in Kubernetes to write to a file in json format. +Everything a containerized application writes to `stdout` and `stderr` is handled and redirected somewhere by a container engine. For example, the Docker container engine redirects those two streams to [a logging driver](https://docs.docker.com/engine/admin/logging/overview), which is configured in Kubernetes to write to a file in json format. -**Note:** The Docker json logging driver treats each line as a separate message. When using the Docker logging driver, there is no direct support for multi-line messages. To do so, you'll need to handle these at the logging agent level or higher. +**Note:** The Docker json logging driver treats each line as a separate message. When using the Docker logging driver, there is no direct support for multi-line messages. You need to handle multi-line messages at the logging agent level or higher. -By default, if a container restarts, kubelet keeps one terminated container with its logs. If a pod is evicted from the node, all corresponding containers are also evicted, along with their logs. +By default, if a container restarts, the kubelet keeps one terminated container with its logs. If a pod is evicted from the node, all corresponding containers are also evicted, along with their logs. An important consideration in node-level logging is implementing log rotation, so that logs don't consume all available storage on the node. Kubernetes uses the [`logrotate`](http://www.linuxcommand.org/man_pages/logrotate8.html) tool to implement log rotation. @@ -61,31 +61,45 @@ Kubernetes performs log rotation daily, or if the log file grows beyond 10MB in The Kubernetes logging configuration differs depending on the node type. For example, you can find detailed information for GCI in the corresponding [configure helper](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/cluster/gce/gci/configure-helper.sh#L96). -When you run [`kubectl logs`](/docs/user-guide/kubectl/kubectl_logs), as in the basic logging example, the kubelet on the node handles the request and reads directly from the log file, returning the contents in the response. Note that `kubectl logs` **only returns the last rotation**; you must manually extract prior rotations, if desired. +When you run [`kubectl logs`](/docs/user-guide/kubectl/kubectl_logs), as in the basic logging example, the kubelet on the node handles the request and reads directly from the log file, returning the contents in the response. Note that `kubectl logs` **only returns the last rotation**; you must manually extract prior rotations, if desired and cluster-level logging is not enabled. -### System components logs +### System component logs -Kubernetes system components use a different logging mechanism than the application containers in pods. Components such as `kube-proxy` (among others) use the [glog](https://godoc.org/github.com/golang/glog) logging library. You can find the conventions for logging severity for those components in the [development docs on logging](https://github.com/kubernetes/kubernetes/tree/{{page.githubbranch}}/docs/devel/logging.md). +There are two types of system components: those that run in a container and those +that do not run in a container. For example: -System components write directly to log files in the `/var/log` directory in the node's host filesystem. Like container logs, system component logs are rotated daily and based on size. However, system component logs have a higher size retention: by default, they store 100MB. +* The Kubernets scheduler and kube-proxy run in a container. +* The kubelet and container runtime, for example Docker, do not run in containers. + +On machines with systemd, the kubelet and container runtime write to journald. If +systemd is not present, they write to `.log` files in the `/var/log` directory. +System components inside containers always write to the `/var/log` directory, +bypassing the default logging mechanism. They use the [glog](https://godoc.org/github.com/golang/glog) +logging library. You can find the conventions for logging severity for those +components in the [development docs on logging](https://github.com/kubernetes/community/blob/master/contributors/devel/logging.md). + +Similarly to the container logs, system component logs in the `/var/log` +directory are rotated daily and based on the log size. However, +system component logs have a higher size retention: by default, +they can store up to 100MB. ## Cluster-level logging architectures -While Kubernetes does not provide a native solution for cluster-level logging, there are several common approaches you can consider: +While Kubernetes does not provide a native solution for cluster-level logging, there are several common approaches you can consider. Here are some options: -* You can use a node-level logging agent that runs on every node. -* You can include a dedicated sidecar container for logging in an application pod. -* You can push logs directly to a back-end from within an application. +* Use a node-level logging agent that runs on every node. +* Include a dedicated sidecar container for logging in an application pod. +* Push logs directly to a backend from within an application. ### Using a node logging agent ![Using a node level logging agent](/images/docs/user-guide/logging/logging-with-node-agent.png) -You can implement cluster-level logging by including a _node-level logging agent_ on each node. The logging agent is a dedicated tool that exposes logs or pushes logs to a back-end. Commonly, the logging agent is a container that has access to a directory with log files from all of the application containers on that node. +You can implement cluster-level logging by including a _node-level logging agent_ on each node. The logging agent is a dedicated tool that exposes logs or pushes logs to a backend. Commonly, the logging agent is a container that has access to a directory with log files from all of the application containers on that node. Because the logging agent must run on every node, it's common to implement it as either a DaemonSet replica, a manifest pod, or a dedicated native process on the node. However the latter two approaches are deprecated and highly discouraged. -Using a node-level logging agent is the most common and encouraged approach for a Kubernetes cluster, since it creates only one agent per node and it doesn't require any changes to the applications running on the node. However, node-level logging _only works for applications' standard output and standard error_. +Using a node-level logging agent is the most common and encouraged approach for a Kubernetes cluster, because it creates only one agent per node, and it doesn't require any changes to the applications running on the node. However, node-level logging _only works for applications' standard output and standard error_. Kubernetes doesn't specify a logging agent, but two optional logging agents are packaged with the Kubernetes release: [Stackdriver Logging](/docs/user-guide/logging/stackdriver) for use with Google Cloud Platform, and [Elasticsearch](/docs/user-guide/logging/elasticsearch). You can find more information and instructions in the dedicated documents. Both use [fluentd](http://www.fluentd.org/) with custom configuration as an agent on the node. @@ -93,9 +107,9 @@ Kubernetes doesn't specify a logging agent, but two optional logging agents are ![Using a sidecar container with the logging agent](/images/docs/user-guide/logging/logging-with-sidecar.png) -You can implement cluster-level logging by including a dedicated logging agent _for each application_ on your cluster. You can include this logging agent as a "sidecar" container in the pod spec for each application; the sidecar container should contain only the logging agent. +You can implement cluster-level logging by including a dedicated logging agent for each application on your cluster. You can include this logging agent as a _sidecar container_ in the pod spec for each application; the sidecar container should contain only the logging agent. -The concrete implementation of the logging agent, the interface between agent and the application, and the interface between the logging agent and the logs back-end are completely up to a you. For an example implementation, see the [fluentd sidecar container](https://github.com/kubernetes/contrib/tree/b70447aa59ea14468f4cd349760e45b6a0a9b15d/logging/fluentd-sidecar-gcp) for the Stackdriver logging backend. +The concrete implementation of the logging agent, the interface between agent and the application, and the interface between the logging agent and the logs backend are completely up to a you. For an example implementation, see the [fluentd sidecar container](https://github.com/kubernetes/contrib/tree/b70447aa59ea14468f4cd349760e45b6a0a9b15d/logging/fluentd-sidecar-gcp) for the Stackdriver logging backend. **Note:** Using a sidecar container for logging may lead to significant resource consumption. diff --git a/docs/user-guide/logging/stackdriver.md b/docs/user-guide/logging/stackdriver.md index 1648d651ec..eb3380ca5c 100644 --- a/docs/user-guide/logging/stackdriver.md +++ b/docs/user-guide/logging/stackdriver.md @@ -5,44 +5,42 @@ assignees: title: Logging with Stackdriver Logging --- -Before reading this page, it's recommended to familiarize yourself with the [overview of logging in Kubernetes](/docs/user-guide/logging/overview). +Before reading this page, it's highly recommended to familiarize yourself with the [overview of logging in Kubernetes](/docs/user-guide/logging/overview). -This article assumes that you have created a Kubernetes cluster with cluster-level logging support for sending logs to Stackdriver Logging. You can do this either by selecting "Enable Stackdriver Logging" checkbox in create cluster dialogue in [GKE](https://cloud.google.com/container-engine/) or by setting flag `KUBE_LOGGING_DESTINATION` to `gcp` when manually starting cluster using `kube-up.sh`. +This article assumes that you have created a Kubernetes cluster with cluster-level logging support for sending logs to Stackdriver Logging. You can do this either by selecting the **Enable Stackdriver Logging** checkbox in the create cluster dialogue in [GKE](https://cloud.google.com/container-engine/), or by setting the `KUBE_LOGGING_DESTINATION` flag to `gcp` when manually starting a cluster using `kube-up.sh`. + +The following guide describes gathering a container's standard output and standard error. To gather logs written by an application to a file, you can use [a sidecar approach](https://github.com/kubernetes/contrib/blob/master/logging/fluentd-sidecar-gcp/README.md). ## Overview -After creation, your cluster has a collection of system pods running in the `kube-system` namespace that support monitoring, logging, and DNS resolution for Kuberentes service names. You can see these system pods by running the following command: +After creation, you can discover logging agent pods in the `kube-system` namespace, +one per node, by running the following command: ```shell $ kubectl get pods --namespace=kube-system -NAME READY REASON RESTARTS AGE -fluentd-cloud-logging-kubernetes-node-0f64 1/1 Running 0 32m -fluentd-cloud-logging-kubernetes-node-27gf 1/1 Running 0 32m -fluentd-cloud-logging-kubernetes-node-pk22 1/1 Running 0 31m -fluentd-cloud-logging-kubernetes-node-20ej 1/1 Running 0 31m -kube-dns-v3-pk22 3/3 Running 0 32m -monitoring-heapster-v1-20ej 0/1 Running 9 32m +NAME READY STATUS RESTARTS AGE +... +fluentd-gcp-v1.30-50gnc 1/1 Running 0 5d +fluentd-gcp-v1.30-v255c 1/1 Running 0 5d +fluentd-gcp-v1.30-f02l5 1/1 Running 0 5d +... ``` -Here is the same information in a picture which shows how the pods might be placed on specific nodes. +To understand how logging with Stackdriver works, consider the following +synthetic log generator pod specification [counter-pod.yaml](/docs/user-guide/logging/counter-pod.yaml): -![image](/images/blog-logging/diagrams/cloud-logging.png) +{% include code.html language="yaml" file="counter-pod.yaml" ghlink="/docs/user-guide/counter-pod.yaml" %} -This diagram shows four nodes created on a Google Compute Engine cluster with the name of each VM node on a purple background. The internal and public IPs of each node are shown on gray boxes and the pods running in each node are shown in green boxes. Each pod box shows the name of the pod and the namespace it runs in, the IP address of the pod and the images which are run as part of the pod's execution. Here we see that every node is running a fluentd-cloud-logging pod which is collecting the log output of the containers running on the same node and sending them to Stackdriver Logging. A pod which provides the -[cluster DNS service](/docs/admin/dns) runs on one of the nodes and a pod which provides monitoring support runs on another node. - -To help explain how cluster-level logging works, consider the following synthetic log generator pod specification [counter-pod.yaml](/docs/user-guide/logging/counter-pod.yaml): - -{% include code.html language="yaml" file="counter-pod.yaml" %} - -This pod specification has one container which runs a bash script when the container is born. This script simply writes out the value of a counter and the date once per second and runs indefinitely. Let's create the pod in the default namespace. +This pod specification has one container that runs a bash script +that writes out the value of a counter and the date once per +second, and runs indefinitely. Let's create this pod in the default namespace. ```shell -$ kubectl create -f examples/blog-logging/counter-pod.yaml - pods/counter +$ kubectl create -f counter-pod.yaml +pod "counter" created ``` -We can observe the running pod: +You can observe the running pod: ```shell $ kubectl get pods @@ -50,123 +48,101 @@ NAME READY STATUS RESTARTS AG counter 1/1 Running 0 5m ``` -This step may take a few minutes to download the ubuntu:14.04 image during which the pod status will be shown as `Pending`. - -One of the nodes is now running the counter pod: - -![image](/images/blog-logging/diagrams/27gf-counter.png) - -When the pod status changes to `Running` we can use the `kubectl logs` command to view the output of this counter pod. +For a short period of time you can observe the 'Pending' pod status, because the kubelet +has to download the container image first. When the pod status changes to `Running` +you can use the `kubectl logs` command to view the output of this counter pod. ```shell $ kubectl logs counter -0: Tue Jun 2 21:37:31 UTC 2015 -1: Tue Jun 2 21:37:32 UTC 2015 -2: Tue Jun 2 21:37:33 UTC 2015 -3: Tue Jun 2 21:37:34 UTC 2015 -4: Tue Jun 2 21:37:35 UTC 2015 -5: Tue Jun 2 21:37:36 UTC 2015 +0: Mon Jan 1 00:00:00 UTC 2001 +1: Mon Jan 1 00:00:01 UTC 2001 +2: Mon Jan 1 00:00:02 UTC 2001 ... ``` -This command fetches the log text from the Docker log file for the image that is running in this container. We can connect to the running container and observe the running counter bash script. - -```shell -$ kubectl exec -i counter bash -ps aux -USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND -root 1 0.0 0.0 17976 2888 ? Ss 00:02 0:00 bash -c for ((i = 0; ; i++)); do echo "$i: $(date)"; sleep 1; done -root 468 0.0 0.0 17968 2904 ? Ss 00:05 0:00 bash -root 479 0.0 0.0 4348 812 ? S 00:05 0:00 sleep 1 -root 480 0.0 0.0 15572 2212 ? R 00:05 0:00 ps aux -``` - -<<<<<<< HEAD:docs/getting-started-guides/logging.md -What happens if for any reason the image in this pod is killed off and then restarted by Kubernetes? Will we still see the log lines from the previous invocation of the container followed by the log lines for the started container? Or will we lose the log lines from the original container's execution and only see the log lines for the new container? Let's find out. First let's delete the currently running counter. -======= -If, for any reason, the image in this pod is killed off and then restarted by Kubernetes, or the pod was evicted from the node, logs for the container are lost. - -Try deleting the currently running counter container: ->>>>>>> 69304ab37e14fac33455b629442bdc3995d05ad2:docs/user-guide/logging/stackdriver.md +As described in the logging overview, this command fetches log entries +from the container log file. If the container is killed and then restarted by +Kubernetes, you can still access logs from the previous container. However, +if the pod is evicted from the node, log files are lost. Let's demonstrate this +by deleting the currently running counter container: ```shell $ kubectl delete pod counter pods/counter ``` -Now let's restart the counter. +and then recreating it: ```shell -$ kubectl create -f examples/blog-logging/counter-pod.yaml +$ kubectl create -f counter-pod.yaml pods/counter ``` -Let's wait for the container to restart and get the log lines again. +After some time, you can access logs from the counter pod again: ```shell $ kubectl logs counter -0: Tue Jun 2 21:51:40 UTC 2015 -1: Tue Jun 2 21:51:41 UTC 2015 -2: Tue Jun 2 21:51:42 UTC 2015 -3: Tue Jun 2 21:51:43 UTC 2015 -4: Tue Jun 2 21:51:44 UTC 2015 -5: Tue Jun 2 21:51:45 UTC 2015 -6: Tue Jun 2 21:51:46 UTC 2015 -7: Tue Jun 2 21:51:47 UTC 2015 -8: Tue Jun 2 21:51:48 UTC 2015 -``` - -As expected, the log lines from the first invocation of the container in this pod have been lost. However, you'll likely want to preserve all the log lines from each invocation of each container in the pod. Furthermore, even if the pod is restarted, you might still want to preserve all the log lines that were ever emitted by the containers in the pod. This is exactly the functionality provided by cluster-level logging in Kubernetes. - -## Viewing logs - -We can click on the Logs item under the Monitoring section of the Google Developer Console and select the logs for the counter container, which will be called kubernetes.counter_default_count. This identifies the name of the pod (counter), the namespace (default) and the name of the container (count) for which the log collection occurred. Using this name we can select just the logs for our counter container from the drop down menu: - -![Cloud Logging Console](/images/docs/cloud-logging-console.png) - -When we view the logs in the Developer Console we observe the logs for both invocations of the container. - -![Both Logs](/images/docs/all-lines.png) - -Note the first container counted to 108 and then it was terminated. When the next container image restarted the counting process resumed from 0. Similarly if we deleted the pod and restarted it we would capture the logs for all instances of the containers in the pod whenever the pod was running. - - Logs ingested into Stackdriver Logging may be exported to various other destinations including [Google Cloud Storage](https://cloud.google.com/storage/) buckets and [BigQuery](https://cloud.google.com/bigquery/). Use the Exports tab in the Cloud Logging console to specify where logs should be streamed to. You can also follow this link to the - [settings tab](https://pantheon.corp.google.com/project/_/logs/settings). - - We could query the ingested logs from BigQuery using the SQL query which reports the counter log lines showing the newest lines first: - -```shell -SELECT metadata.timestamp, structPayload.log -FROM [mylogs.kubernetes_counter_default_count_20150611] -ORDER BY metadata.timestamp DESC -``` - -Here is some sample output: - -![BigQuery](/images/docs/bigquery-logging.png) - -We could also fetch the logs from Google Cloud Storage buckets to our desktop or laptop and then search them locally. The following command fetches logs for the counter pod running in a cluster which is itself in a Compute Engine project called `myproject`. Only logs for the date 2015-06-11 are fetched. - - -```shell -$ gsutil -m cp -r gs://myproject/kubernetes.counter_default_count/2015/06/11 . -``` - -Now we can run queries over the ingested logs. The example below uses the [jq](http://stedolan.github.io/jq/) program to extract just the log lines. - -```shell -$ cat 21\:00\:00_21\:59\:59_S0.json | jq '.structPayload.log' -"0: Thu Jun 11 21:39:38 UTC 2015\n" -"1: Thu Jun 11 21:39:39 UTC 2015\n" -"2: Thu Jun 11 21:39:40 UTC 2015\n" -"3: Thu Jun 11 21:39:41 UTC 2015\n" -"4: Thu Jun 11 21:39:42 UTC 2015\n" -"5: Thu Jun 11 21:39:43 UTC 2015\n" -"6: Thu Jun 11 21:39:44 UTC 2015\n" -"7: Thu Jun 11 21:39:45 UTC 2015\n" +0: Mon Jan 1 00:01:00 UTC 2001 +1: Mon Jan 1 00:01:01 UTC 2001 +2: Mon Jan 1 00:01:02 UTC 2001 ... ``` -This page has touched briefly on the underlying mechanisms that support gathering cluster-level logs on a Kubernetes deployment. The approach here only works for gathering the standard output and standard error output of the processes running in the pod's containers. To gather other logs that are stored in files one can use a sidecar container to gather the required files as described at the page [Collecting log files within containers with Fluentd](https://github.com/kubernetes/contrib/blob/master/logging/fluentd-sidecar-gcp/README.md) and sending them to the Stackdriver Logging service. +As expected, only recent log lines are present. However, for a real-world +application you will likely want to be able to access logs from all containers, +especially for the debug purposes. This is exactly when the previously enabled +Stackdriver Logging can help. -Some of the material in this section also appears in the blog article [Cluster-level Logging with Kubernetes](http://blog.kubernetes.io/2015/06/cluster-level-logging-with-kubernetes.html) +## Viewing logs + +Stackdriver Logging agent attaches metadata to each log entry, for you to use later +in queries to select only the messages you're interested in: for example, +the messages from a particular pod. + +The most important pieces of metadata are the resource type and log name. +The resource type of a container log is `container`, which is named +`GKE Containers` in the UI (even if the Kubernetes cluster is not on GKE). +The log name is the name of the container, so that if you have a pod with +two containers, named `container_1` and `container_2` in the spec, their logs +will have log names `container_1` and `container_2` respectively. + +System components have resource type `compute`, which is named +`GCE VM Instance` in the interface. Log names for system components are fixed. +For a GKE node, every log entry from a system component has one the following +log names: + +* docker +* kubelet +* kube-proxy + +You can learn more about viewing logs on [the dedicated Stackdriver page](https://cloud.google.com/logging/docs/view/logs_viewer). + +One of the possible ways to view logs is using the +[`gcloud logging`](https://cloud.google.com/logging/docs/api/gcloud-logging) +command line interface from the [Google Cloud SDK](https://cloud.google.com/sdk/). +It uses Stackdriver Logging [filtering syntax](https://cloud.google.com/logging/docs/view/advanced_filters) +to query specific logs. For example, you can run the following command: + +```shell +$ gcloud beta logging read 'logName="projects/$YOUR_PROJECT_ID/logs/count"' --format json | jq '.[].textPayload' +... +"2: Mon Jan 1 00:01:02 UTC 2001\n" +"1: Mon Jan 1 00:01:01 UTC 2001\n" +"0: Mon Jan 1 00:01:00 UTC 2001\n" +... +"2: Mon Jan 1 00:00:02 UTC 2001\n" +"1: Mon Jan 1 00:00:01 UTC 2001\n" +"0: Mon Jan 1 00:00:00 UTC 2001\n" +``` + +As you can see, it outputs messages for the count container from both +the first and second runs, despite the fact that the kubelet already deleted +the logs for the first container. + +### Exporting logs + +You can export logs to [Google Cloud Storage](https://cloud.google.com/storage/) +or to [BigQuery](https://cloud.google.com/bigquery/) to run further +analysis. Stackdriver Logging offers the concept of sinks, where you can +specify the destination of log entries. More information is available on +the Stackdriver [Exporting Logs page](https://cloud.google.com/logging/docs/export/configure_export_v2). From 4f3c2951822af0cd2365d47ff19f27015755fa97 Mon Sep 17 00:00:00 2001 From: Peter Lee Date: Sun, 15 Jan 2017 23:09:45 +0800 Subject: [PATCH 06/17] fix the named anchor name anchor `loading-and-merging` should be `loading-and-merging-rules` --- docs/user-guide/kubeconfig-file.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/kubeconfig-file.md b/docs/user-guide/kubeconfig-file.md index fd44eaf999..b4d7425127 100644 --- a/docs/user-guide/kubeconfig-file.md +++ b/docs/user-guide/kubeconfig-file.md @@ -16,7 +16,7 @@ So in order to easily switch between multiple clusters, for multiple users, a ku This file contains a series of authentication mechanisms and cluster connection information associated with nicknames. It also introduces the concept of a tuple of authentication information (user) and cluster connection information called a context that is also associated with a nickname. -Multiple kubeconfig files are allowed, if specified explicitly. At runtime they are loaded and merged along with override options specified from the command line (see [rules](#loading-and-merging) below). +Multiple kubeconfig files are allowed, if specified explicitly. At runtime they are loaded and merged along with override options specified from the command line (see [rules](#loading-and-merging-rules) below). ## Related discussion From ab7cbe3a49386987ed2ff56ffc1506bc909dfe9d Mon Sep 17 00:00:00 2001 From: Xing Zhou Date: Mon, 16 Jan 2017 11:03:01 +0800 Subject: [PATCH 07/17] Fixed Typo --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index cfc3c32125..7c6ae95e73 100644 --- a/docs/api.md +++ b/docs/api.md @@ -77,7 +77,7 @@ groups*](https://github.com/kubernetes/kubernetes/blob/{{page.githubbranch}}/doc same underlying resources. The API group is specified in a REST path and in the `apiVersion` field of a serialized object. -Currently there are two API groups in use: +Currently there are several API groups in use: 1. the "core" group, which is at REST path `/api/v1` and is not specified as part of the `apiVersion` field, e.g. `apiVersion: v1`. From f83bd527d431544a6d50ad0e8095a7777c117799 Mon Sep 17 00:00:00 2001 From: Jared Date: Tue, 17 Jan 2017 10:52:12 -0800 Subject: [PATCH 08/17] Renamed "Petset" to Statefulset Renamed feature, fixed link https://github.com/kubernetes/kubernetes.github.io/issues/2240 --- docs/user-guide/pods/init-container.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/pods/init-container.md b/docs/user-guide/pods/init-container.md index 82524ba753..b6f0cece35 100644 --- a/docs/user-guide/pods/init-container.md +++ b/docs/user-guide/pods/init-container.md @@ -79,8 +79,8 @@ Here are some ideas for how to use init containers: to generate a configuration file to be consumed by the main app contianer. ``` -Complete usage examples can be found in the [PetSets -guide](docs/user-guide/petset/bootstrapping/index.md) and the [Production Pods +Complete usage examples can be found in the [StatefulSets +documentation](/docs/concepts/abstractions/controllers/statefulsets/) and the [Production Pods guide](/docs/user-guide/production-pods.md#handling-initialization). From 26385f0e46a85da5c8d3cc2f0e2a20f869d71484 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 10 Jan 2017 15:49:33 -0800 Subject: [PATCH 09/17] Write new Task: Attaching Handlers to Container Lifecycle Events. --- _data/tasks.yml | 3 +- .../attach-handler-lifecycle-event.md | 72 +++++++++++++++++++ .../lifecycle-events.yaml | 33 +++++++++ docs/tasks/index.md | 1 + 4 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md create mode 100644 docs/tasks/configure-pod-container/lifecycle-events.yaml diff --git a/_data/tasks.yml b/_data/tasks.yml index 9605e925b0..13315bf5ed 100644 --- a/_data/tasks.yml +++ b/_data/tasks.yml @@ -13,7 +13,8 @@ toc: - docs/tasks/configure-pod-container/pull-image-private-registry.md - docs/tasks/configure-pod-container/configure-liveness-readiness-probes.md - docs/tasks/configure-pod-container/communicate-containers-same-pod.md - - docs/tasks/configure-pod-container/configure-pod-initialization.md + - docs/tasks/configure-pod-container/configure-pod-initialization.md + - docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md - title: Accessing Applications in a Cluster section: diff --git a/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md b/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md new file mode 100644 index 0000000000..e6492c7577 --- /dev/null +++ b/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md @@ -0,0 +1,72 @@ +--- +title: Attaching Handlers to Container Lifecycle Events +--- + +{% capture overview %} + +This page shows how to attach handlers to Container lifecycle events. Kubernetes supports +the postStart event and the preStop event. Kubernetes sends the postStart event immediately +after a Container is started, and it sends the preStop event immediately before the +Container is terminated. + +{% endcapture %} + + +{% capture prerequisites %} + +{% include task-tutorial-prereqs.md %} + +{% endcapture %} + + +{% capture steps %} + +### Defining postStart and preStop handlers + +In this exercise, you create a Pod that has one Container. The Container has handlers +for the postStart and preStop events. + +Here is the configuration file for the Pod: + +{% include code.html language="yaml" file="lifecycle-events.yaml" ghlink="/docs/tasks/configure-pod-container/lifecycle-events.yaml" %} + +In the configuration file, you can see that the postStart command writes a `message` +file to the Container's `/usr/share` directory. The preStop command shuts down +nginx gracefully. This is helpful if the Container is being terminated because of a failure. + +Create the Pod: + + kubectl create -f http://k8s.io/docs/tasks/configure-pod-container/lifecycle-events.yaml + +Verify that the Container in the Pod is running: + + kubectl get pod lifecycle-demo + +Get a shell into the Container running in your Pod: + + kubectl exec -it lifecycle-demo -- /bin/bash + +In your shell, verify that the `postStart` handler created the `message` file: + + root@lifecycle-demo:/# cat /usr/share/message + +The output shows the text written by the postStart handler: + + Hello from the postStart handler + +{% endcapture %} + + +{% capture whatsnext %} + +* Learn more about [Container lifecycle hooks](/docs/user-guide/container-environment/.) +* Learn more about the [lifecycle of a Pod](https://kubernetes.io/docs/user-guide/pod-states/). + +#### Reference + +* [Lifecycle](https://kubernetes.io/docs/resources-reference/1_5/#lifecycle-v1) +* [Container](https://kubernetes.io/docs/resources-reference/1_5/#container-v1) + +{% endcapture %} + +{% include templates/task.md %} diff --git a/docs/tasks/configure-pod-container/lifecycle-events.yaml b/docs/tasks/configure-pod-container/lifecycle-events.yaml new file mode 100644 index 0000000000..c62028d7ef --- /dev/null +++ b/docs/tasks/configure-pod-container/lifecycle-events.yaml @@ -0,0 +1,33 @@ +apiVersion: v1 +kind: Pod +metadata: + name: lifecycle-demo +spec: + containers: + - name: lifecycle-demo-container + image: nginx + + lifecycle: + postStart: + exec: + command: ["/bin/sh", "-c", "echo Hello from the postStart handler > /usr/share/message"] + preStop: + exec: + command: ["/usr/sbin/nginx","-s","quit"] + + + + + + + + + + + + + + + + + diff --git a/docs/tasks/index.md b/docs/tasks/index.md index 2482a13677..b9d0284d5e 100644 --- a/docs/tasks/index.md +++ b/docs/tasks/index.md @@ -17,6 +17,7 @@ single thing, typically by giving a short sequence of steps. * [Configuring Liveness and Readiness Probes](/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/) * [Communicating Between Pods Running in the Same Container](/docs/tasks/configure-pod-container/communicate-containers-same-pod/) * [Configuring Pod Initialization](/docs/tasks/configure-pod-container/configure-pod-initialization/) +* [Attaching Handlers to Container Lifecycle Events](/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/) #### Accessing Applications in a Cluster From 6a6028c72704842d43a4668530ad4f43e33d4ee8 Mon Sep 17 00:00:00 2001 From: steveperry-53 Date: Tue, 17 Jan 2017 12:40:55 -0800 Subject: [PATCH 10/17] Address reviewer comments. --- .../attach-handler-lifecycle-event.md | 26 +++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md b/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md index e6492c7577..715ea3effb 100644 --- a/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md +++ b/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md @@ -5,7 +5,7 @@ title: Attaching Handlers to Container Lifecycle Events {% capture overview %} This page shows how to attach handlers to Container lifecycle events. Kubernetes supports -the postStart event and the preStop event. Kubernetes sends the postStart event immediately +the postStart and preStop events. Kubernetes sends the postStart event immediately after a Container is started, and it sends the preStop event immediately before the Container is terminated. @@ -57,15 +57,37 @@ The output shows the text written by the postStart handler: {% endcapture %} + +{% capture discussion %} + +### Discussion + +Kubernetes sends the postStart event immediately after the Container is created. +There is no guarantee, however, that the postStart handler is called before +the Container's entrypoint is called. The postStart handler runs asynchronously +relative to the Container's code, but Kubernetes' management of the container +blocks until the postStart handler completes. The Container's status is not +set to RUNNING until the postStart handler completes. + +Kubernetes sends the preStop event immediately before the Container is terminated. +Kubernetes' management of the Container blocks until the preStop handler completes, +unless the Pod's grace period expires. For more details, see +[Termination of Pods](/docs/user-guide/pods/#termination-of-pods). + +{% endcapture %} + + {% capture whatsnext %} * Learn more about [Container lifecycle hooks](/docs/user-guide/container-environment/.) * Learn more about the [lifecycle of a Pod](https://kubernetes.io/docs/user-guide/pod-states/). -#### Reference +#### Reference + * [Lifecycle](https://kubernetes.io/docs/resources-reference/1_5/#lifecycle-v1) * [Container](https://kubernetes.io/docs/resources-reference/1_5/#container-v1) +* See `terminationGracePeriodSeconds` in [PodSpec](/docs/resources-reference/v1.5/#podspec-v1) {% endcapture %} From 8858b56753fab59c5f432ca4da837f682fe8e46a Mon Sep 17 00:00:00 2001 From: Nathan Quarles Date: Mon, 16 Jan 2017 09:38:07 -0500 Subject: [PATCH 11/17] grammar fix --- docs/tutorials/kubernetes-basics/explore-intro.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorials/kubernetes-basics/explore-intro.html b/docs/tutorials/kubernetes-basics/explore-intro.html index e16d2a0755..5f5cb6354e 100644 --- a/docs/tutorials/kubernetes-basics/explore-intro.html +++ b/docs/tutorials/kubernetes-basics/explore-intro.html @@ -28,7 +28,7 @@ title: Viewing Pods and Nodes

Kubernetes Pods

-

When you created a Deployment in Module 2, Kubernetes created a Pod to host your application instance. A Pod is Kubernetes abstraction that represents a group of one or more application containers (such as Docker or rkt), and some shared resources for those containers. Those resources include:

+

When you created a Deployment in Module 2, Kubernetes created a Pod to host your application instance. A Pod is a Kubernetes abstraction that represents a group of one or more application containers (such as Docker or rkt), and some shared resources for those containers. Those resources include:

  • Shared storage, as Volumes
  • Networking, as a unique cluster IP address
    • From 2495fb890d6fa5346cfbd6230ba08abf579b80c9 Mon Sep 17 00:00:00 2001 From: Francesc Rosas Date: Tue, 17 Jan 2017 14:57:48 +0000 Subject: [PATCH 12/17] Fix jsonpath --- docs/getting-started-guides/minikube.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index 65b7893be5..731ad1c9a4 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -225,7 +225,7 @@ Any services of type `NodePort` can be accessed over that IP address, on the Nod To determine the NodePort for your service, you can use a `kubectl` command like this: -`kubectl get service $SERVICE --output='jsonpath="{.spec.ports[0].NodePort}"'` +`kubectl get service $SERVICE --output='jsonpath="{.spec.ports[0].nodePort}"'` ## Persistent Volumes Minikube supports [PersistentVolumes](http://kubernetes.io/docs/user-guide/persistent-volumes/) of type `hostPath`. From 4a33f4f44c2648806ca77e60012c970d9968d607 Mon Sep 17 00:00:00 2001 From: Janet Kuo Date: Tue, 17 Jan 2017 15:16:27 -0800 Subject: [PATCH 13/17] Fix travis failure by bumping go version to 1.7.3 --- .travis.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.travis.yml b/.travis.yml index 33db17d9e7..791d289e88 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,6 +1,6 @@ language: go go: - - 1.6.2 + - 1.7.3 # Don't want default ./... here: install: From 705f74fad0b6b69ed9dc693ba484e378d50f71c7 Mon Sep 17 00:00:00 2001 From: Michael Mrowetz Date: Fri, 13 Jan 2017 17:16:16 +0900 Subject: [PATCH 14/17] de-duplicated sentence. --- docs/admin/salt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/admin/salt.md b/docs/admin/salt.md index d2479ffff2..ab495521bd 100644 --- a/docs/admin/salt.md +++ b/docs/admin/salt.md @@ -6,7 +6,7 @@ title: Configuring Kubernetes with Salt The Kubernetes cluster can be configured using Salt. -The Salt scripts are shared across multiple hosting providers, so it's important to understand some background information prior to making a modification to ensure your changes do not break hosting Kubernetes across multiple environments. Depending on where you host your Kubernetes cluster, you may be using different operating systems and different networking configurations. As a result, it's important to understand some background information before making Salt changes in order to minimize introducing failures for other hosting providers. +The Salt scripts are shared across multiple hosting providers and depending on where you host your Kubernetes cluster, you may be using different operating systems and different networking configurations. As a result, it's important to understand some background information before making Salt changes in order to minimize introducing failures for other hosting providers. ## Salt cluster setup From 7ca44701da52f467a5aeebcfefbe9131c2c6d69f Mon Sep 17 00:00:00 2001 From: Jared Date: Tue, 17 Jan 2017 16:13:36 -0800 Subject: [PATCH 15/17] Update minikube.md --- docs/getting-started-guides/minikube.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started-guides/minikube.md b/docs/getting-started-guides/minikube.md index 495c68130b..7e47aeadd6 100644 --- a/docs/getting-started-guides/minikube.md +++ b/docs/getting-started-guides/minikube.md @@ -157,11 +157,11 @@ This command also configures your [kubectl](http://kubernetes.io/docs/user-guide If you are behind a web proxy, you will need to pass this information in e.g. via ``` - https_proxy= minikube start --docker-env HTTP_PROXY= --docker-env HTTPS_PROXY= --docker-env NO_PROXY=192.168.99.0/24 +``` Unfortunately just setting the environment variables will not work. -``` + Minikube will also create a "minikube" context, and set it to default in kubectl. To switch back to this context later, run this command: `kubectl config use-context minikube`. From 1e40f9fea5ffb24bfc642f7acfb9d990cf2b7160 Mon Sep 17 00:00:00 2001 From: caiyixiang Date: Tue, 17 Jan 2017 18:21:05 +0800 Subject: [PATCH 16/17] Update index.md --- docs/user-guide/horizontal-pod-autoscaling/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/horizontal-pod-autoscaling/index.md b/docs/user-guide/horizontal-pod-autoscaling/index.md index 81d2c7aca2..44ad3440e2 100644 --- a/docs/user-guide/horizontal-pod-autoscaling/index.md +++ b/docs/user-guide/horizontal-pod-autoscaling/index.md @@ -26,7 +26,7 @@ The autoscaler is implemented as a control loop. It periodically queries CPU utilization for the pods it targets. (The period of the autoscaler is controlled by `--horizontal-pod-autoscaler-sync-period` flag of controller manager. The default value is 30 seconds). -Then, it compares the arithmetic mean of the pods' CPU utilization with the target and adjust the number of replicas if needed. +Then, it compares the arithmetic mean of the pod's CPU utilization with the target and adjust the number of replicas if needed. CPU utilization is the recent CPU usage of a pod divided by the sum of CPU requested by the pod's containers. Please note that if some of the pod's containers do not have CPU request set, @@ -90,7 +90,7 @@ The cluster has to be started with `ENABLE_CUSTOM_METRICS` environment variable ### Pod configuration The pods to be scaled must have cAdvisor-specific custom (aka application) metrics endpoint configured. The configuration format is described [here](https://github.com/google/cadvisor/blob/master/docs/application_metrics.md). Kubernetes expects the configuration to - be placed in `definition.json` mounted via a [config map](/docs/user-guide/configmap/) in `/etc/custom-metrics`. A sample config map may look like this: + be placed in `definition.json` mounted via a [configMap](/docs/user-guide/configmap/) in `/etc/custom-metrics`. A sample config map may look like this: ```yaml apiVersion: v1 From a2d0e7c1655c8820a35bd34491dc70a2b637aa9a Mon Sep 17 00:00:00 2001 From: xilabao Date: Tue, 17 Jan 2017 02:29:16 -0600 Subject: [PATCH 17/17] update role example --- docs/admin/authorization.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/admin/authorization.md b/docs/admin/authorization.md index c9dd662449..8f2b60472c 100644 --- a/docs/admin/authorization.md +++ b/docs/admin/authorization.md @@ -259,7 +259,6 @@ rules: - apiGroups: [""] # The API group "" indicates the core API Group. resources: ["pods"] verbs: ["get", "watch", "list"] - nonResourceURLs: [] ``` `ClusterRoles` hold the same information as a `Role` but can apply to any