Update extendedjob docs after discussion
[#162413776](https://www.pivotaltracker.com/story/show/162413776)
- [ExtendedJob](#extendedjob)
- [Description](#description)
- [Features](#features)
- - [Triggers](#triggers)
+ - [Triggered Jobs](#triggered-jobs)
+ - [State](#state)
+ - [Labels](#labels)
+ - [One-Off Jobs / Auto-Errands](#one-off-jobs-auto-errands)
+ - [Errand Jobs](#errand-jobs)
- [Persisted Output](#persisted-output)
- [Example Resource](#example-resource)
@@ -13,17 +17,60 @@ An `ExtendedJob` allows the developer to run jobs when something interesting hap
Just like an `ExtendedStatefulSet`, an `ExtendedJob` can automatically be restarted if its environment/mounts have changed due to a `ConfigMap` or a `Secret` being updated.
-The same `ExtendedJob` cannot run in parallel for the same pod. Even if it is still running when a new event happens to the pod, there can't be two jobs of the same name.
+There are three different kinds of `ExtendedJob`: triggered jobs, one-offs and
+errands.
## Features
-### Triggers
+### Triggered Jobs
-An `ExtendedJob` can be triggered when something interesting happens for an entity.
+The controller periodically pulls the event log and inspects events involving a
+pod. This should protect against controller downtime, as long as the k8s event
+log covers the duration of the downtime.
-E.g. when a `Pod` is created, updated, deleted, transitioned to **ready** or a **notReady** state.
+An `ExtendedJob` can be triggered when something interesting happens to a pod.
-The *something* can be a selector.
+E.g. when a `Pod` is created, deleted, transitioned to **ready** or a
+**notReady** state.
+
+The execution of `ExtendedJob` can be limited to pods with certain labels.
+
+A separate native k8s job will be started for every pod that changed. The job
+has a label `affected-pod: pod1` to identify which pod it is running for.
+
+#### State
+
+To trigger on the state of the pod, the `when` trigger can be used.
+Possible values are `ready`, `notready`, `created` and `deleted`.
+
+The `when` field is required for triggered jobs.
+
+Example: `when: ready`
+
+#### Labels
+
+To trigger on pods with a matching label, the `selector` trigger can be used.
+It supports matching against a list of labels via `matchLabels`.
+It can also match by expressions if `matchExpressions` are given.
+
+If multiple selectors are given, all must match to include the pod.
+
+### One-Off Jobs / Auto-Errands
+
+One-off jobs run directly when created, just like native k8s jobs, but still
+persist their output.
+
+They can't have a `triggers` section and specify `run: once` instead.
+
+### Errand Jobs
+
+Errands are manually run by the user.
+
+They can't have a `triggers` section and specify `run: manually` instead.
+
+After the `ExtendedJob` is created, run an errand by editing and applying the
+manifest, i.e. via `k edit errand1` and change `run: manually` to `run: now`,
+after completion the value will be reset to `manually`.
### Persisted Output
@@ -33,7 +80,7 @@ Since a Job can run multiple times until it succeeds, the behavior of storing th
- `overwrite` - if true, the ConfigMap or Secret is updated on every run
- `writeOnFailure` - if true, output is written even though the Job failed.
-## Example Resource
+## Example Triggered ExtendedJob Resource
```yaml
---
@@ -53,8 +100,7 @@ spec:
writeOnFailure: false
updateOnConfigChange: true
triggers:
- when:
- ready: true
+ when: ready
selector:
matchLabels:
component: redis
