Skip to main content

Persistent Volumes

Overview​

The Persistent Volumes panel provides comprehensive management of Kubernetes Persistent Volume Claims (PVCs) across all namespaces in the cluster. This feature enables administrators to view, monitor, and resize storage volumes used by applications and services running on the platform. It displays real-time storage usage metrics, identifies which pods are using each volume, and allows for dynamic volume expansion without service disruption.

Access & Location​

  • Route: ?panel=persistent-volumes
  • Navigation: Kubernetes Resources → Persistent Volumes
  • Access Requirements: dashboard-admin role
  • Feature Flags: None

Key Capabilities​

View Persistent Volume Claims​

Browse all PVCs across all namespaces with detailed information including name, namespace, size, storage class, status, and associated pods. The main view displays PVCs in a card-based layout with color-coded status indicators and key metadata at a glance.

Monitor Storage Usage​

View real-time storage usage statistics for each PVC, including total capacity, used space, available space, and usage percentage. Usage metrics are retrieved from Prometheus and displayed with visual indicators (progress bars) that change color based on utilization thresholds (green: <70%, yellow: 70-90%, red: >90%).

Resize Persistent Volumes​

Dynamically expand PVC storage capacity without downtime. The feature validates resize requests to ensure only size increases are allowed (volume shrinking is not supported by Kubernetes) and provides real-time feedback during the resize operation.

Filter PVCs by namespace or status, and search across multiple fields including PVC name, namespace, status, and storage class. Advanced sorting capabilities allow ordering by name, namespace, status, size, or creation date in ascending or descending order.

Track Pod Usage​

Identify which pods are currently using each PVC, helping with dependency analysis, cleanup decisions, and capacity planning. The interface shows a count of pods using each volume and provides detailed pod names in the details view.

User Interface​

Main View​

The main panel displays PVCs as interactive cards in a paginated list. Each card shows:

  • Avatar: Color-coded avatar with the first letter of the PVC name
  • Name: Full PVC name
  • Namespace: Namespace chip (outlined style)
  • Status: Color-coded status chip (green for Bound, yellow for Pending, red for Lost)
  • Storage Size: Allocated capacity (e.g., "10Gi")
  • Storage Class: Type of storage (e.g., "local-path", "standard")
  • Pod Count: Number of pods currently using the volume
  • Creation Date: When the PVC was created

The interface includes a comprehensive control panel with:

  • Filter Section: Dropdowns to filter by namespace and status
  • Sort Section: Dropdown to select sort field (Name, Namespace, Status, Size, Created) with toggle button for ascending/descending order
  • Search Bar: Text input with live search across name, namespace, status, and storage class
  • Action Buttons: Reset filters button (appears when filters are active) and refresh button to reload data
  • Result Counter: Shows current page results, filtered total, and grand total

Dialogs & Modals​

  1. PVC Details Dialog
    • Purpose: Display comprehensive information about a selected PVC and enable resize operations
    • Triggered by: Clicking on any PVC card in the main view
    • Sections:
      • Basic Information: Name, namespace, status, size, storage class, creation timestamp
      • Pod Usage: List of all pods currently mounting this PVC
      • Storage Usage: Real-time usage statistics from Prometheus (if available)
        • Total capacity vs. used space
        • Visual progress bar with color coding
        • Available space calculation
        • Source pod from which metrics were collected
        • Special note for local-path storage explaining that metrics reflect node filesystem usage
      • Resize PVC: Interface to expand volume capacity
    • Fields:
      • New Size: Text input accepting Kubernetes size formats (e.g., "20Gi", "500Mi", "2Ti")
      • Real-time validation to ensure new size is larger than current size
      • Helper text with format examples and validation errors
    • Actions:
      • Resize PVC: Submit button (disabled until valid size is entered)
      • Close: Dismiss dialog without changes

Tables & Data Grids​

The main view uses a card-based layout rather than a traditional table, providing:

  • Columns (displayed as card metadata):
    • Name (with avatar)
    • Namespace (chip)
    • Status (colored chip)
    • Storage Size (icon + text)
    • Storage Class (icon + text)
    • Pod Count (icon + text)
    • Created Date (icon + formatted date)
  • Actions: Click any card to open the details dialog
  • Filtering:
    • Namespace filter (dropdown with all unique namespaces)
    • Status filter (dropdown with all unique statuses)
    • Global search (searches across name, namespace, status, storage class)
  • Sorting:
    • Sort by Name, Namespace, Status, Size, or Created date
    • Toggle between ascending and descending order
    • Proper numeric sorting for sizes (converts to bytes for accurate comparison)
  • Pagination: 20 items per page with first/last/prev/next navigation

Technical Details​

API Operations​

Endpoints:

  • GET /api/pvcs/list - Retrieve all PVCs across all namespaces with pod usage information
  • POST /api/pvcs/usage - Get real-time storage usage metrics for a specific PVC from Prometheus
  • POST /api/pvcs/resize - Resize a PVC by updating its storage request

Authentication: All API endpoints require:

  • Bearer token authentication (Keycloak JWT)
  • dashboard-admin role authorization

List PVCs Operation:

  • Queries Kubernetes API for all PVCs across namespaces
  • Queries all pods to determine PVC usage relationships
  • Returns array of PVC objects with metadata and associated pod names
  • Response includes: name, namespace, size, storageClass, status, volumeName, created, usingPods, podCount

Usage Metrics Operation:

  • Accepts PVC name and namespace as parameters
  • Finds pods currently using the PVC
  • Queries Prometheus for volume statistics:
    • Primary metrics: kubelet_volume_stats_used_bytes and kubelet_volume_stats_capacity_bytes
    • Fallback metrics: container_fs_usage_bytes and container_fs_limit_bytes
  • Calculates available space and usage percentage
  • Formats bytes to human-readable units (B, Ki, Mi, Gi, Ti)
  • Returns null usage with informative message if metrics unavailable

Resize Operation:

  • Accepts PVC name, namespace, and new size
  • Reads current PVC specification from Kubernetes
  • Updates only the storage request field
  • Applies the change using Kubernetes API replace operation
  • Frontend validates size increase before allowing submission

Component Structure​

  • Main Component: components/PVCs/PVCPanel.tsx
  • Table Component: components/PVCs/PVCTable.tsx
  • Dialog Component: components/PVCs/PVCDetailsDialog.tsx
  • Hook: hooks/usePVCs.ts
  • API Routes:
    • pages/api/pvcs/list.ts
    • pages/api/pvcs/usage.ts
    • pages/api/pvcs/resize.ts
  • Utilities: utils/sizeUtils.ts (size parsing and validation)

Data Flow​

  1. Initial Load: PVCPanel mounts → usePVCs hook triggers → API call to /api/pvcs/list → Kubernetes API queries PVCs and Pods → Data processed and returned
  2. Usage Metrics: User clicks PVC card → PVCDetailsDialog opens → API call to /api/pvcs/usage → Prometheus queries → Usage data displayed
  3. Resize: User enters new size → Validation occurs → Resize button clicked → API call to /api/pvcs/resize → Kubernetes API updates PVC → Success notification → Dialog closes

State Management​

  • Local State: React hooks manage component-level state (search, filters, sorting, pagination, dialog open/close)
  • Data Fetching: Custom usePVCs hook handles API calls with loading, error, and refetch capabilities
  • Dialog State: Separate state for resize operation status, usage loading, and error messages
  • Abort Controllers: Used to prevent memory leaks by canceling in-flight requests when components unmount

Special Considerations​

  • Local-Path Storage: Special handling and user notification that usage metrics for local-path storage reflect entire node filesystem, not just the PVC
  • Size Validation: Frontend validates that new size is greater than current size using byte conversion for accurate comparison
  • Prometheus Metrics: Graceful degradation if Prometheus is unavailable or metrics not collected
  • Memory Leak Prevention: Abort controllers and mounted refs prevent state updates after component unmounts
  • Pod Status: Usage metrics only available from running pods; appropriate messaging for stopped/pending pods

Common Workflows​

View Storage Capacity Across Cluster​

  1. Navigate to Persistent Volumes panel
  2. Review the list of all PVCs with their sizes and statuses
  3. Use namespace filter to focus on specific applications
  4. Sort by size to identify largest volumes
  5. Review pod count to understand utilization

Check Storage Usage for a Specific Volume​

  1. Locate the PVC in the main list (use search if needed)
  2. Click on the PVC card to open details dialog
  3. View the Storage Usage section
  4. Check the usage percentage and visual progress bar
  5. Note available space and consider resize if needed

Expand a Volume That's Running Out of Space​

  1. Open the PVC details dialog for the target volume
  2. Review current usage in the Storage Usage section
  3. Scroll to the Resize PVC section
  4. Enter new size larger than current (e.g., if current is "10Gi", enter "20Gi")
  5. Verify that validation passes (no error shown)
  6. Click "Resize PVC" button
  7. Wait for confirmation notification
  8. Close dialog and monitor the PVC status

Identify Unused Volumes for Cleanup​

  1. Review the PVC list in the main panel
  2. Look for PVCs with pod count of 0
  3. Click on suspected unused PVCs to verify no pods listed
  4. Note: This panel provides viewing only; deletion requires other tools or kubectl

Troubleshoot Storage Issues​

  1. Search for the problematic PVC using the search bar
  2. Open details dialog to check status
  3. Review which pods are using the volume
  4. Check storage usage metrics if pod is running
  5. Verify storage class for provisioner issues
  6. Check creation timestamp for age-related issues

Filter PVCs by Namespace for Team-Specific Review​

  1. Use the namespace dropdown filter in the control panel
  2. Select the target namespace (e.g., "hyperplane-pipelines", "hyperplane-jhub")
  3. Review all PVCs in that namespace
  4. Sort by size or creation date as needed
  5. Use "Reset all filters" to return to full view
  • Job Management - Many jobs create temporary PVCs for data persistence
  • Session Management - JupyterHub sessions use PVCs for user workspaces
  • Microservices - Some microservices may mount PVCs for data storage
  • Stack Components - Database and storage components create PVCs

Notes & Tips​

General Usage​

  • Bound Status: Indicates the PVC is successfully attached to a Persistent Volume and ready for use
  • Pending Status: Usually means the provisioner is creating the volume or waiting for resources
  • Lost Status: Indicates the underlying storage has been lost or is unavailable

Resize Considerations​

  • One-Way Operation: PVCs can only be expanded, never shrunk. Plan capacity increases carefully.
  • Storage Class Support: Not all storage classes support volume expansion. Check the allowVolumeExpansion field in the StorageClass.
  • File System Expansion: After PVC resize, the pod may need to be restarted for the file system to recognize the new capacity.
  • Validation: The UI validates size increases before submission, converting sizes to bytes for accurate comparison (e.g., recognizes that "10Gi" < "10000Mi").

Storage Usage Metrics​

  • Prometheus Required: Usage statistics require Prometheus to be deployed and collecting kubelet metrics.
  • Running Pods Only: Metrics are only available when at least one pod mounting the PVC is in Running state.
  • Local-Path Note: For local-path storage, usage shows the entire node's filesystem usage, not just the PVC, since local-path uses a directory on the node rather than a dedicated volume.
  • Metric Collection Delay: Newly created PVCs may not show usage immediately; allow a few minutes for metrics to populate.

Search and Filter Tips​

  • Global Search: Searches across multiple fields simultaneously (name, namespace, status, storage class)
  • Combined Filters: Use multiple filters together (e.g., namespace + status + search) for precise results
  • Reset Filters: Click the reset button to quickly return to unfiltered view
  • Pagination: Results are paginated at 20 per page; filters reset to page 1 when changed

Performance​

  • Large Clusters: For clusters with hundreds of PVCs, initial load may take several seconds
  • Refresh Button: Use the refresh button to reload data after making changes outside the UI
  • Responsive Design: The interface adapts to mobile and tablet screens with adjusted layouts

Troubleshooting​

  • Usage Metrics Not Available: Check that Prometheus is running and that kubelet metrics are being scraped
  • Resize Fails: Verify the storage class supports volume expansion and check Kubernetes events for detailed error messages
  • Empty List: Ensure you have dashboard-admin role and that PVCs exist in the cluster
Last updated on by chyuen-devsentient