github.com/hspak/nomad@v0.7.2-0.20180309000617-bc4ae22a39a5/website/source/docs/commands/plan.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: plan"
     4  sidebar_current: "docs-commands-plan"
     5  description: >
     6    The plan command is used to dry-run a job update to determine its effects.
     7  ---
     8  
     9  # Command: plan
    10  
    11  The `plan` command can be used to envoke the scheduler in a dry-run mode with
    12  new jobs or when updating existing jobs to determine what would happen if the
    13  job is submitted. Job files must conform to the [job
    14  specification](/docs/job-specification/index.html) format.
    15  
    16  ## Usage
    17  
    18  ```
    19  nomad plan [options] <path>
    20  ```
    21  
    22  The plan command requires a single argument, specifying the path to a file
    23  containing a [HCL job specification](/docs/job-specification/index.html). This
    24  file will be read and the resulting parsed job will be validated. If the
    25  supplied path is "-", the job file is read from STDIN. Otherwise it is read
    26  from the file at the supplied path or downloaded and read from URL specified.
    27  Nomad downloads the job file using
    28  [`go-getter`](https://github.com/hashicorp/go-getter)
    29  and supports `go-getter` syntax.
    30  
    31  Plan invokes a dry-run of the scheduler to determine the effects of submitting
    32  either a new or updated version of a job. The plan will not result in any
    33  changes to the cluster but gives insight into whether the job could be run
    34  successfully and how it would affect existing allocations.
    35  
    36  A job modify index is returned with the plan. This value can be used when
    37  submitting the job using [`nomad run
    38  -check-index`](/docs/commands/run.html#check-index), which will check that the
    39  job was not modified between the plan and run command before invoking the
    40  scheduler. This ensures the job has not been modified since the plan.
    41  
    42  A structured diff between the local and remote job is displayed to
    43  give insight into what the scheduler will attempt to do and why.
    44  
    45  If the job has specified the region, the `-region` flag and `NOMAD_REGION`
    46  environment variable are overridden and the job's region is used.
    47  
    48  Plan will return one of the following exit codes:
    49  
    50    * 0: No allocations created or destroyed.
    51    * 1: Allocations created or destroyed.
    52    * 255: Error determining plan results.
    53  
    54  ## General Options
    55  
    56  <%= partial "docs/commands/_general_options" %>
    57  
    58  ## Plan Options
    59  
    60  * `-diff`: Determines whether the diff between the remote job and planned job is
    61    shown. Defaults to true.
    62  
    63  * `-policy-override`: Sets the flag to force override any soft mandatory Sentinel policies.
    64  
    65  * `-verbose`: Increase diff verbosity.
    66  
    67  ## Examples
    68  
    69  Plan a new job that has not been previously submitted:
    70  
    71  ```
    72  $ nomad run job1.nomad
    73  nomad plan example.nomad
    74  + Job: "example"
    75  + Task Group: "cache" (1 create)
    76    + Task: "redis" (forces create)
    77  
    78  Scheduler dry-run:
    79  - All tasks successfully allocated.
    80  
    81  Job Modify Index: 0
    82  To submit the job with version verification run:
    83  
    84  nomad run -check-index 0 example.nomad
    85  
    86  When running the job with the check-index flag, the job will only be run if the
    87  server side version matches the job modify index returned. If the index has
    88  changed, another user has modified the job and the plan's results are
    89  potentially invalid.
    90  ```
    91  
    92  
    93  Increase the count of an existing without sufficient cluster capacity:
    94  
    95  ```
    96  $ nomad plan example.nomad
    97  +/- Job: "example"
    98  +/- Task Group: "cache" (7 create, 1 in-place update)
    99    +/- Count: "1" => "8" (forces create)
   100        Task: "redis"
   101  
   102  Scheduler dry-run:
   103  - WARNING: Failed to place all allocations.
   104    Task Group "cache" (failed to place 3 allocations):
   105      * Resources exhausted on 1 nodes
   106      * Dimension "cpu" exhausted on 1 nodes
   107  
   108  Job Modify Index: 15
   109  To submit the job with version verification run:
   110  
   111  nomad run -check-index 15 example.nomad
   112  
   113  When running the job with the check-index flag, the job will only be run if the
   114  server side version matches the job modify index returned. If the index has
   115  changed, another user has modified the job and the plan's results are
   116  potentially invalid.
   117  ```
   118  
   119  Update an existing job such that it would cause a rolling update:
   120  
   121  ```
   122  $ nomad plan example.nomad
   123  +/- Job: "example"
   124  +/- Task Group: "cache" (3 create/destroy update)
   125    +/- Task: "redis" (forces create/destroy update)
   126      +/- Config {
   127        +/- image:           "redis:2.8" => "redis:3.2"
   128            port_map[0][db]: "6379"
   129      }
   130  
   131  Scheduler dry-run:
   132  - All tasks successfully allocated.
   133  - Rolling update, next evaluation will be in 10s.
   134  
   135  Job Modify Index: 7
   136  To submit the job with version verification run:
   137  
   138  nomad run -check-index 7 example.nomad
   139  
   140  When running the job with the check-index flag, the job will only be run if the
   141  server side version matches the job modify index returned. If the index has
   142  changed, another user has modified the job and the plan's results are
   143  potentially invalid.
   144  ```
   145  
   146  Add a task to the task group using verbose mode:
   147  
   148  ```
   149  $ nomad plan -verbose example.nomad
   150  +/- Job: "example"
   151  +/- Task Group: "cache" (3 create/destroy update)
   152    + Task: "my-website" (forces create/destroy update)
   153      + Driver:      "docker"
   154      + KillTimeout: "5000000000"
   155      + Config {
   156        + image:            "node:6.2"
   157        + port_map[0][web]: "80"
   158      }
   159      + Resources {
   160        + CPU:      "500"
   161        + DiskMB:   "300"
   162        + IOPS:     "0"
   163        + MemoryMB: "256"
   164        + Network {
   165          + MBits: "10"
   166          + Dynamic Port {
   167            + Label: "web"
   168          }
   169        }
   170      }
   171      + LogConfig {
   172        + MaxFileSizeMB: "10"
   173        + MaxFiles:      "10"
   174      }
   175      + Service {
   176        + Name:      "website"
   177        + PortLabel: "web"
   178        + Check {
   179            Command:  ""
   180          + Interval: "10000000000"
   181          + Name:     "alive"
   182            Path:     ""
   183            Protocol: ""
   184          + Timeout:  "2000000000"
   185          + Type:     "tcp"
   186        }
   187      }
   188      Task: "redis"
   189  
   190  Scheduler dry-run:
   191  - All tasks successfully allocated.
   192  - Rolling update, next evaluation will be in 10s.
   193  
   194  Job Modify Index: 7
   195  To submit the job with version verification run:
   196  
   197  nomad run -check-index 7 example.nomad
   198  
   199  When running the job with the check-index flag, the job will only be run if the
   200  server side version matches the job modify index returned. If the index has
   201  changed, another user has modified the job and the plan's results are
   202  potentially invalid.
   203  ```