Skip to content

About

Kubernetes operator for QueryFlux instances (QueryFluxInstance CRD)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

QueryFlux Operator

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.

Description

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 QueryFluxInstance CR → Deployment, Service, Secrets, optional HPA / PDB / Ingress / ServiceMonitor
  • Bootstrap config.yaml from CR (BootstrapOnly by default so Studio/Admin LiveConfig is not clobbered)
  • Validation of referenced Secrets (Postgres, OIDC, admin, engine auth, Ingress TLS)
  • Admin /readyz probing → Healthy condition + status.lastReadyzCheck
  • Status: phase, endpoints, replica counts, conditions
  • suspend: true scales 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 vs operator

  • Helm: QueryFlux app repo charts/queryflux — one-shot / GitOps install
  • Operator: many instances via the Kubernetes API (QueryFluxInstance CRs)

The operator does not wrap Helm. See docs/architecture.md.

Technology

  • Go + Kubebuilder v4 / controller-runtime
  • API: queryflux.dev/v1alpha1 — kind QueryFluxInstance

Quick start

Prerequisites

  • Go 1.22+
  • Docker
  • kubectl + a cluster (Kind, etc.)

Install the operator

make generate manifests
make docker-build IMG=queryflux-operator:dev
make install deploy IMG=queryflux-operator:dev

Deploy a QueryFlux instance

kubectl 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-corp

Minimal sample: config/samples/queryflux_v1alpha1_queryfluxinstance_minimal.yaml.

Run locally against a cluster

make install run

Development

make test           # unit + envtest
make lint
make build
make test-e2e       # Kind (optional)

Roadmap

  • 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

License

Apache License 2.0.

About

Kubernetes operator for QueryFlux instances (QueryFluxInstance CRD)

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages