diff --git a/website/source/assets/images/guide-ui-acl-tokens.png b/website/source/assets/images/guide-ui-acl-tokens.png new file mode 100644 index 000000000..22fc82e0d Binary files /dev/null and b/website/source/assets/images/guide-ui-acl-tokens.png differ diff --git a/website/source/assets/images/guide-ui-active-job-deployment.png b/website/source/assets/images/guide-ui-active-job-deployment.png new file mode 100644 index 000000000..015da9931 Binary files /dev/null and b/website/source/assets/images/guide-ui-active-job-deployment.png differ diff --git a/website/source/assets/images/guide-ui-allocation-detail.png b/website/source/assets/images/guide-ui-allocation-detail.png new file mode 100644 index 000000000..038b5b9bb Binary files /dev/null and b/website/source/assets/images/guide-ui-allocation-detail.png differ diff --git a/website/source/assets/images/guide-ui-allocation-stats.png b/website/source/assets/images/guide-ui-allocation-stats.png new file mode 100644 index 000000000..242219367 Binary files /dev/null and b/website/source/assets/images/guide-ui-allocation-stats.png differ diff --git a/website/source/assets/images/guide-ui-client-detail.png b/website/source/assets/images/guide-ui-client-detail.png new file mode 100644 index 000000000..5b37c9f20 Binary files /dev/null and b/website/source/assets/images/guide-ui-client-detail.png differ diff --git a/website/source/assets/images/guide-ui-clients-list.png b/website/source/assets/images/guide-ui-clients-list.png new file mode 100644 index 000000000..51d379095 Binary files /dev/null and b/website/source/assets/images/guide-ui-clients-list.png differ diff --git a/website/source/assets/images/guide-ui-job-definition.png b/website/source/assets/images/guide-ui-job-definition.png new file mode 100644 index 000000000..7a88e487c Binary files /dev/null and b/website/source/assets/images/guide-ui-job-definition.png differ diff --git a/website/source/assets/images/guide-ui-job-deployment-detail.png b/website/source/assets/images/guide-ui-job-deployment-detail.png new file mode 100644 index 000000000..6ebfd3b88 Binary files /dev/null and b/website/source/assets/images/guide-ui-job-deployment-detail.png differ diff --git a/website/source/assets/images/guide-ui-job-deployments.png b/website/source/assets/images/guide-ui-job-deployments.png new file mode 100644 index 000000000..1bfebe17d Binary files /dev/null and b/website/source/assets/images/guide-ui-job-deployments.png differ diff --git a/website/source/assets/images/guide-ui-job-detail.png b/website/source/assets/images/guide-ui-job-detail.png new file mode 100644 index 000000000..bcae7e6be Binary files /dev/null and b/website/source/assets/images/guide-ui-job-detail.png differ diff --git a/website/source/assets/images/guide-ui-job-version-diff.png b/website/source/assets/images/guide-ui-job-version-diff.png new file mode 100644 index 000000000..f0cdeda09 Binary files /dev/null and b/website/source/assets/images/guide-ui-job-version-diff.png differ diff --git a/website/source/assets/images/guide-ui-job-versions.png b/website/source/assets/images/guide-ui-job-versions.png new file mode 100644 index 000000000..00bfabde8 Binary files /dev/null and b/website/source/assets/images/guide-ui-job-versions.png differ diff --git a/website/source/assets/images/guide-ui-jobs-list.png b/website/source/assets/images/guide-ui-jobs-list.png new file mode 100644 index 000000000..4025a905a Binary files /dev/null and b/website/source/assets/images/guide-ui-jobs-list.png differ diff --git a/website/source/assets/images/guide-ui-jobs-row-detail.png b/website/source/assets/images/guide-ui-jobs-row-detail.png new file mode 100644 index 000000000..bbefa06ad Binary files /dev/null and b/website/source/assets/images/guide-ui-jobs-row-detail.png differ diff --git a/website/source/assets/images/guide-ui-server-detail.png b/website/source/assets/images/guide-ui-server-detail.png new file mode 100644 index 000000000..cf94ec4c9 Binary files /dev/null and b/website/source/assets/images/guide-ui-server-detail.png differ diff --git a/website/source/assets/images/guide-ui-task-group-detail.png b/website/source/assets/images/guide-ui-task-group-detail.png new file mode 100644 index 000000000..30c8edfe1 Binary files /dev/null and b/website/source/assets/images/guide-ui-task-group-detail.png differ diff --git a/website/source/guides/ui.html.md b/website/source/guides/ui.html.md new file mode 100644 index 000000000..acc97f873 --- /dev/null +++ b/website/source/guides/ui.html.md @@ -0,0 +1,168 @@ +--- +layout: "guides" +page_title: "Nomad UI" +sidebar_current: "guides-ui" +description: |- + The Nomad UI is a great companion for both operators and developers. + It is an easy to use way to inspect jobs, allocations, and nodes. +--- + +# Nomad UI + +The Nomad UI offers an easy to use web experience for inspecting a Nomad cluster. +Jobs, Deployments, Task Groups, Allocations, Clients, and Servers can all be +monitored from the Nomad UI. The UI also supports the use of ACL tokens for +clusters that are using the Nomad Access Control List system. + +~> **Beta Feature!** This page covers the Nomad UI, a feature of v0.7 which is still in beta. + +## Accessing the UI + +The Nomad UI is served on the same address and port as the HTTP API. It is namespaced +under `/ui`, but visiting the root of the Nomad server in your browser will redirect you +to the UI. If you are unsure what port the Nomad HTTP API is running under, try the default +port, `4646`. + +## Reviewing Jobs + +The home page of the UI is the jobs list view. This page has a searchable, sortable, +paginated table of all jobs in the cluster, regardless of job status. + +[![Jobs List][img-jobs-list]][img-jobs-list] + +To sort the table, click a table column's header cell. To search, type a query into the searchbox. +By default the search will fuzzy-match any job name, but by starting a query with a `/`, the search +will instead be based on a regular expression. + +Sort property, sort direction, search term, and page number are all stored as query params to make +sharing links easier. + +In addition to name, each job in the table includes details such as current status, type, priority, +number of task groups, and an aggregation of all allocations by allocation status. + +[![Job Row Detail][img-jobs-row-detail]][img-jobs-row-detail] + +## Inspecting a Job + +Clicking on a job will navigate to the Job Detail page. This page shows a list of task groups +for the job as well as the status of each allocation for each task group by allocation status. + +[![Job Detail][img-job-detail]][img-job-detail] + +### Reading a Job Definition + +The Job Detail page has multiple tabs, one of which is Definition. On the Definition page, the full +job definition is shown as an interactive JSON object. + +[![Job Definition][img-job-definition]][img-job-definition] + +### Reviewing Past Job Versions + +Job Versions can be found on the Versions tab on the Job Detail page. This page has a timeline view of +every tracked version for the job. + +[![Job Versions][img-job-versions]][img-job-versions] + +Each version can be toggled to also show the diff between job versions. + +[![Job Version Diff][img-job-version-diff]][img-job-version-diff] + +### Reviewing Past Job Deployments + +Job Deployments are listed on the Deployments tab on the Job Detail page. Every tracked deployment is listed in +a timeline view. + +[![Job Deployments][img-job-deployments]][img-job-deployments] + +Each deployment can be toggle to show information about the deployment, including canaries placed and desired, +allocations placed and desired, healthy and unhealthy allocations, task group metrics, and existing allocations. + +[![Job Deployment Detail][img-job-deployment-detail]][img-job-deployment-detail] + +### Monitoring a Current Job Deployment + +When a deployment is currently running, it is called out on the Job Detail Overview tab. + +[![Active Job Deployment][img-active-job-deployment]][img-active-job-deployment] + +## Inspecting a Task Group + +Clicking on a task group from the Job Detail page will navigate to the Task Group Detail page. This page shows +the aggregated resource metrics for a task group as well as a list of all associated allocations. + +[![Task Group Detail][img-task-group-detail]][img-task-group-detail] + +## Inspecting an Allocation + +From the Task Group Detail page, each allocation in the allocations table will report basic information about +the allocation, including utilized CPU and memory. + +[![Allocation Stats][img-allocation-stats]][img-allocation-stats] + +~> **Note.** To collect current CPU and memory statistics, the Nomad UI makes requests directly to the client +~> the allocation is running on. These requests will fail unless the browser session is running in the same +~> subnet as the Nomad client. + +Clicking an allocation will navigate to the Allocation Detail page. From here, the event history for each task +in the allocation can be seen. + +[![Allocation Detail][img-allocation-detail]][img-allocation-detail] + +## Reviewing Clients + +Clicking the Clients link in the left-hand menu of the Nomad UI will navigate to the Clients List page. This page +has a searchable, sortable, paginated table of all clients in the cluster. + +Sort property, sort direction, search term, and page number are all stored as query params to make +sharing links easier. + +In addition to name, each client in the table includes details such as current status, address, datacenter, +and number of allocations. + +[![Clients List][img-clients-list]][img-clients-list] + +## Inspecting a Client + +Clicking on a client will navigate to the Client Detail page. This page shows the status of the client as +well as the list of all allocations placed on the client. Additionally, all attributes of the machine are +itemized. + +[![Client Detail][img-client-detail]][img-client-detail] + +## Inspecting Servers + +Clicking on the Servers link in the left-hand menu of the Nomad UI will navigate to the Servers List page. This +page lists all servers, including which one is the current leader. + +Clicking on a server in the list will open up a table that lists the Tags for the server. + +[![Server Detail][img-server-detail]][img-server-detail] + +## Using an ACL Token + +When the Nomad ACL system is enabled for the cluster, tokens can be used to gain elevated permissions to see +otherwise private jobs, nodes, and other details. To register a token with the UI, click ACL Tokens on the +right-hand side of the top navigation. + +The ACL Tokens page has a two field form for providing a token Secret ID and token Accessor ID. The form +automatically updates as the values change, and once a Secret ID is provided, all future HTTP requests the +Nomad UI makes will provide the Secret ID as the ACL Token via the `X-Nomad-Token` request header. + +[![ACL Tokens][img-acl-tokens]][img-acl-tokens] + +[img-jobs-list]: /assets/images/guide-ui-jobs-list.png +[img-jobs-row-detail]: /assets/images/guide-ui-jobs-row-detail.png +[img-job-detail]: /assets/images/guide-ui-job-detail.png +[img-job-definition]: /assets/images/guide-ui-job-definition.png +[img-job-versions]: /assets/images/guide-ui-job-versions.png +[img-job-version-diff]: /assets/images/guide-ui-job-version-diff.png +[img-job-deployments]: /assets/images/guide-ui-job-deployments.png +[img-job-deployment-detail]: /assets/images/guide-ui-job-deployment-detail.png +[img-active-job-deployment]: /assets/images/guide-ui-active-job-deployment.png +[img-task-group-detail]: /assets/images/guide-ui-task-group-detail.png +[img-allocation-stats]: /assets/images/guide-ui-allocation-stats.png +[img-allocation-detail]: /assets/images/guide-ui-allocation-detail.png +[img-clients-list]: /assets/images/guide-ui-clients-list.png +[img-client-detail]: /assets/images/guide-ui-client-detail.png +[img-server-detail]: /assets/images/guide-ui-server-detail.png +[img-acl-tokens]: /assets/images/guide-ui-acl-tokens.png diff --git a/website/source/layouts/guides.erb b/website/source/layouts/guides.erb index 5ec7907b3..c9fc3e5a9 100644 --- a/website/source/layouts/guides.erb +++ b/website/source/layouts/guides.erb @@ -62,6 +62,9 @@ Outage Recovery + > + Nomad UI + <% end %>