diff --git a/docs/content/ui-docs/ObjectExplorer.md b/docs/content/ui-docs/ObjectExplorer.md new file mode 100644 index 00000000..1799e559 --- /dev/null +++ b/docs/content/ui-docs/ObjectExplorer.md @@ -0,0 +1,220 @@ +# Object Explorer + +## 1. Introduction + +The **Object Explorer** is a universal resource browser designed to provide a single pane of glass for all Kubernetes resources across your clusters. Whether you are finding, browsing, or managing resources, the Object Explorer offers a unified interface to handle any resource type with ease. + +**Key Benefits:** +- **Access all resource types**: Native and Custom Resources (CRDs) are fully discoverable. +- **Powerful filtering**: Drill down by kind, namespace, status, age, and labels. +- **Multiple view modes**: Visualize data via Grid or List views. +- **Bulk operations**: Manage resources at scale with ease. + +## 2. Prerequisites + +Before using the Object Explorer, ensure you have: +- **Kubernetes Cluster Access**: An active connection to your target cluster. +- **Proper RBAC Permissions**: Sufficient rights to list, get, and watch the resources you intend to manage. +- **KubeStellar UI Access**: Authenticated access to the web interface. + +## 3. Feature Overview + +The Object Explorer is built on three core philosophies: universal resource auto-discovery, smart filtering, and adaptable visualization. + +### 3.1 Universal Resource Browser +The browser provides access to **all** Kubernetes resources, supporting auto-discovery of API groups and versions. + +**Supported Built-in Types:** +- **Workloads**: Pods, Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, ReplicaSets. +- **Network**: Services, Ingresses, NetworkPolicies. +- **Config & Storage**: ConfigMaps, Secrets, PersistentVolumes, PersistentVolumeClaims. +- **Access Control**: ServiceAccounts, Roles, RoleBindings. +- **Custom Resources**: Full support for all Custom Resource Definitions (CRDs). + +**Capabilities:** +- Auto-discovery of available resource types. +- Dynamic key listing based on API group detection. +- Full support for both namespaced and cluster-scoped resources. + +### 3.2 Smart Filtering System +A robust multi-variable filtering system helps you isolate resources quickly. + +**Filter Categories & Features:** +- **Multi-Kind Selection**: Select multiple resource types (e.g., Deployments + Services) via a multi-select dropdown with search and recently used highlights. +- **Multi-Namespace Selection**: Filter across "All Namespaces" or specific sets, with search and count indicators. +- **Status Filter**: `Running`, `Pending`, `Failed`, `Succeeded`, `Unknown`. +- **Label Filter**: Add multiple key-value pairs with AND/OR logic and auto-suggestions. +- **Age Filter**: Presets (Last hour, 24h, 7d, 30d) and custom ranges. + +**Quick Search:** +- Real-time, case-insensitive search by resource name with partial match support. +- Search history and easy "Clear" controls. + +**Diagram: Filter Flow** + +```mermaid +graph LR + A[Select Kinds] --> B[Select Namespaces] + B --> C[Apply Status/Labels] + C --> D[Search Name] + D --> E[Results] +``` + +![Filter Panel Expanded](./images/object-explorer-filters.png) + +### 3.3 View Modes 👁️ +Switch between modes to suit your workflow. Preferences are persisted locally. + +**Grid View (Card Layout)** +*Best for: Visual browsing and health checks.* +- **Card Design**: Prominent name, icon/type badge, status indicator, action menu (⋮), and quick stats (replicas, ports). +- **Features**: Responsive columns, hover effects, and skeleton loading. + +![Grid View Interface](./images/object-explorer-grid-view.png) + +**List View (Compact)** +*Best for: Scanning large datasets.* +- **Row Design**: Type icon, status dot, age, label count, and action menu. +- **Features**: Condensed spacing, keyboard navigation, and double-click to view details. + +![List View Interface](./images/object-explorer-list-view.png) + +**Table View (Future)** +*Best for: Deep analysis.* +- Sortable/resizable columns and CSV export. + +![Table View Interface](./images/object-explorer-table-view.png) + +**Diagram: View Modes Comparison** + +```mermaid +graph TD + A[View Modes] --> B[Grid View] + A --> C[List View] + A --> D[Table View] + B -->|Best for| B1[Visual Browsing] + C -->|Best for| C1[Quick Scanning] + D -->|Best for| D1[Deep Analysis] +``` + +### 3.4 Resource Operations ⚙️ +Perform actions on single or multiple resources. + +**Individual Actions:** +- **View Details**: Opens the detail panel. +- **Edit Manifest**: In-place YAML editor with validation and save capability. +- **View Logs**: Live streaming for Pods with container selection. +- **Delete**: With grace period and cascade options. +- **Additional**: Describe, Copy Name/YAML, View Events. + +**Bulk Operations:** +- **Selection**: "Select All" page or matching filters. +- **Actions**: Bulk delete, bulk export (zip), bulk label update. +- **Progress**: Real-time progress bar with success/error counts. + +**Diagram: Bulk Operations Flow** + +```mermaid +graph LR + A[Select Resources] --> B[Choose Action] + B --> C[Confirm] + C --> D[Execute] + D --> E[Show Results] +``` + +### 3.5 Resource Detail Panel +A comprehensive slide-out panel for deep inspection. + +- **Summary View**: Metadata, Owner References, Labels/Annotations (editable), and Status Conditions. +- **Full Manifest Tab**: Complete YAML/JSON with copy/download/edit controls and syntax highlighting. +- **Related Resources**: Navigable links to Owners (Controllers), Owned resources (Pods), and referencing Services/Ingresses. +- **Events Tab**: Chronological list of warning and normal events. + +![Resource Detail Panel - Summary Tab](./images/object-explorer-resource-panel.png) + +### 3.6 Additional Features +- **Auto-Refresh**: Toggleable (5s, 10s, 30s, 60s) with pause-on-hover/open. +- **Pagination**: Configurable page size (25, 50, 100) and jump-to-page. +- **Error Handling**: Network notifications, permission warnings, and retry options. +- **Loading States**: Skeleton screens and optimistic UI updates. +- **Empty States**: Illustrative graphics with action suggestions (e.g., "Create your first resource"). + +## 4. Step-by-Step Guides + +### Guide 1: Browsing Pods Across Namespaces +1. Navigate to `/resources`. +2. Select **Pods** from the specific Kind dropdown. +3. Choose **All Namespaces** in the namespace selector. +4. (Optional) Apply a **Status Filter** for `Failed` to identify issues. + +### Guide 2: Finding Resources by Labels +1. Open the filters panel. +2. Add a **Label Filter**. +3. Enter key `app` and value `frontend`. +4. Results will filter to matching resources immediately. + +### Guide 3: Using Multi-Kind Filtering +1. Open the Kind dropdown. +2. Select **Deployments**, **Services**, and **API Service**. +3. View the combined list to see the full footprint of your application. + +![Multi-Kind Selection Dropdown](./images/object-explorer-multi-kind-dropdown-1.png) + +### Guide 4: Bulk Deleting Resources +1. Filter for the resources you wish to remove (e.g., by label `env=test`). +2. Check the **Select All** box. +3. Click **Bulk Actions** > **Delete**. +4. Confirm the action in the dialog. + + +### Guide 5: Editing Resource Manifests +1. Click the **Action Menu** (⋮) on a resource. +2. Select **Edit Manifest**. +3. Modify values in the Monaco Editor. +4. Click **Save**. + + + +### Guide 6: Viewing Resource Details +1. Click the resource name or card. +2. The **Detail Panel** opens. +3. Switch to **Events** to see recent activity or **Manifest** to see the live config. + +## 5. Use Cases + +### Use Case 1: Debugging Across Namespaces +**Scenario:** An application is failing, but the specific namespace is unknown. +**Solution:** Filter Kind to `Pod`, Namespace to `All`, and Status to `Failed`. Use Quick Search for the app name. + +### Use Case 2: Auditing ConfigMaps and Secrets +**Scenario:** You need to audit configuration resources created in the last month. +**Solution:** Filter Kinds to `ConfigMap` + `Secret`. Set Age Filter to `Last 30 days`. + +### Use Case 3: Cleaning Up Unused Resources +**Scenario:** A development environment needs to be torn down. +**Solution:** Filter by Namespace `dev-env`. Select all resources. Perform Bulk Delete. + +### Use Case 4: Discovering Custom Resources +**Scenario:** Exploring a newly installed Operator. +**Solution:** Open Kind dropdown. Search for the Operator's group. Select the new CRDs to explore instances. + +## 6. API Reference + +**Endpoints:** +- `GET /api/v1/resources`: List resources. Supports `kind`, `namespace`, `labelSelector`, `fieldSelector`. +- `GET /api/v1/resources/{kind}/{namespace}/{name}`: Get single details. +- `PUT /api/v1/resources/{kind}/{namespace}/{name}`: Update resource. +- `DELETE /api/v1/resources/{kind}/{namespace}/{name}`: Delete resource. + +## 7. Troubleshooting + +| Problem | Possible Cause | Solution | +| :--- | :--- | :--- | +| **Permission Errors** | Missing RBAC. | Request `list/watch` permissions from admin. | +| **Slow Loading** | Large dataset. | Filter by namespace or reduce page size. | +| **Filter Not Working** | Typo in label. | Check label syntax `key=value`. | +| **Empty Results** | No matches. | Clear filters and retry. | + +## 8. Related Features +- **WECS**: Use Object Explorer to verify WECS deployments. +- **ITS & WDS**: Integrated monitoring of inventory and workload descriptions. diff --git a/docs/content/ui-docs/images/object-explorer-filters.png b/docs/content/ui-docs/images/object-explorer-filters.png new file mode 100644 index 00000000..a1c17fce Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-filters.png differ diff --git a/docs/content/ui-docs/images/object-explorer-grid-view.png b/docs/content/ui-docs/images/object-explorer-grid-view.png new file mode 100644 index 00000000..1cd25422 Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-grid-view.png differ diff --git a/docs/content/ui-docs/images/object-explorer-list-view.png b/docs/content/ui-docs/images/object-explorer-list-view.png new file mode 100644 index 00000000..9181d1c1 Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-list-view.png differ diff --git a/docs/content/ui-docs/images/object-explorer-multi-kind-dropdown-1.png b/docs/content/ui-docs/images/object-explorer-multi-kind-dropdown-1.png new file mode 100644 index 00000000..bc0f2585 Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-multi-kind-dropdown-1.png differ diff --git a/docs/content/ui-docs/images/object-explorer-resource-panel.png b/docs/content/ui-docs/images/object-explorer-resource-panel.png new file mode 100644 index 00000000..ef83e135 Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-resource-panel.png differ diff --git a/docs/content/ui-docs/images/object-explorer-table-view.png b/docs/content/ui-docs/images/object-explorer-table-view.png new file mode 100644 index 00000000..b2370d08 Binary files /dev/null and b/docs/content/ui-docs/images/object-explorer-table-view.png differ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 52b433d2..41875564 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -80,7 +80,9 @@ nav: - Missing results in a CombinedStatus object: direct/knownissue-collector-miss.md - Kind host not configured for more than two clusters: direct/installation-errors.md - Insufficient CPU for your clusters: direct/knownissue-cpu-insufficient-for-its1.md - - UI (User Interface): ui-docs/ui-overview.md + - UI (User Interface): + - Overview: ui-docs/ui-overview.md + - Object Explorer: ui-docs/ObjectExplorer.md - Teardown: direct/teardown.md - Contributing: - Overview (How to join in): direct/contribute.md