github.com/smintz/nomad@v0.8.3/website/source/guides/ui.html.md (about) 1 --- 2 layout: "guides" 3 page_title: "Web UI" 4 sidebar_current: "guides-ui" 5 description: |- 6 The Nomad Web UI is a great companion for both operators and developers. 7 It is an easy to use way to inspect jobs, allocations, and nodes. 8 --- 9 10 # Web UI 11 12 The Nomad Web UI offers an easy to use web experience for inspecting a Nomad cluster. 13 Jobs, Deployments, Evaluations, Task Groups, Allocations, Logs, Clients, and Servers can all be 14 monitored from the Web UI. The Web UI also supports the use of ACL tokens for 15 clusters that are using the [ACL system](/guides/acl.html). 16 17 ## Accessing the Web UI 18 19 The Web UI is served on the same address and port as the HTTP API. It is namespaced 20 under `/ui`, but visiting the root of the Nomad server in your browser will redirect you 21 to the Web UI. If you are unsure what port the Nomad HTTP API is running under, try the default 22 port, `4646`. 23 24 ~> **Live Demo!** For a quick test drive, see our online Web UI demo at [demo.nomadproject.io](https://demo.nomadproject.io). 25 26 ## Reviewing Jobs 27 28 The home page of the Web UI is the jobs list view. This page has a searchable, sortable, 29 paginated table of all jobs in the cluster, regardless of job status. This page will automatically 30 update as jobs are started, stopped, and allocations transition through states. 31 32 [![Jobs List][img-jobs-list]][img-jobs-list] 33 34 To sort the table, click a table column's header cell. To search, type a query into the searchbox. 35 By default the search will fuzzy-match any job name, but by starting a query with a `/`, the search 36 will instead be based on a regular expression. 37 38 Sort property, sort direction, search term, and page number are all stored as query params to make 39 sharing links easier. 40 41 In addition to name, each job in the table includes details such as current status, type, priority, 42 number of task groups, and an aggregation of all allocations by allocation status. 43 44 [![Job Row Detail][img-jobs-row-detail]][img-jobs-row-detail] 45 46 ## Inspecting a Job 47 48 Clicking on a job will navigate to the Job Detail page. This page shows a list of task groups 49 for the job as well as the status of each allocation for each task group by allocation status. 50 51 This page will automatically update as deployments start and finish, new versions fail to be placed, 52 allocations transition through states, and evaluations update. 53 54 [![Job Detail][img-job-detail]][img-job-detail] 55 56 ### Reading a Job Definition 57 58 The Job Detail page has multiple tabs, one of which is Definition. On the Definition page, the full 59 job definition is shown as an interactive JSON object. 60 61 [![Job Definition][img-job-definition]][img-job-definition] 62 63 ### Reviewing Past Job Versions 64 65 Job Versions can be found on the Versions tab on the Job Detail page. This page has a timeline view of 66 every tracked version for the job. 67 68 This page will automatically update as new versions are submitted to the cluster. 69 70 [![Job Versions][img-job-versions]][img-job-versions] 71 72 Each version can be toggled to also show the diff between job versions. 73 74 [![Job Version Diff][img-job-version-diff]][img-job-version-diff] 75 76 ### Reviewing Past Job Deployments 77 78 Job Deployments are listed on the Deployments tab on the Job Detail page. Every tracked deployment is listed in 79 a timeline view. 80 81 This page will automatically update as new versions are submitted to the cluster and deployments proceed. 82 83 [![Job Deployments][img-job-deployments]][img-job-deployments] 84 85 Each deployment can be toggle to show information about the deployment, including canaries placed and desired, 86 allocations placed and desired, healthy and unhealthy allocations, task group metrics, and existing allocations. 87 88 [![Job Deployment Detail][img-job-deployment-detail]][img-job-deployment-detail] 89 90 ### Monitoring a Current Job Deployment 91 92 When a deployment is currently running, it is called out on the Job Detail Overview tab. It will update 93 automatically as canaries and allocations are placed and deemed healthy or unhealthy. 94 95 [![Active Job Deployment][img-active-job-deployment]][img-active-job-deployment] 96 97 ### Inspecting Child Jobs 98 99 Child jobs are only listed on the parent periodic or parameterized job detail pages. This leaves the global 100 jobs list view uncluttered. 101 102 [![Periodic Job Detail Showing Children Jobs][img-periodic-job-detail]][img-periodic-job-detail] 103 104 ### Forcing a Periodic Launch 105 106 From the job detail page for a periodic job, a child instance can be launched on demand rather than waiting 107 the scheduled amount of time as defined by the cron in the job definition. 108 109 [![Periodic Force Launch Button][img-periodic-force-launch-button]][img-periodic-force-launch-button] 110 111 ### Inspecting a Dispatch Payload 112 113 When a parameterized job is dispatched, the payload is captured and accessible from the bottom of the 114 parameterized child job detail page. The Web UI will attempt to parse the payload as JSON for improved 115 inspecting capabilities. 116 117 [![Parameterized Dispatch Payload][img-parameterized-dispatch-payload]][img-parameterized-dispatch-payload] 118 119 ## Inspecting a Task Group 120 121 Clicking on a task group from the Job Detail page will navigate to the Task Group Detail page. This page shows 122 the aggregated resource metrics for a task group as well as a list of all associated allocations. 123 124 This page will automatically update as the allocations in the task group change states. 125 126 [![Task Group Detail][img-task-group-detail]][img-task-group-detail] 127 128 ## Inspecting an Allocation 129 130 From the Task Group Detail page, each allocation in the allocations table will report basic information about 131 the allocation, including utilized CPU and memory. 132 133 Each allocation will poll for updates to current stats. 134 135 [![Allocation Stats][img-allocation-stats]][img-allocation-stats] 136 137 Clicking an allocation will navigate to the Allocation Detail page. From here, the event history for each task 138 in the allocation can be seen. 139 140 This page will automatically update as new task events are emitted. 141 142 [![Allocation Detail][img-allocation-detail]][img-allocation-detail] 143 144 ## Reviewing Logs 145 146 Clicking on a task from the allocation detail will navigate to the Task Detail page. The Task Detail page includes 147 a list of recent events as well as a tab for logs. 148 149 On the Logs tab, anything the task writes to `stdout` or `stderr` is accessible. The log stream component allows 150 for pausing and playing log streaming, jumping to the head or tail of the log, and toggling between `stdout` and 151 `stderr`. 152 153 ~> **Note.** The Web UI will first attempt to stream logs directly from the client agent to avoid unnecessary load 154 ~> on server agents. If the client is not accessible, the Web UI will fallback to using the server for convenience. 155 156 [![Task Logs][img-task-logs]][img-task-logs] 157 158 ~> **Note.** Only `stdout` and `stderr` are available in the UI. Any logs written to a file are available from the 159 ~> CLI using the [`nomad alloc fs`](/docs/commands/alloc/fs.html), but filesystem access is not yet in the Web UI. 160 161 ## Reviewing Clients 162 163 Clicking the Clients link in the left-hand menu of the Web UI will navigate to the Clients List page. This page 164 has a searchable, sortable, paginated table of all clients in the cluster. 165 166 Sort property, sort direction, search term, and page number are all stored as query params to make 167 sharing links easier. 168 169 In addition to name, each client in the table includes details such as current status, address, datacenter, 170 and number of allocations. 171 172 This page will automatically update as nodes change states and work is allocated. 173 174 [![Clients List][img-clients-list]][img-clients-list] 175 176 ## Inspecting a Client 177 178 Clicking on a client will navigate to the Client Detail page. This page shows the status of the client as 179 well as the list of all allocations placed on the client. Additionally, all attributes of the machine are 180 itemized. 181 182 This page will automatically update as allocations come and go on the client and the usage stats for an 183 allocation change. 184 185 [![Client Detail][img-client-detail]][img-client-detail] 186 187 ## Inspecting Servers 188 189 Clicking on the Servers link in the left-hand menu of the Web UI will navigate to the Servers List page. This 190 page lists all servers, including which one is the current leader. 191 192 Clicking on a server in the list will open up a table that lists the Tags for the server. 193 194 [![Server Detail][img-server-detail]][img-server-detail] 195 196 ## Using an ACL Token 197 198 When the ACL system is enabled for the cluster, tokens can be used to gain elevated permissions to see 199 otherwise private jobs, nodes, and other details. To register a token with the Web UI, click ACL Tokens on the 200 right-hand side of the top navigation. 201 202 The ACL Tokens page has a two field form for providing a token Secret ID and token Accessor ID. The form 203 automatically updates as the values change, and once a Secret ID is provided, all future HTTP requests the 204 Web UI makes will provide the Secret ID as the ACL Token via the `X-Nomad-Token` request header. 205 206 [![ACL Tokens][img-acl-tokens]][img-acl-tokens] 207 208 [img-jobs-list]: /assets/images/guide-ui-jobs-list.png 209 [img-jobs-row-detail]: /assets/images/guide-ui-jobs-row-detail.png 210 [img-job-detail]: /assets/images/guide-ui-job-detail.png 211 [img-job-definition]: /assets/images/guide-ui-job-definition.png 212 [img-job-versions]: /assets/images/guide-ui-job-versions.png 213 [img-job-version-diff]: /assets/images/guide-ui-job-version-diff.png 214 [img-job-deployments]: /assets/images/guide-ui-job-deployments.png 215 [img-job-deployment-detail]: /assets/images/guide-ui-job-deployment-detail.png 216 [img-active-job-deployment]: /assets/images/guide-ui-active-job-deployment.png 217 [img-task-group-detail]: /assets/images/guide-ui-task-group-detail.png 218 [img-allocation-stats]: /assets/images/guide-ui-allocation-stats.png 219 [img-allocation-detail]: /assets/images/guide-ui-allocation-detail.png 220 [img-clients-list]: /assets/images/guide-ui-clients-list.png 221 [img-client-detail]: /assets/images/guide-ui-client-detail.png 222 [img-server-detail]: /assets/images/guide-ui-server-detail.png 223 [img-acl-tokens]: /assets/images/guide-ui-acl-tokens.png 224 [img-task-logs]: /assets/images/guide-ui-task-logs.png 225 [img-parameterized-dispatch-payload]: /assets/images/guide-ui-parameterized-dispatch-payload.png 226 [img-periodic-force-launch-button]: /assets/images/guide-ui-periodic-force-launch-button.png 227 [img-periodic-job-detail]: /assets/images/guide-ui-periodic-job-detail.png