Add init container documentation

docs/user-guide/nginx-init-containers.yaml

@@ -0,0 +1,31 @@
+apiVersion: v1
+kind: Pod
+metadata:
+  name: nginx
+  annotations:
+    pod.alpha.kubernetes.io/init-containers: '[
+        {
+            "name": "install",
+            "image": "busybox",
+            "command": ["wget", "-O", "/work-dir/index.html", "http://kubernetes.io/index.html"],
+            "volumeMounts": [
+                {
+                    "name": "workdir",
+                    "mountPath": "/work-dir"
+                }
+            ]
+        }
+    ]'
+spec:
+  containers:
+  - name: nginx
+    image: nginx
+    ports:
+    - containerPort: 80
+    volumeMounts:
+    - name: workdir
+      mountPath: /usr/share/nginx/html
+  dnsPolicy: Default
+  volumes:
+  - name: workdir
+    emptyDir: {}

docs/user-guide/production-pods.md

@@ -180,6 +180,26 @@ Other times, applications are only temporarily unable to serve, and will recover
 
 For more details (e.g., how to specify command-based probes), see the [example in the walkthrough](/docs/user-guide/walkthrough/k8s201/#health-checking), the [standalone example](/docs/user-guide/liveness/), and the [documentation](/docs/user-guide/pod-states/#container-probes).
 
+## Handling initialization
+
+Applications often need a set of initialization steps prior to performing their day job. This may include:
+
+* Waiting for other components (like a database or web service) to be available
+* Performing configuration templating from environment variables into a config file
+* Registering the pod into a central database, or fetching remote configuration from that database
+* Downloading application dependencies, seed data, or preconfiguring disk
+
+Kubernetes now includes an alpha feature known as **init containers**, which are one or more containers in a pod that get a chance to run and initialize shared volumes prior to the other application containers starting.  An init container is exactly like a regular container, except that it always runs to completion and each init container must complete successfully before the next one is started. If the init container fails (exits with a non-zero exit code) on a `RestartNever` pod the pod will fail - otherwise it will be restarted until it succeeds or the user deletes the pod.
+
+Since init containers are an alpha feature, they are specified by setting the `pod.alpha.kubernetes.io/init-containers` annotation on a pod (or replica set, deployment, daemon set, pet set, or job). The value of the annotation must be a string containing a JSON array of container definitions:
+
+{% include code.html language="yaml" file="nginx-init-containers.yaml" ghlink="/docs/user-guide/nginx-init-containers.yaml" %}
+
+The status of the init containers is returned as another annotation - `pod.alpha.kubernetes.io/init-container-statuses` -- as an array of the container statuses (similar to the `status.containerStatuses` field).
+
+Init containers support all of the same features as normal containers, including resource limits, volumes, and security settings. The resource requests and limits for an init container are handled slightly different than normal containers since init containers are run one at a time instead of all at once - any limits or quotas will be applied based on the largest init container resource quantity, rather than as the sum of quantities. Init containers do not support readiness probes since they will run to completion before the pod can be ready.
+
+
 ## Lifecycle hooks and termination notice
 
 Of course, nodes and applications may fail at any time, but many applications benefit from clean shutdown, such as to complete in-flight requests, when the termination of the application is deliberate. To support such cases, Kubernetes supports two kinds of notifications: