A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability th
1# Basic Examples
2
3This directory contains basic usage examples to get you started with the HSM Secrets Operator.
4
5## Examples Overview
6
71. **[pico-hsm-device.yaml](pico-hsm-device.yaml)** - HSM device discovery configuration
82. **[database-secret.yaml](database-secret.yaml)** - Database credentials management
93. **[tls-certificate.yaml](tls-certificate.yaml)** - TLS certificate storage
104. **[api-keys.yaml](api-keys.yaml)** - Third-party API key management
11
12## Getting Started
13
14### Step 1: Configure HSM Device
15
16First, create an HSMDevice resource to discover and configure your Pico HSM:
17
18```bash
19kubectl apply -f pico-hsm-device.yaml
20```
21
22Check the device status:
23```bash
24kubectl get hsmdevice pico-hsm -o yaml
25kubectl describe hsmdevice pico-hsm
26```
27
28### Step 2: Create Your First Secret
29
30**Option A: Using kubectl-hsm plugin (recommended for interactive use):**
31```bash
32kubectl hsm create database-credentials \
33 --from-literal=database_url="postgresql://user:pass@db:5432/mydb" \
34 --from-literal=username="dbuser" \
35 --from-literal=password="secret123"
36```
37
38**Option B: Using CRD resources (recommended for GitOps):**
39```bash
40kubectl apply -f database-secret.yaml
41```
42
43Verify the secret was created:
44```bash
45# Using kubectl-hsm
46kubectl hsm get database-credentials
47kubectl hsm list
48
49# Using standard kubectl
50kubectl get hsmsecret database-credentials
51kubectl get secret database-credentials
52```
53
54### Step 3: Use the Secret in Your Application
55
56The operator automatically creates a Kubernetes Secret that your applications can use:
57
58```yaml
59apiVersion: apps/v1
60kind: Deployment
61metadata:
62 name: myapp
63spec:
64 template:
65 spec:
66 containers:
67 - name: app
68 image: myapp:latest
69 env:
70 - name: DATABASE_URL
71 valueFrom:
72 secretKeyRef:
73 name: database-credentials
74 key: database_url
75 - name: DB_USERNAME
76 valueFrom:
77 secretKeyRef:
78 name: database-credentials
79 key: username
80```
81
82## Key Concepts
83
84### HSMDevice
85Represents a physical HSM device and handles:
86- USB device discovery
87- PKCS#11 library configuration
88- Device health monitoring
89
90### HSMSecret
91Represents a secret stored on the HSM and manages:
92- Sync from HSM to Kubernetes Secrets
93- Data integrity with checksums
94- Automatic updates when HSM data changes
95
96### Sync Process
971. HSMSecret reads data from HSM using PKCS#11
982. Creates/updates corresponding Kubernetes Secret
993. Monitors for changes and keeps both in sync
1004. Provides status and health information
101
102## Common Patterns
103
104### Environment-Specific Secrets
105Use namespaces to separate secrets by environment:
106
107```bash
108# Production
109kubectl apply -f database-secret.yaml -n production
110
111# Staging
112kubectl apply -f database-secret.yaml -n staging
113```
114
115### Secret Rotation
116Update secrets directly on the HSM, and they'll automatically sync:
117
118```bash
119# Option 1: Update via kubectl-hsm (writes to HSM, then syncs to K8s)
120kubectl hsm create database-credentials \
121 --from-literal=password="new-secret123" \
122 --dry-run=false
123
124# Option 2: Direct HSM update (via pkcs11-tool or HSM tools)
125# The operator detects HSM changes and updates Kubernetes Secrets automatically
126```
127
128### Multiple Applications
129Share the same HSM secret across multiple applications:
130
131```yaml
132# App 1
133apiVersion: v1
134kind: Secret
135metadata:
136 name: app1-db-secret
137data:
138 url: <from-hsm-secret>
139
140# App 2
141apiVersion: v1
142kind: Secret
143metadata:
144 name: app2-db-secret
145data:
146 url: <from-hsm-secret>
147```