Satellite Clusters

Overview

The Satellite Clusters panel enables administrators to configure and manage connections to external Kubernetes clusters that operate as satellite deployments of the main Shakudo platform. These satellite clusters extend the platform's capabilities by allowing workloads (jobs, services, sessions) to run on geographically distributed or resource-specific infrastructure while maintaining centralized management through the main dashboard.

Satellite clusters are typically used for:

• Running workloads in different geographic regions
• Deploying to customer-owned infrastructure
• Isolating workloads with specific compliance or security requirements
• Scaling beyond the primary cluster's capacity

Access & Location

• Route: ?panel=satellite-clusters
• Navigation: Admin → Satellite Clusters
• Access Requirements: Dashboard Admin role (DASHBOARD_ADMIN_ROLE)
• Feature Flags: None

Key Capabilities

Link Satellite Clusters

Connect external Kubernetes clusters to the main Shakudo platform by providing cluster configuration details. Linked satellite clusters appear as deployment targets for jobs, services, and other workloads.

View Cluster Inventory

Browse all configured satellite clusters with key metadata including cluster name, domain, description, creation date, and the user who created the link.

Search and Filter

Search across all cluster properties (ID, name, domain, description, user ID) to quickly locate specific satellite clusters in large deployments.

Unlink Satellite Clusters

Remove satellite cluster connections from the platform. The system automatically identifies and warns about dependent resources (like git servers) that will be affected by the removal.

User Interface

Main View

The panel displays a data grid table with the following features:

• Title: "Satellite Clusters" with subtitle "Configure a connection to an existing satellite cluster"
• Create Button: "Link a Satellite Cluster" button (top-right, admin-only)
• Search Bar: Filter by any property value
• Column Controls: Toggle column visibility
• Refresh Button: Manually refresh the cluster list
• Pagination: 20 clusters per page

Table Columns

The satellite clusters table displays:

1. Action Column

   • Delete/Unlink button (trash icon) for each cluster
   • Only visible to users with admin permissions

2. ID

   • Unique cluster identifier (first 6 characters shown)
   • Click to copy full ID to clipboard
   • Width: Medium (MEDIUM_TABLE_COLUMN)

3. Name

   • Human-readable cluster name
   • Truncated with ellipsis after 30 characters
   • Click to copy full name to clipboard
   • Width: Extra Large (X_LARGE_TABLE_COLUMN)

4. Domain

   • Cluster domain/endpoint URL
   • Truncated with ellipsis after 30 characters
   • Click to copy full domain to clipboard
   • Width: Large (LARGE_TABLE_COLUMN)

5. Created By

   • Email address of the user who created the cluster link
   • Width: Medium (MEDIUM_TABLE_COLUMN)

6. Created On

   • Timestamp in format: YYYY-MM-DD HH:mm:ss
   • Width: Date column (DATE_TABLE_COLUMN)

7. Description

   • Optional cluster description
   • Truncated with ellipsis after 64 characters
   • Width: Flexible (flex: 1)

Dialogs & Modals

1. Link a Satellite Cluster Dialog

   • Purpose: Create a new satellite cluster connection
   • Trigger: Click "Link a Satellite Cluster" button
   • Fields:
     • Name (required): Alphanumeric cluster identifier
       • Must begin and end with alphanumeric characters
       • Can contain dashes, underscores, dots between characters
       • Maximum 128 characters
       • No spaces allowed
     • Description (optional): Free-text cluster description
     • Domain (required): Cluster domain name
       • Must be a valid domain format (e.g., cluster.example.io)
       • Validated against regex pattern for proper domain structure
   • Actions:
     • Cancel: Close dialog without saving
     • Create: Submit and create the cluster link
   • Validation: Real-time form validation with error messages
   • Success notification: "Created new satellite cluster '[name]'"

2. Delete Satellite Cluster Confirmation

   • Purpose: Confirm cluster unlink operation
   • Trigger: Click delete icon (trash/X) in table row
   • Content:
     • Warning message: "Are you sure you want to delete satellite cluster '[name]'?"
     • List of dependent git servers that will be deleted (if any)
   • Actions:
     • Cancel: Close dialog without deleting
     • Delete: Permanently unlink the cluster
   • Pre-deletion check: Queries for satellite git servers associated with the cluster
   • Success notification: "Deactivated satellite cluster '[name]'"

Interactive Features

• Copy to Clipboard: Click any ID, name, or domain value to copy to clipboard with success notification
• Search/Filter: Type in search bar to filter clusters by any field (ID, name, domain, description, user)
• Column Visibility: Use column selector to show/hide specific columns
• Refresh: Manual refresh button to reload cluster list from server
• Loading States: Progress indicators during data fetching and operations

Technical Details

GraphQL Operations

Queries:

• getSatelliteClusters - Retrieves paginated list of satellite clusters with optional filtering

  • Variables: $offset, $limit, $where (HyperplaneSatelliteClusterWhereInput)
  • Returns: id, name, domain, description, hyperplaneUserEmail, creationDate
  • Order: Alphabetically by name (ascending)

• getSatelliteGitServers - Retrieves git servers associated with a satellite cluster

  • Variables: $satelliteClusterName
  • Used in delete confirmation to show dependent resources
  • Fetch policy: network-only (always fresh data)

Mutations:

• createSatelliteCluster - Creates a new satellite cluster connection

  • Variables: $name (required), $domain (required), $description, $hyperplaneUserEmail
  • Returns: id, name, domain, description, hyperplaneUserEmail, creationDate

• deleteSatelliteCluster - Removes a satellite cluster connection

  • Variables: $name (required)
  • Returns: id, name
  • Note: Also deletes associated satellite git servers

Subscriptions:

• None

Component Structure

• Main Component: /components/SatelliteClusters/SatelliteClusterPanel.tsx
• Dialogs:
  • /components/SatelliteClusters/Dialogs/SatelliteClusterCreateDialog.tsx
  • /components/SatelliteClusters/Dialogs/SatelliteClusterDeleteDialog.tsx
• Hook: /hooks/useSatelliteClusters.ts
• GraphQL Schema: /graphql/hyperplaneSatelliteCluster/
• Roles: /constants/Roles/satellite-clusters.ts

State Management

• Search State: Local component state for search input filtering
• Dialog State: Local state for dialog open/close control
• User Roles: Global Jotai atom HyperplaneUserRolesAtom for permission checks
• Form State: React Hook Form for create dialog validation

Search Implementation

The search feature filters clusters using OR logic across multiple fields:

• id (contains)
• name (contains)
• domain (contains)
• description (contains)
• hyperplaneUserId (contains)

Search triggers with 300ms debounce to optimize server requests.

Permission System

All satellite cluster operations require the DASHBOARD_ADMIN_ROLE:

• Create: Admin role required (button disabled otherwise with tooltip: "Insufficient Permissions")
• Unlink/Delete: Admin role required (delete buttons hidden for non-admins)
• View: Available to all users, but only admins can navigate to the panel

Common Workflows

Linking a New Satellite Cluster

1. Navigate to Admin → Satellite Clusters
2. Click "Link a Satellite Cluster" button (admin only)
3. Enter required information:
   • Name: Unique identifier (e.g., "west-coast-cluster")
   • Domain: Cluster endpoint (e.g., "west.satellite.example.com")
   • Description: Optional notes about the cluster
4. Click "Create" to submit
5. Verify cluster appears in the table
6. Use the cluster as a deployment target in Jobs, Services, or Sessions panels

Searching for a Cluster

1. Click the search input field at the top of the table
2. Type any part of the cluster's name, domain, or description
3. Table automatically filters to matching clusters
4. Click the X icon to clear the search filter

Removing a Satellite Cluster Link

1. Locate the cluster in the table
2. Click the delete icon (trash/X) in the leftmost column
3. Review the confirmation dialog for warnings about dependent resources
4. Click "Delete" to confirm
5. Verify the cluster is removed from the table
6. Note: Associated git servers will also be deleted

Copying Cluster Information

1. Locate the cluster in the table
2. Click on any copyable field (ID, Name, Domain)
3. Receive clipboard confirmation message
4. Paste the value where needed (e.g., in configuration files or other panels)

Related Features

• Immediate Jobs - Create jobs that run on satellite clusters
• Scheduled Jobs - Schedule recurring jobs on satellite clusters
• Services - Deploy microservices to satellite clusters
• Sessions - Launch development environments on satellite clusters
• Git Repositories - Satellite git servers depend on cluster links
• Environment Configs - Satellite-specific environment configurations
• Service Accounts - Satellite service accounts for cluster authentication
• Secrets - Satellite secrets for secure credential management

Notes & Tips

Cluster Naming Conventions

• Use descriptive, location-based names (e.g., "us-west-2", "eu-central-production")
• Avoid spaces and special characters (use dashes or underscores)
• Keep names concise but meaningful for easy identification
• Consider including environment indicators (dev, staging, prod)

Domain Requirements

• Must be a fully qualified domain name (FQDN)
• Should point to the satellite cluster's API endpoint
• Ensure DNS resolution is configured before linking
• Use HTTPS/TLS-secured endpoints for production clusters

Deletion Impact

• Deleting a satellite cluster removes its connection from the platform
• All associated satellite git servers will be automatically deleted
• Existing jobs/services on the cluster may become unmanageable from the dashboard
• Consider migrating workloads before unlinking clusters

Resource Dependencies

Satellite clusters serve as the foundation for several dependent resources:

• Git Servers: Satellite-specific git repositories
• Service Accounts: Authentication credentials for cluster access
• Secrets: Encrypted configuration values scoped to the cluster
• Environment Configs: Pod specifications and resource templates
• Jobs: Workloads running on the satellite infrastructure
• Services: Long-running applications deployed to the cluster

Multi-Cluster Strategy

• Use satellite clusters to distribute workloads geographically
• Assign billing projects to specific clusters for cost tracking
• Implement cluster-level resource quotas for capacity management
• Monitor cluster health and performance independently
• Plan for cluster-level disaster recovery and failover

Troubleshooting

• If cluster linking fails, verify domain accessibility from the main platform
• Check network connectivity between main and satellite clusters
• Ensure satellite cluster has proper authentication configured
• Review error messages for domain validation failures
• Contact platform administrators for cluster configuration assistance

Security Considerations

• Only platform administrators can manage satellite cluster connections
• Satellite clusters inherit platform-wide security policies
• Use dedicated service accounts for cluster-to-cluster communication
• Regularly audit cluster access and usage patterns
• Implement network policies to restrict cross-cluster traffic as needed