Skip to main content

Secrets Management

Overview​

The Secrets panel provides secure management of sensitive configuration data (credentials, API keys, tokens, etc.) that can be accessed by workloads, services, and development sessions in the Shakudo platform. Secrets are stored as Kubernetes secrets and can be scoped to specific namespaces to control where they are accessible. The feature supports both primary cluster secrets and satellite cluster secrets, with comprehensive CRUD operations and role-based access control.

Access & Location​

  • Route: ?panel=secrets
  • Navigation: Main Dashboard → Secrets Panel
  • Access Requirements:
    • View: Available to all authenticated users (can see own secrets by default)
    • Create/Edit/Delete: Role-based permissions (SecretRoles) or secret ownership
    • Admin users can view and manage all secrets
  • Feature Flags: None

Key Capabilities​

Create Secrets​

Create new secrets with key-value pairs that can be accessed by jobs, services, and sessions. Secrets can be scoped to specific purposes:

  • Workloads: Available in jobs and microservices (hyperplane-pipelines namespace)
  • Development: Available in development sessions (hyperplane-jhub namespace)
  • Development & Workloads: Available in both environments

View Secret Details​

View comprehensive information about secrets including:

  • Secret metadata (name, ID, description, creator, timestamps)
  • Key-value pairs stored in the secret
  • Environment variable names generated for each key
  • Creation and update history

Edit Secrets​

Update existing secrets by:

  • Modifying the description
  • Adding new key-value pairs
  • Updating existing key values
  • Removing keys from the secret

Delete Secrets​

Permanently remove secrets from both the Kubernetes cluster and database. This action cannot be undone and will affect any workloads currently using the secret.

Deactivate Secrets​

Temporarily deactivate secrets without permanently deleting them. Deactivated secrets remain in the database but are not accessible to workloads.

Satellite Cluster Support​

Manage secrets on satellite clusters (remote Kubernetes clusters) with the same capabilities available for the primary cluster.

User Interface​

Main View​

The panel features a tabbed interface with two main sections:

Primary Cluster Tab:

  • Data grid displaying all accessible secrets on the primary cluster
  • Columns: Actions, Name, ID, Purpose, Created By, Created On, Description
  • Search/filter functionality across all fields
  • Refresh button to reload data
  • Column visibility controls

Satellite Clusters Tab:

  • Dropdown to select a satellite cluster
  • Data grid showing secrets for the selected satellite cluster
  • Similar columns and functionality as primary cluster view

Dialogs & Modals​

  1. Create Secret Dialog (Full Screen)

    • Purpose: Create new secrets with multiple key-value pairs
    • Fields:
      • Name (required, validated for uniqueness within namespace)
      • Description (optional)
      • Purpose (required, dropdown: Workloads/Development/Both)
      • Data (key-value pairs, at least one required)
    • Features:
      • Tabbed interface (General tab and Data tab)
      • Real-time validation
      • Summary panel showing secret configuration
      • Creates secrets in multiple namespaces when "Development & Workloads" is selected

  2. Secret Details Dialog

    • Purpose: View secret metadata and key-value pairs
    • Shows:
      • Secret name and ID
      • Description
      • Creator email and creation timestamp
      • Last updated information
      • Purpose/namespace label
      • Table of keys with corresponding environment variable names
    • Actions:
      • Copy environment variable names to clipboard
      • Close dialog

  3. Edit Secret Dialog (Half Screen)

    • Purpose: Modify existing secret properties and data
    • Fields:
      • Description (editable text area)
      • Data section with table of existing keys
    • Actions:
      • Edit individual key values (opens nested dialog)
      • Add new keys (opens nested dialog)
      • Delete keys (with confirmation)
      • Save changes (updates description and/or data)
    • Features:
      • Shows creation and last update metadata
      • Validates key names for Kubernetes compatibility
      • Prevents duplicate key names

  4. Delete Secret Dialog

    • Purpose: Permanently remove a secret
    • Confirmation prompt with warning message
    • Actions: Delete or Cancel
    • Note: Only available for activated secrets

  5. Deactivate Secret Dialog

    • Purpose: Temporarily disable a secret
    • Confirmation prompt
    • Actions: Deactivate or Cancel
    • Note: Only available for activated secrets

  6. Edit Key Dialog (Nested)

    • Purpose: Update the value of a specific key
    • Fields:
      • Key name (display only)
      • Secret content (multiline text input)
    • Actions: Save or Cancel

  7. Add Key Dialog (Nested)

    • Purpose: Add a new key-value pair to an existing secret
    • Fields:
      • Key (text input, validated)
      • Content (multiline text input)
    • Actions: Save or Cancel
    • Validation: Ensures key is valid Kubernetes secret key and doesn't already exist

Tables & Data Grids​

  1. Primary Cluster Secrets Table

    • Columns:
      • Actions (Edit and Delete icons)
      • Name (clickable, opens details dialog)
      • ID (copyable, shows first 6 characters)
      • Purpose (copyable, shows label: Workloads/Development)
      • Created By (user email)
      • Created On (formatted timestamp)
      • Description (truncated with ellipsis)
    • Actions:
      • Click name to view details
      • Click edit icon to modify secret
      • Click delete icon to remove secret
    • Filtering:
      • Search across all columns (ID, name, namespace, description, user)
      • Real-time search with 300ms debounce
    • Features:
      • Row styling based on activation status
      • Sortable columns
      • Column visibility toggle
      • Pagination (20 items per page)

  2. Satellite Cluster Secrets Table

    • Similar structure to primary cluster table
    • Additional deactivation action (no delete)
    • Requires satellite cluster selection via dropdown
    • Shows "deactivated" chip for inactive secrets

Technical Details​

GraphQL Operations​

Queries:

  • getHyperplaneSecrets - Fetches list of secrets with filtering, pagination, and ordering
  • getSecretContent - Retrieves key-value pairs for a specific secret (by name and namespace)
  • GetHyperplaneSecretDocument - Gets detailed metadata for a single secret by ID
  • getSatelliteSecrets - Fetches secrets from a satellite cluster

Mutations:

  • createHyperplaneSecret - Creates a new secret with name, namespace, description, and data
  • updateHyperplaneSecret - Updates secret description and/or modifies keys (add/update/remove)
  • deleteHyperplaneSecret - Permanently removes a secret from cluster and database
  • deactivateHyperplaneSecret - Marks a secret as inactive without deleting it
  • createSatelliteSecret - Creates a secret on a satellite cluster
  • deactivateSatelliteSecret - Deactivates a secret on a satellite cluster

Subscriptions:

  • None

Component Structure​

  • Main Component: /components/HyperplaneSecret/HyperplaneSecretPanel.tsx
  • Table Component: /components/HyperplaneSecret/HyperplaneSecretTables.tsx
  • Dialogs:
    • /components/HyperplaneSecret/Dialogs/HyperplaneSecretCreateDialog.tsx
    • /components/HyperplaneSecret/Dialogs/HyperplaneSecretDetailsDialog.tsx
    • /components/HyperplaneSecret/Dialogs/HyperplaneSecretEditDialog.tsx
    • /components/HyperplaneSecret/Dialogs/HyperplaneSecretDeleteDialog.tsx
    • /components/HyperplaneSecret/Dialogs/HyperplaneSecretDeactivateDialog.tsx
  • Satellite Components: /components/HyperplaneSecret/Satellite/

State Management​

  • Uses Jotai atoms for panel-level state:
    • SecretsPanelSectionAtom - Controls which view is displayed (table/create/createSatellite)
    • SecretsTabAtom - Tracks active tab (primary cluster vs satellite)
    • selectedSatelliteClusterAtom - Stores selected satellite cluster name
    • selectedSatelliteClusterIdAtom - Stores selected satellite cluster ID

Data Transformation​

  • Secret values are Base64 encoded before storage and decoded for display
  • Key names are transformed to environment variable format: HYPERPLANE_CUSTOM_SECRET_KEY_<KEY_NAME>
  • Non-alphanumeric characters in keys are replaced with underscores and converted to uppercase
  • Kubernetes secret key validation ensures keys match pattern: ^[a-zA-Z0-9][-._a-zA-Z0-9]*[a-zA-Z0-9]$

Common Workflows​

Creating a Secret for Workloads​

  1. Click "Create Secret" button in the Primary Cluster tab
  2. Enter a unique name for the secret
  3. Add a description (optional but recommended)
  4. Select "Workloads" as the Purpose
  5. Navigate to the "Data" tab
  6. Add one or more key-value pairs (e.g., API_KEY: abc123)
  7. Review the summary panel on the right
  8. Click "Create Secret"
  9. Secret is created and available to jobs and services

Viewing Secret Details and Environment Variables​

  1. Locate the secret in the table
  2. Click on the secret name
  3. View the secret metadata and key-value pairs
  4. Copy environment variable names using the copy button
  5. Use these variable names in your code (e.g., os.environ['HYPERPLANE_CUSTOM_SECRET_KEY_API_KEY'])

Updating a Secret​

  1. Find the secret in the table
  2. Click the edit icon (pencil)
  3. Modify the description if needed
  4. To update a key value: Click the pencil icon next to the key, enter new value, save
  5. To add a key: Click "Add Data" button, enter key and value, save
  6. To remove a key: Click the trash icon next to the key, confirm deletion
  7. Click "Save" to apply all changes

Deleting a Secret​

  1. Locate the secret in the table
  2. Click the delete icon (trash can)
  3. Read the warning message carefully
  4. Click "Delete" to confirm permanent removal
  5. Secret is removed from both Kubernetes and the database

Managing Satellite Cluster Secrets​

  1. Switch to the "Satellite Clusters" tab
  2. Select a satellite cluster from the dropdown
  3. View secrets specific to that cluster
  4. Create, view, edit, or deactivate secrets as needed
  5. Note: Satellite secrets can only be deactivated, not permanently deleted
  • Jobs - Pipeline jobs can access secrets via environment variables
  • Services - Microservices can access secrets for API credentials
  • Sessions - Development sessions can access secrets in the Development namespace
  • Satellite Clusters - Remote cluster management with dedicated secret storage

Notes & Tips​

Security Best Practices​

  • Never hardcode sensitive values in your code - always use secrets
  • Use descriptive names for secrets to make them easy to identify
  • Add descriptions to document the purpose and usage of each secret
  • Regularly review and remove unused secrets
  • Only grant secret access to users who need it

Environment Variable Access​

  • In Python: os.environ['HYPERPLANE_CUSTOM_SECRET_KEY_<YOUR_KEY>']
  • In Shell scripts: $HYPERPLANE_CUSTOM_SECRET_KEY_<YOUR_KEY>
  • Key names are automatically transformed: lowercase → uppercase, special chars → underscores
  • Example: api-key-v2 becomes HYPERPLANE_CUSTOM_SECRET_KEY_API_KEY_V2

Namespace Scoping​

  • Workloads secrets are available to scheduled jobs, immediate jobs, and microservices
  • Development secrets are available in JupyterHub sessions and development environments
  • Development & Workloads creates separate secrets in both namespaces for maximum availability
  • Secrets with the same name can exist in different namespaces

Permissions and Ownership​

  • Users can always view, edit, and delete their own secrets
  • Admin roles can manage all secrets across the organization
  • Role-based access control determines who can create/edit/delete secrets
  • Secret ownership is tracked by creator email and last updater email

Key Validation​

  • Keys must start and end with alphanumeric characters
  • Keys can contain hyphens, periods, and underscores in the middle
  • Maximum key length is 253 characters
  • Duplicate keys within the same secret are not allowed

Satellite Clusters​

  • Satellite secrets are managed independently from primary cluster secrets
  • Must select a satellite cluster before viewing or creating secrets
  • Deactivation (rather than deletion) is the recommended approach for satellite secrets
  • Secrets are not automatically synchronized between primary and satellite clusters
Last updated on by chyuen-devsentient