From de178ca03767c559e756c64494ec6e80615e6b97 Mon Sep 17 00:00:00 2001 From: Alex Dadgar Date: Thu, 16 Jun 2016 17:23:49 -0700 Subject: [PATCH] plan cli docs --- command/plan.go | 6 +- website/source/docs/commands/plan.html.md.erb | 186 ++++++++++++++++++ website/source/docs/commands/run.html.md.erb | 15 +- website/source/layouts/docs.erb | 3 + 4 files changed, 199 insertions(+), 11 deletions(-) create mode 100644 website/source/docs/commands/plan.html.md.erb diff --git a/command/plan.go b/command/plan.go index 5c6ac3333..6a8933b4e 100644 --- a/command/plan.go +++ b/command/plan.go @@ -55,10 +55,8 @@ General Options: Plan Options: -diff - Defaults to true, but can be toggled off to omit diff output. - - -no-color - Disable colored output. + Determines whether the diff between the remote job and planned job is shown. + Defaults to true. -verbose Increase diff verbosity. diff --git a/website/source/docs/commands/plan.html.md.erb b/website/source/docs/commands/plan.html.md.erb new file mode 100644 index 000000000..7afdadd87 --- /dev/null +++ b/website/source/docs/commands/plan.html.md.erb @@ -0,0 +1,186 @@ +--- +layout: "docs" +page_title: "Commands: plan" +sidebar_current: "docs-commands-plan" +description: > + The plan command is used to dry-run a job update to determine its effects. +--- + +# Command: plan + +The `plan` command can be used to envoke the scheduler in a dry-run mode with new +jobs or when updating existing jobs to determine what would happen if the job +is submitted. Job files must conform to the [job specification](/docs/jobspec/index.html) +format. + +## Usage + +``` +nomad plan [options] +``` + +Plan invokes a dry-run of the scheduler to determine the effects of submitting +either a new or updated version of a job. The plan will not result in any +changes to the cluster but gives insight into whether the job could be run +successfully and how it would affect existing allocations. + +A job modify index is returned with the plan. This value can be used when +submitting the job using [`nomad run +-check-index`](/docs/commands/run.html#check-index), which will check that the +job was not modified between the plan and run command before invoking the +scheduler. This ensures the job has not been modified since the plan. + +A structured diff between the local and remote job is displayed to +give insight into what the scheduler will attempt to do and why. + +If the job has specified the region, the `-region` flag and `NOMAD_REGION` +environment variable are overridden and the the job's region is used. + +## General Options + +<%= general_options_usage %> + +## Plan Options + +* `-diff`: Determines whether the diff between the remote job and planned job is + shown. Defaults to true. + +* `-verbose`: Increase diff verbosity. + +## Examples + +Plan a new job that has not been previously submitted: + +``` +$ nomad run job1.nomad +nomad plan example.nomad ++ Job: "example" ++ Task Group: "cache" (1 create) + + Task: "redis" (forces create) + +Scheduler dry-run: +- All tasks successfully allocated. + +Job Modify Index: 0 +To submit the job with version verification run: + +nomad run -check-index 0 example.nomad + +When running the job with the check-index flag, the job will only be run if the +server side version matches the the job modify index returned. If the index has +changed, another user has modified the job and the plan's results are +potentially invalid. +``` + + +Increase the count of an existing without sufficient cluster capacity: + +``` +$ nomad plan example.nomad ++/- Job: "example" ++/- Task Group: "cache" (7 create, 1 in-place update) + +/- Count: "1" => "8" (forces create) + Task: "redis" + +Scheduler dry-run: +- WARNING: Failed to place all allocations. + Task Group "cache" (failed to place 3 allocations): + * Resources exhausted on 1 nodes + * Dimension "cpu exhausted" exhausted on 1 nodes + +Job Modify Index: 15 +To submit the job with version verification run: + +nomad run -check-index 15 example.nomad + +When running the job with the check-index flag, the job will only be run if the +server side version matches the the job modify index returned. If the index has +changed, another user has modified the job and the plan's results are +potentially invalid. +``` + +Update an existing job such that it would cause a rolling update: + +``` +$ nomad plan example.nomad ++/- Job: "example" ++/- Task Group: "cache" (3 create/destroy update) + +/- Task: "redis" (forces create/destroy update) + +/- Config { + +/- image: "redis:2.8" => "redis:3.2" + port_map[0][db]: "6379" + } + +Scheduler dry-run: +- All tasks successfully allocated. +- Rolling update, next evaluation will be in 10s. + +Job Modify Index: 7 +To submit the job with version verification run: + +nomad run -check-index 7 example.nomad + +When running the job with the check-index flag, the job will only be run if the +server side version matches the the job modify index returned. If the index has +changed, another user has modified the job and the plan's results are +potentially invalid. +``` + +Add a task to the task group using verbose mode: + +``` +$ nomad plan -verbose example.nomad ++/- Job: "example" ++/- Task Group: "cache" (3 create/destroy update) + + Task: "my-website" (forces create/destroy update) + + Driver: "docker" + + KillTimeout: "5000000000" + + Config { + + image: "node:6.2" + + port_map[0][web]: "80" + } + + Resources { + + CPU: "500" + + DiskMB: "300" + + IOPS: "0" + + MemoryMB: "256" + + Network { + + MBits: "10" + + Dynamic Port { + + Label: "web" + } + } + } + + LogConfig { + + MaxFileSizeMB: "10" + + MaxFiles: "10" + } + + Service { + + Name: "website" + + PortLabel: "web" + + Check { + Command: "" + + Interval: "10000000000" + + Name: "alive" + Path: "" + Protocol: "" + + Timeout: "2000000000" + + Type: "tcp" + } + } + Task: "redis" + +Scheduler dry-run: +- All tasks successfully allocated. +- Rolling update, next evaluation will be in 10s. + +Job Modify Index: 7 +To submit the job with version verification run: + +nomad run -check-index 7 example.nomad + +When running the job with the check-index flag, the job will only be run if the +server side version matches the the job modify index returned. If the index has +changed, another user has modified the job and the plan's results are +potentially invalid. +``` diff --git a/website/source/docs/commands/run.html.md.erb b/website/source/docs/commands/run.html.md.erb index e0b3e6ef5..aa80355a8 100644 --- a/website/source/docs/commands/run.html.md.erb +++ b/website/source/docs/commands/run.html.md.erb @@ -41,12 +41,12 @@ environment variable are overridden and the the job's region is used. ## Run Options -* `-check-index`: If set, the job is only registered or updated if the the - passed job modify index matches the server side version. If a check-index value - of zero is passed, the job is only registered if it does not yet exist. If a - non-zero value is passed, it ensures that the job is being updated from a known - state. The use of this flag is most common in conjunction with [plan - command](/docs/commands/plan.html). +* `-check-index`: If set, the job is only registered or + updated if the the passed job modify index matches the server side version. + If a check-index value of zero is passed, the job is only registered if it does + not yet exist. If a non-zero value is passed, it ensures that the job is being + updated from a known state. The use of this flag is most common in conjunction + with [plan command](/docs/commands/plan.html). * `-detach`: Return immediately instead of monitoring. A new evaluation ID will be output, which can be used to examine the evaluation using the @@ -72,7 +72,8 @@ $ nomad run job1.nomad ==> Evaluation "52dee78a" finished with status "complete" ``` -Update the job using check-index: + Update the job using `check-index`: + ``` $ nomad run -check-index 5 example.nomad Enforcing job modify index 5: job exists with conflicting job modify index: 6 diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index 0abef6c64..999b85dda 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -135,6 +135,9 @@ > node-status + > + plan + > run