Skip to main content

Environment Configs

Overview​

The Environment Configs panel is the central management hub for creating and managing environment configurations (also called "Pod Specs") in the Shakudo Dashboard. Environment Configs define the computational resources, container images, and runtime settings that can be used when launching sessions, running jobs, or deploying microservices. This feature allows platform administrators and users to create reusable, standardized environment templates with specific CPU, memory, GPU allocations, Docker images, and advanced Kubernetes configurations.

Environment Configs serve as templates that ensure consistency across workloads while providing flexibility for different computational requirements. They can be configured for both the main Shakudo cluster and satellite clusters.

Access & Location​

  • Route: ?panel=environment-configs
  • Navigation: Platform Management → Environment Configs
  • Access Requirements:
    • View: Available to all authenticated users
    • Create/Edit/Delete: Requires specific roles (configured via EnvironmentConfigRoles)
  • Feature Flags: None

Key Capabilities​

Create Environment Configurations​

Define new environment templates with customized resource allocations, Docker images, and Kubernetes settings. Users can specify CPU/memory limits and requests, GPU resources, node selectors, environment variables, volumes, tolerations, and custom Kubernetes spec fields. Configurations can include a README for documentation purposes.

Edit Existing Configurations​

Modify environment configurations to update resource limits, change Docker images, or adjust Kubernetes settings. When an environment config is updated, new jobs and sessions will use the updated version, while in-progress jobs and sessions continue using the old version. Services using the updated config are automatically restarted.

Clone Configurations​

Duplicate existing environment configs to quickly create variations with similar settings. This accelerates the creation of new configs by starting with a proven template.

View Configuration Details​

Inspect complete environment config specifications including all resource settings, environment variables, custom fields, volumes, tolerations, and node selectors. The details view provides links to view all sessions, jobs, and services using the configuration.

Delete Configurations​

Remove environment configs that are no longer needed. This action is permanent and cannot be reversed. Shakudo default environment configs cannot be deleted.

Satellite Cluster Management​

Create and manage environment configs specifically for satellite clusters, enabling distributed workload execution across multiple Kubernetes clusters.

User Interface​

Main View​

The Environment Configs panel features a tabbed interface with two primary views:

Table View: Displays all environment configs in a searchable data grid with the following columns:

  • Actions column (clone, edit, delete)
  • Name (clickable to view details)
  • Owner (shows creator email or Shakudo logo for defaults)
  • Display Name
  • Image (Docker image URL with copy functionality)
  • CPU Limit and Request
  • Memory Limit and Request
  • GPU (type and count)
  • Node Selector (key-value pairs)
  • ID (hidden by default)

Satellite Cluster View: Similar table specifically for managing environment configs on satellite clusters. Requires selecting a satellite cluster from a dropdown before viewing or creating configs.

The table supports:

  • Full-text search across all properties
  • Column visibility customization
  • Refresh functionality
  • Pagination (20 items per page)
  • Visual indicators for configs with custom fields

Dialogs & Modals​

  1. Create Environment Config Dialog

    • Purpose: Create new environment configurations from scratch
    • Tabs: General, Resources, Advanced, Readme
    • Fields:
      • General Tab: Name, Internal Name (auto-generated, Kubernetes-compliant), Description, Image URL
      • Resources Tab: CPU Request/Limit, Memory Request/Limit, GPU Type, GPU Count
      • Advanced Tab: Volumes (YAML), Volume Mounts (YAML), Tolerations (YAML), Node Selector Key/Value, Environment Variables (key-value pairs), Custom Fields (spec path overrides)
      • Readme Tab: Markdown editor for documentation
    • Actions: Create Environment Config, Cancel, View Equivalent GraphQL Mutation
    • Features: Real-time validation, auto-generation of internal names, live summary preview

  2. Edit Environment Config Dialog

    • Purpose: Modify existing environment configurations
    • Fields: Same as Create dialog, but Internal Name is disabled (immutable)
    • Actions: Save Changes, Cancel, View Equivalent GraphQL Mutation
    • Features: Confirmation dialog explaining impact of changes (can be disabled), dirty state detection
    • Note: Displays warning when changes will restart services using this config

  3. Environment Config Details Dialog

    • Purpose: View comprehensive information about a specific environment config
    • Sections:
      • Summary panel with all resource specifications
      • Environment Variables table
      • Custom Fields list
      • Volumes, Volume Mounts, and Tolerations viewers
      • README.md display
      • Quick navigation buttons to view associated Sessions, Jobs, and Services
    • Actions: Back, View Equivalent GraphQL Mutation

  4. Delete Confirmation Dialog

    • Purpose: Confirm permanent deletion of an environment config
    • Fields: Warning message with config name
    • Actions: Delete, Cancel
    • Warning: Action is irreversible

  5. Custom Field Add/Edit Dialog

    • Purpose: Add or edit custom Kubernetes spec field overrides
    • Fields:
      • Path (autocomplete with examples like spec.nodeSelector, spec.tolerations)
      • Value (YAML editor with syntax highlighting)
    • Actions: Save, Cancel
    • Features: Path validation (must start with "spec."), backend validation of path and value, example field suggestions
    • Note: Can be opened in view-only mode from details view

  6. Custom Field Container

    • Purpose: Display individual custom field entries
    • Shows: Field path with edit and delete actions
    • Features: Inline editing and removal

Tables & Data Grids​

  1. Environment Configs Table

    • Columns: Actions, Name, Owner, Display Name, Image, CPU Limit, CPU Request, Memory Limit, Memory Request, GPU, Node Selector, ID
    • Actions: Clone (opens Create dialog with pre-filled values), Edit, Delete
    • Filtering: Real-time search across all columns
    • Special Features:
      • Visual indicator (info icon) for configs with custom fields
      • Shakudo logo icon for default system configs
      • Copy-to-clipboard for Image URL, Node Selector, and ID
      • Clickable names open details dialog
    • Pagination: 20 items per page

  2. Satellite Environment Configs Table

    • Columns: Same as main table
    • Context: Requires satellite cluster selection
    • Actions: Same as main table but operations apply to selected satellite cluster
    • Note: Independent from main cluster configs

Technical Details​

GraphQL Operations​

Queries:

  • getEnvironmentConfigs - Retrieves all environment configs with optional search filtering across multiple fields (name, description, owner, resources, image, etc.)
  • GetPodSpecNameDocument - Validates that a proposed environment config name is available
  • validatePathAndValue - Validates custom field path and YAML value before saving
  • GetSatelliteEnvironmentConfigsDocument - Retrieves environment configs for a specific satellite cluster

Mutations:

  • createEnvironmentConfig - Creates a new environment configuration with all specified parameters including custom fields
  • updateEnvironmentConfig - Updates an existing environment config, triggering service restarts if applicable
  • deleteEnvironmentConfig - Permanently deletes an environment configuration by ID
  • createSatelliteEnvironmentConfig - Creates environment config on a satellite cluster
  • updateSatelliteEnvironmentConfig - Updates satellite cluster environment config
  • deleteSatelliteEnvironmentConfig - Deletes satellite cluster environment config

Subscriptions:

  • None

Component Structure​

  • Main Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/EnvironmentConfigPanel.tsx
  • Table Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/EnvironmentConfigTables.tsx
  • Dialogs:
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigCreateDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigEditDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigDetailsDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigDeleteDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigCustomFieldAddOrEditDialog.tsx
    • /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/EnvironmentConfigs/Dialogs/EnvironmentConfigCustomFieldContainer.tsx
  • State Management: Jotai atoms for panel navigation and data sharing

Resource Validation​

The feature includes comprehensive validation for Kubernetes resource specifications:

CPU Resources:

  • Accepts numeric values or millicores (e.g., "2", "2000m")
  • Valid units: 'm' (millicores)
  • Validates that values are positive and within safe integer bounds

Memory Resources:

  • Accepts binary units: Ki, Mi, Gi, Ti, Pi, Ei (power of 1024)
  • Accepts decimal units: k, M, G, T, P, E (power of 1000)
  • Validates that values are positive and within safe integer bounds
  • Example: "2Gi", "2048Mi", "2000000k"

GPU Resources:

  • Numeric values only (count of GPUs)
  • Supported types: nvidia.com/gpu, nvidia.com/mig-* (MIG types currently disabled)

Internal Name Validation:

  • Must be 1-63 characters
  • Lowercase alphanumeric with dashes and dots
  • Must start and end with alphanumeric character
  • No spaces allowed
  • Must be unique across all environment configs
  • Real-time availability checking

Common Workflows​

Creating a Basic Environment Config​

  1. Navigate to Environment Configs panel
  2. Click "Create Environment Config" button
  3. Fill in General tab:
    • Enter Name (e.g., "Python ML Environment")
    • Verify auto-generated Internal Name or customize
    • Add Description
    • Specify Image URL (Docker container)
  4. Configure Resources tab:
    • Set CPU Request and Limit (e.g., "2", "4")
    • Set Memory Request and Limit (e.g., "4Gi", "8Gi")
    • Optionally configure GPU if needed
  5. (Optional) Configure Advanced settings:
    • Add environment variables
    • Configure volumes, mounts, tolerations
    • Set node selectors for specific hardware
  6. (Optional) Add README documentation in Markdown
  7. Review summary panel on the right
  8. Click "Create Environment Config"

Cloning and Customizing an Existing Config​

  1. Find the environment config you want to clone in the table
  2. Click the Clone icon in the Actions column
  3. Create dialog opens with all fields pre-populated
  4. Modify the Name and Internal Name (required - must be unique)
  5. Adjust any other settings as needed (resources, image, etc.)
  6. Click "Create Environment Config"

Editing Resource Limits for Existing Config​

  1. Locate the environment config in the table
  2. Click the Edit icon in the Actions column
  3. Navigate to the Resources tab
  4. Update CPU and/or Memory limits and requests
  5. Review changes in the summary panel
  6. Click "Save Changes"
  7. Confirm in the dialog (explains that services will restart)
  8. Changes are applied to new sessions/jobs immediately; services restart automatically

Adding Custom Kubernetes Spec Fields​

  1. Open Environment Config in Edit or Create mode
  2. Navigate to Advanced tab
  3. Scroll to "Custom Fields" section
  4. Click the Add button
  5. In the Custom Field dialog:
    • Enter or select a spec path (e.g., "spec.nodeSelector")
    • Enter the YAML value in the editor
    • Use provided examples for common patterns
  6. Click Save to validate and add the field
  7. Repeat for additional custom fields
  8. Save the environment config

Viewing Environment Config Usage​

  1. Click on any environment config name in the table
  2. Details dialog opens showing full configuration
  3. Scroll to the bottom of the right panel
  4. Click "View Sessions", "View Jobs", or "View Services"
  5. Navigates to respective panel with pre-filtered results showing only items using this config
  • Sessions Panel: Uses environment configs to determine session resources and container images
  • Jobs Panel: Immediate and scheduled jobs select environment configs for execution environment
  • Services Panel: Microservices use environment configs for deployment specifications
  • Satellite Clusters: Manages distributed environment configs across multiple Kubernetes clusters

Notes & Tips​

Best Practices​

  • Naming Convention: Use descriptive names that indicate the purpose and resource level (e.g., "python-ml-gpu-large", "spark-processing-xlarge")
  • Documentation: Always fill in the README tab to explain the intended use case, pre-installed packages, and any special configurations
  • Resource Requests vs Limits: Set requests to guaranteed minimum resources and limits to prevent resource overconsumption
  • GPU Configurations: Ensure node selectors and tolerations are properly configured to schedule on GPU-enabled nodes
  • Testing: Clone production configs for testing changes before modifying the original
  • Version Control: Use descriptive names with version indicators when creating multiple variations (e.g., "python-ml-v2")

Important Considerations​

  • Immutability: The Internal Name (Kubernetes object name) cannot be changed after creation
  • Shakudo Defaults: System-provided environment configs (marked with Shakudo logo) cannot be edited or deleted
  • Service Restarts: Editing an environment config automatically restarts all services using it, causing brief downtime
  • Custom Fields: Custom fields override existing spec values and can create or update nested Kubernetes fields - use with caution
  • Resource Availability: Ensure cluster has available resources matching your config specifications
  • Image Accessibility: Verify Docker images are accessible from the cluster (check registry credentials if using private images)
  • Validation: Backend validates custom field paths and values - ensure YAML syntax is correct
  • Satellite Clusters: Satellite environment configs are completely separate from main cluster configs

Troubleshooting​

  • "Environment Config name is already used": Choose a different Internal Name - this field must be globally unique
  • "Please enter a valid CPU unit": Use numeric values or millicores (e.g., "2" or "2000m")
  • "Please enter a valid memory unit": Use Kubernetes memory units (e.g., "4Gi", "4096Mi")
  • Custom field validation errors: Ensure path starts with "spec." and YAML value is valid
  • "Insufficient Permissions": Contact administrator for Environment Config creation/edit roles
  • Services not using updated config: Services automatically restart, but check service panel for any errors during restart
  • GPU scheduling failures: Verify node selectors, tolerations, and GPU resource types match cluster configuration

Advanced Features​

  • Equivalent GraphQL Mutation: Every create/edit dialog provides a "View Equivalent GraphQL Mutation" button to see the exact API call being made - useful for automation and scripting
  • Environment Variables: Support key-value pairs that are injected as environment variables into pods
  • Custom Fields: Advanced feature allowing direct Kubernetes spec field overrides using path notation (e.g., spec.containers[0].securityContext.runAsUser)
  • Tutorial Video: Click the tutorial icon next to "Environment Configs" title to watch usage guide
  • Markdown README: Supports full Markdown syntax including code blocks, links, and formatting for comprehensive documentation
Last updated on by chyuen-devsentient