Merge pull request #6396 from hashicorp/d-updated-ui-guides

Docs: Updated UI guides

scripts/screenshots/src/index.js

@@ -31,7 +31,7 @@ const ANSI_YELLOW = "\x1b[33m%s\x1b[0m";
   const page = await browser.newPage();
 
   // Make sure the page is 4K is high-dpi scaling
-  page.setViewport({ width: 1920, height: 1080, deviceScaleFactor: 2 });
+  page.setViewport({ width: 1440, height: 900, deviceScaleFactor: 2 });
   console.log("Loading Nomad UI...");
   console.log(
     ANSI_YELLOW,

website/source/assets/stylesheets/_inner.scss

@@ -1,5 +1,7 @@
 #inner {
-  p, li, .alert {
+  p,
+  li,
+  .alert {
     font-size: $font-size;
     font-family: $font-family-open-sans;
     font-weight: $font-weight-reg;
@@ -52,9 +54,9 @@
   img {
     display: block;
     margin: 25px auto;
-    max-width: 650px;
+    max-width: 95%;
     height: auto;
-    width: 90%;
+    width: auto;
   }
 
   h1,
@@ -76,7 +78,7 @@
   h2 > code,
   h3 > code,
   h4 > code,
-  h5 > code
+  h5 > code,
   h6 > code,
   li code,
   table code,

website/source/guides/web-ui/access.html.md

@@ -0,0 +1,41 @@
+---
+layout: "guides"
+page_title: "Accessing the Web UI"
+sidebar_current: "guides-web-ui-access"
+description: |-
+  Learn how to access the Nomad Web UI from a browser or from the CLI.
+---
+
+# Accessing the Web UI
+
+The Nomad Web UI is served alongside the API. If you visit the Nomad server address in a web
+browser, you will be redirected to the Web UI, which is served under `/ui`. If you are unsure what
+port the Nomad HTTP API is running on, try the default port: `4646`.
+
+The first page you will see is a listing of all Jobs for the default namespace.
+
+[![Jobs List][img-jobs-list]][img-jobs-list]
+
+The entire Web UI sitemap is [documented as an API](/api/ui.html).
+
+## Getting to the Web UI from the CLI
+
+In order to make it as seamless as possible to jump between the CLI and UI, the Nomad CLI has a
+[`ui` subcommand](/docs/commands/ui.html). This command can take any identifier and open the
+appropriate web page.
+
+**Open the UI directly to look at a job:**
+
+```
+$ nomad ui redis-job
+http://127.0.0.1:4646/ui/jobs/redis-job
+```
+
+**Open the UI directly to look at an allocation:**
+
+```
+$ nomad ui d4005969
+Opening URL "http://127.0.0.1:4646/ui/allocations/d4005969-b16f-10eb-4fe1-a5374986083d"
+```
+
+[img-jobs-list]: /assets/images/guide-ui-jobs-list.png

website/source/guides/web-ui/index.html.md

@@ -0,0 +1,19 @@
+---
+layout: "guides"
+page_title: "Web UI"
+sidebar_current: "guides-web-ui"
+description: |-
+  Learn how to use the Nomad Web UI.
+---
+
+# Using Nomad with the Web UI
+
+The Nomad Web UI offers an easy to use web experience for inspecting a Nomad cluster. It's built
+into the Nomad binary and is served alongside the API. With zero additional configuration, you can
+use the Web UI instead of the CLI to inspect cluster state and submit and manage jobs.
+
+1. [Accessing the Web UI](/guides/web-ui/access.html)
+1. [Submitting a Job](/guides/web-ui/submitting-a-job.html)
+1. [Operating a Job](/guides/web-ui/operating-a-job.html)
+1. [Inspecting the Cluster](/guides/web-ui/inspecting-the-cluster.html)
+1. [Securing the Web UI with ACLs](/guides/web-ui/securing.html)

website/source/guides/web-ui/inspecting-the-cluster.html.md

@@ -0,0 +1,148 @@
+---
+layout: "guides"
+page_title: "Inspecting the Cluster"
+sidebar_current: "guides-web-ui-inspecting-the-cluster"
+description: |-
+  Learn how to inspect the state of the cluster from the Web UI.
+---
+
+# Inspecting the Cluster
+
+The Web UI can be a powerful tool for monitoring the state of the Nomad cluster from an
+operator's perspective. This includes showing all client nodes, showing driver health for client nodes,
+driver status, resource utilization, allocations by client node, and more.
+
+## Reviewing All Clients
+
+From any page, the Clients List page can be accessed from the left-hand navbar. On narrow screens
+this navbar may need to opened from the top-right menu button. Here you see every client in the
+cluster. The table of clients is searchable, sortable, and filterable. Each client row in the table
+show basic information, such as the Node ID, name, state, address, datacenter, and how many
+allocations are running in it.
+
+This view will also live-update as the state of client nodes change.
+
+[![Clients List][img-clients-list]][img-clients-list]
+
+## Filtering Clients
+
+If your Nomad cluster has many client nodes, it can be useful to filter the list of all client nodes
+down to only those matching certain facets. The Web UI has three facets you can filter by:
+
+1. **Class:** The node of the client, including a dynamically generated list based on the node class
+   of each client node in the cluster.
+2. **State:** The state of the cluster, including Initializing, Ready, Down, Ineligible, and
+   Draining.
+3. **Datacenter:** The datacenter the client node is in, including a dynamically generated list based
+   on all the datacenters in the cluster.
+
+[![Clients filters][img-clients-filters]][img-clients-filters]
+
+## Inspecting an Individual Client
+
+From the Clients List page, clicking a client node in the table will direct you to the Client Detail
+page for the client node. This page includes all information about the client node is live-updated
+to always present up-to-date information.
+
+[![Client Detail][img-client-detail]][img-client-detail]
+
+### Resource Utilization
+
+Nomad as APIs for reading point-in-time resource utilization metrics for client nodes. The Web UI
+uses these metrics to create time-series graphics for the current session.
+
+When viewing a client node, resource utilization will automatically start logging.
+
+[![Client Resource Utilization][img-client-resource-utilization]][img-client-resource-utilization]
+
+### Allocations
+
+Allocations belong to jobs and are placed on client nodes. The Client Detail page will list all
+allocations for a client node, including completed, failed, and lost allocations, until they are
+garbage-collected.
+
+This is presented in a searchable table which can additionally be filtered to only preempted
+allocations.
+
+[![Client Allocations][img-client-allocations]][img-client-allocations]
+
+### Client Events
+
+Client nodes will also emit events on meaningful state changes, such as when the node becomes ready
+for scheduling or when a driver becomes unhealthy.
+
+[![Client Events][img-client-events]][img-client-events]
+
+### Driver Status
+
+Task drivers are additional services running on a client node. Nomad will fingerprint and
+communicate with the task driver to determine if the driver is available and healthy. This
+information is reported through the Web UI on the Client Detail page.
+
+[![Client Driver Status][img-client-driver-status]][img-client-driver-status]
+
+### Attributes
+
+In order to allow job authors to constrain the placement of their jobs, Nomad fingerprints the
+hardware of the node the client agent is running on. This is a deeply nested document of properties
+that the Web UI presents in a scannable way.
+
+In addition to the hardware attributes, Nomad operators can annotate
+[a client node with metadata](/docs/configuration/client.html#meta) as part of the client configuration. This metadata
+is also presented on the Client Detail page.
+
+[![Client Attributes][img-client-attributes]][img-client-attributes]
+
+## When a Node is Draining
+
+A routine part of maintaining a Nomad cluster is draining nodes of allocations. This can be in
+preparation of performing operating system upgrades or decommissioning an old node in favor of a new
+VM.
+
+Drains are [performed from the CLI](/guides/operations/node-draining.html) but the status of a drain
+can be seen from the Web UI. A client node will state if it is actively draining or ineligible for
+scheduling.
+
+Since drains can be configured in a variety of ways, the Client Detail page will also present the
+details of how the drain is performed.
+
+[![Client Drain][img-client-drain]][img-client-drain]
+
+## Reviewing All Servers
+
+Whereas client nodes are used to run your jobs, server nodes are used to run Nomad and maintain
+availability. From any page, the Servers List page can be accessed from the left-hand navbar.
+
+Here you can see every server node. This will be a small list—[typically three or five](/docs/internals/consensus.html#deployment-table).
+
+[![Servers List][img-servers-list]][img-servers-list]
+
+## Inspecting an Individual Server
+
+Clicking a server node on the Servers List will expand the tags table for the server node.
+
+[![Server Detail][img-server-detail]][img-server-detail]
+
+## Access Control
+
+Depending on the size of your team and the details of you Nomad deployment, you may wish to control
+which features different internal users have access to. This includes limiting who has access to see
+and manage client nodes and see and manage server nodes. You can enforce this with Nomad's access
+control list system.
+
+By default, all features—read and write—are available to all users of the Web UI. Check out the
+[Securing the Web UI with ACLs](/guides/web-ui/securing.html) guide to learn how to prevent
+anonymous users from having write permissions as well as how to continue to use Web UI write
+features as a privileged user.
+
+[img-client-allocations]: /assets/images/guide-ui-img-client-allocations.png
+[img-client-attributes]: /assets/images/guide-ui-img-client-attributes.png
+[img-client-detail]: /assets/images/guide-ui-img-client-detail.png
+[img-client-drain]: /assets/images/guide-ui-img-client-drain.png
+[img-client-driver-status]: /assets/images/guide-ui-img-client-driver-status.png
+[img-client-events]: /assets/images/guide-ui-img-client-events.png
+[img-client-resource-utilization]: /assets/images/guide-ui-img-client-resource-utilization.png
+[img-clients-filters]: /assets/images/guide-ui-img-clients-filters.png
+[img-clients-list]: /assets/images/guide-ui-img-clients-list.png
+[img-server-detail]: /assets/images/guide-ui-img-server-detail.png
+[img-servers-list]: /assets/images/guide-ui-img-servers-list.png

website/source/guides/web-ui/operating-a-job.html.md

@@ -0,0 +1,212 @@
+---
+layout: "guides"
+page_title: "Operating a Job from the Web UI"
+sidebar_current: "guides-web-ui-operating-a-job"
+description: |-
+  Learn how to operate a job from the Web UI.
+---
+
+# Reviewing Job and Allocation Status
+
+The Web UI can be a powerful companion when monitoring and debugging jobs running in Nomad. The Web
+UI will list all jobs, link jobs to allocations, allocations to client nodes, client nodes to driver
+health, and much more.
+
+## Reviewing All Jobs
+
+The first page you will see in the Web UI is the Jobs List page. Here you will find every job for a
+namespace in a region. The table of jobs is searchable, sortable, and filterable. Each job row in
+the table shows basic information, such as job name, status, type, and priority, as well as richer
+information such as a visual representation of all allocation statuses.
+
+This view will also live-update as jobs get submitted, get purged, and change status.
+
+[![Jobs List][img-jobs-list]][img-jobs-list]
+
+## Filtering Jobs
+
+If your Nomad cluster has many jobs, it can be useful to filter the list of all jobs down to only
+those matching certain facets. The Web UI has four facets you can filter by:
+
+1. **Type:** The type of job, including Batch, Parameterized, Periodic, Service, and System.
+2. **Status:** The status of the job, including Pending, Running, and Dead.
+3. **Datacenter:** The datacenter the job is running in, including a dynamically generated list
+   based on the jobs in the namespace.
+4. **Prefix:** The possible common naming prefix for a job, including a dynamically generated list
+   based on job names up to the first occurrence of `-`, `.`, and `_`. Only prefixes that match
+   multiple jobs are included.
+
+[![Job Filters][img-job-filters]][img-job-filters]
+
+## Monitoring an Allocation
+
+In Nomad, allocations are the schedulable units of work. This is where runtime metrics begin to
+surface. An allocation is composed of one or more tasks, and the utilization metrics for tasks are
+aggregated so they can be observed at the allocation level.
+
+### Resource Utilization
+
+Nomad has APIs for reading point-in-time resource utilization metrics for tasks and allocations. The
+Web UI uses these metrics to create time-series graphs for the current session.
+
+When viewing an allocation, resource utilization will automatically start logging.
+
+[![Allocation Resource Utilization][img-alloc-resource-utilization]][img-alloc-resource-utilization]
+
+### Task Events
+
+When Nomad places, prepares, and starts a task, a series of task events are emitted to help debug
+issues in the event that the task fails to start.
+
+Task events are listed on the Task Detail page and live-update as Nomad handles managing the task.
+
+[![Task Events][img-task-events]][img-task-events]
+
+### Rescheduled Allocations
+
+Allocations will be placed on any client node that satisfies the constraints of the job definition.
+There are events, however, that will cause Nomad to reschedule allocations, (e.g., node failures).
+
+Allocations can be configured [in the job definition to reschedule](/docs/job-specification/reschedule.html)
+to a different client node if the allocation ends in a failed status. This will happen after the
+task has exhausted its [local restart attempts](/docs/job-specification/restart.html).
+
+The end result of this automatic procedure is a failed allocation and that failed allocation's
+rescheduled successor. Since Nomad handles all of this automatically, the Web UI makes sure to
+explain the state of allocations through icons and linking previous and next allocations in a
+reschedule chain.
+
+[![Allocation Reschedule Icon][img-alloc-reschedule-icon]][img-alloc-reschedule-icon]
+
+[![Allocation Reschedule Details][img-alloc-reschedule-details]][img-alloc-reschedule-details]
+
+### Unhealthy Driver
+
+Given the nature of long-lived processes, it's possible for the state of the client node an
+allocation is scheduled on to change during the lifespan of the allocation. Nomad attempts to
+monitor pertinent conditions including driver health.
+
+The Web UI denotes when a driver an allocation depends on is unhealthy on the client node the
+allocation is running on.
+
+[![Allocation Unhealthy Driver][img-alloc-unhealthy-driver]][img-alloc-unhealthy-driver]
+
+### Preempted Allocations
+
+Much like how Nomad will automatically reschedule allocations, Nomad will automatically preempt
+allocations when necessary. When monitoring allocations in Nomad, it's useful to know what
+allocations were preempted and what job caused the preemption.
+
+The Web UI makes sure to tell this full story by showing which allocation caused an allocation to be
+preempted as well as the opposite: what allocations an allocation preempted. This makes it possible
+to traverse down from a job to a preempted allocation, to the allocation that caused the preemption,
+to the job that the preempting allocation is for.
+
+[![Allocation Preempter][img-alloc-preempter]][img-alloc-preempter]
+
+[![Allocation Preempted][img-alloc-preempted]][img-alloc-preempted]
+
+## Reviewing Logs for a Task
+
+A task will typically emit log information to `stdout` and `stderr`. Nomad captures these logs and
+exposes them through an API. The Web UI uses these APIs to offer `head`, `tail`, and streaming logs
+from the browser.
+
+The Web UI will first attempt to directly connect to the client node the task is running on.
+Typically, client nodes are not accessible from the public internet. If this is the case, the Web UI
+will fall back and proxy to the client node from the server node with no loss of functionality.
+
+[![Task Logs][img-task-logs]][img-task-logs]
+
+~> Not all browsers support streaming http requests. In the event that streaming is not supported,
+logs will still be followed using interval polling.
+
+## Restarting or Stopping an Allocation or Task
+
+Nomad allows for restarting and stopping individual allocations and tasks. When a
+task is restarted, Nomad will perform a local restart of the task. When an allocation is stopped,
+Nomad will mark the allocation as complete and perform a reschedule onto a different client node.
+
+Both of these features are also available in the Web UI.
+
+[![Allocation Stop and Restart][img-alloc-stop-restart]][img-alloc-stop-restart]
+
+## Forcing a Periodic Instance
+
+Periodic jobs are configured like a cron job. Sometimes, we want to micromanage the job instead of
+waiting for the period duration to elapse. Nomad calls this a
+[periodic force](/docs/commands/job/periodic-force.html) and it can be done from the Web UI on the
+Job Overview page for a periodic job.
+
+[![Periodic Force][img-periodic-force]][img-periodic-force]
+
+## Submitting a New Version of a Job
+
+From the Job Definition page, a job can be edited. After clicking the Edit button in the top-right
+corner of the code window, the job definition JSON becomes editable. The edits can then be planned
+and scheduled.
+
+[![Job Definition Edit][img-job-definition-edit]][img-job-definition-edit]
+
+~> Since each job within a namespace must have a unique name, it is possible to submit a new version
+of a job from the Run Job screen. Always review the plan output!
+
+## Monitoring a Deployment
+
+When a system or service job includes the [`update` stanza](/docs/job-specification/update.html), a
+deployment is created upon job submission. Job deployments can be monitored in realtime from the Web
+UI.
+
+The Web UI will show as new allocations become placed, tallying towards the expected total, and
+tally allocations as they becme healthy or unhealthy.
+
+Optionally, a job may use canary deployments to allow for additional health checks or manual testing
+before a full roll out. If a job uses canaries and is not configured to automatically promote the
+canary, the canary promotion operation can be done from the Job Overview page in the Web UI.
+
+[![Job Deployment with Canary Promotion][img-job-deployment-canary]][img-job-deployment-canary]
+
+## Stopping a Job
+
+Jobs can be stopped from the Job Overview page. Stopping a job will gracefully stop all allocations,
+marking them as complete, and freeing up resources in the cluster.
+
+[![Job Stop][img-job-stop]][img-job-stop]
+
+## Access Control
+
+Depending on the size of your team and the details of your Nomad deployment, you may wish to control
+which features different internal users have access to. This includes differentiation between
+submitting jobs, restarting allocations, and viewing potentially sensitive logs. You can enforce
+this with Nomad's access control list system.
+
+By default, all features—read and write—are available to all users of the Web UI. Check out the
+[Securing the Web UI with ACLs](/guides/web-ui/securing.html) guide to learn how to prevent
+anonymous users from having write permissions as well as how to continue to use Web UI write
+features as a privileged user.
+
+## Best Practices
+
+Although the Web UI lets users submit jobs in an ad-hoc manner, Nomad was deliberately designed to
+declare jobs using a configuration language. It is recommended to treat your job definitions, like
+the rest of your infrastructure, as code.
+
+By checking in your job definition files as source control, you will always have a log of changes to
+assist in debugging issues, rolling back versions, and collaborating on changes using development
+best practices like code review.
+
+[img-jobs-list]: /assets/images/guide-ui-jobs-list.png
+[img-job-filters]: /assets/images/guide-ui-img-job-filters.png
+[img-alloc-resource-utilization]: /assets/images/guide-ui-img-alloc-resource-utilization.png
+[img-task-events]: /assets/images/guide-ui-img-task-events.png
+[img-alloc-reschedule-icon]: /assets/images/guide-ui-img-alloc-reschedule-icon.png
+[img-alloc-reschedule-details]: /assets/images/guide-ui-img-alloc-reschedule-details.png
+[img-alloc-unhealthy-driver]: /assets/images/guide-ui-img-alloc-unhealthy-driver.png
+[img-alloc-preempter]: /assets/images/guide-ui-img-alloc-preempter.png
+[img-alloc-preempted]: /assets/images/guide-ui-img-alloc-preempted.png
+[img-task-logs]: /assets/images/guide-ui-img-task-logs.png
+[img-alloc-stop-restart]: /assets/images/guide-ui-img-alloc-stop-restart.png
+[img-periodic-force]: /assets/images/guide-ui-img-periodic-force.png
+[img-job-definition-edit]: /assets/images/guide-ui-img-job-definition-edit.png
+[img-job-deployment-canary]: /assets/images/guide-ui-img-job-deployment-canary.png
+[img-job-stop]: /assets/images/guide-ui-img-job-stop.png

website/source/guides/web-ui/securing.html.md

@@ -0,0 +1,32 @@
+---
+layout: "guides"
+page_title: "Web UI"
+sidebar_current: "guides-web-ui-securing"
+description: |-
+  Learn how to use ACLs to secure the Web UI
+---
+
+# Securing the Web UI with ACLs
+
+By default, all features—read and write—are available to all users of the Web UI. By using [Access Control Lists](/guides/security/acl.html), it is possible to lock down what users get access to which features.
+
+## Browsing the Web UI Without an Access Control Token
+
+When a user browses the Web UI without specifying an access control token, they assume the rules of the [anonymous policy](/guides/security/acl.html#set-an-anonymous-policy-optional-). Since Nomad ACLs use a default-deny model, if ACLs are enabled and no anonymous policy is authored, the Web UI will show unauthorized messages on every page other than the settings page.
+
+[![Not authorized to see jobs][img-jobs-list-unauthorized]][img-jobs-list-unauthorized]
+
+## Setting an Access Control Token
+
+From the ACL Tokens page, which is accessible from the top-right menu, you can set your access control token via the token Secret ID.
+
+This token is saved to local storage and can be manually cleared from the ACL Tokens page.
+
+[![ACL token page][img-acl-token]][img-acl-token]
+
+[![ACL token set][img-acl-token-set]][img-acl-token-set]
+
+
+[img-jobs-list-unauthorized]: /assets/images/guide-ui-jobs-list-unauthorized.png
+[img-acl-token]: /assets/images/guide-ui-acl-token.png
+[img-acl-token-set]: /assets/images/guide-ui-acl-token-set.png

website/source/guides/web-ui/submitting-a-job.html.md

@@ -0,0 +1,184 @@
+---
+layout: "guides"
+page_title: "Submitting a Job from the Web UI"
+sidebar_current: "guides-web-ui-submitting-a-job"
+description: |-
+  Learn how to submit a job from the Web UI.
+---
+
+# Submitting a Job
+
+On the Jobs List page of the Web UI (this is the home page), there is a "Run Job" button in the
+top-left corner. Clicking this button will take you to the Job Run page.
+
+The first step in running a job is authoring the job HCL or JSON. Code can be authored directly in
+the UI, complete with syntax highlighting, or it can be pasted in. After you have authored the job,
+the next step is to run the plan.
+
+[![Job Run Page][img-job-run]][img-job-run]
+
+## Nomad plan
+
+It is best practice to run `nomad plan` before running `nomad run`, so the Web UI enforces this
+best practice. From the Job Run page, underneath the code editor, there is a Plan button. Clicking
+this button will proceed the run process to the second step.
+
+The second step to submitting a job is reviewing the job plan. If you are submitting a new job, the
+plan will only show additions. If you are submitting a new version of the job, the plan will include
+details on what has been changed, added, and removed.
+
+[![Job Plan Page][img-job-plan]][img-job-plan]
+
+The plan operation will also perform a scheduler dry-run. This dry-run is helpful for catching
+potential issues early. Some potential issues are:
+
+1. There is not enough capacity in the cluster to start your job.
+2. There is not enough capacity remaining in your quota to start your job.
+3. Your job has an unresolvable hard constraint (e.g., required port not available).
+4. In order to start your job, other jobs must be preempted.
+
+[![Job Plan Placement Failures][img-job-plan-placement-failures]][img-job-plan-placement-failures]
+
+From the plan step, you can either cancel to make edits, or run the job. When you run the job, you
+are redirected to the Job Overview page.
+
+## Placement failures
+
+One class of potential issues when planning a job is a placement failure. This happens when Nomad
+can tell ahead of time that a job cannot be started. Since Nomad does bookkeeping on cluster state
+and node metadata, Nomad will already know the answer to basic constraints, such as available
+capacity, available hardware, and available ports.
+
+Nomad will always let you submit a job to the cluster despite placement failures. The job will just
+remain in a queued state until the placement failures are resolved.
+
+Keep in mind that there will always be the possibility that Nomad cannot start a job despite there
+being no placement failures (e.g., artifact cannot download or container startup script errors).
+
+## Preemptions
+
+Another class of potential issues when planning a job is
+[preemptions](/docs/internals/scheduling/preemption.html). This happens when the cluster does not
+have capacity for your job, but your job is a high priority and the cluster has preemptions enabled.
+
+[![Job Plan Preemptions][img-job-plan-preemptions]][img-job-plan-preemptions]
+
+Unlike with placement failures, when you submit a job that has expected preemptions, the job will
+start. However, other allocations will be stopped to free up capacity.
+
+~> With Nomad OSS, only system jobs can preempt allocations. Nomad Enterprise allows for both
+service and batch type jobs to preempt lower priority allocations.
+
+## Job Overview
+
+Upon submitting a job, you will be redirected to the Job Overview page for the job you submitted.
+
+If this is a new job, the job will start in a queued state. If there are no placement failures,
+allocations for the job will naturally transition from a starting to a running or failed state.
+Nomad is quick to schedule allocations (i.e., find a client node to start the allocation on), but an
+allocation may sit in the starting state for a while if it has to download
+[source images](/docs/job-specification/task.html#task-examples) or
+[other artifacts](/docs/job-specification/artifact.html). It may also sit in a starting state if the
+task fails to start and requires retry attempts.
+
+If this is was an existing job that was resubmitted, the job overview will show old allocations
+moving into a completed status before new allocations are spun up. The exact sequence of events
+depends on the configuration of the job.
+
+No matter the configuration of the job, the Job Overview page will live-update as the state of the
+job and its allocations change.
+
+[![Job Overview][img-job-overview]][img-job-overview]
+
+## Job Definition
+
+From the subnav on any job detail page, you can access the Job Definition page.
+
+The Job Definition page will show the job's underlying JSON representation. This can be useful for
+quickly verifying how the job was configured. Many properties from the job configuration will also
+be on the Job Overview page, but some deeper properties may only be available in the definition
+itself. It can also be convenient to see everything at once rather than traversing through task
+groups, allocations, and tasks.
+
+[![Job Definition][img-job-definition]][img-job-definition]
+
+## Job Versions
+
+From the subnav on any job detail page, you can access the Job Versions page.
+
+The Job Versions page will show a timeline view of every version of the job. Each version in the
+timeline includes the version number, the time the version was submitted, whether the version is/was
+stable, the number of changes, and the job diff.
+
+Reviewing the job diffs version by version can be used to debug issues in a similar manner to `git log`.
+
+[![Jobs Versions][img-job-versions]][img-job-versions]
+
+## Job Deployments
+
+From the subnav on any service job detail page, you can access the Job Deployments page.
+
+The Job Deployments page will show a timeline view of every deployment of the job. Each deployment
+in the timeline includes the deployment ID, the deployment status, whether or not the deployment
+requires promotion, the associated version number, the relative time the deployment started, and a
+detailed allocation breakdown.
+
+The allocation breakdown includes information on allocation placement, including how many canaries
+have been placed, how many canaries are expected, how many total allocations have been placed, how
+many total allocations are desired, and the health of each allocation.
+
+[![Jobs Deployments][img-job-deployments]][img-job-deployments]
+
+## Job Allocations
+
+From the subnav on any job detail page, you can access the Job Allocations page.
+
+The Job Allocations page will show a complete table of every allocation for a job. Allocations,
+being the unit of work in Nomad, are accessible from many places. The Job Overview page lists some
+of the recent allocations for a job for convenience and the Job Task Group page will list all
+allocations for that task group, but only the Job Allocations page shows every allocation across all
+task groups for the job.
+
+[![Jobs Allocations][img-job-allocations]][img-job-allocations]
+
+## Job Evaluations
+
+From the subnav on any job detail page, you can access the Job Evaluations page.
+
+The Job Evaluations page will show the most recent evaluations for the job. Evaluations are an
+internal detail of Nomad's inner scheduling process and as such are generally unimportant to
+monitor, but an experienced Nomad user can use evaluations to diagnose potential issues.
+
+[![Job Evaluations][img-job-evaluations]][img-job-evaluations]
+
+## Access Control
+
+Depending on the size of your team and the details of your Nomad deployment, you may wish to control
+which features different internal users have access to. You can enforce this with Nomad's access
+control list system.
+
+By default, all features—read and write—are available to all users of the Web UI. Check out the
+[Securing the Web UI with ACLs](/guides/web-ui/securing.html) guide to learn how to prevent
+anonymous users from having write permissions as well as how to continue to use Web UI write
+features as a privileged user.
+
+## Best Practices
+
+Although the Web UI lets users submit jobs in an ad-hoc manner, Nomad was deliberately designed to
+declare jobs using a configuration language. It is recommended to treat your job definitions, like
+the rest of your infrastructure, as code.
+
+By checking in your job definition files as source control, you will always have a log of changes to
+assist in debugging issues, rolling back versions, and collaborating on changes using development
+best practices like code review.
+
+[img-job-run]: /assets/images/guide-ui-img-job-run.png
+[img-job-plan]: /assets/images/guide-ui-img-job-plan.png
+[img-job-plan-placement-failures]: /assets/images/guide-ui-img-job-plan-placement-failures.png
+[img-job-plan-preemptions]: /assets/images/guide-ui-img-job-plan-preemptions.png
+[img-job-overview]: /assets/images/guide-ui-img-job-overview-system.png
+[img-job-definition]: /assets/images/guide-ui-img-job-definition.png
+[img-job-versions]: /assets/images/guide-ui-img-job-versions.png
+[img-job-deployments]: /assets/images/guide-ui-img-job-deployments.png
+[img-job-allocations]: /assets/images/guide-ui-img-job-allocations.png
+[img-job-evaluations]: /assets/images/guide-ui-img-job-evaluations.png

website/source/layouts/guides.erb

@@ -281,6 +281,27 @@
         </ul>
       </li>
 
+      <li<%= sidebar_current("guides-web-ui") %>>
+        <a href="/guides/web-ui/">Web UI</a>
+        <ul class="nav">
+          <li<%= sidebar_current("guides-web-ui-access") %>>
+            <a href="/guides/web-ui/access.html">Accessing the Web UI</a>
+          </li>
+          <li<%= sidebar_current("guides-web-ui-submitting-a-job") %>>
+            <a href="/guides/web-ui/submitting-a-job.html">Submitting a Job</a>
+          </li>
+          <li<%= sidebar_current("guides-web-ui-operating-a-job") %>>
+            <a href="/guides/web-ui/operating-a-job.html">Operating a Job</a>
+          </li>
+          <li<%= sidebar_current("guides-web-ui-inspecting-the-cluster") %>>
+            <a href="/guides/web-ui/inspecting-the-cluster.html">Inspecting the Cluster</a>
+          </li>
+          <li<%= sidebar_current("guides-web-ui-securing") %>>
+            <a href="/guides/web-ui/securing.html">Securing the Web UI with ACLs</a>
+          </li>
+        </ul>
+      </li>
+
     </ul>
   <% end %>