For the complete documentation index, see llms.txt. This page is also available as Markdown.

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:

Your situation
How Lunar reaches Grafana

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.

Source
Destination
Direction
Purpose

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.

Port
Protocol
Purpose
Who talks to it

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