Basic Examples#

This directory contains basic usage examples to get you started with the HSM Secrets Operator.

Examples Overview#

pico-hsm-device.yaml - HSM device discovery configuration
database-secret.yaml - Database credentials management
tls-certificate.yaml - TLS certificate storage
api-keys.yaml - Third-party API key management

Getting Started#

Step 1: Configure HSM Device#

First, create an HSMDevice resource to discover and configure your Pico HSM:

kubectl apply -f pico-hsm-device.yaml

Check the device status:

kubectl get hsmdevice pico-hsm -o yaml
kubectl describe hsmdevice pico-hsm

Step 2: Create Your First Secret#

Option A: Using kubectl-hsm plugin (recommended for interactive use):

kubectl hsm create database-credentials \
  --from-literal=database_url="postgresql://user:pass@db:5432/mydb" \
  --from-literal=username="dbuser" \
  --from-literal=password="secret123"

Option B: Using CRD resources (recommended for GitOps):

kubectl apply -f database-secret.yaml

Verify the secret was created:

# Using kubectl-hsm
kubectl hsm get database-credentials
kubectl hsm list

# Using standard kubectl
kubectl get hsmsecret database-credentials
kubectl get secret database-credentials

Step 3: Use the Secret in Your Application#

The operator automatically creates a Kubernetes Secret that your applications can use:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  template:
    spec:
      containers:
      - name: app
        image: myapp:latest
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: database-credentials
              key: database_url
        - name: DB_USERNAME
          valueFrom:
            secretKeyRef:
              name: database-credentials
              key: username

Key Concepts#

HSMDevice#

Represents a physical HSM device and handles:

USB device discovery
PKCS#11 library configuration
Device health monitoring

HSMSecret#

Represents a secret stored on the HSM and manages:

Sync from HSM to Kubernetes Secrets
Data integrity with checksums
Automatic updates when HSM data changes

Sync Process#

HSMSecret reads data from HSM using PKCS#11
Creates/updates corresponding Kubernetes Secret
Monitors for changes and keeps both in sync
Provides status and health information

Common Patterns#

Environment-Specific Secrets#

Use namespaces to separate secrets by environment:

# Production
kubectl apply -f database-secret.yaml -n production

# Staging  
kubectl apply -f database-secret.yaml -n staging

Secret Rotation#

Update secrets directly on the HSM, and they'll automatically sync:

# Option 1: Update via kubectl-hsm (writes to HSM, then syncs to K8s)
kubectl hsm create database-credentials \
  --from-literal=password="new-secret123" \
  --dry-run=false

# Option 2: Direct HSM update (via pkcs11-tool or HSM tools)
# The operator detects HSM changes and updates Kubernetes Secrets automatically

Multiple Applications#

Share the same HSM secret across multiple applications:

# App 1
apiVersion: v1
kind: Secret
metadata:
  name: app1-db-secret
data:
  url: <from-hsm-secret>

# App 2  
apiVersion: v1
kind: Secret
metadata:
  name: app2-db-secret
data:
  url: <from-hsm-secret>

Configure Feed