Create Comprehensive MDX Documentation for WECS - Remote Cluster Monitoring

[btwshivam]

Overview

Create detailed MDX documentation for the WECS (Workload Execution Cluster Space) component, covering remote cluster tree view, real-time monitoring via WebSocket, resource details, and live logs streaming.

File to Create

File: docs/wecs-remote-monitoring.mdx

Features to Document

1. Remote Cluster Tree View

Hierarchical Structure

• Multi-cluster visualization
• Cluster-level nodes (top level)
• Namespace-level organization (2nd level)
• Resource type grouping (3rd level)
• Individual resources (4th level)
• Sub-resources like Pods (5th level)

Cluster Nodes

• Cluster name display
• Cluster status indicator
• Connection status (WebSocket)
• Expand/collapse functionality
• Resource count per cluster
• Click to load namespaces

Namespace Nodes

• Namespace name
• Resource count per namespace
• Filtered display (only with resources)
• Color-coded by status
• Expand to show resource types

Resource Type Nodes

• Deployments
• Services
• Pods
• StatefulSets
• DaemonSets
• Jobs
• CronJobs
• ConfigMaps
• Secrets
• ReplicaSets
• Count display per type

Individual Resource Nodes

• Resource name
• Status icon (Running/Pending/Failed)
• Creation timestamp
• Click to view details

2. WebSocket Integration

Real-Time Data Streaming

• Live WebSocket connection to clusters
• Automatic reconnection on disconnect
• Connection status indicators:
  • 🟢 Connected
  • 🟡 Connecting
  • 🔴 Disconnected
• Backoff retry strategy
• Data caching for performance
• Incremental updates

Connection Management

• Automatic connection on cluster selection
• Manual reconnect button
• Connection pooling
• Graceful disconnection
• Error handling and recovery
• Timeout configuration

Data Updates

• Real-time resource status changes
• New resource detection
• Resource deletion updates
• Status condition changes
• Event streaming

3. Resource Details Panel

Summary Tab

• Basic Information:

  • Resource name
  • Namespace
  • Kind/Type
  • Cluster name
  • Creation timestamp
  • UID
  • Resource version
  • API version

• Status Information:

  • Overall status (Ready/Not Ready)
  • Replicas (desired vs available vs ready)
  • Conditions array:
    • Type (Available, Progressing, etc.)
    • Status (True/False)
    • Reason
    • Message
    • Last update time
    • Last transition time
  • Observed generation

• Labels and Annotations:

  • All labels as key-value pairs
  • All annotations as key-value pairs
  • Click to copy
  • Visual chip display

• Spec Information:

  • Selector labels
  • Container images
  • Ports
  • Environment variables
  • Volume mounts
  • Resource requests/limits

Edit Tab (Manifest Editor)

• Full YAML manifest display
• Syntax highlighting
• Read-only or editable mode
• Line numbers
• Format validation
• Save changes button
• JSON/YAML toggle
• Copy to clipboard
• Download manifest

Logs Tab

• Container Selection:

  • Dropdown to select container
  • Multi-container support
  • Init container logs
  • Sidecar container logs

• Log Display:

  • Real-time log streaming
  • Auto-scroll to bottom
  • Manual scroll with sticky mode
  • Timestamp display (optional)
  • Log level highlighting:
    • ERROR in red
    • WARN in yellow
    • INFO in blue
  • Search/filter logs
  • Line numbers
  • Word wrap toggle

• Log Controls:

  • Refresh button
  • Clear logs button
  • Download logs
  • Tail lines selector (50, 100, 500, 1000, All
  • Follow mode toggle
  • Previous container logs (if restarted)

Events Tab

• Event List:

  • Event type (Normal/Warning)
  • Reason
  • Message
  • Source component
  • First seen timestamp
  • Last seen timestamp
  • Count (if repeated)

• Event Filtering:

  • Filter by type (Normal/Warning)
  • Search by reason/message
  • Sort by time
  • Clear filters

• Visual Indicators:

  • ⚠️ Warning events in yellow
  • ℹ️ Normal events in blue
  • Time since last occurrence

4. Interactive Features 🖱️

Navigation

• Click to expand cluster → namespaces
• Click to expand namespace → resource types
• Click to expand type → individual resources
• Click resource → open details panel
• Breadcrumb navigation
• Back button to close details

Search and Filter

• Search resources by name
• Filter by resource type
• Filter by namespace
• Filter by status (Running/Pending/Failed)
• Filter by cluster (if monitoring multiple)
• Combined filters
• Clear all filters button

Actions

• Refresh cluster data
• Refresh individual resource
• Delete resource (with confirmation)
• Edit resource manifest
• View logs
• Describe resource
• Export resource YAML
• Copy resource name

Auto-Refresh

• Toggle auto-refresh on/off
• Configurable interval (5s, 10s, 30s, 60s)
• Manual refresh button
• Last updated timestamp display
• Pause on details panel open

5. Multi-Cluster Support

Cluster Selection

• Dropdown to select active cluster
• Monitor multiple clusters simultaneously
• Cluster status badges
• Quick switch between clusters
• Recently viewed clusters

Cluster Comparison

• Side-by-side resource comparison
• Status aggregation across clusters
• Health dashboard per cluster
• Resource count comparison

6. Resource Type Coverage

Workload Resources

• Deployments
• StatefulSets
• DaemonSets
• ReplicaSets
• Jobs
• CronJobs
• Pods

Service Resources

• Services (ClusterIP, NodePort, LoadBalancer)
• Endpoints
• Ingresses

Configuration Resources

• ConfigMaps
• Secrets

Storage Resources

• PersistentVolumes
• PersistentVolumeClaims
• StorageClasses

Custom Resources

• Support for CRDs
• Dynamic resource type detection

Visual Content Requirements

Screenshots Needed (12+ screenshots)

1. WECS Tree View Overview

   • Multiple clusters visible
   • Expanded namespace structure
   • Resource type organization
   • Annotations showing hierarchy

2. Cluster Node Expanded

   • Namespaces listed
   • Resource counts
   • Connection status indicator

3. Namespace Expanded to Resource Types

   • Deployments, Services, Pods visible
   • Count per type
   • Status indicators

4. Resource Details - Summary Tab

   • All sections visible
   • Labels and annotations
   • Status conditions
   • Replicas information

5. Resource Details - Edit Tab

   • YAML editor with syntax highlighting
   • Line numbers
   • Copy and download buttons

6. Resource Details - Logs Tab

   • Container selector dropdown
   • Live log streaming
   • Auto-scroll indicator
   • Log controls (refresh, clear, download)
   • Colored log levels

7. Resource Details - Events Tab

   • Event list with warnings and normal events
   • Timestamps
   • Event details

8. WebSocket Connection Indicators

   • Connected state (green)
   • Connecting state (yellow)
   • Disconnected state (red)
   • Reconnect button

9. Search and Filter Interface

   • Search bar
   • Filter dropdowns
   • Active filters display
   • Clear filters button

10. Multi-Container Pod Logs

    • Container selection dropdown
    • Multiple containers listed
    • Init container option

11. Auto-Refresh Controls

    • Toggle switch
    • Interval selector
    • Last updated timestamp

12. Mobile/Responsive View

    • Tree view on mobile
    • Details panel adaptation

Diagrams Required

1. WECS Architecture

WECS Frontend
     ↓ WebSocket
WECS Backend
     ↓
Remote Clusters (via agents)
     ↓
Kubernetes API

2. Tree Hierarchy

Cluster
└─ Namespace
   └─ Resource Type
      └─ Resource Instance
         └─ Sub-resources (Pods)

3. Data Flow

Cluster → WebSocket → Backend → Cache → Frontend → Tree View
                                   ↓
                             Real-time Updates

4. Resource Detail Tabs

Resource Details Panel
├─ Summary (metadata, status, conditions)
├─ Edit (YAML/JSON manifest)
├─ Logs (live streaming)
└─ Events (resource events)

Documentation Structure

1. Introduction

• What is WECS?
• Purpose: Remote cluster monitoring
• When to use: Monitoring deployed workloads
• Key benefits:
  • Real-time visibility
  • Live logs from remote clusters
  • Hierarchical resource organization
  • WebSocket-based efficiency

2. Prerequisites

• Clusters imported in ITS
• Workloads deployed via BP
• WECS agent running on clusters (if required)
• Network connectivity
• WebSocket support

3. Feature Overview

• WECS architecture
• WebSocket connection model
• Resource hierarchy
• Relationship with ITS and BP

4. Step-by-Step Guides

Guide 1: Navigating the WECS Tree

1. Open WECS page
2. See list of monitored clusters
3. Click cluster to expand
4. View namespaces
5. Expand namespace to see resource types
6. Click resource type to see instances
7. Click resource to view details

Guide 2: Viewing Resource Details

1. Navigate to specific resource
2. Click resource name
3. Review Summary tab
4. Check status conditions
5. View labels and annotations
6. Switch to Edit tab for YAML
7. Switch to Logs tab for live logs
8. Switch to Events tab for history

Guide 3: Streaming Live Logs

1. Open resource details
2. Go to Logs tab
3. Select container (if multiple)
4. Enable "Follow" mode
5. Set tail lines (e.g., 100)
6. Watch real-time logs
7. Search/filter logs
8. Download logs if needed

5. Use Cases

Use Case 1: Troubleshooting Failed Deployments

Scenario: Deployment shows 0/3 pods ready
Solution:

• Navigate to deployment in WECS
• Check status conditions
• View events tab for errors
• Check pod logs for crash reasons
• Edit manifest if configuration issue

Use Case 2: Live Log Monitoring

Scenario: Monitor application logs in real-time
Solution:

• Open pod details
• Go to Logs tab
• Enable follow mode
• Search for error patterns
• Download logs for analysis

Use Case 3: Multi-Cluster Health Check

Scenario: Verify deployment across multiple clusters
Solution:

• Switch between clusters in WECS
• Check resource status in each
• Compare replica counts
• Verify all pods running
• Check events for issues

6. API/Integration Reference

Backend Endpoints

• GET /api/wecs/clusters - List monitored clusters
• GET /api/wecs/:cluster/resources - Get resources
• GET /api/wecs/:cluster/:namespace/:kind/:name - Get details
• GET /api/wecs/:cluster/logs - Stream logs
• GET /api/wecs/:cluster/events - Get events
• WebSocket: /ws/wecs/:cluster - Real-time updates

WebSocket Messages

• Resource created
• Resource updated
• Resource deleted
• Status changed
• Event received

7. Troubleshooting

Issue 1: WebSocket disconnects frequently

Solutions:

• Check network stability
• Verify firewall rules
• Increase timeout settings
• Check backend logs

Issue 2: Logs not streaming

Solutions:

• Verify container is running
• Check pod status
• Try different container
• Check backend connectivity

Issue 3: Resources not showing

Solutions:

• Verify cluster connected
• Check namespace permissions
• Refresh cluster data
• Reconnect WebSocket

Issue 4: Slow loading

Solutions:

• Enable auto-refresh with longer interval
• Filter by namespace
• Reduce tail lines for logs
• Check network latency

8. Related Features

• Integration with ITS (cluster list)
• Integration with BP (deployed workloads)
• Integration with Object Explorer (resource browser)

Acceptance Criteria

• All features documented
• 5+ screenshots with annotations
• 5 step-by-step guides
• 3 detailed use cases
• WebSocket connection flow explained
• Troubleshooting section complete
• API reference included
• Both dark and light mode screenshots
• Animated GIF of log streaming
• Technical review complete

📚 References

• Code: /frontend/src/pages/WECS.tsx
• Code: /frontend/src/components/wecs/
• Backend: /backend/wecs/
• E2E Tests: /frontend/e2e/WECS.spec.ts
• WebSocket implementation: /backend/routes/wecs.go

[harshakumar25]

Hello, I’m interested in working on this issue. Could you please assign it to me? Thanks!

[github-actions]

👋 Hi @harshakumar25!

To assign yourself to this issue, please use the slash command:

/assign

This will automatically assign the issue to you via our Prow bot. You can also use /unassign to remove yourself from an issue.

📚 For more information about contributing, please check out our Contributors Guide.

Thank you for your interest in contributing to KubeStellar! 🚀

[harshakumar25]

/assign