Skip to main content

Microservices (Services Panel)

Overview​

The Services panel provides comprehensive management capabilities for deploying and maintaining long-running microservices on the Shakudo platform. This feature enables users to deploy containerized applications with custom endpoints, configure autoscaling, set up health monitoring, and manage the complete lifecycle of production-ready services. Microservices differ from regular pipeline jobs by running continuously with exposed network ports, horizontal pod autoscaling, and dedicated endpoints for external access.

Access & Location​

  • Route: ?panel=services
  • Navigation: Workloads → Microservices
  • Access Requirements: None (basic user access)
  • Feature Flags: None

Key Capabilities​

Create Microservices​

Deploy new long-running services with customizable configurations including environment settings, Git integration, networking options, and resource scaling. Services can be created from scratch, cloned from existing services, or deployed from custom pod specifications.

Manage Service Lifecycle​

Control running microservices with operations including:

  • Start/stop services (scaling to 0 replicas)
  • Restart services to apply configuration changes
  • Scale services manually or configure horizontal pod autoscaling
  • Monitor service health and replica status
  • View real-time logs and Kubernetes events

Configure Service Networking​

Set up external access through:

  • Custom subdomains for public access (e.g., myservice.dev.hyperplane.dev)
  • Subpath routing under the main domain
  • In-cluster service URLs for internal Kubernetes communication
  • Public webhooks with special subdomain suffixes (-webhook, -public)
  • URL rewriting and request routing options

Health Monitoring & Alerting​

Configure proactive monitoring with:

  • Automatic health checks on exposed ports
  • Configurable failure thresholds before alerting
  • Integration with alert notification targets
  • Cooldown periods between notifications
  • Grafana integration for detailed metrics

User Interface​

Main View​

The Services panel presents two tabbed views for managing microservices:

Available Tab - Displays currently running and pending microservices with:

  • Service status (healthy, not ready, off, failed)
  • Replica counts (desired vs ready replicas)
  • Scaling configuration (fixed replicas or HPA range)
  • Public endpoint URLs with copy-to-clipboard
  • In-cluster service URLs for Kubernetes access
  • Quick access to logs, events, and service details

History Tab - Shows completed, failed, or stopped microservices with:

  • Historical service records
  • Completion times and durations
  • Status reasons for failures
  • Same filtering and search capabilities as Available tab

Both views support:

  • Real-time filtering by status, name, owner, type, timeframe, and custom parameters
  • Quick search across name, endpoint, pipeline path, ID, and author
  • Pagination for large service lists
  • Column customization and sorting
  • Pin favorite services for quick access

Dialogs & Modals​

  1. Create/Edit/Clone Microservice Dialog

    • Purpose: Full-featured form for creating new services or modifying existing ones
    • Sections:
      • General Tab: Name, endpoint configuration, environment config, pipeline type (Shell/Multi-step), Git settings
      • Advanced Tab: Worker config, autoscaling, failure alerts, Cloud SQL proxies, secrets, service accounts, billing projects
      • Parameters Tab: Key-value parameters passed to the service
      • Readme Tab: Markdown documentation for the service
    • Features:
      • Subdomain/subpath configuration with availability checking
      • Environment config selection with resource specifications
      • Git repository integration (branch/commit selection)
      • Horizontal pod autoscaling (min/max replicas)
      • Health check configuration with alert targets
      • Custom pod YAML editing for advanced users
      • GraphQL mutation preview
      • Job summary panel with configuration overview

  2. Service Details Dialog

    • Purpose: Comprehensive view of a running or completed service
    • Information: Full job metadata, configuration, logs, events, metrics
    • Actions: Edit, clone, restart, scale, cancel operations

  3. Events and Logs Dialog

    • Purpose: View Kubernetes pod events and container logs
    • Features: Real-time log streaming, event history, container selection

  4. Scale Up/Down Dialog

    • Purpose: Adjust service replica counts
    • Options: Start service (scale up), stop service (scale to 0), custom replica count

  5. Service Status Dialog

    • Purpose: Show detailed service condition information
    • Details: Pod conditions, readiness status, health check results

  6. Customize Pod YAML Dialog

    • Purpose: Advanced users can directly edit the Kubernetes pod specification
    • Features: YAML editor with validation, diff view for edited services, generate from form values

Tables & Data Grids​

  1. Current Services Table (Available Tab)

    • Purpose: Display active and pending microservices
    • Columns:
      • Actions: Dropdown menu with clone, edit, restart, scale, cancel options
      • Name: Service name with pin button, start button (if off), and link to details
      • Status: Visual status indicator (healthy, not ready, off, failed with reason)
      • Scaling: Replica information (current/min/max with autoscaling indicator)
      • Logs: Quick access to events/logs dialog and Grafana dashboard
      • Endpoint: Public URL with copy button and iframe preview
      • In-cluster URL: Internal Kubernetes service URL
      • Ready Replicas: Number of healthy pods
      • Port: Exposed service port
      • ID: Unique service identifier
      • Start Time: When service was started
      • Hidden columns: Desired replicas, max replicas, env config, custom image URL, pipeline path, billing project, service account, Git branch/commit, owner, status reason
    • Actions:
      • Click name to view full details
      • Pin/unpin services for favorites
      • Start services that are scaled to 0
      • Clone existing services with same configuration
      • Edit service configuration (creates new version)
      • Restart services to apply changes
      • Scale services up/down
      • Cancel/delete services
    • Filtering:
      • Quick search across multiple fields
      • Status filter (with "off" option for stopped services)
      • Owner/user filter
      • Type/environment config filter
      • Custom parameter filters
      • Timeframe filters

  2. Past Services Table (History Tab)

    • Purpose: Display historical microservice records
    • Columns: Similar to Current Services, with additional completion time and duration
    • Filtering: Same filtering capabilities as Current Services
    • Actions: View details, clone (recreate with same config)

Technical Details​

GraphQL Operations​

Queries:

  • GetServices - Retrieves paginated list of microservices with filtering and sorting
    • Filters by status (in progress/pending for current, completed/failed for past)
    • Includes replica counts, scaling configuration, endpoints
    • Returns port, timeout=-1, activeTimeout=-1 (identifies as service vs job)
    • Supports filtering by user, group, billing project, parameters, Git details
  • GetUserServicePodSpec - Generates Kubernetes pod specification from form inputs
  • IsUserServiceUrlAvailable - Validates subdomain/subpath availability before creation
  • IsPipelineJobYamlEdited - Checks if service YAML has been manually customized
  • CountJobs - Returns total count for pagination

Mutations:

  • CreateService (createPipelineJobWithAlerting) - Creates new microservice
    • Sets timeout=-1 and activeTimeout=-1 (distinguishes from regular jobs)
    • Sets exposedPort to enable network access
    • Configures minReplicas/maxHpaRange for autoscaling
    • Supports notification targets for health alerts
    • Accepts custom pod YAML or generates from form
  • EditService (editMicroserviceWithAlerting) - Updates existing microservice
    • Can modify all service parameters
    • Returns whether service was automatically restarted
    • Changes to core config (image, YAML path) trigger restart
  • RestartService - Restarts service pods to apply configuration changes
  • CancelService - Stops and deletes the microservice
  • UpdateServiceReplicas (ScaleService) - Adjusts min/max replica counts for scaling
  • PinJob - Pins/unpins service for quick access

Subscriptions: None (uses polling via refetch for real-time updates)

Component Structure​

  • Main Component: /components/Jobs/Services/ServicesPanel.tsx
  • Service Dialog: /components/Jobs/Services/ServiceDialog.tsx
  • Tables:
    • /components/Jobs/Services/Tables/CurrentServicesTable.tsx
    • /components/Jobs/Services/Tables/PastServicesTable.tsx
  • Table Toolbar: /components/Jobs/Services/ServicesTableToolbar.tsx
  • Action Menu: /components/Jobs/Services/ServicesActionMenu.tsx (inferred)
  • Supporting Dialogs:
    • /components/Jobs/Services/ServiceCreateFromSpecDialog.tsx
    • /components/Jobs/Services/EditServiceYamlDiffModal.tsx
    • /components/Jobs/Services/ServicesStatusDialog.tsx
    • /components/Jobs/Services/ScaleUpDownDialogContainer.tsx
    • /components/Jobs/shared/EventsAndLogsDialog.tsx

State Management​

The panel uses Jotai atoms for state management:

  • ServicesPanelSectionAtom - Current view (table/create/clone/edit/details)
  • ServicesCloneDefaultValuesAtom - Values when cloning a service
  • ServiceIdToShowAtom - ID of service to display in details
  • ServicesDetailsValueAtom - Cached service details
  • CurrentServicesAtom / PastServicesAtom - Service data for each tab
  • CurrentServicesTablePageAtom / PastServicesTablePageAtom - Pagination state
  • CurrentServicesFiltersAtom / PastServicesFiltersAtom - Active filters
  • CurrentServicesDataLoadingAtom / PastServicesDataLoadingAtom - Loading state
  • ServicesTableTabAtom - Active tab (0=Available, 1=History)

Filters persist in URL query parameters for bookmarking and sharing.

Common Workflows​

Deploy a New Microservice​

  1. Navigate to Workloads → Microservices
  2. Click "Create Microservice" button
  3. General Tab:
    • Enter a unique service name (alphanumeric with dashes/dots)
    • Choose subdomain (recommended) or subpath for the endpoint
    • Select an Environment Config (resource template)
    • Choose pipeline type: Shell (single script) or Multi-step (YAML pipeline)
    • Specify the path to your startup script or YAML
    • Optionally configure Git repository, branch, and commit
  4. Advanced Tab (optional):
    • Enable/disable default command execution
    • Configure working directory
    • Enable horizontal pod autoscaling with min/max replicas
    • Set up failure alerts with notification targets
    • Configure health check thresholds and cooldown periods
    • Add Cloud SQL proxy for database connections
    • Attach secrets and service accounts
    • Select billing project for cost tracking
  5. Parameters Tab (optional):
    • Add key-value parameters accessible to your service
  6. Readme Tab (optional):
    • Add markdown documentation for the service
  7. Click "Create Microservice" to deploy
  8. Service starts automatically and endpoint becomes available when healthy

Clone and Modify an Existing Service​

  1. Find the service you want to clone in the Available or History tab
  2. Click the Actions menu (three dots) for the service
  3. Select "Clone"
  4. The create dialog opens with all values pre-filled from the original
  5. Modify any settings (name, endpoint, configuration, etc.)
  6. Click "Create Microservice" to deploy the cloned service
  7. Original service continues running unchanged

Scale a Running Service​

  1. Locate the running service in the Available tab
  2. Check current scaling in the "Scaling" column
  3. Option A - Quick Scale via Actions Menu:
    • Click Actions → "Scale Up/Down"
    • Enter new min/max replica counts
    • Click "Scale" to apply
  4. Option B - Enable Autoscaling via Edit:
    • Click Actions → "Edit"
    • Navigate to Advanced tab
    • Enable "Horizontal Pod Autoscaling"
    • Set min and max replica counts
    • Save changes (triggers restart)
  5. Monitor the "Scaling" column for replica status updates

Stop and Start a Service​

To Stop a Service:

  1. Find the running service in the Available tab
  2. Click Actions → "Scale Up/Down"
  3. Enter 0 for both min and max replicas
  4. Click "Scale"
  5. Service shows "off" status and stops consuming resources

To Start a Stopped Service:

  1. Find the stopped service (shows "off" status)
  2. Click the start icon next to the service name, OR
  3. Click Actions → "Scale Up/Down"
  4. Enter desired replica count (e.g., min=1, max=1)
  5. Click "Scale"
  6. Service starts and endpoint becomes available when healthy

Monitor Service Health and Debug Issues​

  1. Find the service in the Available tab
  2. Check the Status column for health indicators:
    • "healthy" - Service is running normally
    • "not ready" - Service starting or pods not ready
    • "off" - Service scaled to 0
    • "failed" - Service encountered errors (hover for reason)
  3. View Logs:
    • Click the logs icon in the "Logs" column
    • Select "Events" tab for Kubernetes events
    • Select "Logs" tab for container output
    • Use Grafana link for detailed metrics and dashboards
  4. View Full Details:
    • Click on the service name
    • Review complete configuration
    • Check replica status and conditions
    • View startup parameters and environment
  5. Common Issues:
    • "not ready" for extended time: Check logs for application errors
    • "failed" status: Check status reason in hidden column or details
    • 0 ready replicas: Service may be crashing, check logs
    • If issues persist, use Edit to adjust configuration or Restart to apply fixes

Configure Public Webhook Endpoints​

  1. Create new microservice or edit existing one
  2. In the General tab, configure the subdomain field:
    • For webhook: use name ending in -webhook (e.g., payment-processor-webhook)
    • For public service: use name ending in -public (e.g., api-public)
  3. This makes the endpoint accessible without authentication
  4. Complete other configuration as needed
  5. After deployment, share the public URL with external services
  6. Note: Regular subdomains and subpaths require authentication

Edit Service Configuration​

  1. Find the service to edit (can be in Available or History tab)
  2. Click Actions → "Edit"
  3. Modify desired settings in the edit dialog
  4. Review the "Customized YAML" badge if present (indicates manual YAML edits)
  5. Click "Save Changes"
  6. If configuration changes affect runtime (image, script, etc.), service automatically restarts
  7. Monitor status to confirm successful restart
  • Immediate Jobs - One-time pipeline executions without exposed ports
  • Scheduled Jobs - Recurring pipeline jobs that run on a schedule
  • Environment Configs - Define resource templates and container images for services
  • Stack Components - Pin frequently-used services for quick access
  • Git Repositories - Sync code from Git servers for service deployment
  • Billing Projects - Track costs and resource usage by project

Notes & Tips​

  • Services vs Jobs: Microservices run continuously with timeout=-1 and activeTimeout=-1, while regular jobs have finite execution times. Services expose network ports; jobs typically don't.
  • Endpoint Configuration: Prefer subdomains over subpaths for better URL structure and routing. Subdomains provide cleaner URLs and avoid path conflicts.
  • Public Endpoints: Services with subdomains ending in -webhook or -public are accessible without authentication - useful for webhooks and public APIs.
  • In-cluster URLs: Use the in-cluster URL pattern http://hyperplane-service-{id-prefix}.{namespace}.svc.cluster.local:8787 for service-to-service communication within Kubernetes.
  • Stopping Services: Scaling to 0 replicas stops the service but preserves configuration. This is useful for cost savings during periods of non-use.
  • Autoscaling: When HPA (Horizontal Pod Autoscaling) is enabled, Kubernetes automatically adjusts replicas based on CPU utilization between min and max bounds.
  • Health Checks: Default TCP liveness (30s delay) and readiness probes (10s delay) can be enabled. Advanced users can customize via the pod YAML editor.
  • Custom Pod YAML: Services with customized YAML show a badge indicator. Editing the service form with customized YAML may override manual changes - review the diff dialog before saving.
  • Pinning Services: Pin frequently-accessed services to keep them at the top of the list for quick access.
  • Default Port: Services default to port 8787, but this can be changed. Ensure your application listens on the configured port.
  • Restart After Edit: Some configuration changes (environment config, pipeline path, image) trigger automatic restart. Others require manual restart to apply.
  • Pipeline Types: Shell (BASH) runs a single startup script; Multi-step (YAML) supports complex multi-stage pipelines with dependencies.
  • Git Integration: Non-custom environment configs require Git integration. Custom images can optionally disable Git sync.
  • Status Polling: The UI automatically refreshes service status. Manual refresh button available in toolbar.
  • Filtering: Filters persist in the URL, allowing you to bookmark or share specific filtered views.
  • Grafana Integration: If configured, services automatically get Grafana dashboards for detailed metrics and logging.
Last updated on by chyuen-devsentient