> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/overview.md).

# 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](/install/lunar-hub/self-hosted/prerequisites.md).

## 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

```mermaid
flowchart LR
  CLI["Lunar CLI"]
  Agent["Lunar CI Tracer"]

  Hub["Lunar Hub"]

  PG[("PostgreSQL")]
  S3[("S3 buckets<br/>logs · resources")]
  Git["GitHub or GitLab"]

  CLI -- gRPC --> Hub
  Agent -- gRPC --> Hub
  Git -- webhooks --> Hub

  Hub -- SQL --> PG
  Hub -- reads/writes --> S3
  Hub -- API --> Git
```

#### 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](#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.](/install/cli.md).

#### Lunar CI Tracer

Instruments your CI runners to report data to the Hub. This is also installed separately. We support [Self-hosted GitHub Actions](/install/ci-tracer/github-actions-self-hosted.md) and [Managed GitHub Actions](/install/ci-tracer/github-actions-managed.md) options, plus [Buildkite](/install/ci-tracer/buildkite.md). GitLab CI tracing is [coming soon](/install/ci-tracer/gitlab-ci.md) — see [GitLab](/install/git-platforms/gitlab.md) for how collection works there today.

### Inside the cluster

```mermaid
flowchart LR
  subgraph K8s["Kubernetes cluster"]
    subgraph CP["Control-plane namespace"]
      Hub["Lunar Hub"]
      Op["Lunar Operator"]
    end
    subgraph RP["Run-pods namespace"]
      SP["Run Pods<br/>(init + sidecar + user code)"]
    end
    Op -- creates --> SP
  end

  PG[("PostgreSQL")]

  Hub -- SQL --> PG
  Op -- polls queue --> PG
  SP -- gRPC --> Hub
```

#### 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](/install/lunar-hub/self-hosted/prerequisites.md#step-1-plan-your-kubernetes-namespaces) 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](/install/lunar-hub/self-hosted/install-walkthrough.md#grafana) walks through all three. To turn Grafana off entirely, set `grafana.mode: off`; full configuration is in the [chart README](https://github.com/earthly/charts/blob/main/README.md#grafana).

## Networking

### Connectivity

Use this table when planning ingress rules, egress allowlists, and NetworkPolicies. Specific Hub ports are detailed in the [next section](#ports-and-protocols).

| 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](/install/lunar-hub/self-hosted/prerequisites.md) — external dependencies you need in place before `helm install`.
* [Install walkthrough](/install/lunar-hub/self-hosted/install-walkthrough.md) — step-by-step from zero to a working Hub.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.