Skip to main content

Service Accounts

Overview​

The Service Accounts feature provides identity management for processes running in Kubernetes pods, enabling secure and manageable role-based access control (RBAC) within the Shakudo platform. This feature allows users to create service accounts for both the primary cluster and satellite clusters, ensuring proper isolation and access control for workloads and development environments.

Service accounts in Kubernetes provide an identity for processes that run in pods, allowing them to interact with the Kubernetes API and other cluster resources. In Shakudo, service accounts can be configured with default roles or custom permissions depending on the namespace and requirements.

Access & Location​

  • Route: ?panel=service-accounts
  • Navigation: Shakudo Objects → Service Accounts
  • Access Requirements:
    • View service accounts: All authenticated users can view their own service accounts
    • View all service accounts: Requires DASHBOARD_ADMIN_ROLE or DASHBOARD_MAINTAINER_ROLE
    • Deactivate service accounts: Requires DASHBOARD_ADMIN_ROLE or the service account must be owned by the user
  • Feature Flags: None

Key Capabilities​

Create Primary Cluster Service Account​

Create a service account for the primary Shakudo cluster with customizable name, namespace, and permissions. Service accounts can be configured with either default roles (in managed namespaces) or custom role definitions for specific access control needs.

Create Satellite Cluster Service Account​

Create a service account for a satellite cluster, extending the platform's capabilities to remote or distributed environments. Requires selecting a target satellite cluster in addition to the standard service account configuration.

Deactivate Service Account​

Deactivate an existing service account when it's no longer needed. This is a soft-delete operation that marks the account as inactive while preserving the record for audit purposes. Only administrators or the service account owner can perform this action.

Search and Filter​

Search across service accounts by ID, name, namespace, or user email. The search functionality helps quickly locate specific service accounts in large deployments with many accounts.

Copy Service Account Details​

Copy important service account information (ID, name, purpose) directly to clipboard for use in configurations, scripts, or documentation.

User Interface​

Main View​

The Service Accounts panel features a tabbed interface with two sections:

  1. Primary Cluster Tab: Displays service accounts for the main Shakudo cluster
  2. Satellite Clusters Tab: Displays service accounts for satellite clusters, with a cluster selector dropdown

Each tab shows a data grid with the following information:

  • Service account ID (shortened with copy-to-clipboard functionality)
  • Name (with deactivated status indicator if applicable)
  • Purpose (Workloads or Development)
  • Created By (user email)
  • Created On (timestamp)
  • Description
  • Quick deactivate action button

The panel header includes:

  • Panel title with description explaining service account purpose
  • Create button to open the creation dialog
  • Search/filter input with column visibility controls and refresh button

Dialogs & Modals​

  1. Create Service Account Dialog

    • Purpose: Create a new service account in the primary cluster
    • Fields:
      • Use Default Role (checkbox): Toggle to use predefined Shakudo managed permissions
      • Name (required): Unique identifier for the service account (alphanumeric with dashes, underscores, dots; max 128 characters)
      • Description (optional): Descriptive text explaining the service account's purpose
      • Purpose (required): Dropdown to select namespace - Workloads (hyperplane-pipelines) or Development (hyperplane-jhub)
    • Actions: Cancel or Create
    • Validation: Name must be unique within the namespace and follow naming conventions

  2. Create Satellite Service Account Dialog

    • Purpose: Create a service account for a satellite cluster
    • Fields:
      • Use Default Role (checkbox): Toggle for default permissions
      • Name (required): Service account name
      • Satellite Cluster (required): Dropdown to select target satellite cluster
      • Description (optional): Purpose description
      • Purpose (required): Namespace selection (Workloads or Development)
    • Actions: Cancel or Create
    • Validation: Same as primary cluster, plus requires valid satellite cluster selection

  3. Deactivate Service Account Confirmation

    • Purpose: Confirm deactivation of a service account
    • Prompt: "Are you sure you want to deactivate service account '{name}'?"
    • Actions: Cancel or Deactivate

Tables & Data Grids​

  1. Primary Cluster Service Accounts Table

    • Columns:
      • Empty (40px): Deactivate action button
      • ID (medium width): Service account identifier with copy functionality
      • Name (extra-large width): Account name with deactivated chip if inactive
      • Purpose (large width): Namespace display (Workloads/Development)
      • Created By (medium width): User email who created the account
      • Created On (date width): Creation timestamp
      • Description (flex): Full description text
    • Actions:
      • Row-level deactivate button (only for active accounts)
      • Copy to clipboard for ID, name, and purpose
    • Filtering: Real-time search across all visible columns
    • Sorting: Activated accounts shown first, then alphabetically by name

  2. Satellite Cluster Service Accounts Table

    • Columns: Identical to primary cluster table
    • Additional: Requires satellite cluster selection before displaying data
    • Actions: Same as primary cluster with satellite-specific deactivation logic

Technical Details​

GraphQL Operations​

Queries:

  • getHyperplaneServiceAccounts - Retrieves service accounts from the primary cluster with filtering, ordering, pagination support. Returns account details including activation status, role configuration, and metadata
  • getSatelliteServiceAccounts - Retrieves service accounts from a specified satellite cluster. Requires satellite cluster name parameter

Mutations:

  • createHyperplaneServiceAccount - Creates a new service account in the primary cluster with name, namespace, description, default role flag, and user email
  • createSatelliteServiceAccount - Creates a new service account in a satellite cluster, includes satellite cluster name parameter
  • deleteHyperplaneServiceAccount - Deactivates (soft deletes) a service account in the primary cluster by name and namespace
  • deleteSatelliteServiceAccount - Deactivates a service account in a satellite cluster

Component Structure​

  • Main Component: /components/HyperplaneServiceAccount/HyperplaneServiceAccountPanel.tsx
  • Dialogs:
    • /components/HyperplaneServiceAccount/HyperplaneServiceAccountCreate.tsx
    • /components/HyperplaneServiceAccount/HyperplaneServiceAccountDeactivate.tsx
    • /components/HyperplaneServiceAccount/satellite/SatelliteServiceAccountCreate.tsx
    • /components/HyperplaneServiceAccount/satellite/SatelliteServiceAccountDeactivate.tsx
  • Hooks:
    • /hooks/useHyperplaneServiceAccounts.ts - Primary cluster operations
    • /hooks/useSatelliteServiceAccounts.ts - Satellite cluster operations
  • Search Results: /components/Search/ServiceAccountsSearchResults.tsx

Key Implementation Details​

  • Naming Validation: Service account names must start and end with alphanumeric characters, can contain dashes, underscores, and dots, with a maximum length of 128 characters
  • Namespace Mapping: Purpose field maps to Kubernetes namespaces:
    • "Workloads" → hyperplane-pipelines (for jobs and microservices)
    • "Development" → hyperplane-jhub (for development sessions)
  • Role Configuration: Default roles are only available for Shakudo managed namespaces (Workloads and Development). Custom namespaces require manual role definition
  • Soft Delete: Deactivation sets activated flag to false and records deactivationDate rather than permanently deleting the record
  • Access Control: Non-admin users can only see and manage their own service accounts unless they have MAINTAINER or ADMIN roles

Common Workflows​

Creating a Service Account for Workloads​

  1. Navigate to Service Accounts panel (Shakudo Objects → Service Accounts)
  2. Ensure "Primary Cluster" tab is selected
  3. Click "Create Service Account" button
  4. Check "Use Default Role" (recommended for managed namespaces)
  5. Enter a descriptive name (e.g., "data-pipeline-prod")
  6. Select "Workloads" from Purpose dropdown
  7. Add optional description (e.g., "Service account for production data pipelines")
  8. Click "Create"
  9. Copy the service account name from the table for use in pipeline configurations

Creating a Service Account for Satellite Cluster​

  1. Navigate to Service Accounts panel
  2. Select "Satellite Clusters" tab
  3. Select target satellite cluster from dropdown
  4. Click "Create Satellite Service Account" button
  5. Configure service account (name, purpose, description)
  6. Verify satellite cluster selection is correct
  7. Click "Create"
  8. Note the service account details for remote cluster configuration

Deactivating an Unused Service Account​

  1. Locate the service account in the appropriate tab (Primary or Satellite)
  2. Use search if needed to find the specific account
  3. Click the deactivate icon (red X) in the leftmost column
  4. Review the service account name in the confirmation dialog
  5. Click "Deactivate" to confirm
  6. The account will be marked as deactivated and appear with a "deactivated" chip
  • Secrets - Service accounts often need associated secrets for authentication
  • Sessions - Development sessions may use service accounts for cluster access
  • Jobs - Workload jobs can be configured to run with specific service accounts
  • Microservices - Microservices use service accounts for API access and resource permissions

Notes & Tips​

  • Default Roles: Always use default roles for managed namespaces (Workloads and Development) unless you have specific RBAC requirements that aren't met by the defaults
  • Naming Convention: Use descriptive names that indicate the service account's purpose and environment (e.g., "ml-training-dev", "api-service-prod")
  • Security: Regularly audit service accounts and deactivate those that are no longer in use to maintain security hygiene
  • Satellite Clusters: Satellite cluster service accounts are managed independently and require the satellite cluster to be accessible and properly configured
  • Search Performance: For large deployments with many service accounts, use specific search terms rather than browsing to improve load times
  • Role Permissions: If you uncheck "Use Default Role", you'll need to manually configure RBAC permissions using Kubernetes role and rolebinding resources
  • Deactivation vs Deletion: Service accounts are deactivated rather than deleted to maintain audit trails. Deactivated accounts can be identified by the gray "deactivated" chip
  • Multi-user Environments: Administrators can see all service accounts across users, while regular users only see their own accounts by default
Last updated on by chyuen-devsentient