A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability th
remove references to bidirectional sync
+36
-12
+27
-3
CLAUDE.md
+27
-3
CLAUDE.md
···
6
6
7
7
**Remote Kubernetes Environment**: The Kubernetes cluster is running remotely, NOT on this local development system. Any local device checks (like `ls /dev/tty*` or local USB device detection) will NOT work and will not reflect the actual state of devices on the remote cluster nodes.
8
8
9
+
**Sync Architecture**: The operator implements **unidirectional sync from HSM to Kubernetes Secrets only**. HSM is the authoritative source of truth. K8s Secrets are read-only replicas that get updated when HSM data changes. There is no K8s → HSM sync functionality.
10
+
9
11
## Project Overview
10
12
11
-
A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability through hardware-based security. The operator implements a controller pattern that maintains bidirectional synchronization between HSM binary data files and Kubernetes Secret objects using a unified binary architecture with gRPC communication, automatic USB device discovery, and dynamic agent deployment.
13
+
A Kubernetes operator that bridges Hardware Security Module (HSM) data storage with Kubernetes Secrets, providing true secret portability through hardware-based security. The operator implements a controller pattern that synchronizes HSM binary data files to Kubernetes Secret objects using a unified binary architecture with gRPC communication, automatic USB device discovery, and dynamic agent deployment.
12
14
13
15
## Architecture: Unified Binary with Mode-Based Operation
14
16
···
55
57
**Controller Hierarchy:**
56
58
```
57
59
Manager Controllers:
58
-
├── HSMSecretReconciler - Bidirectional HSM/K8s Secret sync
60
+
├── HSMSecretReconciler - HSM to K8s Secret sync
59
61
├── HSMPoolReconciler - Aggregates discovery reports from pod annotations
60
62
├── HSMPoolAgentReconciler - Deploys agents when pools are ready
61
63
└── DiscoveryDaemonSetReconciler - Manages discovery DaemonSet lifecycle
···
142
144
metadata:
143
145
name: my-secret # HSM path = metadata.name
144
146
spec:
145
-
autoSync: true # Bidirectional sync (default)
147
+
autoSync: true # Automatic sync from HSM to K8s (default)
146
148
syncInterval: 30 # Sync interval in seconds
147
149
status:
148
150
syncStatus: "InSync" # InSync|OutOfSync|Error|Pending
···
275
277
- **Agent crash loop**: Check library path and PIN secret configuration
276
278
- **gRPC connection failed**: Verify agent on port 9090, check service/endpoint configuration
277
279
- **Proto generation issues**: Install buf tool (`go install github.com/bufbuild/buf/cmd/buf@latest`)
280
+
- **Metadata keys in K8s Secrets**: If you see `_metadata` keys in Kubernetes Secrets, this indicates a bug in the PKCS#11 client filtering (should be excluded in `ReadSecret`)
278
281
279
282
## Manual HSM Access
280
283
···
295
298
**Secret Storage Structure:**
296
299
- Each K8s Secret becomes multiple PKCS#11 data objects
297
300
- Object naming: `secret-name/key-name` (e.g., `user-credentials/api_key`)
301
+
- Metadata stored separately with `/_metadata` suffix (filtered out from K8s Secrets)
298
302
- Private objects require PIN authentication to access
303
+
304
+
## Code Architecture Critical Points
305
+
306
+
**Controller Interaction Flow:**
307
+
1. `HSMSecretReconciler` reads from HSM via gRPC agents
308
+
2. `HSMPoolReconciler` aggregates device discovery reports from pod annotations (race-free)
309
+
3. `HSMPoolAgentReconciler` deploys agents dynamically when devices are ready
310
+
4. `HSMSyncReconciler` handles multi-device HSM synchronization (HSM ↔ HSM only)
311
+
312
+
**PKCS#11 Client Implementation:**
313
+
- Production: `internal/hsm/pkcs11_client.go` with CGO
314
+
- Testing: `internal/hsm/pkcs11_client_nocgo.go` and `mock_client.go`
315
+
- **Critical**: ReadSecret must filter out `metadataKeySuffix` ("/_metadata") objects
316
+
- Build tags control which client is compiled
317
+
318
+
**Protocol Buffer Workflow:**
319
+
1. Modify `api/proto/hsm/v1/hsm.proto`
320
+
2. Run `buf generate` to update Go code
321
+
3. Implement in `internal/agent/grpc_server.go`
322
+
4. Update client calls in controller or agent code
299
323
300
324
This operator provides secure, hardware-backed secret management that integrates seamlessly with Kubernetes while maintaining the security benefits of HSM-based storage.
+2
-2
README.md
+2
-2
README.md
···
4
4
5
5
## Description
6
6
7
-
The HSM Secrets Operator implements a controller pattern that maintains bidirectional synchronization between HSM binary data files and Kubernetes Secret objects. It uses a four-binary architecture with gRPC communication, automatic USB device discovery, and dynamic agent deployment to provide secure, hardware-backed secret management in Kubernetes environments.
7
+
The 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
8
9
9
### Key Features
10
10
11
11
- **Hardware Security**: Leverages Pico HSM and other PKCS#11 compatible devices for tamper-resistant secret storage
12
-
- **Bidirectional Sync**: Automatic synchronization between HSM storage and Kubernetes Secrets
12
+
- **Automatic Sync**: Synchronization from HSM storage to Kubernetes Secrets
13
13
- **Device Discovery**: Automatic USB HSM device detection with support for multiple device types
14
14
- **Agent Architecture**: Dynamic deployment of HSM agent pods with node affinity for direct hardware access
15
15
- **gRPC Communication**: High-performance gRPC protocol for manager-agent communication with fallback to HTTP
+1
-1
api/v1alpha1/hsmsecret_types.go
+1
-1
api/v1alpha1/hsmsecret_types.go
···
61
61
// +optional
62
62
SecretName string `json:"secretName,omitempty"`
63
63
64
-
// AutoSync enables bidirectional synchronization between HSM and Kubernetes Secret
64
+
// AutoSync enables automatic synchronization from HSM to Kubernetes Secret
65
65
// +kubebuilder:default=true
66
66
// +optional
67
67
AutoSync bool `json:"autoSync,omitempty"`
+2
-2
config/crd/bases/hsm.j5t.io_hsmsecrets.yaml
+2
-2
config/crd/bases/hsm.j5t.io_hsmsecrets.yaml
···
56
56
properties:
57
57
autoSync:
58
58
default: true
59
-
description: AutoSync enables bidirectional synchronization between
60
-
HSM and Kubernetes Secret
59
+
description: AutoSync enables automatic synchronization from HSM to
60
+
Kubernetes Secret
61
61
type: boolean
62
62
parentRef:
63
63
description: |-
+1
-1
examples/basic/README.md
+1
-1
examples/basic/README.md
+1
-1
examples/basic/database-secret.yaml
+1
-1
examples/basic/database-secret.yaml
+2
-2
helm/hsm-secrets-operator/crds/hsm.j5t.io_hsmsecrets.yaml
+2
-2
helm/hsm-secrets-operator/crds/hsm.j5t.io_hsmsecrets.yaml
···
56
56
properties:
57
57
autoSync:
58
58
default: true
59
-
description: AutoSync enables bidirectional synchronization between
60
-
HSM and Kubernetes Secret
59
+
description: AutoSync enables automatic synchronization from HSM to
60
+
Kubernetes Secret
61
61
type: boolean
62
62
parentRef:
63
63
description: |-