Skip to main content

Sessions

Overview​

The Sessions feature provides a comprehensive interface for managing interactive development environments (JupyterLab, VS Code, and Shell) in the Shakudo platform. Users can create, monitor, and manage containerized sessions with customizable compute resources, storage drives, and environment configurations. Sessions are ephemeral development environments that automatically shut down after a configurable idle timeout period.

Access & Location​

  • Route: ?panel=sessions
  • Navigation: Development → Sessions
  • Access Requirements: None (basic authenticated user access)
  • Feature Flags: None

Key Capabilities​

Create New Sessions​

Launch containerized development environments with customizable configurations including environment type, idle timeout, storage drive, billing project, service accounts, secrets, Cloud SQL proxies, and custom ports. Sessions support both public (shared) and private modes.

View Active Sessions​

Monitor all currently running sessions with real-time status updates and quick access links to JupyterLab, VS Code, and Shell interfaces. Active sessions display connection status and automatically poll for server readiness.

Browse Session History​

Review past sessions with detailed information about session duration, resources used, status outcomes, and associated metadata. History can be filtered by status (cancelled, failed, done, etc.).

Clone Sessions​

Quickly duplicate existing session configurations to launch new sessions with identical settings, including environment configs, drives, service accounts, secrets, and billing projects.

Stop Running Sessions​

Terminate active sessions to free up compute resources. This action cancels the underlying pods and stops all associated services.

Restart Failed Sessions​

Relaunch sessions that have failed or completed, recreating them with the same configuration and resources.

Publish/Unpublish Sessions​

Toggle session visibility between private (owner-only) and public (all platform users) modes. Published sessions can be accessed by any authenticated platform user.

Add Ports to Active Sessions​

Dynamically open additional network ports on running sessions to expose custom services or applications.

SSH Access​

Copy SSH connection commands for direct terminal access to sessions via SSH proxy.

User Interface​

Main View​

The Sessions panel features a tabbed interface with two main views:

  1. Active Sessions Tab - Displays currently running or pending sessions with:

    • Real-time status indicators (in progress, pending)
    • Quick access buttons for JupyterLab, VS Code, and Shell
    • SSH connection command copy button
    • Session metadata (ID, drive, environment config, start time)
    • Published/private indicators

  2. History Tab - Shows completed, failed, or cancelled sessions with:

    • Session lifecycle information (start time, end time, status)
    • Historical session metadata
    • Ability to restart or clone past sessions

Both tabs support:

  • Real-time filtering by email, drive name, environment config, and billing project
  • Quick search across drive names and email addresses
  • Pagination with 20 sessions per page
  • Auto-refresh every 30 seconds
  • Column visibility customization

Dialogs & Modals​

  1. Session Create Dialog

    • Purpose: Create new development sessions with full configuration control
    • Fields:
      • General Tab:
        • Environment Config (required): Pre-configured development environment
        • Custom Image URL (optional): Override default image with custom container image
        • Idle Timeout (required): Auto-shutdown timer (presets: 15min, 30min, 1hr, 2hr, 12hr, 24hr, unlimited)
        • Drive (required): Storage volume to mount (default or custom drives)
      • Advanced Tab:
        • Cloud SQL Proxy: Enable Google Cloud SQL sidecar connection
        • External Dependencies: Attach Kubernetes secrets and service accounts
        • Billing Project: Associate session costs with specific billing project
        • Publish Session: Make session accessible to all platform users
        • Open Additional Ports: Expose custom network ports
    • Actions: Create Session, Customize YAML, View GraphQL Mutation
    • Features: Real-time session summary, YAML customization for advanced users

  2. Session Create From Spec Dialog

    • Purpose: Create sessions from custom Kubernetes pod specifications
    • Fields: YAML editor for full pod spec customization
    • Actions: Create session from YAML, validate YAML syntax
    • Features: Pre-populated with default spec, syntax highlighting

  3. Session Status Dialog

    • Purpose: View real-time status of session creation process
    • Shows: Pod events, container statuses, startup progress
    • Access: Click loading spinner on pending sessions

  4. Port Management Dialog

    • Purpose: Configure custom network ports for sessions
    • Fields: Port number, protocol (TCP/UDP), port name
    • Actions: Add/remove ports dynamically

  5. Drive Management Dialog

    • Purpose: Manage persistent storage drives
    • Access: Storage icon next to Drive field in create dialog

Tables & Data Grids​

  1. Active Sessions Table

    • Columns:
      • Actions (pinned right): Actions menu dropdown
      • Access: Quick links to JupyterLab, VS Code, Shell, SSH command
      • Session ID: Copyable unique identifier
      • Drive: Storage volume name (shows "user's default" for default drives)
      • Status: Visual status indicator with "published" chip for public sessions
      • Env Config: Environment configuration name
      • Custom Image URL (hidden by default): Custom container image
      • Email (hidden by default): Session owner email
      • Billing Project ID (hidden by default): Copyable project ID
      • Service Account ID (hidden by default): Copyable service account ID
      • Start: Session creation timestamp
      • Opened Ports (hidden by default): List of exposed ports
    • Actions:
      • Clone session
      • Add ports (active sessions only)
      • Stop session
      • Publish/unpublish session
    • Filtering: Email, environment config, drive name, billing project, quick search
    • Features: Auto-refresh, real-time status polling, link health checking

  2. History Sessions Table

    • Columns:
      • Actions (pinned right): Actions menu dropdown
      • Session ID: Copyable unique identifier
      • Env Config: Environment configuration name
      • Custom Image URL (hidden by default): Custom container image
      • Drive: Storage volume name
      • Status (hidden by default): Final session status
      • Email (hidden by default): Session owner email
      • Billing Project ID (hidden by default): Copyable project ID
      • Service Account ID (hidden by default): Copyable service account ID
      • Start: Session creation timestamp
      • End: Session completion/termination timestamp
      • Opened Ports (hidden by default): List of exposed ports
    • Actions:
      • Clone session
      • Restart session (failed/done sessions only)
    • Filtering: Email, status (cancelling, cancelled, failed, failing), environment config, drive name, billing project, quick search
    • Features: Auto-refresh, historical records

Technical Details​

GraphQL Operations​

Queries:

  • getSessions - Retrieves paginated list of sessions with filtering support (email, status, imageType, driveName, billingProjectId, quickSearch). Supports both active and historical queries via status filters. Returns session metadata including URLs, resource limits, costs, and pod specs.
  • countSessions - Returns total count of sessions matching filter criteria for pagination
  • getSessionById - Fetches detailed information for a specific session by ID
  • getHyperhubSessionPodSpec - Generates Kubernetes pod specification JSON for session creation
  • getSessionResourceLimits - Retrieves resource quota information for sessions

Mutations:

  • createOneHyperHubSession - Creates a new session with specified configuration (imageType, timeout, drive, billing project, service account, secrets, Cloud SQL proxy, visibility, ports)
  • cancelSession - Terminates a running session by ID
  • restartHyperhubSession - Relaunches a failed or completed session by ID
  • toggleSessionVisibility - Switches session between public and private modes
  • updateOneHyperHubSession - Updates session properties (primarily used for publishing/unpublishing)

Subscriptions:

  • None (uses polling for real-time updates)

Component Structure​

  • Main Component: components/Sessions/SessionsPanel.tsx
  • Table: components/Sessions/SessionsTable.tsx
  • Toolbar: components/Sessions/SessionsTableToolbar.tsx
  • Create Dialog: components/Sessions/Dialog/SessionCreateDialog.tsx
  • Create From Spec: components/Sessions/Dialog/SessionCreateFromSpecDialog.tsx
  • Actions Menu: components/Sessions/SessionsActionsMenu.tsx
  • Session URLs: components/Sessions/SessionUrls.tsx
  • Menu Items:
    • components/Sessions/CloneSessionMenuItem.tsx
    • components/Sessions/RestartSessionMenuItem.tsx
    • components/Sessions/TogglePublishSessionMenuItem.tsx
    • components/Sessions/Dialog/StopSessionMenuItem.tsx
  • Ports: components/Sessions/Ports/PortManagementDialog.tsx, components/Sessions/Ports/SessionAddPortsDialog.tsx

State Management​

  • Uses Jotai atoms for global state:
    • SessionsPanelSectionAtom: Controls view mode (table, create, clone)
    • SessionIdToShowAtom: Tracks selected session ID
    • PastSessionsFiltersAtom: Stores history tab filters
    • CurrentSessionsFiltersAtom: Stores active tab filters
    • SessionsCloneDefaultValuesAtom: Holds default values for cloning
    • SessionsTableTabAtom: Tracks active tab index (0=Active, 1=History)
  • Uses React Context for:
    • SessionLinks: Manages embedded/opened session URLs
    • SessionsFrameContext: Controls session iframe display state
    • HyperplaneUserContext: Current user information
    • PodSpecsContext: Available environment configurations
    • KeycloakRBACContext: Permission checking

URL Generation​

Sessions support three access methods with automatic URL generation:

  1. JupyterLab: <protocol>://<domain>/<hash>/jupyter/lab?token=hyperhub
  2. VS Code: <protocol>://<domain>/<hash>/code/
  3. Shell: <protocol>://<domain>/<hash>/bash/

URLs are derived from the legacy jLabUrl field and converted using getNewJLabAndCodeServerUrlFromOldJLabUrl().

Common Workflows​

Creating a Basic Session​

  1. Click "Create Session" button in the Sessions panel
  2. Select an Environment Config (e.g., "basic-ai-tools", "python-data-science")
  3. Choose Idle Timeout (default: 15 minutes)
  4. Select storage Drive (defaults to user's default drive)
  5. Click "Create Session" button
  6. Wait for session to start (status changes from "pending" to "in progress")
  7. Access via JupyterLab, VS Code, or Shell icons when ready

Creating a Session with Advanced Options​

  1. Click "Create Session" button
  2. Configure general settings (environment, timeout, drive)
  3. Click "Advanced" button or switch to Advanced tab
  4. Enable Cloud SQL Proxy if needed and select proxy
  5. Attach any required Kubernetes secrets
  6. Select service account for cloud provider authentication
  7. Assign to billing project for cost tracking
  8. Enable "Publish" to make session accessible to all users
  9. Add custom ports if exposing additional services
  10. Review Session Summary panel
  11. Click "Create Session"

Cloning an Existing Session​

  1. Locate the session to clone in Active or History tab
  2. Click "Actions" dropdown on the session row
  3. Select "Clone" from the menu
  4. Review and modify pre-populated configuration
  5. Click "Create Session" to launch the clone
  6. New session inherits all settings from original (environment, drive, service account, secrets, ports, billing project)

Stopping a Running Session​

  1. Find active session in Active Sessions tab
  2. Click "Actions" dropdown
  3. Select "Stop Session"
  4. Session status changes to "cancelling" then "cancelled"
  5. Resources are freed and session appears in History tab

Restarting a Failed Session​

  1. Navigate to History tab
  2. Find failed/completed session
  3. Click "Actions" dropdown
  4. Select "Restart"
  5. Session is recreated with identical configuration
  6. New session appears in Active tab

Publishing a Session for Team Access​

  1. Locate session in Active Sessions tab
  2. Click "Actions" dropdown
  3. Select "Publish Session" (or "Unpublish" to revert)
  4. Session displays "published" chip next to status
  5. All platform users can now access this session's interfaces

Adding Ports to Running Session​

  1. Find running session in Active Sessions tab
  2. Click "Actions" dropdown
  3. Select "Add Ports"
  4. In Port Management dialog, specify:
    • Port number (e.g., 8080)
    • Protocol (TCP/UDP)
    • Port name (optional label)
  5. Click Save
  6. Port becomes accessible on session

Accessing Session via SSH​

  1. Find running session in Active Sessions tab
  2. Locate SSH terminal icon in Access column
  3. Click icon to copy SSH connection command
  4. Paste command in local terminal
  5. Authenticate via SSH proxy to access session shell

Notes & Tips​

Session Lifecycle​

  • Sessions automatically stop after the configured idle timeout period
  • Idle timeout is calculated from last user activity (keyboard/mouse input)
  • Timeout options: 15min, 30min, 1hr, 2hr, 12hr, 24hr, unlimited (-1)
  • Default timeout is 15 minutes (900 seconds)
  • Sessions in "pending" status are starting up and not yet ready
  • Sessions in "in progress" status are fully running and accessible
  • Failed sessions can be restarted to retry with same configuration

Resource Management​

  • Each session consumes compute resources (CPU, RAM, GPU if configured)
  • Sessions count against user or team resource quotas
  • Stopping unused sessions frees resources for other workloads
  • Default drives are automatically created per user if not exists
  • Custom drives can be shared across multiple sessions
  • Drive selection determines which files/folders are accessible in session

Access Patterns​

  • JupyterLab provides notebook interface and file browser
  • VS Code provides full IDE with extensions and terminal
  • Shell provides direct terminal access via browser
  • All three interfaces share the same filesystem (mounted drive)
  • Sessions auto-detect when servers are ready and enable access buttons
  • Server readiness is polled every 5 seconds during startup
  • Published sessions bypass permission checks for access URLs

Filtering & Search​

  • Quick search supports partial matches on email and drive name (case-insensitive)
  • Multiple filters can be combined (AND logic)
  • Email filter is automatically applied based on user roles
  • Users without admin role only see their own sessions by default
  • Filter state persists in URL query parameters for sharing/bookmarking
  • Active and History tabs maintain independent filter states

GraphQL Mutation Visibility​

  • "GraphQL Mutation" button shows the exact API call for session creation
  • Useful for debugging, API integration, or automation scripts
  • Mutation updates in real-time as form fields change
  • Can be copied and executed in GraphQL Playground (/graphql endpoint)

YAML Customization​

  • "Customize YAML" allows direct editing of Kubernetes pod specification
  • Advanced users can modify resource requests, node selectors, environment variables
  • YAML editor includes syntax highlighting and validation
  • Changes override form-based configuration
  • Useful for special pod configurations not exposed in UI

Public Sessions​

  • Published sessions are accessible by all authenticated platform users
  • Owner retains full control (stop, restart, publish/unpublish)
  • Public sessions show "published" chip in status column
  • Use for shared demonstrations, tutorials, or collaborative work
  • Consider resource usage when publishing long-running sessions

Clone vs Restart​

  • Clone: Creates new session with copied configuration, allows modifications before launch
  • Restart: Immediately recreates session with exact same configuration
  • Clone is available for all sessions (active and historical)
  • Restart is only available for completed/failed sessions
  • Both preserve environment config, drive, service account, secrets, billing project, and ports

Performance​

  • Tables auto-refresh every 30 seconds to show latest session states
  • Active sessions poll for server readiness independently
  • Pagination limits to 20 sessions per page for performance
  • Column visibility can be customized to reduce table width
  • Actions column is pinned to right for consistent access
Last updated on by chyuen-devsentient