Querdian (query + guardian) is an Apache-2.0, Kubernetes-native reverse proxy that enforces label-based access control on read queries against Prometheus/Thanos (PromQL), Loki (LogQL) and Tempo (TraceQL). Policies are Kubernetes CRDs, queries are rewritten with real parsers, and everything fails closed: unknown endpoints, unknown users and unparseable queries are rejected.
Status: alpha, v0.1.2 is the latest
release. It is not ready for production use: the policy API is v1alpha1 and may change
incompatibly, and there are no production adopters yet. The proxy, the policy CRDs and the PromQL,
LogQL and TraceQL enforcers are covered by unit, fuzz, envtest and container-based
differential/equivalence suites (make e2e) against real Prometheus, Loki and Tempo. Read the
release notes and the known limitations before
you evaluate it. See also CHANGELOG.md and ROADMAP.md.
helm install querdian oci://ghcr.io/querdian-dev/charts/querdian --version 0.1.2 \
--namespace querdian --create-namespace -f my-values.yaml- Helm chart:
oci://ghcr.io/querdian-dev/charts/querdian, also on Artifact Hub; values in the chart README. - Container image:
ghcr.io/querdian-dev/querdian:0.1.2(linux/amd64,linux/arm64). - Binaries, checksums and SBOMs: the GitHub release.
- Everything is signed with cosign (keyless) and has build-provenance attestations; see Verify.
To see it working first, run the quickstart.
Querdian verifies the OIDC token of the user, finds the rules of the user in the policies, rewrites the query with a real parser and sends it to the backend. It rejects each request that it cannot check. How Querdian works explains the parts, also for a hub with spoke clusters.
Inspired by evoila/janus.
See PLAN.md for the design and TASKS.md for the work breakdown.
The website (landing page and rendered documentation) is built from site/ and docs/ and published at https://querdian.dev, see site/README.md.
- How Querdian works: the path of a query, the policies, and hub and spoke, with drawings.
- Quickstart on kind: a complete isolation demo (Keycloak, Grafana, Prometheus, Loki, Tempo, two teams, 24 h of demo history and four Grafana dashboards) on a laptop with one script. The quickstart reference has the options and the internals of the demo.
- Policy guide: the CRDs, union semantics, tenants, denied labels and status conditions. Includes the requirement that the namespace label is set by your telemetry pipeline. The policy reference has the tables for denied labels and redaction.
- Policy dashboard: optional read-only view of active policies and a query test bench.
- Operations: installation checklist, configuration reference, flags, tracing, logging and upgrade. The operations reference has the limits, the metrics and the spans.
- Multi-cluster: one hub Querdian for the policies of several clusters, with the requirements, the migration steps and the procedures for certs and spokes. The multi-cluster reference has the configuration, the receiver and the agent. The multi-cluster quickstart is a demo on kind.
- Troubleshooting: decision reason codes and ready-made PromQL/TraceQL queries.
- Known limitations: strictness choices and unsupported syntax.
- Threat model and security policy.
- Releasing (maintainers), OpenSSF Best Practices checklist and the security self-assessment.
- Design notes: PromQL enforcement, endpoint inventory, research notes.
- Bugs and feature requests: open an issue at https://github.com/querdian-dev/querdian/issues.
Please include the Querdian version or commit, the backend and its version, the request (with
secrets removed), the response and the
X-Trace-Idof the response. - Contributions: see CONTRIBUTING.md (DCO sign-off and the clean-room rule apply).
- Security problems: do not open a public issue, follow SECURITY.md.
- Project governance: GOVERNANCE.md, MAINTAINERS.md, ADOPTERS.md, CODE_OF_CONDUCT.md.
make build test lintApache-2.0, see LICENSE.