Skip to content

Secrets Management

Jump to bottom
Adrian Burlacu edited this page Feb 11, 2026 · 1 revision

Secrets Management

Stark Orchestrator provides a built-in secrets management system for securely storing and injecting sensitive data into pods. Secrets are encrypted at rest, scoped to namespaces, and injected into pods as environment variables or volume mounts.

Overview

┌──────────────────────────────────────────────────────────────────┐
│                        Secret Lifecycle                          │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│   CLI / API                                                      │
│      │                                                           │
│      ▼                                                           │
│   Validation ──► Encryption (AES-256-GCM) ──► Secret Store       │
│                                                      │           │
│                                                      ▼           │
│   Service create ──► SecretManager.resolveForPod()               │
│                           │                                      │
│                           ├──► Decrypt secret data               │
│                           ├──► Build env vars / volume mounts    │
│                           ├──► Inject into PodSecretPayload      │
│                           └──► Wipe decrypted material           │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

Secret Types

Type Required Keys Description
opaque Any Generic secret for passwords, API keys, tokens, connection strings
tls tls.crt, tls.key TLS certificate and private key pair
docker-registry server, username, password Container registry authentication credentials

Each type enforces its required keys at creation time. Additional keys can be added to any type.

Injection Modes

Secrets define how they are delivered to pods via an injection configuration.

Environment Variable Injection

Secret keys become environment variables in the pod. An optional prefix scopes the variables.

stark secret create db-creds --type opaque \
  --from-literal username=admin \
  --from-literal password=s3cret \
  --inject env --prefix DB_

Result in pod:

DB_USERNAME=admin
DB_PASSWORD=s3cret

Key mapping allows renaming keys to custom variable names:

stark secret create db-creds --type opaque \
  --from-literal username=admin \
  --inject env --key-mapping username:DATABASE_USER

Result: DATABASE_USER=admin

Volume Mount Injection

Secret keys are written as files in a directory inside the pod.

stark secret create api-cert --type tls \
  --from-file tls.crt=./cert.pem \
  --from-file tls.key=./key.pem \
  --inject volume --mount-path /etc/ssl/certs

Result in pod filesystem:

/etc/ssl/certs/tls.crt  →  (certificate content)
/etc/ssl/certs/tls.key  →  (private key content)

File mapping allows renaming files in the mount:

--file-mapping tls.crt:server.crt

Result: /etc/ssl/certs/server.crt

Mount Path Conflict Detection

When a pod references multiple secrets with volume injection, Stark validates that mount paths do not overlap. Conflicting paths are rejected before pod creation.

Encryption

At Rest

All secret data is encrypted before storage using AES-256-GCM:

Property Value
Algorithm AES-256-GCM (authenticated encryption)
Key derivation SHA-256 hash of STARK_MASTER_KEY environment variable
IV Random 12-byte nonce generated per encryption
Auth tag 16-byte GCM authentication tag for tamper detection 
# Required for production deployments
export STARK_MASTER_KEY="your-secret-master-key"

If STARK_MASTER_KEY is not set, an ephemeral random key is generated. This is acceptable for development but means secret data is lost on restart.

In Transit

Secret payloads to pods travel over the existing WSS (WebSocket Secure) transport, encrypted by TLS.

In Memory

After resolving secrets for pod injection, decrypted material is explicitly wiped from memory using the wipeSecretMaterial() utility.

Service Integration

Services reference secrets by name. At pod creation time, the SecretManager resolves all referenced secrets, decrypts them, and builds a PodSecretPayload containing environment variables and volume mounts.

stark service create my-api \
  --pack my-api --ver 1.0.0 \
  --secret db-creds \
  --secret api-cert

The resolution flow:

  1. Look up each secret name in the secret store
  2. Validate all referenced secrets exist
  3. Check for volume mount path conflicts
  4. Decrypt each secret's data
  5. Build env var bundle and volume mount list
  6. Wipe decrypted material from memory
  7. Return PodSecretPayload to the pod scheduler

Validation Rules

Rule Constraint
Name format Lowercase alphanumeric, -, .; max 253 characters
Name pattern Must match /^[a-z0-9][a-z0-9.\-]*[a-z0-9]$/
Max keys per secret 64
Max data size 1 MB (total serialized data)
Type-specific keys tls requires tls.crt + tls.key; docker-registry requires server + username + password
Namespace Must be a valid, existing namespace
Uniqueness Secret names must be unique within a namespace
Mount paths Must be absolute paths; no conflicts between secrets on the same pod

CLI Quick Reference

Command Description
stark secret create <name> Create a new secret
stark secret list List all secrets
stark secret get <name> Get secret metadata (never shows values)
stark secret update <name> Update secret data or injection config
stark secret delete <name> Delete a secret

See CLI Reference for full option documentation.

API Endpoints

Method Endpoint Description
GET /api/secrets List secrets
POST /api/secrets Create a secret
GET /api/secrets/name/:name Get secret by name
PATCH /api/secrets/name/:name Update a secret
DELETE /api/secrets/name/:name Delete a secret

See API Reference for request/response schemas.

Package Architecture

The secrets system spans three packages:

Package Module Responsibility
@stark-o/shared types/secret.ts Type definitions, constants, required-key maps
@stark-o/shared validation/secret-validation.ts Input validation and mount conflict detection
@stark-o/core services/secret-crypto.ts AES-256-GCM encryption and decryption
@stark-o/core stores/secret-store.ts Reactive secret store (Vue reactivity)
@stark-o/core models/secret.ts SecretModel wrapper with computed properties
@stark-o/core services/secret-manager.ts Central CRUD orchestration and pod injection
@stark-o/cli commands/secret.ts CLI command definitions

Security Guarantees

  • Never logged — Secret values are excluded from all logs and events
  • Never echoed — CLI never displays secret data, only metadata
  • Encrypted at rest — AES-256-GCM with authenticated encryption
  • Memory wiping — Decrypted material wiped after injection
  • Namespace isolation — Secrets scoped to namespace boundaries
  • Tamper detection — GCM auth tags detect data corruption

Related Topics

Clone this wiki locally