Documenting dedicated job & quota relationship.
authorMaxim Khutornenko <maxim@apache.org>
Mon, 21 Sep 2015 22:38:30 +0000 (15:38 -0700)
committerMaxim Khutornenko <maxim@apache.org>
Mon, 21 Sep 2015 22:38:30 +0000 (15:38 -0700)
Bugs closed: AURORA-1462

Reviewed at https://reviews.apache.org/r/38385/

docs/README.md
docs/client-commands.md
docs/configuration-reference.md
docs/configuration-tutorial.md
docs/deploying-aurora-scheduler.md
docs/resources.md [moved from docs/resource-isolation.md with 86% similarity]

index fe115dc..fdea212 100644 (file)
@@ -23,7 +23,7 @@ We encourage you to ask questions on the [Aurora developer list](http://aurora.a
  * [Scheduler Storage](storage.md)
  * [Scheduler Storage and Maintenance](storage-config.md)
  * [SLA Measurement](sla.md)
- * [Resource Isolation and Sizing](resource-isolation.md)
+ * [Resource Isolation and Sizing](resources.md)
  * [Generating test resources](test-resource-generation.md)
 
 ## Developers
index f91e5df..9977b49 100644 (file)
@@ -332,7 +332,8 @@ configuration file, and displays the parsed configuration.
     aurora quota get CLUSTER/ROLE
 
   Prints the production quota allocated to the role's value at the given
-cluster.
+cluster. Only non-[dedicated](deploying-aurora-scheduler.md#dedicated-attribute)
+[production](configuration-reference.md#job-objects) jobs consume quota.
 
 ### Finding a Job on Web UI
 
index 8d50c45..ba0dc86 100644 (file)
@@ -294,7 +294,7 @@ ordering constraints.
 ### Resource Object
 
 Specifies the amount of CPU, Ram, and disk resources the task needs. See the
-[Resource Isolation document](resource-isolation.md) for suggested values and to understand how
+[Resource Isolation document](resources.md) for suggested values and to understand how
 resources are allocated.
 
   param      | type    | description
@@ -325,7 +325,7 @@ Job Schema
   ```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 backed by quota (Default: False). Production jobs may preempt any non-production job, and may only be preempted by production jobs in the same role and of higher priority. To run jobs at this level, the job role must have the appropriate quota. To grant quota to a particular role in production, operators use the ``aurora_admin set_quota`` command.
+  ```production``` | Boolean |  Whether or not this is a production task that may [preempt](resources.md#task-preemption) other tasks (Default: False). Production job role must have the appropriate [quota](resources.md#resource-quota).
   ```health_check_config``` | ```heath_check_config``` object | Parameters for controlling a task's health checks via HTTP. Only used if a  health port was assigned with a command line wildcard.
   ```container``` | ```Container``` 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.
index d6e7c35..bbb1684 100644 (file)
@@ -581,12 +581,7 @@ Three attributes deal with configuring the Job's Task:
     values.
 
 -   `production`: a Boolean, defaulting to `False`, specifying that this
-    is a production job backed by quota. Tasks from production Jobs may
-    preempt tasks from any non-production job, and may only be preempted
-    by tasks from production jobs in the same role with higher
-    priority. **WARNING**: To run Jobs at this level, the Job role must
-    have the appropriate quota. To grant quota to a particular role in
-    production, operators use the ``aurora_admin set_quota`` command.
+    is a [production](configuration-reference.md#job-objects) job.
 
 The final three Job attributes each take an object as their value.
 
index 2a46d2f..22a27f8 100644 (file)
@@ -225,6 +225,9 @@ constraints are arbitrary and available for custom use.  There is one exception,
 `dedicated` attribute.  Aurora treats this specially, and only allows matching jobs to run on these
 machines, and will only schedule matching jobs on these machines.
 
+See the [section](resources.md#resource-quota) about resource quotas to learn how quotas apply to
+dedicated jobs.
+
 ##### Syntax
 The dedicated attribute has semantic meaning. The format is `$role(/.*)?`. When a job is created,
 the scheduler requires that the `$role` component matches the `role` field in the job
similarity index 86%
rename from docs/resource-isolation.md
rename to docs/resources.md
index 7e8d88d..27a2678 100644 (file)
@@ -1,10 +1,6 @@
-Resource Isolation and Sizing
+Resources and Sizing
 =============================
 
-**NOTE**: Resource Isolation and Sizing is very much a work in progress.
-Both user-facing aspects and how it works under the hood are subject to
-change.
-
 - [Introduction](#introduction)
 - [CPU Isolation](#cpu-isolation)
 - [CPU Sizing](#cpu-sizing)
@@ -13,6 +9,8 @@ change.
 - [Disk Space](#disk-space)
 - [Disk Space Sizing](#disk-space-sizing)
 - [Other Resources](#other-resources)
+- [Resource Quota](#resource-quota)
+- [Task Preemption](#task-preemption)
 
 ## Introduction
 
@@ -145,3 +143,22 @@ Other resources, such as network bandwidth, do not have any performance
 guarantees. For some resources, such as memory bandwidth, there are no
 practical sharing methods so some application combinations collocated on
 the same host may cause contention.
+
+## Resource Quota
+
+Aurora requires resource quotas for
+[production non-dedicated jobs](configuration-reference.md#job-objects). Quota is enforced at
+the job role level and when set, defines a non-preemptible pool of compute resources within
+that role.
+
+To grant quota to a particular role in production use `aurora_admin set_quota` command.
+
+NOTE: all job types (service, adhoc or cron) require role resource quota unless a job has
+[dedicated constraint set](deploying-aurora-scheduler.md#dedicated-attribute).
+
+## Task preemption
+
+Under a particular resource shortage pressure, tasks from
+[production](configuration-reference.md#job-objects) jobs may preempt tasks from any non-production
+job. A production task may only be preempted by tasks from production jobs in the same role with
+higher [priority](configuration-reference.md#job-objects).
\ No newline at end of file