Kubernetes operator for managing QueryFlux instances via a QueryFluxInstance custom resource.
Warning
Work in Progress — APIs, CRDs, and behavior may change. Not production-ready yet.
The operator automates deployment and lifecycle of QueryFlux (universal SQL proxy) on Kubernetes: config bootstrap, health checks, scaling hooks, and status reporting. External dependencies (Postgres, OIDC IdP, engine credentials) are validated, not provisioned.
Key capabilities:
- Declarative
QueryFluxInstanceCR → Deployment, Service, Secrets, optional HPA / PDB / Ingress / ServiceMonitor - Bootstrap
config.yamlfrom CR (BootstrapOnlyby default so Studio/Admin LiveConfig is not clobbered) - Validation of referenced Secrets (Postgres, OIDC, admin, engine auth, Ingress TLS)
- Admin
/readyzprobing →Healthycondition +status.lastReadyzCheck - Status: phase, endpoints, replica counts, conditions
suspend: truescales to zero; image tag bumps roll the Deployment- Watches referenced Secrets so missing deps recover without a manual CR touch
Operator capability level: Level 2 (seamless image upgrades via Deployment) — working toward richer autopilot.
Postgres schema migrations default to Refinery on QueryFlux startup (autoMigrate: true). For multi-replica rollouts, disable auto-migrate and run queryflux migrate -c /config/config.yaml as a Job first — see docs/architecture.md. The operator does not create that Job yet.
- Helm: QueryFlux app repo
charts/queryflux— one-shot / GitOps install - Operator: many instances via the Kubernetes API (
QueryFluxInstanceCRs)
The operator does not wrap Helm. See docs/architecture.md.
- Go + Kubebuilder v4 / controller-runtime
- API:
queryflux.dev/v1alpha1— kindQueryFluxInstance
- Go 1.22+
- Docker
- kubectl + a cluster (Kind, etc.)
make generate manifests
make docker-build IMG=queryflux-operator:dev
make install deploy IMG=queryflux-operator:devkubectl create secret generic queryflux-rds \
--from-literal=host=postgres.default.svc \
--from-literal=user=queryflux \
--from-literal=password=changeme
kubectl apply -f config/samples/queryflux_v1alpha1_queryfluxinstance.yaml
kubectl get queryfluxinstances -o wide
kubectl describe queryfluxinstance acme-corpMinimal sample: config/samples/queryflux_v1alpha1_queryfluxinstance_minimal.yaml.
make install runmake test # unit + envtest
make lint
make build
make test-e2e # Kind (optional)- Platform ConfigMap for regional Ingress host construction
- Custom-metrics HPA on
queryflux_queued_queries - Admission webhooks (defaulting / validation)
- Installer bundle (
dist/install.yaml) + optional operator Helm chart
Apache License 2.0.