Merge pull request #3232 from hashicorp/d-ui-api-doc

Document each route in the UI for the API docs
2026-01-01 16:05:42 +03:00 · 2017-09-18 19:52:04 -05:00
parent 2eaa26d492 e50f944cc7
commit 7b01e43b7c
2 changed files with 150 additions and 0 deletions
--- a/website/source/api/ui.html.md
+++ b/website/source/api/ui.html.md
@@ -0,0 +1,146 @@
+---
+layout: api
+page_title: UI
+sidebar_current: ui
+description: |-
+  The /ui namespace is used to access the Nomad web user interface.
+---
+
+# Nomad Web UI
+
+Starting in v0.7, the Nomad UI is accessible at `/ui`. It is not namespaced by version. A request to `/`
+will also redirect to `/ui`.
+
+
+## List Jobs
+
+This page lists all known jobs in a paginated, searchable, and sortable table.
+
+| Path       | Produces    |
+| ---------- | ----------- |
+| `/ui/jobs` | `text/html` |
+
+
+## Job Detail
+
+This page shows an overview of a specific job. Details include name, status, type,
+priority, allocation statuses, and task groups. Additionally, if there is a running
+deployment for the job, it will be shown on the overview.
+
+| Path               | Produces    |
+| ------------------ | ----------- |
+| `/ui/jobs/:job_id` | `text/html` |
+
+
+### Job Definition
+
+This page shows the definition of a job as pretty-printed, syntax-highlighted, JSON.
+
+| Path                          | Produces    |
+| ----------------------------- | ----------- |
+| `/ui/jobs/:job_id/definition` | `text/html` |
+
+
+### Job Versions
+
+This page lists all available versions for a job in a timeline view. Each version in
+the timeline can be expanded to show a pretty-printed, syntax-highlighted diff between
+job versions.
+
+| Path                          | Produces    |
+| ----------------------------- | ----------- |
+| `/ui/jobs/:job_id/versions`   | `text/html` |
+
+
+### Job Deployments
+
+This page lists all available deployments for a job when the job has deployments. The
+deployments are listed in a timeline view. Each deployment shows pertinent information
+such as deployment ID, status, associated version, and submit time. Each deployment can
+also be expanded to show detail information regarding canary placements, allocation
+placements, healthy and unhealthy allocations, as well the current description for the
+status. A table of task groups is also present in the detail view, which shows allocation
+metrics by task group. Lastly, each expanded deployment lists all associated allocations
+in a table to drill into for task events.
+
+| Path                             | Produces    |
+| -------------------------------- | ----------- |
+| `/ui/jobs/:job_id/deployments`   | `text/html` |
+
+
+## Task Group Detail
+
+This page shows an overview of a specific task group. Details include the number of tasks, the aggregated amount of reserved CPU, memory, and disk, all associated allocations broken
+down by status, and a list of allocations. The list of allocations include details such as
+status, the node the allocation was placed on, and the current CPU and Memory usage of the
+allocations.
+
+| Path                                | Produces    |
+| ----------------------------------- | ----------- |
+| `/ui/jobs/:job_id/:task_group_name` | `text/html` |
+
+
+## Allocation Detail
+
+This page shows details and events for an allocation. Details include the job the allocation
+belongs to, the node the allocation is placed on, a list of all tasks, and lists of task
+events per task. Each task in the task list includes the task name, state, last event, time,
+and addresses. Each task event in a task history list includes the time, type, and
+description of the event.
+
+| Path                        | Produces    |
+| --------------------------- | ----------- |
+| `/ui/allocations/:alloc_id` | `text/html` |
+
+
+## Nodes List
+
+This page lists all nodes in the Nomad cluster in a sortable, searchable, paginated
+table.
+
+| Path        | Produces    |
+| ----------- | ----------- |
+| `/ui/nodes` | `text/html` |
+
+
+## Node Detail
+
+This page shows the details of a node, including the node name, status, full ID,
+address, port, datacenter, allocations, and attributes.
+
+| Path                 | Produces    |
+| -------------------- | ----------- |
+| `/ui/nodes/:node_id` | `text/html` |
+
+
+## Servers List
+
+This page lists all servers in the Nomad cluster in a sortable table. Details for each
+server include the server status, address, port, datacenter, and whether or not it is
+the leader.
+
+| Path          | Produces    |
+| ------------- | ----------- |
+| `/ui/servers` | `text/html` |
+
+
+## Server Detail
+
+This page lists all tags assocaited with a server.
+
+| Path                     | Produces    |
+| ------------------------ | ----------- |
+| `/ui/servers/:server_id` | `text/html` |
+
+
+## ACL Tokens
+
+This page lets you enter an ACL token (both accessor ID and secret ID) to use with the UI.
+If the cluster does not have ACLs enabled, this page is unnecessary. If the cluster has an
+anonymous policy that grants cluster-wide read access, this page is unnecessary. If the
+anonymous policy only grants partial read access, then providing an ACL Token will
+authenticate all future requests to allow read access to additional resources.
+
+| Path                  | Produces    |
+| --------------------- | ----------- |
+| `/ui/settings/tokens` | `text/html` |
--- a/website/source/layouts/api.erb
+++ b/website/source/layouts/api.erb
@@ -75,6 +75,10 @@
        <a href="/api/system.html">System</a>
      </li>

+      <li<%= sidebar_current("ui") %>>
+        <a href="/api/ui.html">UI</a>
+      </li>
+
      <li<%= sidebar_current("api-validate") %>>
        <a href="/api/validate.html">Validate</a>
      </li>