Skip to main content

Stack Components

Overview​

The Stack Components panel provides a centralized interface for managing pre-configured data tools and services in the Shakudo platform. It allows users to browse, install, activate, pause, and monitor various data infrastructure components like databases, monitoring tools, and other third-party applications that are packaged as Helm charts. Users can access component dashboards, view logs, check service URLs, and manage the lifecycle of these tools.

Access & Location​

  • Route: ?panel=stack-components (also accessible via ?panel=apps)
  • Navigation: Main Dashboard → Stack Components (or Apps)
  • Access Requirements:
    • Basic viewing: Available to all users
    • Install/Uninstall/Pause/Activate: Requires admin privileges (RBAC permissions)
    • Shakudo Core components: Cannot be modified (system-managed)
  • Feature Flags: None

Key Capabilities​

Browse Stack Components​

View all available data infrastructure components organized by status (Active/Inactive) with real-time status updates. Components display their name, logo, description, category, license type, and version information. The grid layout automatically adapts to show all components with smooth animations and transitions.

Install New Components​

Install pre-configured tools from the catalogue into your Shakudo environment. When installing, components are deployed to dedicated Kubernetes namespaces with appropriate resource configurations. Installation progress can be tracked through real-time logs.

Activate/Pause Components​

Control resource usage by pausing inactive components (scales down to 0 replicas) or activating paused components (scales back to default replica count). This helps optimize cluster resources while maintaining configuration state. Status changes are reflected immediately with visual feedback.

Pin Favorite Components​

Pin frequently-used components to keep them at the top of the Active tab for quick access. Pins are user-specific and persist across sessions, allowing each team member to customize their view.

Access Component Dashboards​

Click on active components to open their native web interfaces. Components with custom dashboard pages open in dedicated views, while others open in an embedded iframe dialog. If a component has no UI, users are notified appropriately.

Monitor Component Logs​

View real-time Kubernetes event logs for any active component to troubleshoot issues, monitor startup progress, or verify operational status. Logs auto-refresh every 2 seconds and show the most recent 20 lines of events.

View Internal Service URLs​

Access the in-cluster service URLs and port information for components, useful for connecting services together or debugging network connectivity. This dialog also displays component usage documentation and license information when available.

Search and Filter​

Quickly find components using the search bar, which filters by component name or category. Results update in real-time as you type, searching across all components in the selected tab.

User Interface​

Main View​

The main panel displays a grid of component cards organized into two tabs:

  • Active Tab: Shows components with ACTIVE, SCALING, or PAUSING status. Pinned components appear first, followed by others alphabetically.
  • Inactive Tab: Shows components with PAUSED status that can be reactivated.

Each card includes:

  • Component logo/icon
  • Component name with version badge (if applicable)
  • License type
  • Description preview (truncated to 2 lines)
  • Category tag
  • Action buttons (logs, monitoring, install/pause/activate, info)
  • Pin button (Active tab only)

The grid uses responsive layout with cards sized at minimum 300px width, automatically adjusting columns based on viewport size. Cards feature hover effects and smooth animations when filtering or status changes occur.

Dialogs & Modals​

  1. Component Dashboard Dialog

    • Purpose: View the component's web interface in an embedded iframe
    • Displays: Full-screen iframe loading the component's appUrl
    • Actions: Close dialog
    • Used when: Clicking on a component that has a web UI but no custom dashboard page

  2. Component Details Dialog

    • Purpose: View internal service information, usage documentation, and license details
    • Tabs:
      • Internal Services: Lists Kubernetes services in the component's namespace with ClusterIP and port details
      • Component Details: Displays markdown-formatted usage documentation (if available)
      • License: Shows license terms and conditions (if available)
    • Actions: Close dialog
    • Used when: Clicking the info icon on a component card

  3. Component Logs Dialog

    • Purpose: Monitor real-time Kubernetes event logs for the component
    • Displays: Scrollable text area with the last 20 lines of namespace/pod events
    • Refresh: Auto-polls every 2 seconds while open
    • Actions: Close dialog
    • Used when: Clicking the logs icon on an active component

  4. Install/Pause/Activate Confirmation

    • Purpose: Confirm lifecycle actions before execution
    • Displays: Action description and component name
    • Actions: Confirm or Cancel
    • Used when: Clicking install, pause, or activate buttons

Tables & Data Grids​

The panel uses a card-based grid layout rather than traditional tables. The grid displays stack components as individual cards with the following structure:

Active Components Grid

  • Layout: Responsive CSS grid with auto-fill columns (minimum 300px)
  • Sorting: Pinned components first, then alphabetical by name
  • Filtering: Search by name/category, real-time updates
  • Animation: Smooth transitions when cards appear/disappear

Inactive Components Grid

  • Layout: Same responsive grid layout
  • Sorting: Alphabetical by name
  • Filtering: Search by name/category
  • No pinning functionality

Technical Details​

GraphQL Operations​

Queries:

  • GetApps - Fetches all platform apps with their metadata (name, status, namespace, URLs, images, descriptions, categories, licenses). Supports optional WHERE clause filtering for search.
  • GetAppVersions - Retrieves version information for all deployed Helm applications across namespaces (returns getHelmAllAppVersions as a nested object)
  • GetPinnedApps - Fetches the current user's pinned platform apps (filtered by ACTIVE status and show=true)
  • GetNamespaceResourceServices - Gets Kubernetes service details (ClusterIP, ports) for a specific namespace and label selector
  • GetNamespaceEventLogs - Retrieves Kubernetes event logs for resources in a namespace matching a label selector (last N lines)
  • installStackComponent - Installs a stack component by name and namespace, returns installation status
  • scaleNamespaceResourcesToDefault - Scales up resources in a namespace (with label selector) to their default replica counts
  • scaleDownNamespaceResources - Scales down resources in a namespace (with label selector) to 0 replicas

Mutations:

  • PinApp - Connects a platform app to the current user's pinned apps list
  • UnpinApp - Disconnects a platform app from the current user's pinned apps list
  • installOnePlatformApp - Creates and installs a new platform app (used for catalogue installations)
  • deleteOnePlatformApp - Permanently removes a platform app by name

Subscriptions:

  • None

Component Structure​

  • Main Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsPanel.tsx
  • Grid View: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsGrid.tsx
  • Card Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsCard.tsx
  • Install/Control: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsInstall.tsx
  • Dialogs:
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsDetailsDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsLogsDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppIframeDialog.tsx
  • Pin Button: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformApps/PlatformAppsPinButton.tsx

State Management​

  • Jotai Atom: PlatformAppPageAtom - Stores currently selected platform app for detail pages
  • Apollo Client: Polling interval of 5000ms (5 seconds) for GetApps query to keep status updated
  • Local State: Component-level state for dialogs, search filters, and tab selection

Component Categories​

Components are organized by platformAppCategoryName with a special category "SHAKUDO_CORE" for system-managed infrastructure (JupyterHub, Keycloak, etc.) that cannot be modified by users.

Install Status Types​

  • ACTIVE: Component is running and accessible
  • PAUSED: Component is scaled down (0 replicas) but configuration preserved
  • SCALING: Component is currently scaling up (transitioning to ACTIVE)
  • PAUSING: Component is currently scaling down (transitioning to PAUSED)
  • CATALOGUED: Component is available for installation but not yet installed
  • ARCHIVED: Component is deprecated/archived
  • UNAVAILABLE: Component status unknown or unavailable
  • UNKNOWN: Component status cannot be determined

Common Workflows​

Installing a New Stack Component​

  1. Navigate to Stack Components panel
  2. Browse available components in the Inactive or catalogue view
  3. Click the Install icon (download arrow) on the desired component card
  4. Confirm installation in the dialog
  5. Wait for installation to complete (status changes from CATALOGUED to ACTIVE)
  6. Click the logs icon to monitor installation progress
  7. Once active, click the component card to access its dashboard

Pausing an Active Component​

  1. Locate the active component in the Active tab
  2. Click the Pause icon (pause symbol) in the component card footer
  3. Confirm the pause action in the dialog
  4. Component status changes to PAUSING, then PAUSED
  5. Component moves to the Inactive tab
  6. Resources are scaled down to save cluster capacity

Reactivating a Paused Component​

  1. Switch to the Inactive tab
  2. Locate the paused component
  3. Click the Activate icon (play arrow) in the component card footer
  4. Confirm the activation
  5. Component status changes to SCALING, then ACTIVE
  6. Component moves back to the Active tab
  7. Click the component card to verify it's accessible

Pinning Frequently-Used Components​

  1. Hover over an active component card
  2. Click the pin icon in the top-right corner
  3. Component immediately moves to the top of the Active tab
  4. Pin state persists across browser sessions
  5. Click the pin icon again to unpin

Viewing Component Service URLs​

  1. Click the info icon (i) on any component card
  2. View the "Internal Services" tab showing Kubernetes service details
  3. Copy ClusterIP and port information for connecting other services
  4. Switch to "Component Details" tab for usage documentation (if available)
  5. Check "License" tab for license terms (if available)

Troubleshooting Component Issues​

  1. Click the logs icon (radio waves) on the component card
  2. Review real-time Kubernetes event logs in the dialog
  3. Logs auto-refresh every 2 seconds
  4. Look for error messages, pod crashes, or resource issues
  5. Click info icon to check service URLs and verify network connectivity
  6. If needed, pause and reactivate the component to force a restart
  • Sessions - User development environments that may connect to stack components
  • Jobs - Data pipeline jobs that may use stack components as data sources
  • Services - Custom services that may integrate with stack components
  • Apps Catalogue - Browse and install additional stack components

Notes & Tips​

Best Practices​

  • Pin your most frequently-used components (databases, monitoring tools) for quick access
  • Pause components you're not actively using to save cluster resources
  • Check component logs immediately after installation to verify successful deployment
  • Use the search bar to quickly locate components in large installations
  • Review component details dialog for usage instructions and connection information

Important Limitations​

  • Shakudo Core components (marked with "SHAKUDO_CORE" category) cannot be paused, activated, or uninstalled as they are essential system services
  • Only users with admin privileges can install, uninstall, pause, or activate components
  • Components in SCALING or PAUSING status cannot have actions performed on them until the transition completes
  • Some components may not have web dashboards - check the info dialog for service URLs instead

Performance Considerations​

  • The panel polls for updates every 5 seconds to show real-time status changes
  • Log dialogs poll every 2 seconds while open - close them when not needed to reduce load
  • Pinned components are stored per-user and require an additional GraphQL query
  • Component version information is fetched once at panel load for all namespaces

Troubleshooting Common Issues​

  • "Component has no dashboard" message: Not all components provide web UIs - use the info dialog to find service URLs instead
  • Pin button disabled with error icon: Failed to load user pin preferences - refresh the page
  • Component stuck in SCALING status: Check logs for errors, may need manual intervention
  • Search not finding components: Ensure component names or categories match your search terms
  • Version information missing: Not all components report versions, especially custom deployments

Version Information Display​

  • Single version: Shows as a small badge next to component name
  • Multiple versions: Shows "View versions" chip that expands to list all detected versions
  • Version detection: Attempts to match based on URL, app name, or explicit release name
  • Shakudo Core components: Do not display version badges
Last updated on by chyuen-devsentient