Job and DaemonSet documentation.

docs/admin/daemon.yaml

+apiVersion: experimental/v1alpha1
+kind: DaemonSet
+metadata:
+  name: prometheus-node-exporter
+spec:
+  template:
+    metadata:
+      name: prometheus-node-exporter
+      labels:
+        daemon: prom-node-exp
+    spec:
+      containers:
+      - name: c
+        image: prom/prometheus
+        ports:
+        - containerPort: 9090
+          hostPort: 9090
+          name: serverport

docs/admin/node.md

@@ -214,6 +214,10 @@ unschedulable, run this command:
 kubectl replace nodes 10.1.2.3 --patch='{"apiVersion": "v1", "unschedulable": true}'
 ```
 
+Note that pods which are created by a daemonSet controller bypass the Kubernetes scheduler,
+and do not respect the unschedulable attribute on a node.   The assumption is that daemons belong on
+the machine even if it is being drained of applications in preparation for a reboot.
+
 ### Node capacity
 
 The capacity of the node (number of cpus and amount of memory) is part of the node resource.

docs/user-guide/job.yaml

+apiVersion: experimental/v1alpha1
+kind: Job
+metadata:
+  name: pi
+spec:
+  selector:
+    app: pi
+  template:
+    metadata:
+      name: pi
+      labels:
+        app: pi
+    spec:
+      containers:
+      - name: pi
+        image: perl
+        command: ["perl",  "-Mbignum=bpi", "-wle", "print bpi(2000)"]
+      restartPolicy: Never
+

docs/user-guide/pod-states.md

@@ -80,13 +80,27 @@ More detailed information about the current (and previous) container statuses ca
 
 The possible values for RestartPolicy are `Always`, `OnFailure`, or `Never`. If RestartPolicy is not set, the default value is `Always`. RestartPolicy applies to all containers in the pod. RestartPolicy only refers to restarts of the containers by the Kubelet on the same node. Failed containers that are restarted by Kubelet, are restarted with an exponential back-off delay, the delay is in multiples of sync-frequency 0, 1x, 2x, 4x, 8x ... capped at 5 minutes and is reset after 10 minutes of successful execution. As discussed in the [pods document](pods.md#durability-of-pods-or-lack-thereof), once bound to a node, a pod will never be rebound to another node. This means that some kind of controller is necessary in order for a pod to survive node failure, even if just a single pod at a time is desired.
 
-The only controller we have today is [`ReplicationController`](replication-controller.md).  `ReplicationController` is *only* appropriate for pods with `RestartPolicy = Always`.  `ReplicationController` should refuse to instantiate any pod that has a different restart policy.
+Three types of controllers are currently available:
 
-There is a legitimate need for a controller which keeps pods with other policies alive. Pods having any of the other policies (`OnFailure` or `Never`) eventually terminate, at which point the controller should stop recreating them.  Because of this fundamental distinction, let's hypothesize a new controller, called [`JobController`](http://issue.k8s.io/1624) for the sake of this document, which can implement this policy.
+- Use a [`Job`](jobs.md) for pods which are expected to terminate (e.g. batch computations).
+- Use a [`ReplicationController`](replication-controller.md) for pods which are not expected to
+  terminate, and where (e.g. web servers).
+- Use a [`DaemonSet`](../admin/daemons.md): Use for pods which need to run 1 per machine because they provide a
+  machine-specific system service.
+If you are unsure whether to use ReplicationController or Daemon, then see [Daemon Set versus
+Replication Controller](../admin/daemons.md#daemon-set-versus-replication-controller).
+
+`ReplicationController` is *only* appropriate for pods with `RestartPolicy = Always`.
+`Job` is *only* appropriate for pods with `RestartPolicy` equal to `OnFailure` or `Never`.
+
+All 3 types of controllers contain a PodTemplate, which has all the same fields as a Pod.
+It is recommended to create the appropriate controller and let it create pods, rather than to
+directly create pods yourself.  That is because pods alone are not resilient to machine failures,
+but Controllers are.
 
 ## Pod lifetime
 
-In general, pods which are created do not disappear until someone destroys them.  This might be a human or a `ReplicationController`.  The only exception to this rule is that pods with a `PodPhase` of `Succeeded` or `Failed` for more than some duration (determined by the master) will expire and be automatically reaped.
+In general, pods which are created do not disappear until someone destroys them.  This might be a human or a `ReplicationController`, or another controller.  The only exception to this rule is that pods with a `PodPhase` of `Succeeded` or `Failed` for more than some duration (determined by the master) will expire and be automatically reaped.
 
 If a node dies or is disconnected from the rest of the cluster, some entity within the system (call it the NodeController for now) is responsible for applying policy (e.g. a timeout) and marking any pods on the lost node as `Failed`.
 

examples/examples_test.go

@@ -106,6 +106,16 @@ func validateObject(obj runtime.Object) (errors []error) {
 			t.Namespace = api.NamespaceDefault
 		}
 		errors = expValidation.ValidateDeployment(t)
+	case *experimental.Job:
+		if t.Namespace == "" {
+			t.Namespace = api.NamespaceDefault
+		}
+		errors = expValidation.ValidateJob(t)
+	case *experimental.DaemonSet:
+		if t.Namespace == "" {
+			t.Namespace = api.NamespaceDefault
+		}
+		errors = expValidation.ValidateDaemonSet(t)
 	default:
 		return []error{fmt.Errorf("no validation defined for %#v", obj)}
 	}
@@ -211,6 +221,10 @@ func TestExampleObjectSchemas(t *testing.T) {
 			"multi-pod":   nil,
 			"pod":         &api.Pod{},
 			"replication": &api.ReplicationController{},
+			"job":         &experimental.Job{},
+		},
+		"../docs/admin": {
+			"daemon": &experimental.DaemonSet{},
 		},
 		"../examples": {
 			"scheduler-policy-config": &schedulerapi.Policy{},

pkg/apis/experimental/v1alpha1/types.go

@@ -314,14 +314,17 @@ type DaemonSetSpec struct {
 type DaemonSetStatus struct {
 	// CurrentNumberScheduled is the number of nodes that are running exactly 1
 	// daemon pod and are supposed to run the daemon pod.
+	// More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md
 	CurrentNumberScheduled int `json:"currentNumberScheduled"`
 
 	// NumberMisscheduled is the number of nodes that are running the daemon pod, but are
 	// not supposed to run the daemon pod.
+	// More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md
 	NumberMisscheduled int `json:"numberMisscheduled"`
 
 	// DesiredNumberScheduled is the total number of nodes that should be running the daemon
 	// pod (including nodes correctly running the daemon pod).
+	// More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md
 	DesiredNumberScheduled int `json:"desiredNumberScheduled"`
 }
 
@@ -400,17 +403,21 @@ type JobSpec struct {
 	// run at any given time. The actual number of pods running in steady state will
 	// be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism),
 	// i.e. when the work left to do is less than max parallelism.
+	// More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md
 	Parallelism *int `json:"parallelism,omitempty"`
 
 	// Completions specifies the desired number of successfully finished pods the
 	// job should be run with. Defaults to 1.
+	// More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md
 	Completions *int `json:"completions,omitempty"`
 
 	// Selector is a label query over pods that should match the pod count.
+	// More info: http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors
 	Selector map[string]string `json:"selector,omitempty"`
 
 	// Template is the object that describes the pod that will be created when
 	// executing a job.
+	// More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md
 	Template *v1.PodTemplateSpec `json:"template"`
 }
 
@@ -418,6 +425,7 @@ type JobSpec struct {
 type JobStatus struct {
 
 	// Conditions represent the latest available observations of an object's current state.
+	// More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md
 	Conditions []JobCondition `json:"conditions,omitempty" patchStrategy:"merge" patchMergeKey:"type"`
 
 	// StartTime represents time when the job was acknowledged by the Job Manager.

pkg/apis/experimental/v1alpha1/types_swagger_doc_generated.go

@@ -70,9 +70,9 @@ func (DaemonSetSpec) SwaggerDoc() map[string]string {
 
 var map_DaemonSetStatus = map[string]string{
 	"": "DaemonSetStatus represents the current status of a daemon set.",
-	"currentNumberScheduled": "CurrentNumberScheduled is the number of nodes that are running exactly 1 daemon pod and are supposed to run the daemon pod.",
-	"numberMisscheduled":     "NumberMisscheduled is the number of nodes that are running the daemon pod, but are not supposed to run the daemon pod.",
-	"desiredNumberScheduled": "DesiredNumberScheduled is the total number of nodes that should be running the daemon pod (including nodes correctly running the daemon pod).",
+	"currentNumberScheduled": "CurrentNumberScheduled is the number of nodes that are running exactly 1 daemon pod and are supposed to run the daemon pod. More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md",
+	"numberMisscheduled":     "NumberMisscheduled is the number of nodes that are running the daemon pod, but are not supposed to run the daemon pod. More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md",
+	"desiredNumberScheduled": "DesiredNumberScheduled is the total number of nodes that should be running the daemon pod (including nodes correctly running the daemon pod). More info: http://releases.k8s.io/HEAD/docs/admin/daemon.md",
 }
 
 func (DaemonSetStatus) SwaggerDoc() map[string]string {
@@ -285,10 +285,10 @@ func (JobList) SwaggerDoc() map[string]string {
 
 var map_JobSpec = map[string]string{
 	"":            "JobSpec describes how the job execution will look like.",
-	"parallelism": "Parallelism specifies the maximum desired number of pods the job should run at any given time. The actual number of pods running in steady state will be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism), i.e. when the work left to do is less than max parallelism.",
-	"completions": "Completions specifies the desired number of successfully finished pods the job should be run with. Defaults to 1.",
-	"selector":    "Selector is a label query over pods that should match the pod count.",
-	"template":    "Template is the object that describes the pod that will be created when executing a job.",
+	"parallelism": "Parallelism specifies the maximum desired number of pods the job should run at any given time. The actual number of pods running in steady state will be less than this number when ((.spec.completions - .status.successful) < .spec.parallelism), i.e. when the work left to do is less than max parallelism. More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md",
+	"completions": "Completions specifies the desired number of successfully finished pods the job should be run with. Defaults to 1. More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md",
+	"selector":    "Selector is a label query over pods that should match the pod count. More info: http://releases.k8s.io/HEAD/docs/user-guide/labels.md#label-selectors",
+	"template":    "Template is the object that describes the pod that will be created when executing a job. More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md",
 }
 
 func (JobSpec) SwaggerDoc() map[string]string {
@@ -297,7 +297,7 @@ func (JobSpec) SwaggerDoc() map[string]string {
 
 var map_JobStatus = map[string]string{
 	"":               "JobStatus represents the current state of a Job.",
-	"conditions":     "Conditions represent the latest available observations of an object's current state.",
+	"conditions":     "Conditions represent the latest available observations of an object's current state. More info: http://releases.k8s.io/HEAD/docs/user-guide/jobs.md",
 	"startTime":      "StartTime represents time when the job was acknowledged by the Job Manager. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.",
 	"completionTime": "CompletionTime represents time when the job was completed. It is not guaranteed to be set in happens-before order across separate operations. It is represented in RFC3339 form and is in UTC.",
 	"active":         "Active is the number of actively running pods.",