https://github.com/gen0sec/synapse-operator
Kubernetes operator for Synapse
https://github.com/gen0sec/synapse-operator
arxignis firewall k8s kubernetes moat
Last synced: 5 months ago
JSON representation
Kubernetes operator for Synapse
- Host: GitHub
- URL: https://github.com/gen0sec/synapse-operator
- Owner: gen0sec
- License: apache-2.0
- Created: 2025-11-03T21:31:42.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-01-16T09:29:35.000Z (5 months ago)
- Last Synced: 2026-01-16T23:47:35.153Z (5 months ago)
- Topics: arxignis, firewall, k8s, kubernetes, moat
- Language: Go
- Homepage: https://gen0sec.com
- Size: 246 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Community
[](https://discord.gg/jzsW5Q6s9q)
[](https://arxignis.substack.com/)
## Synapse Operator (Go)
This Go operator watches Synapse configuration ConfigMaps and Secrets and keeps the running pods in sync by forcing a rollout any time config content changes. It relies on matching labels (default `app.kubernetes.io/name=synapse`) so it naturally plugs into Helm releases of Synapse.
### How It Works
- Reconciles ConfigMaps and Secrets that match the configured label selector.
- Hashes the combined data across all matching config sources in the namespace, with optional per-key ignores (for example, hot-reloadable `upstreams.yaml`).
- Patches Synapse workloads (Deployments, DaemonSets, StatefulSets) with the hash stored under `synapse.gen0sec.com/config-hash` by default.
- Updating the annotation bumps the workload template hash, causing Kubernetes to roll the pods and pick up the new configuration.
### Project Layout
- `main.go` bootstraps a controller-runtime manager with health probes and optional namespace scoping.
- `controllers/configmap_controller.go` contains the reconciliation logic and hashing helper.
- `config/` holds a kustomize deployment (service account, RBAC, manager deployment). Replace `ghcr.io/example/synapse-operator:latest` with your published image.
### Building
```bash
GOOS=linux GOARCH=amd64 go build -o bin/synapse-operator
```
Adjust the target architecture if you are building for another platform.
To containerize:
```bash
docker build -t ghcr.io//synapse-operator:latest .
docker push ghcr.io//synapse-operator:latest
```
Update `config/manager.yaml` with the pushed image reference.
### Deploying with Kustomize
```bash
kubectl apply -k config
```
This creates the `synapse-system` namespace, service account, RBAC, and a single replica of the operator.
### Testing From WSL (no commands executed yet)
1. **Prepare tools** - ensure WSL has `docker`, `kubectl`, and `kind` (or `minikube`) installed and on `$PATH`.
2. **Build & load the image** - inside WSL build the Linux image and use `kind load docker-image ghcr.io//synapse-operator:latest` (or push to a registry reachable by your cluster).
3. **Create a test cluster** - `kind create cluster --name synapse`.
4. **Deploy Synapse via Helm** - from `synapse-main/helm`, run `helm install synapse ./helm --namespace synapse --create-namespace`. This produces the ConfigMap and workloads with the expected labels.
5. **Apply the operator manifests** - `kubectl apply -k ../synapse-operator/config`.
6. **Trigger a config change** - edit the Synapse ConfigMap (`kubectl edit configmap synapse -n synapse`) or use `kubectl patch`.
7. **Verify restart** - watch the rollout: `kubectl rollout status deployment/synapse -n synapse` and ensure pod annotation `synapse.gen0sec.com/config-hash` updates.
### Helm Integration Notes
The Helm chart already labels both the ConfigMap and workloads with `app.kubernetes.io/name=synapse`. The operator leans on that selector to discover which objects belong together. When Helm updates config sources (e.g., via `helm upgrade`), the operator sees the new data, recalculates the hash, and patches the workloads so the change propagates without any manual restarts.
### Configuration Flags
- `--label-selector` - Label selector for config sources and workloads (default `app.kubernetes.io/name=synapse`).
- `--config-hash-annotation` - Annotation key used for the hash (default `synapse.gen0sec.com/config-hash`).
- `--ignore-configmap-keys` - Comma-separated ConfigMap keys to ignore when hashing (default `upstreams.yaml`).
- `--ignore-secret-keys` - Comma-separated Secret keys to ignore when hashing (default empty).