Update container-environment.md. Fixes kubernetes#14127.

joevandyk · Oct 10, 2015 · 678032f · 678032f
1 parent 9305a98
commit 678032f
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 28 deletions.
diff --git a/docs/user-guide/container-environment.md b/docs/user-guide/container-environment.md
@@ -89,61 +89,42 @@ Services have dedicated IP address, and are also surfaced to the container via D
 
 ## Container Hooks
 
-*NB*: Container hooks are under active development, we anticipate adding additional hooks as the Kubernetes container management system evolves.*
-
 Container hooks provide information to the container about events in its management lifecycle.  For example, immediately after a container is started, it receives a *PostStart* hook.  These hooks are broadcast *into* the container with information about the life-cycle of the container.  They are different from the events provided by Docker and other systems which are *output* from the container.  Output events provide a log of what has already happened.  Input hooks provide real-time notification about things that are happening, but no historical log.
 
 ### Hook Details
 
-There are currently two container hooks that are surfaced to containers, and two proposed hooks:
-
-*PreStart - ****Proposed***
-
-This hook is sent immediately before a container is created.  It notifies that the container will be created immediately after the call completes.  No parameters are passed. *Note - *Some event handlers (namely ‘exec’ are incompatible with this event)
+There are currently two container hooks that are surfaced to containers:
 
 *PostStart*
 
 This hook is sent immediately after a container is created.  It notifies the container that it has been created.  No parameters are passed to the handler.
 
-*PostRestart - ****Proposed***
-
-This hook is called before the PostStart handler, when a container has been restarted, rather than started for the first time.  No parameters are passed to the handler.
-
 *PreStop*
 
-This hook is called immediately before a container is terminated.  This event handler is blocking, and must complete before the call to delete the container is sent to the Docker daemon.  The SIGTERM notification sent by Docker is also still sent.
-
-A single parameter named reason is passed to the handler which contains the reason for termination.  Currently the valid values for reason are:
-
-* `Delete` - indicating an API call to delete the pod containing this container.
-* `Health` - indicating that a health check of the container failed.
-* `Dependency` - indicating that a dependency for the container or the pod is missing, and thus, the container needs to be restarted.  Examples include, the pod infra container crashing, or persistent disk failing for a container that mounts PD.
-
-Eventually, user specified reasons may be [added to the API](http://issue.k8s.io/137).
-
+This hook is called immediately before a container is terminated. No parameters are passed to the handler. This event handler is blocking, and must complete before the call to delete the container is sent to the Docker daemon.  The SIGTERM notification sent by Docker is also still sent. A more complete description of termination behavior can be found in [Termination of Pods](pods.md#termination-of-pods).
 
 ### Hook Handler Execution
 
-When a management hook occurs, the management system calls into any registered hook handlers in the container for that hook.  These hook handler calls are synchronous in the context of the pod containing the container. Note:this means that hook handler execution blocks any further management of the pod.  If your hook handler blocks, no other management (including [health checks](production-pods.md#liveness-and-readiness-probes-aka-health-checks)) will occur until the hook handler completes.  Blocking hook handlers do *not* affect management of other Pods.  Typically we expect that users will make their hook handlers as lightweight as possible, but there are cases where long running commands make sense (e.g. saving state prior to container stop)
-
-For hooks which have parameters, these parameters are passed to the event handler as a set of key/value pairs.  The details of this parameter passing is handler implementation dependent (see below).
+When a management hook occurs, the management system calls into any registered hook handlers in the container for that hook.  These hook handler calls are synchronous in the context of the pod containing the container. Typically we expect that users will make their hook handlers as lightweight as possible, but there are cases where long running commands make sense (e.g. saving state prior to container stop).
 
 ### Hook delivery guarantees
 
-Hook delivery is "at least one", which means that a hook may be called multiple times for any given event (e.g. "start" or "stop") and it is up to the hook implementer to be able to handle this
+Hook delivery is intended to be "at least once", which means that a hook may be called multiple times for any given event (e.g. "start" or "stop") and it is up to the hook implementer to be able to handle this
 correctly.
 
-We expect double delivery to be rare, but in some cases if the `kubelet` restarts in the middle of sending a hook, the hook may be resent after the kubelet comes back up.
+We expect double delivery to be rare, but in some cases if the Kubelet restarts in the middle of sending a hook, the hook may be resent after the Kubelet comes back up.
 
 Likewise, we only make a single delivery attempt.  If (for example) an http hook receiver is down, and unable to take traffic, we do not make any attempts to resend.
 
+Currently, there are (hopefully rare) scenarios where PostStart hooks may not be delivered.
+
 ### Hook Handler Implementations
 
 Hook handlers are the way that hooks are surfaced to containers.  Containers can select the type of hook handler they would like to implement.  Kubernetes currently supports two different hook handler types:
 
-   * Exec - Executes a specific command (e.g. pre-stop.sh) inside the cgroup and namespaces of the container.  Resources consumed by the command are counted against the container.  Commands which print "ok" to standard out (stdout) are treated as healthy, any other output is treated as container failures (and will cause kubelet to forcibly restart the container).  Parameters are passed to the command as traditional linux command line flags (e.g. pre-stop.sh --reason=HEALTH)
+   * Exec - Executes a specific command (e.g. pre-stop.sh) inside the cgroups and namespaces of the container.  Resources consumed by the command are counted against the container.
 
-   * HTTP - Executes an HTTP request against a specific endpoint on the container.  HTTP error codes (5xx) and non-response/failure to connect are treated as container failures. Parameters are passed to the http endpoint as query args (e.g. http://some.server.com/some/path?reason=HEALTH)
+   * HTTP - Executes an HTTP request against a specific endpoint on the container.
 
 [1]: http://man7.org/linux/man-pages/man2/gethostname.2.html
 

diff --git a/docs/user-guide/pods.md b/docs/user-guide/pods.md
@@ -33,6 +33,23 @@ Documentation for other releases can be found at
 
 # Pods
 
+**Table of Contents**
+<!-- BEGIN MUNGE: GENERATED_TOC -->
+
+- [Pods](#pods)
+  - [What is a _pod_?](#what-is-a-pod)
+  - [Motivation for pods](#motivation-for-pods)
+    - [Resource sharing and communication](#resource-sharing-and-communication)
+    - [Management](#management)
+  - [Uses of pods](#uses-of-pods)
+  - [Alternatives considered](#alternatives-considered)
+  - [Durability of pods (or lack thereof)](#durability-of-pods-or-lack-thereof)
+  - [Termination of Pods](#termination-of-pods)
+  - [Privileged mode for pod containers](#privileged-mode-for-pod-containers)
+  - [API Object](#api-object)
+
+<!-- END MUNGE: GENERATED_TOC -->
+
 In Kubernetes, rather than individual application containers, _pods_ are the smallest deployable units that can be created, scheduled, and managed.
 
 ## What is a _pod_?
@@ -78,6 +95,8 @@ Pods can be used to host vertically integrated application stacks, but their pri
 
 Individual pods are not intended to run multiple instances of the same application, in general.
 
+For a longer explanation, see [The Distributed System ToolKit: Patterns for Composite Containers](http://blog.kubernetes.io/2015/06/the-distributed-system-toolkit-patterns.html).
+
 ## Alternatives considered
 
 _Why not just run multiple programs in a single (Docker) container?_