A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability th
1# hsm-secrets-operator
2
3A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability through hardware-based security.
4
5## Description
6
7The HSM Secrets Operator implements a controller pattern that synchronizes HSM binary data files to Kubernetes Secret objects. It uses a unified binary architecture with gRPC communication, automatic USB device discovery, and dynamic agent deployment to provide secure, hardware-backed secret management in Kubernetes environments.
8
9### Key Features
10
11- **Hardware Security**: Leverages Pico HSM and other PKCS#11 compatible devices for tamper-resistant secret storage
12- **Automatic Sync**: Synchronization from HSM storage to Kubernetes Secrets
13- **Device Discovery**: Automatic USB HSM device detection with support for multiple device types
14- **Agent Architecture**: Dynamic deployment of HSM agent pods with node affinity for direct hardware access
15- **gRPC Communication**: High-performance gRPC protocol for manager-agent communication with fallback to HTTP
16- **Unified API**: Single REST API endpoint that routes operations to appropriate HSM agents
17- **Secret Portability**: Move secrets between clusters by carrying the HSM device
18- **Multi-Device Support**: Support for Pico HSM, SmartCard-HSM, YubiKey HSM, and custom devices
19
20### Architecture
21
22The operator consists of four main components:
23
241. **Manager**: Orchestrates HSMSecret resources, deploys agents, and provides unified REST API proxy (port 8090)
252. **Discovery**: DaemonSet that discovers USB HSM devices on cluster nodes and reports via pod annotations
263. **Agent**: Dynamically deployed pods that handle direct HSM communication via gRPC (port 9090) with HTTP health checks (port 8093)
274. **Test HSM**: Utility for HSM operations testing and debugging
28
29**Communication Architecture:**
30- **Manager ↔ Agent**: gRPC for efficient, type-safe HSM operations
31- **Discovery → Manager**: Pod annotations for race-free device reporting
32- **External → Manager**: REST API for user/application access
33- **Protocol Buffers**: Structured message definitions in `api/proto/hsm/v1/hsm.proto`
34
35This architecture ensures that HSM operations only occur on nodes with physical device access while providing a centralized management interface with high-performance communication.
36
37## Getting Started
38
39### Prerequisites
40- Kubernetes v1.20+ cluster
41- Go 1.24+ (for building from source)
42- Docker 17.03+ (for building images)
43- kubectl with cluster-admin privileges
44- HSM device (Pico HSM, SmartCard-HSM, YubiKey HSM, or compatible PKCS#11 device)
45- **For development**: buf tool (`go install github.com/bufbuild/buf/cmd/buf@latest`)
46
47### Deployment Options
48
49#### Option 1: Using Helm (Recommended)
50
511. **Deploy with Helm:**
52```bash
53# Install from local chart
54helm install hsm-secrets-operator helm/hsm-secrets-operator \
55 --namespace hsm-secrets-operator-system \
56 --create-namespace
57```
58
592. **Configure HSM Devices:**
60```bash
61# Apply HSMDevice configuration for your HSM type
62kubectl apply -f config/samples/hsm_v1alpha1_hsmdevice.yaml
63```
64
653. **Create HSM Secrets:**
66```bash
67# Create HSMSecret resources to sync with Kubernetes Secrets
68kubectl apply -f config/samples/hsm_v1alpha1_hsmsecret.yaml
69```
70
71#### Option 2: Manual Deployment
72
731. **Build and deploy images:**
74**Build and push your image to the location specified by `IMG`:**
75
76```sh
77make docker-build docker-push IMG=<some-registry>/hsm-secrets-operator:tag
78```
79
80**NOTE:** This image ought to be published in the personal registry you specified.
81And it is required to have access to pull the image from the working environment.
82Make sure you have the proper permission to the registry if the above commands don’t work.
83
84**Install the CRDs into the cluster:**
85
86```sh
87make install
88```
89
90**Deploy the Manager to the cluster with the image specified by `IMG`:**
91
92```sh
93make deploy IMG=<some-registry>/hsm-secrets-operator:tag
94```
95
96> **NOTE**: If you encounter RBAC errors, you may need to grant yourself cluster-admin
97privileges or be logged in as admin.
98
99**Create instances of your solution**
100You can apply the samples (examples) from the config/sample:
101
102```sh
103kubectl apply -k config/samples/
104```
105
106>**NOTE**: Ensure that the samples has default values to test it out.
107
108### Quick Start with API
109
110Once deployed, the operator provides a unified API endpoint:
111
112```bash
113# Port forward to access the API
114kubectl port-forward -n hsm-secrets-operator-system svc/hsm-secrets-operator-api 8090:8090
115
116# Check API health
117curl http://localhost:8090/api/v1/health
118
119# List secrets
120curl http://localhost:8090/api/v1/hsm/secrets
121
122# Check discovered HSM devices
123kubectl get hsmdevices
124
125# Check HSM pools (aggregated device discovery)
126kubectl get hsmpools
127
128# Check agent pods (deployed automatically when devices are ready)
129kubectl get pods -l app.kubernetes.io/component=agent
130
131# Test gRPC agent health (from within cluster)
132kubectl exec -it <agent-pod> -- curl http://localhost:8093/healthz
133```
134
135### Uninstallation
136
137#### Using Helm:
138```bash
139helm uninstall hsm-secrets-operator -n hsm-secrets-operator-system
140```
141
142#### Manual cleanup:
143```bash
144# Delete sample resources
145kubectl delete -k config/samples/
146
147# Delete operator
148make undeploy
149
150# Delete CRDs (optional - will remove all HSMSecret/HSMDevice resources)
151make uninstall
152```
153
154## Project Distribution
155
156Following the options to release and provide this solution to the users.
157
158### By providing a bundle with all YAML files
159
1601. Build the installer for the image built and published in the registry:
161
162```sh
163make build-installer IMG=<some-registry>/hsm-secrets-operator:tag
164```
165
166**NOTE:** The makefile target mentioned above generates an 'install.yaml'
167file in the dist directory. This file contains all the resources built
168with Kustomize, which are necessary to install this project without its
169dependencies.
170
1712. Using the installer
172
173Users can just run 'kubectl apply -f <URL for YAML BUNDLE>' to install
174the project, i.e.:
175
176```sh
177kubectl apply -f https://raw.githubusercontent.com/<org>/hsm-secrets-operator/<tag or branch>/dist/install.yaml
178```
179
180### By providing a Helm Chart
181
1821. Build the chart using the optional helm plugin
183
184```sh
185operator-sdk edit --plugins=helm/v1-alpha
186```
187
1882. See that a chart was generated under 'dist/chart', and users
189can obtain this solution from there.
190
191**NOTE:** If you change the project, you need to update the Helm Chart
192using the same command above to sync the latest changes. Furthermore,
193if you create webhooks, you need to use the above command with
194the '--force' flag and manually ensure that any custom configuration
195previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml'
196is manually re-applied afterwards.
197
198## Contributing
199
200We welcome contributions! The HSM Secrets Operator follows standard Kubernetes operator development practices.
201
202### Development Setup
203
2041. **Clone and setup:**
205```bash
206git clone <repository-url>
207cd hsm-secrets-operator
208```
209
2102. **Run quality checks:**
211```bash
212# Format, vet, and lint code (REQUIRED before committing)
213make quality
214
215# Run tests
216make test
217```
218
2193. **Local development:**
220```bash
221# Generate manifests after CRD changes
222make manifests
223
224# Generate protocol buffer code after .proto changes
225buf generate
226
227# Build all binaries (manager, discovery, agent, test-hsm)
228make build
229```
230
231### Code Quality Requirements
232
233**⚠️ CRITICAL: Always run before committing:**
234```bash
235make quality # Runs format + vet + lint
236```
237
238### Architecture Notes
239
240- **Manager**: Handles HSMSecret CRDs, agent deployment, and REST API proxy (port 8090)
241- **Discovery**: DaemonSet for USB device discovery with pod annotation reporting
242- **Agent**: Dynamic pods for direct HSM communication via gRPC (port 9090)
243- **gRPC Protocol**: Type-safe communication defined in `api/proto/hsm/v1/hsm.proto`
244- **Health Checks**: HTTP endpoints on port 8093 for Kubernetes probes
245
246### Protocol Buffer Development
247
248When modifying the gRPC service definition:
249
250```bash
251# 1. Edit the protocol definition
252vim api/proto/hsm/v1/hsm.proto
253
254# 2. Generate Go code
255buf generate
256
257# 3. Lint and format
258buf lint
259buf format -w api/proto/hsm/v1/hsm.proto
260
261# 4. Run tests to ensure compatibility
262make test
263```
264
265**NOTE:** Run `make help` for more information on all potential `make` targets
266
267More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
268
269## License
270
271Copyright 2025.
272
273Licensed under the Apache License, Version 2.0 (the "License");
274you may not use this file except in compliance with the License.
275You may obtain a copy of the License at
276
277 http://www.apache.org/licenses/LICENSE-2.0
278
279Unless required by applicable law or agreed to in writing, software
280distributed under the License is distributed on an "AS IS" BASIS,
281WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
282See the License for the specific language governing permissions and
283limitations under the License.