https://github.com/ferrlabs/ferrvault
Kubernetes operator that syncs FerrFlow secrets into native Kubernetes Secrets
https://github.com/ferrlabs/ferrvault
controller crd devtools external-secrets ferrflow go helm kubernetes kubernetes-operator secrets-management
Last synced: about 1 month ago
JSON representation
Kubernetes operator that syncs FerrFlow secrets into native Kubernetes Secrets
- Host: GitHub
- URL: https://github.com/ferrlabs/ferrvault
- Owner: FerrLabs
- License: mpl-2.0
- Created: 2026-04-16T19:27:55.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-12T21:29:05.000Z (about 2 months ago)
- Last Synced: 2026-06-12T23:11:24.135Z (about 2 months ago)
- Topics: controller, crd, devtools, external-secrets, ferrflow, go, helm, kubernetes, kubernetes-operator, secrets-management
- Language: Go
- Homepage: https://ferrflow.com
- Size: 287 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# ferrflow-operator
[](https://github.com/FerrLabs/FerrVault/releases/latest)
[](https://sonar.ferrlabs.com/dashboard?id=FerrVault)
[](https://sonar.ferrlabs.com/dashboard?id=FerrVault)
[](LICENSE)
[](https://scorecard.dev/viewer/?uri=github.com/FerrLabs/FerrVault)
Kubernetes operator that syncs secrets stored in [FerrFlow](https://ferrflow.com) into native Kubernetes `Secret` resources.
> **Status: alpha.** The MVP reconciler is in place — it reads secrets from a FerrFlow vault via the bulk-reveal API and materialises them into a Kubernetes Secret, with owner-ref GC and status conditions. Rolling restarts, Helm chart, and integration tests are tracked in [issue #1](https://github.com/FerrLabs/FerrFlow-Operator/issues/1).
## Custom resources
Two CRDs under `ferrflow.io/v1alpha1`:
### `FerrFlowConnection` (shortname `ffc`)
Declares how to reach a FerrFlow instance. One per (namespace, org). Shared by every `FerrFlowSecret` in that namespace that targets the same organization.
```yaml
apiVersion: ferrflow.io/v1alpha1
kind: FerrFlowConnection
metadata:
name: prod
spec:
url: https://ferrflow.example.com
organization: acme
tokenSecretRef:
name: ferrflow-api-token
key: token
```
The referenced Secret must hold a FerrFlow API token (`fft_...`) with at least the `secrets:read` scope.
### `FerrFlowSecret` (shortname `ffs`)
Declares a sync from a vault to a Kubernetes Secret.
```yaml
apiVersion: ferrflow.io/v1alpha1
kind: FerrFlowSecret
metadata:
name: web-env
spec:
connectionRef: { name: prod }
project: web
vault: production # FerrFlow vault name (often the environment)
selector:
names: [DATABASE_URL, STRIPE_KEY] # omit to sync every key in the vault
target:
name: web-env # target Secret name; defaults to metadata.name
type: Opaque
refreshInterval: 30m # Go time.Duration; 0s disables scheduled refresh
```
On reconciliation the operator calls `GET /api/v1/orgs/:org/projects/:project/vaults/by-name/:vault/secrets/reveal` once, writes the returned `{name: value}` map into `spec.target.name`, and sets the CR's `Ready` condition based on whether any requested keys were missing upstream.
The generated Secret is owned by the CR — deleting the CR garbage-collects the Secret.
#### Value transforms
Revealed values can be reshaped before they land in the target Secret via `spec.transforms`. Transforms are applied in order; each one sees the output of the previous step.
```yaml
spec:
connectionRef: { name: prod }
project: web
vault: production
selector:
names: [DATABASE_URL, STRIPE_KEY, CONFIG_JSON]
transforms:
- type: rename
from: DATABASE_URL
to: DB_URL
- type: base64Decode
keys: [STRIPE_KEY] # omit `keys` to decode every value
- type: jsonExpand
key: CONFIG_JSON # {"db":{"host":"pg"}} → CONFIG_JSON_DB_HOST=pg
- type: prefix
value: APP_ # stamps APP_ on every remaining key
```
Supported types:
| `type` | Fields | Effect |
| -------------- | ------------------- | ------------------------------------------------------------ |
| `prefix` | `value` | Prepends `value` to every key. |
| `suffix` | `value` | Appends `value` to every key. |
| `rename` | `from`, `to` | Projects one key. Missing `from` is a no-op; collisions fail.|
| `base64Decode` | `keys` (optional) | Decodes listed keys (or all when empty) from base64. |
| `jsonExpand` | `key` | Flattens a JSON object under `_`. Drops the source.|
Malformed transforms (unknown type, invalid base64, non-object JSON, destination-key collisions) leave the CR in `Ready=False` with `Reason=TransformError` and increment `ferrflow_secret_sync_errors_total{reason="TransformError"}`. The target Secret is not written on failure — workloads keep the last known-good value.
## Running
### Helm (recommended)
```bash
helm install ferrflow-operator oci://ghcr.io/ferrlabs/charts/ferrflow-operator \
--namespace ferrflow-operator-system --create-namespace
```
Upgrade: `helm upgrade` against the same release. CRDs carry `helm.sh/resource-policy: keep` so they survive uninstall (protects your CRs + managed Secrets). See [`charts/ferrflow-operator/README.md`](charts/ferrflow-operator/README.md) for the full `values.yaml` reference.
### Locally against a cluster
```bash
make install-crds # CRDs only
make run # runs the manager as your user, not as a Pod
```
### Raw manifests (without Helm at runtime)
The Helm chart is the single source of truth for all manifests (CRDs, RBAC,
ServiceAccount, Deployment). If your cluster policy forbids running Helm at
deploy time, render once and commit/apply the plain YAML:
```bash
kubectl create namespace ferrflow-operator-system
helm template ferrflow-operator charts/ferrflow-operator \
--namespace ferrflow-operator-system \
> manager.yaml
kubectl apply -f manager.yaml
```
No duplicate `config/rbac/` or `config/crd/` lives in the repo — anything
rendered from the chart *is* the canonical version.
## Prerequisites in FerrFlow
The operator relies on endpoints in [`FerrLabs/FerrVault-Cloud`](https://github.com/FerrLabs/FerrVault-Cloud) that shipped in `api@v4.0.0`:
- API token auth (`Authorization: Bearer fft_...`) with granular scopes — #268
- `secrets:read` scope enforcement on all secrets routes — #268
- Bulk reveal endpoint — #277
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Code of conduct in [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Vulnerability reports via [SECURITY.md](SECURITY.md).
## License
[MPL-2.0](LICENSE)