Overview
This page is a high-level overview of what a Lunar Hub deployment looks like on Kubernetes. It's meant to provide a conceptual overview of the system before you dive into the installation process. When you're ready to install, start by setting up the prerequisites.
What you're installing
A Lunar deployment primarily consists of:
the Lunar Hub (a Kubernetes service)
the Lunar Operator (a Kubernetes controller)
a fleet of transient policy/cataloger/collector batches managed by the operator
and three external dependencies you provide (PostgreSQL, S3, and credentials for your Git platform — a GitHub App or a GitLab group access token)
External boundaries
Hub
This is the central API server. It:
talks to Postgres, your Git platform, and S3
serves the gRPC API consumed by the CLI, CI tracers, and the Lunar operator
receives Git platform webhooks on its HTTP port
issues pre-signed S3 URLs for bulk data (run resources, run logs) transferred between work units orchestrated by the operator
For more details on how this hooks into the rest of the system, see Ports and protocols below.
Lunar CLI
The lunar binary. Used by platform engineers to push configuration, inspect components, and run collectors/policies locally. This is installed separately..
Lunar CI Tracer
Instruments your CI runners to report data to the Hub. This is also installed separately. We support Self-hosted GitHub Actions and Managed GitHub Actions options, plus Buildkite. GitLab CI tracing is coming soon — see GitLab for how collection works there today.
Inside the cluster
Lunar Operator
A Kubernetes controller that groups enqueued runs into batches and materializes each batch as a short-lived Kubernetes pod. It manages the whole lifecycle of these pods, from creation to cleanup.
Run pods
Short-lived batch pods. The init container fetches needed data from S3 and your Git platform and coordinates the user containers. User containers execute the specified cataloger, collector, or policy. The sidecar streams each container's logs to S3 and reports exit codes back to the Hub over gRPC.
Splitting the control plane (Hub + operator) and run pods into separate namespaces is recommended. This provides different blast radius, different resource profile, and different RBAC for distinctly different pieces of the system. Single-namespace installs also work; see Step 1 of the prerequisites for details.
Grafana
Grafana is the primary UI for Lunar today — dashboards for policy results, component health, and collection activity, reading from the same Postgres database as the Hub. Lunar ships those dashboards (plus the datasources and panel plugins they need) and installs them into a target Grafana over its HTTP API. You pick which Grafana based on what you already run:
No Grafana of your own — you want Lunar to run one
The chart deploys a stock Grafana alongside the Hub and installs the dashboards into it for you. Enabled by default; admin credentials are auto-generated.
Grafana Cloud or Grafana Enterprise
Point Lunar at your Grafana and give it a service-account token.
Self-hosted OSS Grafana
Point Lunar at your Grafana and give it admin username + password (OSS Grafana needs a server admin to install the dashboards' panel plugins — a service-account token can't).
In every case the chart provisions the dashboards for you on helm install / helm upgrade via a post-install/post-upgrade hook Job (grafana.provisioning).
Install Step 4 walks through all three. To turn Grafana off entirely, set grafana.mode: off; full configuration is in the chart README.
Networking
Connectivity
Use this table when planning ingress rules, egress allowlists, and NetworkPolicies. Specific Hub ports are detailed in the next section.
GitHub / GitLab
Hub HTTP ingress
Inbound
Webhook delivery
CLI / CI tracers
Hub gRPC ingress
Inbound
API calls (config sync, results)
CLI / CI tracers
Hub HTTP ingress
Inbound
Pre-signed log URL fetches
Hub
GitHub / GitLab API
Outbound
Read repos, post results, manage webhooks
Hub
Postgres
Outbound
Hub state (incl. work queue, migrations)
Hub
S3
Outbound
Run pod resource uploads
Operator
Postgres
Outbound
Poll work queue (own schema)
Run pods
S3
Outbound
Upload logs, download resources
Run pods
Hub Service
In-cluster
Exit codes (gRPC); log URL fetches (HTTP)
Ports and protocols
The Hub listens on three ports inside the pod. Only two are exposed externally; the third is for in-cluster health probes.
8000
gRPC
API — config sync, policy evaluation, run results
CLI, CI tracers, run pods (sidecar)
8001
HTTP
Webhook receivers + pre-signed URL redirector for run logs
Your Git platform, Buildkite, CLI, CI tracers, sidecar
8002
HTTP
Liveness / readiness probes (GET /health, GET /ready)
Kubelet only
The HTTP port serves webhook ingestion — /webhooks/github, /webhooks/gitlab, and /webhooks/buildkite — plus /logs/runs/, which redirects to pre-signed S3 URLs for log upload and download. No other HTTP routes exist. The Hub does not currently expose Prometheus metrics; observability is via OpenTelemetry (OTLP).
Next steps
Prerequisites — external dependencies you need in place before
helm install.Install walkthrough — step-by-step from zero to a working Hub.
Last updated