AURORA-1656 Document tier concept
Bugs closed: AURORA-1656
Reviewed at https://reviews.apache.org/r/50530/
diff --git a/docs/features/multitenancy.md b/docs/features/multitenancy.md
index 62bcd53..417c433 100644
--- a/docs/features/multitenancy.md
+++ b/docs/features/multitenancy.md
@@ -34,6 +34,24 @@
increasing level of stability: `devel`, `test`, `staging`, `production`.
+Configuration Tiers
+-------------------
+
+Tier is a predefined bundle of task configuration options. Aurora schedules tasks and assigns them
+resources based on their tier assignment. The default scheduler tier configuration allows for
+3 tiers:
+ - `revocable`: The `revocable` tier requires the task to run with [revocable](../resource-isolation/#oversubscription)
+ resources.
+ - `preemptible`: Setting the task’s tier to `preemptible` allows for the possibility of that task
+ being [preempted](#preemption) by other tasks when cluster is running low on resources.
+ - `preferred`: The `preferred` tier prevents the task from using [revocable](../resource-isolation/#oversubscription)
+ resources and from being [preempted](#preemption).
+
+Since it is possible that a cluster is configured with a custom tier configuration, users should
+consult their cluster administrator to be informed of the tiers supported by the cluster. Attempts
+to schedule jobs with an unsupported tier will be rejected by the scheduler.
+
+
Preemption
----------
@@ -46,12 +64,12 @@
- both candidate and victim are owned by the same role and the
[priority](../reference/configuration.md#job-objects) of a victim is lower than the
[priority](../reference/configuration.md#job-objects) of the candidate.
- - OR a victim is non-[production](../reference/configuration.md#job-objects) and the candidate is
- [production](../reference/configuration.md#job-objects).
+ - OR a victim is a `preemptible` or `revocable` [tier](#configuration-tiers) task and the candidate
+ is a `preferred` [tier](#configuration-tiers) task.
-In other words, tasks from [production](../reference/configuration.md#job-objects) jobs may preempt
-tasks from any non-production job. However, a production task may only be preempted by tasks from
-production jobs in the same role with higher [priority](../reference/configuration.md#job-objects).
+In other words, tasks from `preferred` [tier](../reference/configuration.md#job-objects) jobs may
+preempt tasks from any `preemptible` or `revocable` job. However, a `preferred` task may only be
+preempted by tasks from `preferred` jobs in the same role with higher [priority](../reference/configuration.md#job-objects).
Aurora requires resource quotas for [production non-dedicated jobs](../reference/configuration.md#job-objects).
Quota is enforced at the job role level and when set, defines a non-preemptible pool of compute resources within
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 64c076d..16b31be 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -330,6 +330,9 @@
deprecated in favor of setting its value directly to the appropriate ```Docker``` or ```Mesos```
container type*
+*Note: Specifying preemption behavior of tasks through `production` flag is deprecated in favor of
+ electing appropriate task tier via `tier` attribute.*
+
name | type | description
------ | :-------: | -------
```task``` | Task | The Task object to bind to this job. Required.
@@ -346,11 +349,11 @@
```service``` | Boolean | If True, restart tasks regardless of success or failure. (Default: False)
```max_task_failures``` | Integer | Maximum number of failures after which the task is considered to have failed (Default: 1) Set to -1 to allow for infinite failures
```priority``` | Integer | Preemption priority to give the task (Default 0). Tasks with higher priorities may preempt tasks at lower priorities.
- ```production``` | Boolean | Whether or not this is a production task that may [preempt](../features/multitenancy.md#preemption) other tasks (Default: False). Production job role must have the appropriate [quota](../features/multitenancy.md#preemption).
+ ```production``` | Boolean | (Deprecated) Whether or not this is a production task that may [preempt](../features/multitenancy.md#preemption) other tasks (Default: False). Production job role must have the appropriate [quota](../features/multitenancy.md#preemption).
```health_check_config``` | ```HealthCheckConfig``` object | Parameters for controlling a task's health checks. HTTP health check is only used if a health port was assigned with a command line wildcard.
```container``` | Choice of ```Container```, ```Docker``` or ```Mesos``` object | An optional container to run all processes inside of.
```lifecycle``` | ```LifecycleConfig``` object | An optional task lifecycle configuration that dictates commands to be executed on startup/teardown. HTTP lifecycle is enabled by default if the "health" port is requested. See [LifecycleConfig Objects](#lifecycleconfig-objects) for more information.
- ```tier``` | String | Task tier type. The default scheduler tier configuration allows for 3 tiers: `revocable`, `preemptible`, and `preferred`. The `revocable` tier requires the task to run with Mesos revocable resources. Setting the task's tier to `preemptible` allows for the possibility of that task being preempted by other tasks when cluster is running low on resources. The `preferred` tier prevents the task from using revocable resources and from being preempted. Since it is possible that a cluster is configured with a custom tier configuration, users should consult their cluster administrator to be informed of the tiers supported by the cluster. Attempts to schedule jobs with an unsupported tier will be rejected by the scheduler.
+ ```tier``` | String | Task tier type. The default scheduler tier configuration allows for 3 tiers: `revocable`, `preemptible`, and `preferred`. If a tier is not elected, Aurora assigns the task to a tier based on its choice of `production` (that is `preferred` for production and `preemptible` for non-production jobs). See the section on [Configuration Tiers](../features/multitenancy#configuration-tiers) for more information.
```announce``` | ```Announcer``` object | Optionally enable Zookeeper ServerSet announcements. See [Announcer Objects] for more information.
```enable_hooks``` | Boolean | Whether to enable [Client Hooks](client-hooks.md) for this job. (Default: False)
