A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability th
1# Deployment Examples
2
3This directory contains complete deployment examples for the HSM Secrets Operator in production environments.
4
5## Files
6
7- **[complete-setup.yaml](complete-setup.yaml)** - Full production deployment with all components
8
9> **Additional Configurations:** See the [config](../../config/) directory for CRDs, RBAC, and operator deployments, or the [helm](../../helm/) directory for Helm chart deployments.
10
11## Complete Setup
12
13The `complete-setup.yaml` file demonstrates a full production deployment including:
14
15### Core Components
16- HSM Secrets Operator deployment
17- HSMDevice configuration with mirroring
18- Production HSMSecret resources
19- RBAC configuration
20
21### Sample Application
22- Web application deployment using HSM secrets
23- Database credentials from HSM
24- TLS certificates from HSM
25- High availability configuration
26
27### Production Features
28- Pod anti-affinity for distribution across nodes
29- Horizontal Pod Autoscaler for scaling
30- Pod Disruption Budget for availability
31- Network policies for security
32- Resource limits and health checks
33
34### Monitoring
35- ServiceMonitor for Prometheus integration
36- Metrics collection from operator
37- HSM device health monitoring
38
39## Deployment Steps
40
41### 1. Prerequisites
42
43Ensure you have:
44- Kubernetes cluster (v1.20+)
45- HSM devices connected to nodes
46- OpenSC libraries installed
47- Prometheus Operator (for monitoring)
48
49### 2. Label HSM Nodes
50
51Label nodes that have HSM devices:
52```bash
53kubectl label node <node-name> hsm.j5t.io/enabled=true
54```
55
56### 3. Deploy the Operator
57
58```bash
59# Deploy CRDs first
60kubectl apply -f config/crd/bases/
61
62# Deploy the operator
63kubectl apply -f config/default/
64
65# Or use the complete setup
66kubectl apply -f examples/deployment/complete-setup.yaml
67```
68
69### 4. Verify Deployment
70
71```bash
72# Check operator pods
73kubectl get pods -n hsm-secrets-operator-system
74
75# Check HSM devices
76kubectl get hsmdevice
77
78# Check secrets (multiple ways)
79kubectl hsm list # via kubectl-hsm plugin
80kubectl get hsmsecret # via CRDs
81kubectl get secret # via K8s secrets
82```
83
84### 5. Test Secret Operations
85
86**Option A: Using kubectl-hsm plugin (recommended):**
87```bash
88# Check health
89kubectl hsm health
90
91# Create a test secret
92kubectl hsm create test-secret --from-literal=key=value
93
94# List secrets
95kubectl hsm list
96
97# Get secret details
98kubectl hsm get test-secret
99```
100
101**Option B: Using REST API (advanced):**
102```bash
103# Port forward to access API locally
104kubectl port-forward -n hsm-secrets-operator-system service/hsm-secrets-operator-api 8090:8090
105
106# Test health endpoint
107curl http://localhost:8090/api/v1/health
108```
109
110## Configuration Options
111
112### HSM Device Configuration
113
114```yaml
115spec:
116 deviceType: PicoHSM # or SmartCardHSM, Generic
117 usb:
118 vendorId: "20a0"
119 productId: "4230"
120 nodeSelector:
121 hsm.j5t.io/enabled: "true"
122 mirroring:
123 policy: "ReadOnly"
124 syncInterval: 300
125 autoFailover: true
126```
127
128### Secret Configuration
129
130```yaml
131spec:
132 hsmPath: "secrets/production/my-secret"
133 secretName: "my-secret"
134 autoSync: true
135 syncInterval: 600
136 secretType: Opaque # or kubernetes.io/tls, etc.
137```
138
139## Security Considerations
140
141### 1. RBAC
142- Limit access to HSMSecret resources
143- Use service accounts with minimal permissions
144- Separate dev/staging/prod access
145
146### 2. Network Security
147- Use NetworkPolicies to restrict traffic
148- Enable TLS for API communication
149- Use private networks where possible
150
151### 3. HSM Security
152- Properly configure HSM authentication
153- Regular security updates for OpenSC libraries
154- Monitor HSM access and operations
155
156### 4. Secret Management
157- Use strong passwords and keys
158- Implement secret rotation policies
159- Monitor secret access and changes
160
161## Monitoring and Alerting
162
163### Key Metrics to Monitor
164- HSM device connectivity
165- Secret sync status and lag
166- API response times and errors
167- Operator pod health
168
169### Sample Alerts
170```yaml
171# HSM Device Down
172- alert: HSMDeviceDown
173 expr: hsm_device_connected == 0
174 for: 5m
175 labels:
176 severity: critical
177 annotations:
178 summary: "HSM device is disconnected"
179
180# Secret Sync Failed
181- alert: SecretSyncFailed
182 expr: hsm_secret_sync_failed > 0
183 for: 2m
184 labels:
185 severity: warning
186 annotations:
187 summary: "Secret synchronization failed"
188```
189
190## Troubleshooting
191
192### Common Issues
193
1941. **HSM Device Not Found**
195 ```bash
196 # Check USB devices
197 lsusb
198
199 # Check OpenSC
200 pkcs11-tool --list-slots
201
202 # Check node labels
203 kubectl describe node <node-name>
204 ```
205
2062. **Secrets Not Syncing**
207 ```bash
208 # Check HSMSecret status
209 kubectl describe hsmsecret <secret-name>
210
211 # Check operator logs
212 kubectl logs -n hsm-secrets-operator-system deployment/hsm-secrets-operator-controller-manager
213 ```
214
2153. **API Not Responding**
216 ```bash
217 # Check API service
218 kubectl get service -n hsm-secrets-operator-system
219
220 # Check API logs
221 kubectl logs -n hsm-secrets-operator-system -l control-plane=controller-manager
222 ```
223
224## Backup and Recovery
225
226### Backup HSM Configuration
227```bash
228# Export HSMDevice configurations
229kubectl get hsmdevice -o yaml > hsm-devices-backup.yaml
230
231# Export HSMSecret configurations
232kubectl get hsmsecret --all-namespaces -o yaml > hsm-secrets-backup.yaml
233```
234
235### Recovery Process
2361. Restore HSM devices and configure authentication
2372. Deploy operator and CRDs
2383. Apply HSMDevice configurations
2394. Apply HSMSecret configurations
2405. Verify secret synchronization