This is an automated email from the ASF dual-hosted git repository. ArafatKhan2198 pushed a commit to branch HDDS-15976 in repository https://gitbox.apache.org/repos/asf/ozone-site.git
commit 49f3954341f4473bd924260c51d799c09fc05651 Author: arafat <[email protected]> AuthorDate: Sat Jul 25 12:27:05 2026 +0530 HDDS-15976. Add Recon Web UI namespace pages: Volumes, Buckets, Namespace Usage. --- .../02-recon/01-recon-web-ui/03-volumes.mdx | 120 +++++++++++++++++ .../02-recon/01-recon-web-ui/04-buckets.mdx | 138 +++++++++++++++++++ .../01-recon-web-ui/10-namespace-usage.mdx | 146 +++++++++++++++++++++ .../{ => 01-recon-web-ui}/ozone_recon_buckets.png | Bin .../ozone_recon_namespace_usage.png | Bin .../{ => 01-recon-web-ui}/ozone_recon_volumes.png | Bin 6 files changed, 404 insertions(+) diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/03-volumes.mdx b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/03-volumes.mdx new file mode 100644 index 0000000000..3a3aeb7f7e --- /dev/null +++ b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/03-volumes.mdx @@ -0,0 +1,120 @@ +--- +sidebar_label: Volumes +--- + +# Recon UI — Volumes Page + + + +## 1. Page Overview + +The **Volumes** page lists the volumes in your Ozone cluster and their key +properties: owner, administrator, creation and modification times, quota, and +namespace usage. From here you can inspect a volume's access control list (ACL) +and jump to the buckets inside a volume. + +It is a read-only listing used to browse and search volumes and to review +their ownership and quota settings. + +## 2. When to Use This Page + +- To browse all volumes in the cluster and see who owns them. +- To find a specific volume by name, owner, or admin. +- To review a volume's quota and how much of its namespace is in use. +- To inspect the ACLs (permissions) configured on a volume. +- As a jumping-off point to the buckets contained in a volume. + +## 3. How to Access the Page + +Open the **Volumes** entry in the left navigation menu, or go to the `/Volumes` +route directly. You can also reach a filtered view from the **Volumes** count +card on the Overview page. + +## 4. Information Displayed + +The page header shows the title and an **Auto Reload** panel (see Available +Actions). The main area is a single table of volumes. + +### Table columns + +- **Volume** — the volume name. Sortable; sorted ascending by default. +- **Owner** — the user that owns the volume. Sortable. +- **Admin** — the administrator of the volume. Sortable. +- **Creation Time** — when the volume was created. Shows `NA` if not available. +- **Modification Time** — when the volume was last modified. Shows `NA` if not + available. +- **Quota (Size)** — the storage quota set on the volume. Shows `NA` when no + quota is set. +- **Namespace Capacity** — a bar showing used namespace against the namespace + quota (number of objects allowed). Hovering shows the used and remaining + values. A quota of `-1` (unset) is shown as `-`. +- **Actions** — per-row links: + - **Show buckets** — opens the Buckets page filtered to that volume. + - **Show ACL** — opens a side panel listing the volume's ACL entries. + +### ACL side panel + +Selecting **Show ACL** opens a drawer showing the access-control entries +configured on the volume (who has access and what permissions they hold). + +## 5. Available Actions + +- **Columns** selector — choose which columns are visible. The **Volume** column + is always shown; you can remove others by unchecking them or closing their + tag. +- **Limit** selector — controls how many volumes are fetched from the server. + Options are 1000, 5000, 10000, and 20000 (default 1000). +- **Search** — filter the loaded rows by **Volume**, **Owner**, or **Admin**. + Pick the field to search, then type; matching is a simple contains match and + is applied to the rows already loaded. Search is disabled when the table is + empty. +- **Sort** — click a sortable column header (Volume, Owner, Admin, Creation + Time, Modification Time, Namespace Capacity). +- **Pagination** — page through results; the page size is adjustable and the + footer shows the range and total (for example, `1-10 of 240 volumes`). +- **Auto Reload** panel — an **Auto Refresh** toggle (refreshes every 60 seconds + and remembers your choice for the session) and a manual **reload** button that + shows the last refreshed time. +- **Row links** — **Show buckets** and **Show ACL** as described above. + +## 6. How to Interpret the Information + +- **Quota (Size) = NA:** no size quota is set on the volume, so it is not + limited by a volume-level size quota. +- **Namespace Capacity bar:** a nearly full bar means the volume is close to its + namespace quota (the number of objects it may contain); `-` means no namespace + quota is set. +- **Creation / Modification Time = NA:** a timestamp was not available for that + volume. +- **Search vs. Limit:** search filters only the rows already loaded. If you + expect a volume that is not showing, increase the **Limit** so it is included + in what is fetched, then search. + +## 7. Common Use Cases + +1. **Find a tenant's volumes.** Set Search to **Owner**, type the user name, and + review the matching volumes and their quotas. +2. **Check quota pressure.** Sort by **Namespace Capacity** to see which volumes + are closest to their namespace quota, then plan quota increases. +3. **Audit access.** Use **Show ACL** on a volume to confirm which users and + groups have permissions, and **Show buckets** to continue the review at the + bucket level. + +## 8. Important Notes and Limitations + +- **Data freshness.** The volume list comes from Recon's own copy of the Ozone + Manager (OM) database, which is updated by a periodic sync. Very recent + changes on OM may not appear until the next sync. **Auto Refresh** only + re-queries Recon; it does not force a re-sync from OM. +- **Limit caps the result set.** Only up to the selected limit of volumes is + fetched. On very large clusters, raise the limit to see more, keeping in mind + larger limits take longer to load. +- **Search and sorting apply to loaded rows only**, not to volumes beyond the + selected limit. +- On an error, the page reports a data-fetch error and the table stays empty. + +## 9. Related Pages + +- **Buckets** — the buckets inside a volume (reachable via **Show buckets**). +- **Overview** — cluster-wide totals, including the volume count. +- **Namespace Usage** — disk usage broken down across the namespace. diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/04-buckets.mdx b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/04-buckets.mdx new file mode 100644 index 0000000000..180b0587c1 --- /dev/null +++ b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/04-buckets.mdx @@ -0,0 +1,138 @@ +--- +sidebar_label: Buckets +--- + +# Recon UI — Buckets Page + + + +## 1. Page Overview + +The **Buckets** page lists the buckets in your Ozone cluster along with their +properties: the volume they belong to, owner, versioning, storage type, bucket +layout, creation and modification times, storage and namespace usage against +quota, and (for linked buckets) their source volume and bucket. You can also +inspect each bucket's access control list (ACL). + +It is a read-only listing for browsing, searching, and filtering buckets, and +for reviewing their configuration and quota usage. + +## 2. When to Use This Page + +- To browse all buckets, or just the buckets within one or more volumes. +- To find a bucket by name or by volume. +- To check a bucket's storage type, layout, and versioning setting. +- To review storage and namespace usage against quota. +- To inspect the ACLs (permissions) on a bucket. +- To identify link buckets and see their source. + +## 3. How to Access the Page + +Open the **Buckets** entry in the left navigation menu, or go to the `/Buckets` +route directly. From the **Volumes** page, the **Show buckets** action opens +this page pre-filtered to a single volume. + +## 4. Information Displayed + +The page header shows the title and an **Auto Reload** panel (see Available +Actions). The main area is a table of buckets, filtered by the selected +volume(s). + +### Table columns + +- **Bucket** — the bucket name (always shown, pinned to the left). Sortable. +- **Volume** — the parent volume (always shown, pinned to the left). Sortable. +- **Owner** — the bucket owner. Sortable. +- **Versioning** — a green check when versioning is enabled, otherwise a neutral + cross. +- **Storage Type** — RAM_DISK, SSD, DISK, or ARCHIVE, each with an icon. + Filterable and sortable. +- **Bucket Layout** — a colored tag: FILE_SYSTEM_OPTIMIZED (green), OBJECT_STORE + (orange), or LEGACY (blue). Filterable and sortable. +- **Creation Time** — when the bucket was created. Shows `NA` if not available. +- **Modification Time** — when the bucket was last modified. Shows `NA` if not + available. +- **Storage Capacity** — a bar showing used bytes against the size quota. + Hovering shows used and remaining. Sortable by used bytes. +- **Namespace Capacity** — a bar showing used namespace (object count) against + the namespace quota. Sortable by used namespace. +- **Source Volume** — for link buckets, the volume the bucket links to; + otherwise `NA`. +- **Source Bucket** — for link buckets, the bucket it links to; otherwise `NA`. +- **ACLs** — a **Show ACL** link that opens a side panel with the bucket's ACL + entries. + +### ACL side panel + +Selecting **Show ACL** opens a drawer listing the access-control entries on the +bucket (who has access and what permissions they hold). + +## 5. Available Actions + +- **Volumes** selector — choose one or more volumes to show buckets for. + Supports search and select-all. When the page first loads, all volumes are + selected; if you arrived from the Volumes page, only that volume is selected. +- **Columns** selector — choose which columns are visible. The **Bucket** and + **Volume** columns are always shown. +- **Limit** selector — how many buckets are fetched from the server: 1000, 5000, + 10000, or 20000 (default 1000). +- **Search** — filter the shown rows by **Bucket** or **Volume** name; matching + is a simple contains match on the rows already loaded. Disabled when there are + no rows. +- **Column filters** — Storage Type and Bucket Layout can be filtered to + specific values from their column headers. +- **Sort** — click a sortable column header. +- **Pagination** — page through results; page size is adjustable and the footer + shows the range and total (for example, `1-10 of 320 buckets`). +- **Auto Reload** panel — an **Auto Refresh** toggle (refreshes every 60 seconds + and remembers your choice for the session) and a manual **reload** button + showing the last refreshed time. +- **Show ACL** — opens the ACL side panel for a bucket. + +## 6. How to Interpret the Information + +- **Versioning:** a green check means object versioning is enabled; a cross + means each key keeps only its latest version. +- **Bucket Layout:** FILE_SYSTEM_OPTIMIZED (FSO) buckets behave like a file + system with directories; OBJECT_STORE (OBS) buckets behave like flat object + storage; LEGACY is the older layout. This affects how keys are organized. +- **Storage Type:** the storage medium the bucket's data targets (for example + DISK or SSD). +- **Storage / Namespace Capacity bars:** a nearly full bar means the bucket is + close to its size or object-count quota. A quota shown as `-` means no quota + is set, so the bucket is not limited at the bucket level. +- **Source Volume / Source Bucket present (not NA):** the bucket is a link + bucket that points to another bucket rather than storing its own data. +- **Creation / Modification Time = NA:** a timestamp was not available. + +## 7. Common Use Cases + +1. **Review one volume's buckets.** From the Volumes page click **Show buckets** + (or pick the volume in the Volumes selector) to see just that volume's + buckets, their layouts, and quota usage. +2. **Find quota pressure.** Sort by **Storage Capacity** or **Namespace + Capacity** to see which buckets are closest to their limits. +3. **Audit configuration.** Filter by **Bucket Layout** or **Storage Type** to + confirm buckets are configured as expected, and use **Show ACL** to verify + permissions. + +## 8. Important Notes and Limitations + +- **Data freshness.** The bucket list comes from Recon's own copy of the Ozone + Manager (OM) database, updated by a periodic sync. Very recent changes on OM + may not appear until the next sync. **Auto Refresh** only re-queries Recon; it + does not force a re-sync from OM. +- **Limit caps the result set.** Only up to the selected limit of buckets is + fetched. On large clusters, raise the limit to see more, keeping in mind + larger limits take longer to load. +- **Search, sorting, and column filters apply to loaded rows only**, not to + buckets beyond the selected limit. +- The **Volumes** selector chooses which of the loaded buckets are shown; it + does not fetch additional buckets beyond the limit. +- On an error, the page reports a data-fetch error and the table stays empty. + +## 9. Related Pages + +- **Volumes** — the parent volumes; use **Show buckets** to filter this page. +- **Overview** — cluster-wide totals, including the bucket count. +- **Namespace Usage** — disk usage broken down across the namespace. diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/10-namespace-usage.mdx b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/10-namespace-usage.mdx new file mode 100644 index 0000000000..2ed9f2e8b3 --- /dev/null +++ b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/10-namespace-usage.mdx @@ -0,0 +1,146 @@ +--- +sidebar_label: Namespace Usage +--- + +# Recon UI — Namespace Usage Page + + + +## 1. Page Overview + +The **Namespace Usage** page (also called Disk Usage) lets you explore how +storage is consumed across the Ozone namespace. Starting from a path, it shows a +pie chart of the largest sub-paths by size and a metadata table describing the +selected entity (volume, bucket, directory, or key). You can drill down into +sub-paths to find what is using the most space. + +It is an interactive, read-only explorer for capacity investigation at the +namespace level. + +## 2. When to Use This Page + +- To find which volumes, buckets, or directories are consuming the most space. +- To drill down a path and locate large sub-directories or keys. +- To inspect the metadata and quota of a specific volume, bucket, directory, or + key. +- To compare a path's logical size against its size with replication. + +## 3. How to Access the Page + +Open the **Namespace Usage** entry in the left navigation menu, or go to the +`/NamespaceUsage` route directly. + +## 4. Information Displayed + +The page header shows the title. Below it are informational banners, a +breadcrumb navigator, a limit selector, a pie chart, and a metadata table. + +### Banners + +- An **info** banner explaining that a small amount of extra block size is added + to small entities in the chart for visibility, and that the pie-chart tooltip + shows exact sizes. +- At the root path (`/`), a **warning** banner noting that root-path usage can + be expensive in large deployments and suggesting you enter an exact path. + +### Breadcrumb navigator + +Shows the current path and lets you move up or down the namespace. Selecting a +segment or sub-path reloads the chart and metadata for that location. + +### Pie chart + +A pie of the current path's sub-paths by size: + +- Each slice is a sub-path; keys are shown with no trailing slash and + directories with a trailing `/`. +- If there are more sub-paths than the selected limit (or leftover size beyond + the shown slices), the remainder is grouped into an **Other Objects** slice. +- The chart title shows the currently selected size against the total (for + example, `12 GB / 40 GB`). +- Hovering a slice shows its exact **Total Data Size** and **Percentage**. +- Toggling slices in the chart updates the selected-size shown in the title. + +### Metadata table + +A **Property / Value** table describing the current entity. Depending on the +entity type, it can include: + +- **Entity Type** (volume, bucket, directory, or key). +- Object information such as Volume, Bucket, Name, Owner, Storage Type, Bucket + Layout, Used Namespace, and (for linked entities) Source Volume / Source + Bucket. +- **Creation Time** and **Modification Time**. +- **Used Bytes** / **Data Size**. +- **Quota In Namespace**, **Quota Allowed**, and **Quota Used** (only when a + quota is set). +- Replication details: **Replication Factor**, **Replication Type**, and + **Replication Required Nodes**. +- Counts for container-like paths: **Volumes**, **Buckets**, **Total + Directories**, **Total Keys**. +- For a **key**, a focused view with **File Size** and **File Size With + Replication** plus creation and modification times. + +## 5. Available Actions + +- **Breadcrumb navigation** — click path segments or sub-paths to drill in and + out. +- **Limit** selector — how many sub-paths to show as individual slices: 5, 10, + 15, 20, or 30 (default 10). Sub-paths beyond the limit roll into **Other + Objects**. +- **Reload** button — re-fetches usage for the current path. At the root path it + re-triggers the root-path load confirmation. +- **Load usage / root-path confirmation** — at the root path, usage is not + loaded automatically. You must click **Load usage** and confirm the + "expensive operation" dialog before root usage is calculated. +- **Pie-chart interactions** — hover a slice for exact size and percentage; + toggle slices to update the selected-size total. + +## 6. How to Interpret the Information + +- **Slice size vs. Other Objects:** the largest slices are the biggest consumers + at the current level. A large **Other Objects** slice means much of the usage + is spread across sub-paths beyond the selected limit — raise the limit or drill + in to see them. +- **Extra block size note:** very small entities are padded slightly in the + chart so they remain visible; always trust the tooltip's exact size over the + slice's apparent area. +- **Size vs. Size With Replication:** the plain size is logical data; the + replicated size reflects the physical space used after replication. +- **Quota Allowed vs. Quota Used:** how close the entity is to its configured + quota; absent when no quota is set. +- **Status messages:** + - **INITIALIZING** — Recon is still building its namespace summary; wait and + retry. + - **PATH_NOT_FOUND / Invalid Path** — the entered path does not exist. + +## 7. Common Use Cases + +1. **Find the biggest space consumer.** Enter a bucket path, review the pie + chart, and drill into the largest slice repeatedly until you reach the + directory or key responsible. +2. **Inspect a specific key.** Navigate to a key to see its File Size, File Size + With Replication, and timestamps in the metadata table. +3. **Check quota headroom.** Open a volume or bucket and compare Quota Used + against Quota Allowed to decide whether to raise the quota. + +## 8. Important Notes and Limitations + +- **Root path is not loaded by default.** Because computing usage from `/` can be + expensive on large clusters, you must explicitly click **Load usage** and + confirm. Entering an exact path loads directly without the prompt. +- **Data source and freshness.** Usage, summary, and quota data come from + Recon's namespace summary, which Recon builds from its copy of the Ozone + Manager (OM) database. If it is still building, the page reports + **INITIALIZING**; wait and retry. +- **Limit affects the chart only.** It controls how many sub-paths are drawn as + individual slices; the rest are grouped into **Other Objects**. +- **Small entities are visually padded** in the chart; use the tooltip for exact + values. +- On an invalid path or fetch error, the page shows an error notification. + +## 9. Related Pages + +- **Volumes** and **Buckets** — the entities whose usage you explore here. +- **Overview** — cluster-wide capacity and object totals. +- **Capacity** — cluster-level storage breakdown. diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_buckets.png b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_buckets.png similarity index 100% rename from docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_buckets.png rename to docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_buckets.png diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_namespace_usage.png b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_namespace_usage.png similarity index 100% rename from docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_namespace_usage.png rename to docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_namespace_usage.png diff --git a/docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_volumes.png b/docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_volumes.png similarity index 100% rename from docs/05-administrator-guide/03-operations/09-observability/02-recon/ozone_recon_volumes.png rename to docs/05-administrator-guide/03-operations/09-observability/02-recon/01-recon-web-ui/ozone_recon_volumes.png --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
