Add jobs support to CLI

* Added two new modes accepted by the `--mode` flag
  * `replicated-job` creates a replicated job
  * `global-job` creates a global job.
* When using `replicated-job` mode, the `replicas` flag sets the
  `TotalCompletions` parameter of the job. This is the total number of
  tasks that will run
* Added a new flag, `max-concurrent`, for use with `replicated-job`
  mode. This flag sets the `MaxConcurrent` parameter of the job, which
  is the maximum number of replicas the job will run simultaneously.
* When using `replicated-job` or `global-job` mode, using any of the
  update parameter flags will result in an error, as jobs cannot be
  updated in the traditional sense.
* Updated the `docker service ls` UI to include the completion status
  (completed vs total tasks) if the service is a job.
* Updated the progress bars UI for service creation and update to
  support jobs. For jobs, there is displayed a bar covering the overall
  progress of the job (the number of tasks completed over the total
  number of tasks to complete).
* Added documentation explaining the use of the new flags, and of jobs
  in general.

Signed-off-by: Drew Erny <derny@mirantis.com>

docs/reference/commandline/service_create.md

@@ -41,7 +41,8 @@ Options:
       --limit-memory bytes                 Limit Memory
       --log-driver string                  Logging driver for service
       --log-opt list                       Logging driver options
-      --mode string                        Service mode (replicated or global) (default "replicated")
+      --max-concurrent                     Number of job tasks to run at once (default equal to --replicas)
+      --mode string                        Service mode (replicated, global, replicated-job, or global-job) (default "replicated")
       --mount mount                        Attach a filesystem mount to the service
       --name string                        Service name
       --network network                    Network attachments
@@ -1115,6 +1116,66 @@ $ docker service create \
     nvidia/cuda
 ```
 
+### Running as a job
+
+Jobs are a special kind of service designed to run an operation to completion
+and then stop, as opposed to running long-running daemons. When a Task
+belonging to a job exits successfully (return value 0), the Task is marked as
+"Completed", and is not run again.
+
+Jobs are started by using one of two modes, `replicated-job` or `global-job`
+
+```bash
+$ docker service create --name myjob \
+                        --mode replicated-job \
+                        bash "true"
+```
+
+This command will run one Task, which will, using the `bash` image, execute the
+command `true`, which will return 0 and then exit.
+
+Though Jobs are ultimately a different kind of service, they a couple of
+caveats compared to other services:
+
+- None of the update or rollback configuration options are valid.  Jobs can be
+  updated, but cannot be rolled out or rolled back, making these configuration
+  options moot.
+- Jobs are never restarted on reaching the `Complete` state. This means that
+  for jobs, setting `--restart-condition` to `any` is the same as setting it to
+  `on-failure`.
+
+Jobs are available in both replicated and global modes.
+
+#### Replicated Jobs
+
+A replicated job is like a replicated service. Setting the `--replicas` flag
+will specify total number of iterations of a job to execute.
+
+By default, all replicas of a replicated job will launch at once. To control
+the total number of replicas that are executing simultaneously at any one time,
+the `--max-concurrent` flag can be used:
+
+```bash
+$ docker service create --name mythrottledjob \
+                        --mode replicated-job \
+                        --replicas 10 \
+                        --max-concurrent 2 \
+                        bash "true"
+```
+
+The above command will execute 10 Tasks in total, but only 2 of them will be
+run at any given time.
+
+#### Global Jobs
+
+Global jobs are like global services, in that a Task is executed once on each node
+matching placement constraints. Global jobs are represented by the mode `global-job`.
+
+Note that after a Global job is created, any new Nodes added to the cluster
+will have a Task from that job started on them. The Global Job does not as a
+whole have a "done" state, except insofar as every Node meeting the job's
+constraints has a Completed task.
+
 ## Related commands
 
 * [service inspect](service_inspect.md)

docs/reference/commandline/service_ls.md

@@ -39,14 +39,17 @@ On a manager node:
 ```bash
 $ docker service ls
 
-ID            NAME      MODE        REPLICAS    IMAGE
-c8wgl7q4ndfd  frontend  replicated  5/5         nginx:alpine
-dmu1ept4cxcf  redis     replicated  3/3         redis:3.0.6
-iwe3278osahj  mongo     global      7/7         mongo:3.3
+ID            NAME      MODE            REPLICAS             IMAGE
+c8wgl7q4ndfd  frontend  replicated      5/5                  nginx:alpine
+dmu1ept4cxcf  redis     replicated      3/3                  redis:3.0.6
+iwe3278osahj  mongo     global          7/7                  mongo:3.3
+hh08h9uu8uwr  job       replicated-job  1/1 (3/5 completed)  nginx:latest        
 ```
 
 The `REPLICAS` column shows both the *actual* and *desired* number of tasks for
-the service.
+the service. If the service is in `replicated-job` or `global-job`, it will
+additionally show the completion status of the job as completed tasks over
+total tasks the job will execute.
 
 ### Filtering
 

docs/reference/commandline/service_scale.md

@@ -52,7 +52,7 @@ b4g08uwuairexjub6ome6usqh
 
 $ docker service scale backend=10
 
-backend: scale can only be used with replicated mode
+backend: scale can only be used with replicated or replicated-job mode
 ```
 
 Directly afterwards, run `docker service ls`, to see the actual number of

docs/reference/commandline/service_update.md

@@ -54,6 +54,7 @@ Options:
       --limit-memory bytes                 Limit Memory
       --log-driver string                  Logging driver for service
       --log-opt list                       Logging driver options
+      --max-concurrent                     Number of job tasks to run at once (default equal to --replicas)
       --mount-add mount                    Add or update a mount on a service
       --mount-rm list                      Remove a mount by its target path
       --network-add network                Add a network
@@ -298,6 +299,23 @@ See [`service create`](service_create.md#create-services-using-templates) for th
 `service update` supports the same `--isolation` flag as `service create`
 See [`service create`](service_create.md) for the reference.
 
+### Updating Jobs
+
+When a service is created as a job, by setting its mode to `replicated-job` or
+to `global-job` when doing `service create`, options for updating it are
+limited.
+
+Updating a Job immediately stops any Tasks that are in progress. The operation
+creates a new set of Tasks for the job and effectively resets its completion
+status. If any Tasks were running before the update, they are stopped, and new
+Tasks are created.
+
+Jobs cannot be rolled out or rolled back. None of the flags for configuring
+update or rollback settings are valid with job modes.
+
+To run a job again with the same parameters that it was run previously, it can
+be force updated with the `--force` flag.
+
 ## Related commands
 
 * [service create](service_create.md)