This document describes how the web user interface implements the normative requirements in SPECIFICATION.md. It focuses on routes, screen structure, per-step form controls, batch-mode presentation, and Monitoring/Logs view affordances. It does not replace SPECIFICATION.md: all FR-* SHALL statements that define product behavior—including FR-INTERACTIVE-*, FR-UI-*, and FR-I18N-*—live in SPECIFICATION.md (§6 and §18).
Use this document to:
- map screens to requirement IDs;
- implement consistent navigation, step transitions, and control inventories;
- align REST API usage with the public UI (FR-API-004).
Traceability: Subsections below cite the FR-* identifiers they realize. Where SPECIFICATION.md and this document differ in wording, SPECIFICATION.md prevails.
This section elaborates the primary session screens referenced by SPECIFICATION.md §6.4, together with FR-INTERACTIVE-014–FR-INTERACTIVE-017, FR-ACCESS-003, and FR-UI-005.
Implementation notes: Path names in SPECIFICATION.md are illustrative; equivalent routing is permitted (FR-INTERACTIVE-011). Keep navigation affordances for Home, Configuration, Monitoring, Logs, and Logout consistent with FR-INTERACTIVE-017 and role rules in SPECIFICATION.md §3.2.
Authentication, REST API usage, and authorization rules follow SPECIFICATION.md §3.2, §10.2, and §17.
| Screen | Route (illustrative) | Purpose | Operator controls | Observer controls |
|---|---|---|---|---|
| Home | / |
Authentication and session-entry screen with role switch and credentials; after authentication, it shows the current session identity and entry points to workflow screens. | Authenticate as Operator; navigate to Configuration, Monitoring, and Logs; use actions permitted by role and mode. | Authenticate as Observer; navigate to Configuration, Monitoring, and Logs; read-only access only. |
| Configuration | /configuration |
Multi-step session workflow, including configuration, review, and run-state step 10. | In interactive mode: edit configuration steps and execute allowed actions. In batch mode, or after installation has started: configuration is pre-filled and read-only. | Same steps visible in read-only form; no configuration edits, no confirmation submissions, and no execution-control actions. |
| Monitoring | /monitoring |
Live or polled progress, phase and task detail, run state, and failure context. | Read run state; request cancel or resume through documented UI controls when the session state allows and the user is authorized. | Read run state only; no cancel, resume, or other execution-control actions. |
| Logs | /logs |
Session log view with filtering and historical browsing for installation logs. | Read logs; use filters; export or download logs where available. | Read logs with the same filtering and navigation in read-only form; no operator-only execution controls. |
| Logout | /logout |
Terminate access to the application. | End the authenticated session and return to the Home screen. | Same as for Operator. |
This mapping elaborates the relationship between the workflow phases in SPECIFICATION.md §4 and the UI views described in this companion.
| Workflow phase | Primary UI step or view | Notes |
|---|---|---|
| 1. target definition | Step 1 targets |
Initial session target and access definition. |
| 2. discovery | Step 2 discovery |
Discovery execution and review of the resulting snapshot on one screen. |
| 3. configuration input or import | Steps 3–8 in interactive mode; read-only projection of steps 1–10 in batch mode | Interactive mode captures configuration input; batch mode presents imported configuration. |
| 4. preflight validation | Transition from step 8 into step 9 | Validation may be automatic or explicit per FR-INTERACTIVE-028A. |
| 5. review and approval | Step 9 review |
Destructive-scope approval and execution start gate. |
| 6-13. execution through reporting | Step 10 run_state, /monitoring, and /logs |
Execution-time interaction, confirmation prompts, run control, monitoring, logs, and final reporting. |
The step identifiers and English labels referenced by SPECIFICATION.md §6.5 are:
| Step | Id | Label (English) |
|---|---|---|
| 1 | targets |
Target definition |
| 2 | discovery |
Discovery |
| 3 | layout |
Cluster layout |
| 4 | storage |
Disk selection |
| 5 | network |
Network & endpoints |
| 6 | security |
Security & TLS |
| 7 | artifacts |
Artifacts & version |
| 8 | database |
Database settings |
| 9 | review |
Review & approval |
| 10 | run_state |
Run state & confirmations |
Each subsection describes one configuration-step form: its role in the workflow, the primary input controls (type and purpose), and dependencies on other steps or data. Control labels are illustrative. Localization and secret-handling requirements are defined by FR-I18N-001, FR-SECURITY-008, and FR-USABILITY-005.
Description. Collect the set of target hosts and parameters needed to reach them over SSH for discovery and later execution (§5.1, FR-DISCOVERY-001, FR-DISCOVERY-002, FR-DISCOVERY-002C).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Target rows (repeatable) | List | One row per target host. |
| Address | Text | Hostname, IP, or composite host:port (FR-DISCOVERY-001). Required per row in the sense that a reachable address must be defined before advancing; placeholder and parsing behavior SHALL be consistent for the default block and per-row edit (no divergent “host-only” versus “host:port” copy for the same field). |
| SSH port | Number | TCP port for SSH when per-target settings apply; the default profile defines the port for rows that follow the default (FR-DISCOVERY-002C). |
| SSH auth mode | Selection | Per row: use default profile, password, secret key, or SSH agent. Required per row. |
| SSH user | Text | Login user for SSH. MAY be left empty; in read-only summaries the UI SHALL show a localized operator-facing phrase (English resource example: Unconfigured (using SSH default)) rather than a blank or placeholder dash, loaded from UI language resources (FR-I18N-001). |
| SSH password | Password text | Password for SSH. Required for the edited row when password mode is selected. |
| SSH key | Upload control | Private key for SSH. Required for the edited row when secret key mode is selected. |
| Add / Remove / Edit | Buttons | Add appends a row; Remove deletes a row and updates persisted targets when committed per product rules; Edit opens per-row settings (address, port when applicable, user, auth mode, secrets). |
| Default SSH authentication | Block | Same SSH fields as a custom row except there is no “use default” auth option. Shown read-only with an Edit action for Operator; Done commits changes to the draft/session per implementation. |
| Persist targets | Commits | Target list persistence to the session SHALL occur on explicit commits (for example Done on the default SSH block, Done on the per-row edit dialog, and row removal that updates server state), satisfying FR-INTERACTIVE-024 and FR-INTERACTIVE-024A. There is no separate Save targets control in the current UI shape. |
Presentation notes.
- The form contains two blocks: default SSH access settings and a targets table. Both use read-only summary presentation with Edit (and table Add / Remove / Edit) for Operator in interactive mode.
- Per-target SSH access MAY follow the default profile or use custom settings entered in the row editor.
- Operator-assigned host id is not collected on this screen; stable host identifiers for discovery and later steps are assigned by the Installer/backend as needed. The
set targetsAPI payload from the UI need not include a host id field. - Multi-line read-only summaries for default and per-row SSH settings SHOULD align field order and labels (authentication mode, port, user, password/key status when relevant).
Description. Trigger remote discovery against saved targets, show run status, and present the Discovery Snapshot (§5.2) for operator review on the same configuration step before cluster design (phase 2 in §4.1; FR-INTERACTIVE-025A).
Presentation notes.
- A short explanatory phrase describing discovery (for example that it connects over SSH and collects inventory) SHOULD appear below the step strip (breadcrumb), not overlapping the step heading or primary card title.
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Run discovery | Button | Starts or re-runs discovery to update the Discovery Snapshot (FR-DISCOVERY-006); disabled until targets are saved. |
| Progress / error display | Text, progress indicator | Shows running state and per-session errors without leaking secrets. |
| Host inventory table or cards | Read-only grid | Host column: operator-entered target address from target definition and the resolved hostname or FQDN identified during discovery; when the two differ, show both on separate lines; when they are the same, a single line is sufficient. Other columns: OS, hardware summary, disk inventory, Discovery status (FR-DISCOVERY-003, FR-DISCOVERY-007). The status column SHALL show an explicit success indicator (for example OK) when discovery completed without a per-host error; otherwise it SHALL show the error text. |
| Acknowledge discovery results | Checkbox or equivalent explicit action | Records the acknowledgment required by FR-INTERACTIVE-026A before the operator leaves this step. |
| Continue to cluster layout | Wizard Next (or equivalent primary navigation) | Moves to layout only after the acknowledgment requirement is satisfied; the UI can warn if critical hosts failed discovery. |
Description. Define base storage topology, optional bridge mode and piles, node roles, and placement (§8, FR-LAYOUT-001–FR-LAYOUT-017, FR-INTERACTIVE-007).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Preset selector | Select or radio group | Single-DC block-4-2, multi-DC mirror-3-dc, reduced mirror-3-dc, bridge preset (FR-INTERACTIVE-007). |
| Base storage topology | Select | Must match §8.1; distinct from bridge mode (FR-LAYOUT-003). |
| Bridge mode | Toggle | When on, enables pile and synchronous-replication controls (FR-LAYOUT-002, FR-LAYOUT-014–FR-LAYOUT-017). |
| Pile definitions | Repeatable group | Name/id and failure-domain labels for each pile (FR-LAYOUT-004, FR-LAYOUT-005). |
| Per-host or per-node role assignment | Matrix, multi-select, or drag targets | Storage Node, Compute Node, Broker Node where applicable (FR-LAYOUT-008–FR-LAYOUT-010). |
| Compute nodes per host | Number (where allowed) | FR-LAYOUT-009. |
| Location attributes | Text or select per host | Rack, data center, availability zone, pile membership (FR-LAYOUT-007). |
Description. Map discovered disks to YDB storage, partitioning, labels, and media grouping (§9, FR-STORAGE-001–FR-STORAGE-008).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Disk pick lists per host | Multi-select from discovery | Restricted to Discovery Snapshot unless Expert Override is on (FR-DISCOVERY-010, FR-STORAGE-001). |
| Expert Override | Toggle + text fields | Manual device identifiers with risk warnings (FR-DISCOVERY-010). |
| Partitioning scheme | Select or guided form | For unpartitioned disks (FR-STORAGE-002, FR-STORAGE-003, FR-STORAGE-004). |
| Disk type / kind / label pattern | Fields per group | FR-STORAGE-005–FR-STORAGE-008. |
| Safety summaries | Read-only callouts | Warnings for mounted, system, or in-use disks (FR-STORAGE-009–FR-STORAGE-011). |
Description. Client-facing and intra-cluster network settings, including separated front-end and back-end models (§8.3, FR-LAYOUT-011–FR-LAYOUT-013).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Network model | Radio | Standard single-network vs separated front/back (FR-LAYOUT-011, FR-LAYOUT-012). |
| Front-end FQDN / endpoints | Text | Client access (FR-LAYOUT-013). |
| Back-end FQDN / internal addresses | Text | Intra-cluster communication (FR-LAYOUT-013). |
| Additional listeners / ports | Text or number | As required by selected layout and validation. |
Description. TLS materials, Installer-facing HTTPS options where relevant, and YDB authentication settings (§10).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| TLS mode | Select | Operator-provided certs, installer-managed generation, or equivalent (FR-SECURITY-002, FR-SECURITY-003). |
| Certificate and key material | File upload or path on control host | FR-SECURITY-002; masked display. |
| Certificate generation parameters | Form fields | Validity, SANs, CA settings as supported (FR-SECURITY-003). |
| YDB authentication | Toggles and credential capture | FR-SECURITY-006, FR-SECURITY-007; secrets masked. Credentials captured here are for YDB cluster bootstrap (not Installer UI/REST authentication). |
Description. YDB version, configuration generation, and artifact source (§11, FR-ARTIFACT-001–FR-ARTIFACT-005).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Artifact source mode | Radio | Download, local archive, local binaries (FR-ARTIFACT-001). |
| Version / component selectors | Text or select | Compatible with configuration V1 or V2 (FR-ARTIFACT-004). |
| Local path fields | Text | Paths on the control host for archives or binaries. |
| Offline / mirror URL | Text | When used instead of public download in restricted environments. |
Description. Initial database creation parameters used before compute nodes start (§13.4, FR-EXECUTION-009).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Database name | Text | Initial database identifier. |
| Domain / root paths | Text | As required by YDB deployment model. |
| Additional DB options | Fields | Charset, pools, or other documented first-run settings exposed by the Installer. |
Description. Consolidated read-only summary of effective configuration, latest preflight-validation outcome captured before review, destructive-scope confirmation, and execution start (§12, §9.2).
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Configuration summary | Read-only sections | Hosts, topology, disks, security, artifacts. |
| Validation results | Read-only panel | Shows latest preflight result summary with blocking, warning, and informational classifications (FR-VALIDATION-003). |
| Run preflight / refresh validation | Button or automatic transition trigger | Invokes the preflight required before entry to review when the UI does not trigger it automatically on leaving step 8. |
| Approve destructive actions | Checkbox or typed confirmation | Identifies affected hosts and disks (FR-STORAGE-012). |
| Start installation / Proceed | Primary button | Available only when blocking errors are cleared and required destructive confirmations are completed. |
Description. Execution-time configuration-step screen that shows current session state, highlights pending confirmation requests that gate progress, and provides quick navigation to monitoring and logs views. For Operator, this step allows submission of confirmation responses where required. For Observer, this step is read-only.
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Current run state summary | Read-only panel | Current phase/task, session status, elapsed time, and high-level warnings/errors (FR-MONITORING-002). |
| Pending confirmation requests | List | Shows active confirmation prompts that gate execution, including scope and consequence summary. |
| Confirmation response controls | Buttons or form actions (authorized roles) | Allow Operator to submit required responses; Observer sees state only (FR-ACCESS-002, FR-ACCESS-003, FR-UI-009). |
| Resume or rerun from checkpoint | Button (authorized roles, when eligible) | Allows Operator to invoke documented rerun or resume behavior when FR-RUNCONTROL-008 eligibility conditions are met. |
| Accept degraded completion | Confirmation control (authorized roles, when applicable) | Allows Operator to accept completion with failed or incomplete verification checks only after the UI lists the exceptions that would otherwise block normal completion (FR-EXECUTION-014). |
| Open Monitoring | Link or button | Navigates to /monitoring for detailed progress timeline and host/task status. |
| Open Logs | Link or button | Navigates to /logs for detailed installation logs. |
Section references such as §6.5, §5, §8, §9, §10, §11, §12, or §13 in the subsections above refer to SPECIFICATION.md.
Description. Satisfies FR-MONITORING-001–FR-MONITORING-003, FR-RUNCONTROL-001, and FR-RUNCONTROL-008: current phase and task, per-host state, elapsed time, overall completion estimate when available, log tail, warnings and errors, cancellation, rerun or resume when eligible, completion-report access, and bridge-vs-base distinction where applicable.
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Phase and task display | Read-only text / timeline | FR-MONITORING-002. |
| Host list with status | Table or list | FR-MONITORING-002. |
| Overall completion estimate | Read-only indicator | Shows overall completion estimate when the backend can provide it (FR-MONITORING-002). |
| Log viewer | Scrollable text with severity | FR-MONITORING-002; secrets redacted. |
| Filter by host / phase / severity | Select or toggles | FR-UI-006. |
| Cancel run | Button (authorized roles) | FR-RUNCONTROL-001; cooperative cancel (FR-RUNCONTROL-002–FR-RUNCONTROL-005). |
| Resume or rerun | Button (authorized roles, when eligible) | Exposed only when the backend reports that rerun or resume is implemented and currently allowed for the session (FR-RUNCONTROL-008, FR-RUNCONTROL-009). |
| View or export completion report | Link or button | Opens or exports the completion report and final session report when FR-REPORTING applies post-run. |
Description. Dedicated view for installation logs of the active session, including live tail during execution and historical log browsing after completion or failure.
Input controls.
| Control | Type | Semantics |
|---|---|---|
| Log stream viewer | Scrollable text/table | Shows timestamped log entries with severity; secrets redacted (FR-SECURITY-008, FR-USABILITY-005). |
| Filter by host / phase / severity / time range | Selectors and inputs | Narrows visible log entries for troubleshooting (FR-UI-006). |
| Auto-follow toggle | Toggle | Keeps view pinned to newest entries while enabled. |
| Download or export logs | Link or button | Exports logs for reporting and troubleshooting (FR-REPORTING-002, FR-REPORTING-006). |
| Back to run state or monitor | Link or button | Returns to /configuration step 10 or /monitoring without losing session context. |
These views implement FR-MONITORING-001–FR-MONITORING-003, FR-MONITORING-005, FR-RUNCONTROL-001, FR-RUNCONTROL-008, FR-SECURITY-008, FR-USABILITY-005, and FR-UI-006 as cited in the tables, together with SPECIFICATION.md §6.8.
This section elaborates SPECIFICATION.md §6.7 (normative interaction rules) for implementers.
Description. In batch Installation Mode, the UI uses the same /configuration route and step sequence as SPECIFICATION.md §6.5 and the read-only form content defined in §3 of this document. There is no separate batch configuration screen or route.
Interaction rules.
| Rule | Semantics |
|---|---|
| Batch data source | Session configuration values come from the loaded batch specification and its validated effective form (FR-BATCH-001–FR-BATCH-004). |
| No configuration overrides | Configuration-step controls for targets, topology, storage, network, security, artifacts, and database settings are pre-filled and read-only in batch mode (FR-MODE-003, FR-ACCESS-005). |
| Allowed actions | Users with Operator privileges can provide required confirmation responses and run-control actions where SPECIFICATION.md allows them (FR-ACCESS-002, FR-BATCH-008A, §15). |
| Visibility | The UI indicates that values are batch-sourced, pre-filled, and non-editable for the running session (FR-BATCH-001A). |
- Step strip and deep linking: FR-INTERACTIVE-021, FR-INTERACTIVE-021A, FR-INTERACTIVE-031B, and FR-INTERACTIVE-031C constrain step presentation, URL query parameters, and SPA fallback routing; align component behavior with
ydb-platform/ydb-ui-componentsand keep completed steps visibly completed even when selected. - Target commit affordances: Where the UI requires explicit commit before discovery, implementation examples include a Done action on the default SSH block, a Done action on the per-row edit dialog, and row removal that writes the new target set to the server (FR-INTERACTIVE-024A).
- Localization: Load operator-visible strings from locale resources per FR-I18N-001–FR-I18N-003; never use the backend binary as the sole source of localized UI text (FR-I18N-003A).
- Secrets: Mask secrets in forms and logs per FR-SECURITY-008 and FR-USABILITY-005.