github.com/ranjib/nomad@v0.1.1-0.20160225204057-97751b02f70b/website/source/intro/getting-started/jobs.html.md (about)

     1  ---
     2  layout: "intro"
     3  page_title: "Jobs"
     4  sidebar_current: "getting-started-jobs"
     5  description: |-
     6    Learn how to submit, modify and stop jobs in Nomad.
     7  ---
     8  
     9  # Jobs
    10  
    11  Jobs are the primary configuration that users interact with when using
    12  Nomad. A job is a declarative specification of tasks that Nomad should run.
    13  Jobs have a globally unique name, one or many task groups, which are themselves
    14  collections of one or many tasks.
    15  
    16  The format of the jobs is [documented here](/docs/jobspec/index.html). They
    17  can either be specified in [HCL](https://github.com/hashicorp/hcl) or JSON,
    18  however we recommend only using JSON when the configuration is generated by a machine.
    19  
    20  ## Running a Job
    21  
    22  To get started, we will use the [`init` command](/docs/commands/init.html) which
    23  generates a skeleton job file:
    24  
    25  ```
    26  $ nomad init
    27  Example job file written to example.nomad
    28  
    29  $ cat example.nomad
    30  
    31  # There can only be a single job definition per file.
    32  # Create a job with ID and Name 'example'
    33  job "example" {
    34  	# Run the job in the global region, which is the default.
    35  	# region = "global"
    36  ...
    37  ```
    38  
    39  In this example job file, we have declared a single task 'redis' which is using
    40  the Docker driver to run the task. The primary way you interact with Nomad
    41  is with the [`run` command](/docs/commands/run.html). The `run` command takes
    42  a job file and registers it with Nomad. This is used both to register new
    43  jobs and to update existing jobs.
    44  
    45  We can register our example job now:
    46  
    47  ```
    48  $ nomad run example.nomad
    49  ==> Monitoring evaluation "26cfc69e"
    50      Evaluation triggered by job "example"
    51      Allocation "8ba85cef" created: node "171a583b", group "cache"
    52      Evaluation status changed: "pending" -> "complete"
    53  ==> Evaluation "26cfc69e" finished with status "complete"
    54  ```
    55  
    56  Anytime a job is updated, Nomad creates an evaluation to determine what
    57  actions need to take place. In this case, because this is a new job, Nomad has
    58  determined that an allocation should be created and has scheduled it on our
    59  local agent.
    60  
    61  To inspect the status of our job we use the [`status` command](/docs/commands/status.html):
    62  
    63  ```
    64  $ nomad status example
    65  ID          = example
    66  Name        = example
    67  Type        = service
    68  Priority    = 50
    69  Datacenters = dc1
    70  Status      = running
    71  Periodic    = false
    72  
    73  ==> Evaluations
    74  ID        Priority  Triggered By  Status
    75  26cfc69e  50        job-register  complete
    76  
    77  ==> Allocations
    78  ID        Eval ID   Node ID   Task Group  Desired  Status
    79  8ba85cef  26cfc69e  171a583b  cache       run      running
    80  ```
    81  
    82  Here we can see that our evaluation that was created has completed, and that
    83  it resulted in the creation of an allocation that is now running on the local node.
    84  
    85  ## Modifying a Job
    86  
    87  The definition of a job is not static, and is meant to be updated over time.
    88  You may update a job to change the docker container, to update the application version,
    89  or to change the count of a task group to scale with load.
    90  
    91  For now, edit the `example.nomad` file to uncomment the count and set it to 3:
    92  
    93  ```
    94  # Control the number of instances of this group.
    95  # Defaults to 1
    96  count = 3
    97  ```
    98  
    99  Once you have finished modifying the job specification, use `nomad run` to
   100  push the updated version of the job:
   101  
   102  ```
   103  $ nomad run example.nomad
   104  ==> Monitoring evaluation "127a49d0"
   105      Evaluation triggered by job "example"
   106      Allocation "8ab24eef" created: node "171a583b", group "cache"
   107      Allocation "f6c29874" created: node "171a583b", group "cache"
   108      Allocation "8ba85cef" modified: node "171a583b", group "cache"
   109      Evaluation status changed: "pending" -> "complete"
   110  ==> Evaluation "127a49d0" finished with status "complete"
   111  ```
   112  
   113  Because we set the count of the task group to three, Nomad created two
   114  additional allocations to get to the desired state. It is idempotent to
   115  run the same job specification again and no new allocations will be created.
   116  
   117  Now, let's try to do an application update. In this case, we will simply change
   118  the version of redis we want to run. Edit the `example.nomad` file and change
   119  the Docker image from "redis:latest" to "redis:2.8":
   120  
   121  ```
   122  # Configure Docker driver with the image
   123  config {
   124      image = "redis:2.8"
   125  }
   126  ```
   127  
   128  This time we have not changed the number of task groups we want running,
   129  but we've changed the task itself. This requires stopping the old tasks
   130  and starting new tasks. Our example job is configured to do a rolling update via
   131  the `stagger` attribute, doing a single update every 10 seconds. Use `run` to push the updated
   132  specification now:
   133  
   134  ```
   135  $ nomad run example.nomad
   136  ==> Monitoring evaluation "ebcc3e14"
   137      Evaluation triggered by job "example"
   138      Allocation "9a3743f4" created: node "171a583b", group "cache"
   139      Evaluation status changed: "pending" -> "complete"
   140  ==> Evaluation "ebcc3e14" finished with status "complete"
   141  ==> Monitoring evaluation "b508d8f0"
   142      Evaluation triggered by job "example"
   143      Allocation "926e5876" created: node "171a583b", group "cache"
   144      Evaluation status changed: "pending" -> "complete"
   145  ==> Evaluation "b508d8f0" finished with status "complete"
   146  ==> Monitoring next evaluation "ea78c05a" in 10s
   147  ==> Monitoring evaluation "ea78c05a"
   148      Evaluation triggered by job "example"
   149      Allocation "3c8589d5" created: node "171a583b", group "cache"
   150      Evaluation status changed: "pending" -> "complete"
   151  ==> Evaluation "ea78c05a" finished with status "complete"
   152  ```
   153  
   154  We can see that Nomad handled the update in three phases, only updating a single task
   155  group in each phase. The update strategy can be configured, but rolling updates makes
   156  it easy to upgrade an application at large scale.
   157  
   158  ## Stopping a Job
   159  
   160  So far we've created, run and modified a job. The final step in a job lifecycle
   161  is stopping the job. This is done with the [`stop` command](/docs/commands/stop.html):
   162  
   163  ```
   164  $ nomad stop example
   165  ==> Monitoring evaluation "fd03c9f8"
   166      Evaluation triggered by job "example"
   167      Evaluation status changed: "pending" -> "complete"
   168  ==> Evaluation "fd03c9f8" finished with status "complete"
   169  ```
   170  
   171  When we stop a job, it creates an evaluation which is used to stop all
   172  the existing allocations. This also deletes the job definition out of Nomad.
   173  If we try to query the job status, we can see it is no longer registered:
   174  
   175  ```
   176  $ nomad status example
   177  No job(s) with prefix or id "example" found
   178  ```
   179  
   180  If we wanted to start the job again, we could simply `run` it again.
   181  
   182  ## Next Steps
   183  
   184  Users of Nomad primarily interact with jobs, and we've now seen
   185  how to create and scale our job, perform an application update,
   186  and do a job tear down. Next we will add another Nomad
   187  client to [create our first cluster](cluster.html)
   188