A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability th
1# HSM Secrets Operator Examples
2
3This directory contains practical examples demonstrating how to use the HSM Secrets Operator in various scenarios.
4
5## Directory Structure
6
7- **[basic/](basic/)** - Basic CRD resource examples for getting started
8- **[advanced/](advanced/)** - Advanced configurations and use cases
9- **[api/](api/)** - REST API usage examples and bulk operation scripts
10- **[deployment/](deployment/)** - Complete deployment configurations
11- **[high-availability/](high-availability/)** - High availability and mirroring setups
12
13## Quick Start
14
15### Method 1: kubectl-hsm Plugin (Recommended)
16
171. **Install the Operator**
18 ```bash
19 # Install CRDs and deploy the operator
20 kubectl apply -f config/default/
21 ```
22
232. **Install kubectl-hsm plugin**
24 ```bash
25 cd kubectl-hsm && make install
26 ```
27
283. **Create your first secret**
29 ```bash
30 kubectl hsm create my-secret --from-literal=password=secret123
31 ```
32
334. **List and get secrets**
34 ```bash
35 kubectl hsm list
36 kubectl hsm get my-secret
37 ```
38
39### Method 2: CRD Resources
40
411. **Install the Operator**
42 ```bash
43 kubectl apply -f config/default/
44 ```
45
462. **Create your first HSM Device**
47 ```bash
48 kubectl apply -f examples/basic/pico-hsm-device.yaml
49 ```
50
513. **Create an HSM Secret**
52 ```bash
53 kubectl apply -f examples/basic/database-secret.yaml
54 ```
55
56### Method 3: REST API (Advanced)
57
58For automation and bulk operations:
59```bash
60# Port forward to API
61kubectl port-forward -n hsm-secrets-operator-system svc/hsm-secrets-operator-api 8090:8090
62
63# Check health
64curl http://localhost:8090/api/v1/health
65
66# Create a secret via API
67curl -X POST http://localhost:8090/api/v1/hsm/secrets \
68 -H "Content-Type: application/json" \
69 -d @examples/api/create-secret.json
70```
71
72## Prerequisites
73
74- Kubernetes cluster (v1.20+)
75- Pico HSM or compatible PKCS#11 device
76- OpenSC libraries installed on nodes with HSM devices
77
78## Common Use Cases
79
80### 1. Database Credentials
81Store and rotate database credentials securely using HSM hardware protection.
82→ See [basic/database-secret.yaml](basic/database-secret.yaml)
83
84### 2. TLS Certificates
85Manage TLS certificates with automatic sync to Kubernetes Secrets.
86→ See [basic/tls-certificate.yaml](basic/tls-certificate.yaml)
87
88### 3. API Keys
89Store third-party API keys with hardware-based security.
90→ See [basic/api-keys.yaml](basic/api-keys.yaml)
91
92### 4. High Availability Setup
93Configure cross-node mirroring for fault tolerance.
94→ See [high-availability/](high-availability/)
95
96### 5. Import Existing Secrets
97Migrate existing Kubernetes Secrets to HSM storage.
98→ See [api/import-from-k8s.sh](api/import-from-k8s.sh)
99
100## Security Considerations
101
102- HSM devices should be properly authenticated and configured
103- Use RBAC to control access to HSMSecret resources
104- Enable audit logging for secret operations
105- Regular backup of HSM configurations (not the secrets themselves)
106
107## Troubleshooting
108
109Common issues and solutions:
110
1111. **HSM Device Not Found**
112 - Check USB connection and permissions
113 - Verify OpenSC installation
114 - Review HSMDevice status: `kubectl describe hsmdevice`
115
1162. **Sync Failures**
117 - Check HSM connectivity
118 - Verify PKCS#11 library path
119 - Review controller logs: `kubectl logs -n hsm-secrets-operator-system`
120
1213. **API Server Issues**
122 - Confirm API is enabled: `--enable-api=true`
123 - Check port availability: `--api-port=8090`
124 - Review API server logs
125
126## Contributing
127
128Found an issue or have a suggestion? Please open an issue or submit a pull request.
129
130## Additional Resources
131
132- [Operator Documentation](../README.md)
133- [API Reference](../internal/api/types.go)
134- [PKCS#11 Guide](https://www.opendnssec.org/softhsm/)