> 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/dedicated/privatelink-inbound.md).

# PrivateLink to Your Hub

Reach your Lunar Dedicated hub, UI, and optional SQL and monitoring endpoints over AWS PrivateLink from your own VPC.

Your CI runners, CLI users, and browsers all need to reach your Lunar Dedicated install, and PrivateLink is the recommended way to let them. The hub API and the UI answer only inside the networks you connect to them, and nothing is published to the internet. If your install includes SQL API access or Prometheus federation, the same PrivateLink endpoint carries those optional surfaces too. The alternative, a public hostname behind TLS and token authentication, is there for teams whose CI runs on shared hosted runners and so cannot reach a private endpoint.

This page is the setup guide for that path. It's written for whoever runs your AWS networking. You can forward it on its own.

{% hint style="info" %}
This page covers reaching the hub **in**. Lunar reaching **out** to your internal systems (a self-managed Git platform, an internal registry or API) is a separate, independent setup, covered in [PrivateLink to Your Internal Systems](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/privatelink-outbound.md). Many installs need both.
{% endhint %}

## Do you need this?

Three questions to decide.

**1. Does your CI run in a network you control?** PrivateLink reaches your install from a VPC, so self-hosted runners in AWS are the natural fit. Shared hosted runners (github.com's, gitlab.com's) aren't in your VPC and can't use the endpoint, so an install that serves those still needs the internet route for whatever they call.

**2. How will your Git platform deliver webhooks?** Your Git platform calls the hub every time someone pushes, and it isn't on your runner network, so the endpoint you're about to create won't carry its traffic. This is the part most likely to have lead time, so settle it first: see [Decide the webhook path](#decide-the-webhook-path).

**3. How will developers reach the UI?** The UI is Grafana, on your install's apex hostname, and a private install resolves only inside the VPCs you connect to it. If your developers already work behind a VPN, Direct Connect, or Transit Gateway that reaches the VPC, PrivateLink covers them once you add DNS forwarding and a route ([step 5](#step-5-reach-the-install-from-elsewhere)). If they don't, you would have to build that path first, and an install on the internet, where Grafana sits behind a login, may be the better trade.

## How it works

Earthly publishes your install as an **endpoint service**. You create a matching **interface endpoint** in your VPC, plus two DNS records so your install's normal hostnames resolve to it.

```mermaid
flowchart LR
  subgraph Customer["Your AWS account"]
    CI["CI runners · CLI users<br/>browsers"]
    EP["Interface VPC endpoint<br/>(you create)"]
    CI --> EP
  end
  subgraph Dedicated["Lunar Dedicated account (Earthly-managed)"]
    ES["Endpoint service<br/>(Earthly creates)"]
    LB["Internal proxies"]
    HUB["Lunar Hub · Grafana<br/>optional SQL API · health metrics"]
    ES --> LB --> HUB
  end
  EP -- "AWS PrivateLink (one-way, you initiate)" --> ES
```

Three properties are worth knowing up front, because they answer most security-review questions:

* **The connection is one-way.** Your side initiates every session. Nothing in the install can initiate a connection back into your VPC.
* **Neither side learns the other's addresses.** PrivateLink does not join the networks, add routes, or expose either CIDR range. Overlapping address ranges are fine.
* **You reach only the service Earthly publishes.** Not the VPC it lives in, not anything else in Earthly's account.

You own and pay for the endpoint, the hosted zone, and any resolver infrastructure in [step 5](#step-5-reach-the-install-from-elsewhere).

{% hint style="warning" %}
**PrivateLink is not authentication.** It controls which AWS account may *create* an endpoint; it does not identify individual workloads or requests. The hub API still requires its bearer token.

**The UI has no login on a private install** unless you turn on [dashboard sign-in](https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/setup.md#dashboard-sign-in). Without it, Grafana is read-only to anyone who can reach the endpoint, so the endpoint's security group is what limits who sees it. Scope it to the systems and people you intend, and treat reaching the endpoint as equivalent to being able to read the UI.

**SQL API access is optional.** If enabled, the same endpoint accepts PostgreSQL clients at `sql.<your-install-domain>` on TCP 5432. PrivateLink supplies the network path; a database credential and TLS still protect the read-only SQL API.

**Prometheus federation is optional.** If enabled, the endpoint exposes a curated set of Lunar health metrics at `/federate` over HTTPS on port 9090. This is a scrape endpoint, not an interactive Prometheus API. It has no application credentials, so treat workloads with access to the PrivateLink endpoint as authorized to read these metrics, and restrict port 9090 to your monitoring collector.

Lunar Dedicated does not support mutual TLS today.
{% endhint %}

## Checklist

If you've consumed endpoint services before, this is all you need. The [Prefer Terraform?](#prefer-terraform) section has the resource definitions.

1. Decide the [webhook path](#decide-the-webhook-path). Most likely to have lead time, so start it first.
2. Interface endpoint against Earthly's service name, in subnets whose **zone IDs** Earthly supports.
3. **Private DNS disabled** on that endpoint. Leaving it on fails endpoint creation.
4. Endpoint security group: inbound TCP **443** from your systems, plus **5432** from SQL clients and **9090** from your monitoring scraper when those optional surfaces are enabled.
5. Private hosted zone for your install's domain, associated with that VPC.
6. Two **alias A records** in it, apex and wildcard, both targeting the endpoint's **regional** DNS name.
7. [Confirm it works](#confirm-it-works) and tell Earthly when you're good to go.

## What you need from Earthly first

Earthly builds its side first, so you'll receive these before you start:

| Value                               | Example                                                                                   |
| ----------------------------------- | ----------------------------------------------------------------------------------------- |
| **Region**                          | `us-east-2`                                                                               |
| **Endpoint service name**           | `com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0`                                 |
| **Supported availability zone IDs** | `use2-az1`, `use2-az2`                                                                    |
| **Your install's domain**           | `you.dedicated.earthly.dev`                                                               |
| **Hub hostname**                    | `hub.you.dedicated.earthly.dev`                                                           |
| **Enabled protocols and ports**     | HTTPS 443; PostgreSQL TLS 5432 if enabled; HTTPS 9090 if Prometheus federation is enabled |

Lunar Dedicated supports same-region endpoints only, so build everything here in the install's region.

Earthly also allowlists your AWS account beforehand, so your endpoint connects without an approval step. If your security team would rather Earthly allowlist one specific IAM role, send its ARN. It must be **pathless**, because AWS rejects principal ARNs containing a path on endpoint services.

## Four names that look alike

Four names come up below. Three of them are `vpce` strings that are easy to mix up, and the fourth is what your CI actually calls.

| Name                           | Looks like                                                                                                                                            | Used for                                                                  |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| **Endpoint service name**      | `com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0`                                                                                             | Earthly gives you this; it's the input when you create the endpoint       |
| **Endpoint ID**                | `vpce-0123456789abcdef0`                                                                                                                              | your endpoint, once created                                               |
| **Endpoint regional DNS name** | `vpce-0123456789abcdef0-a1b2c3d4.vpce-svc-0123456789abcdef0.us-east-2.vpce.amazonaws.com`                                                             | the target your DNS records alias to                                      |
| **Your install's hostnames**   | `you.dedicated.earthly.dev`, `hub.you.dedicated.earthly.dev`, and optional `sql.you.dedicated.earthly.dev` and `prometheus.you.dedicated.earthly.dev` | what your CI, browsers, SQL clients, and monitoring scraper actually call |

## Decide the webhook path

Your Git platform delivers webhooks to the hub. Without them, pushes don't trigger anything and pull/merge-request status checks never post. Your Git platform isn't on your runner network, so **the endpoint you're about to create won't carry that traffic.**

Which case applies depends on where your platform runs:

* **A cloud-hosted Git platform** (github.com, gitlab.com, etc.) delivers from the public internet and can't use PrivateLink. Earthly can leave *just* the webhook listener on the internet while everything else stays private. Webhooks are authenticated by a signed secret shared with the platform.
* **A self-managed Git platform in your own network** can usually reach the hub through the same endpoint, or through a second one in whichever VPC it runs in. The steps are the same either way.
* **A managed single-tenant Git platform** runs in your vendor's account. Some vendors offer an outbound private connection to a customer-published endpoint service; if yours does, request it and send Earthly the principal it gives you. **This is usually a support ticket with a lead time you don't control**, so raise it as soon as you have the endpoint service name. It runs in parallel with everything else here.

## Step 1 — Create the interface endpoint

In your runner VPC: **VPC → Endpoints → Create endpoint → Other endpoint services**, paste Earthly's service name, verify it, then choose subnets.

**Subnets must be in the zone IDs Earthly listed.** AWS maps zone *names* like `us-east-2a` to different physical zones in different accounts, so a name means nothing across an account boundary:

```bash
aws ec2 describe-availability-zones \
  --query 'AvailabilityZones[].[ZoneName,ZoneId]' --output table
```

Use two of the supported zones for redundancy; one is enough if that's all you have. If none of your subnets land in a supported zone, talk to Earthly before creating anything, because either side may need to add a subnet in a shared zone.

This constrains **placement only**: workloads anywhere in the VPC reach the endpoint across zones by ordinary VPC routing.

Attach a security group allowing inbound **TCP 443** from your runners. If Earthly's coordinates include 5432, allow it from the systems that query the SQL API. If they include 9090, allow that port from the Prometheus or compatible scraper that collects Lunar's health metrics.

## Step 2 — Turn private DNS off

Leave **Enable DNS name** unchecked (`private_dns_enabled = false` in Terraform).

Some tools default it on, and endpoint creation then fails with:

```
Private DNS can't be enabled because the service ... does not provide a private DNS name.
```

Enabling it asks AWS to resolve a hostname the *provider* has verified, and Earthly deliberately publishes none. Handling DNS on your side is what lets a single endpoint serve every hostname your install has today or gains later.

## Step 3 — Create the private hosted zone

Create a **private hosted zone** named after your install's domain (`you.dedicated.earthly.dev`), associated with the VPC holding the endpoint. That zone is dedicated to this install, so shadowing all of it is safe.

Add **two alias A records** with the same target. You need both, because a wildcard doesn't match its own apex:

| Record                        | Serves                     |
| ----------------------------- | -------------------------- |
| `you.dedicated.earthly.dev`   | the Grafana UI             |
| `*.you.dedicated.earthly.dev` | `hub.` and everything else |

**The alias target is your endpoint's regional DNS name**, the third row of [Four names that look alike](#four-names-that-look-alike). Find it on the endpoint's **Details** tab under **DNS names**, or:

```bash
aws ec2 describe-vpc-endpoints --vpc-endpoint-ids vpce-0123456789abcdef0 \
  --query 'VpcEndpoints[0].DnsEntries' --output table
```

{% hint style="warning" %}
**Two ways to get the target wrong.**

Pick the **regional** entry, not one of the per-zone variants ending `...-us-east-2a...`. A zonal target pins all your traffic to one availability zone.

And alias to the **endpoint**, not to the hostname you're creating the record for, and not to Earthly's endpoint *service* name.
{% endhint %}

Use alias records rather than CNAMEs, because a CNAME isn't valid at a zone apex.

## Step 4 — Point your CI at the hub

Nothing about Lunar's configuration changes for a private install:

```bash
LUNAR_HUB_HOST=hub.you.dedicated.earthly.dev
LUNAR_HUB_TOKEN=...
```

The gRPC API and the HTTP endpoints share port 443. Authentication is the same bearer token you'd use over the internet.

## Optional — connect to the SQL API

If Earthly enabled the SQL API for your install, connect to `sql.you.dedicated.earthly.dev:5432`. Let the Lunar CLI produce the complete PostgreSQL connection string rather than constructing one yourself:

```bash
lunar login
psql "$(lunar sql connection-string)"
```

The connection string includes the database name, your read-only credential, the private SQL hostname, and TLS verification settings. Don't replace its hostname with the interface endpoint's AWS DNS name or weaken its TLS options; either change breaks hostname verification.

The SQL API exposes only the documented read-only views. See [SQL API Overview](https://docs-lunar.earthly.dev/sql-api/sql-api.md) for credential lifecycle, schemas, and query examples.

## Optional — scrape Lunar health metrics

If Earthly enabled Prometheus federation for your install, configure your Prometheus-compatible collector to scrape the endpoint once per minute:

```yaml
scrape_configs:
  - job_name: lunar-dedicated
    scrape_interval: 60s
    scheme: https
    metrics_path: /federate
    honor_labels: true
    static_configs:
      - targets:
          - prometheus.you.dedicated.earthly.dev:9090
```

Don't add a `match[]` parameter. The endpoint returns the supported Lunar Dedicated health metrics automatically. General PromQL, the Prometheus UI, and Prometheus administration endpoints are not part of this service.

Federation returns current samples rather than historical data; your monitoring system builds history from the first successful scrape onward.

Metrics include install identity such as deployment, cluster, region, and dedicated account ID, so one monitoring system can distinguish several Lunar Dedicated installs. Keep `honor_labels: true` as shown above to preserve that identity.

Point Grafana at your own Prometheus-compatible store. Evaluate alerts there with Prometheus rules and Alertmanager, Grafana Alerting, or your managed monitoring provider. Alert on `up{job="lunar-dedicated"} == 0` to detect a failed federation scrape; `lunar_fleet_monitoring_heartbeat` distinguishes a reachable endpoint from a healthy Lunar monitoring pipeline.

## Step 5 — Reach the install from elsewhere

**Another VPC**: repeat steps 1 to 3 in it. Each VPC gets its own endpoint and its own copy of the two records; the hostnames stay the same everywhere.

**Laptops on the corporate network** need two separate things, and it's easy to do only the first:

1. **DNS**: forward `you.dedicated.earthly.dev` into the VPC, typically via a Route 53 Resolver inbound endpoint plus a conditional forwarder on your corporate resolvers.
2. **Network**: a route from the corporate network to the endpoint's addresses (VPN, Direct Connect, or Transit Gateway), and the endpoint's security group must allow that source.

Resolver forwarding only makes the name resolve. Do the first without the second and the browser gets the right address with no way to reach it.

## Prefer Terraform?

Steps 1 to 3 are five resources:

```hcl
resource "aws_security_group" "lunar_hub" {
  name   = "lunar-hub-endpoint"
  vpc_id = var.vpc_id
}

resource "aws_vpc_security_group_ingress_rule" "lunar_hub_tls" {
  security_group_id = aws_security_group.lunar_hub.id
  ip_protocol       = "tcp"
  from_port         = 443
  to_port           = 443
  cidr_ipv4         = var.runner_cidr # or referenced_security_group_id
}

# Add this rule only when Earthly's coordinates include port 5432.
resource "aws_vpc_security_group_ingress_rule" "lunar_sql_api" {
  security_group_id = aws_security_group.lunar_hub.id
  ip_protocol       = "tcp"
  from_port         = 5432
  to_port           = 5432
  cidr_ipv4         = var.sql_client_cidr # or referenced_security_group_id
}

# Add this rule only when Earthly's coordinates include port 9090.
resource "aws_vpc_security_group_ingress_rule" "lunar_prometheus_tls" {
  security_group_id = aws_security_group.lunar_hub.id
  ip_protocol       = "tcp"
  from_port         = 9090
  to_port           = 9090
  cidr_ipv4         = var.monitoring_cidr # or referenced_security_group_id
}

resource "aws_vpc_endpoint" "lunar_hub" {
  vpc_id             = var.vpc_id
  vpc_endpoint_type  = "Interface"
  service_name       = "com.amazonaws.vpce.us-east-2.vpce-svc-0123456789abcdef0"
  subnet_ids         = var.subnet_ids # subnets in the zone IDs Earthly supports
  security_group_ids = [aws_security_group.lunar_hub.id]

  # Required: Earthly publishes no verified private DNS name. See step 2.
  private_dns_enabled = false
}

resource "aws_route53_zone" "lunar" {
  name = "you.dedicated.earthly.dev"

  vpc {
    vpc_id = var.vpc_id
  }
}

resource "aws_route53_record" "lunar" {
  for_each = toset(["you.dedicated.earthly.dev", "*.you.dedicated.earthly.dev"])

  zone_id = aws_route53_zone.lunar.zone_id
  name    = each.value
  type    = "A"

  alias {
    name                   = aws_vpc_endpoint.lunar_hub.dns_entry[0].dns_name
    zone_id                = aws_vpc_endpoint.lunar_hub.dns_entry[0].hosted_zone_id
    evaluate_target_health = false
  }
}
```

{% hint style="warning" %}
**AWS doesn't document the order of `dns_entry`,** so `[0]` being the regional entry is a convention rather than a guarantee. Output it and check the value has no availability zone in it before relying on this in production.
{% endhint %}

## Confirm it works

From a host inside the VPC:

```bash
getent hosts hub.you.dedicated.earthly.dev
curl -sS https://you.dedicated.earthly.dev/api/health
```

The first should return the endpoint's **private** addresses; public addresses mean your hosted zone isn't answering and traffic would be leaving your network. The second should return JSON.

If the SQL API is enabled, verify the network path, credentials, and TLS together:

```bash
psql "$(lunar sql connection-string)" -v ON_ERROR_STOP=1 -c 'SELECT 1;'
```

Expect one row containing `1`. A TCP connection alone is not enough: this command also proves the certificate matches `sql.you.dedicated.earthly.dev` and that the issued credential works.

If Prometheus federation is enabled, verify its heartbeat:

```bash
curl -fsS https://prometheus.you.dedicated.earthly.dev:9090/federate \
  | grep '^lunar_fleet_monitoring_heartbeat{'
```

The response should contain your install's identity labels. A request to `/api/v1/query` should return 404; if it returns Prometheus JSON, stop and tell Earthly because that API is not part of the federation service.

{% hint style="info" %}
**An endpoint reaching `available` proves less than it sounds.** It means the PrivateLink connection was established, not that DNS is right and not that anything behind it works. The application requests above are the real check.
{% endhint %}

Then tell Earthly three things, so the install can be verified end to end from both sides:

* **Your endpoint ID**, so Earthly can confirm the connection is accepted and healthy rather than pending or rejected.
* **Which zone IDs you placed it in**, which is what Earthly checks against if connectivity works from some subnets but not others.
* **Which webhook case applies**, plus any principal to allowlist for a vendor-managed connection.

## Troubleshooting

**Endpoint creation fails on private DNS.** `Private DNS can't be enabled because the service ... does not provide a private DNS name` means the flag is on. See [step 2](#step-2-turn-private-dns-off).

**Endpoint creation fails on availability zones.** Your subnets aren't in a zone the service supports. Compare zone **IDs**, not names.

**Endpoint creation is rejected outright.** Your account isn't allowlisted, or a different one is. An unlisted account can't see the service at all, so the failure never reaches Earthly's side. Confirm the account ID.

**The endpoint sits in `pendingAcceptance`.** Earthly's service accepts allowlisted connections automatically, so tell Earthly rather than waiting.

**Hostnames don't resolve, or resolve to public addresses.** The hosted zone isn't associated with the VPC you're testing from, or the records are missing. Test from inside that VPC; laptops need [step 5](#step-5-reach-the-install-from-elsewhere).

**Hostnames resolve but connections hang.** Check the endpoint's security group allows the enabled port, TCP 443, 5432, or 9090, from the client.

**The SQL client reports a certificate hostname error.** Use the connection string from `lunar sql connection-string` unchanged. Connecting to the endpoint's `vpce-...amazonaws.com` name does not match the certificate served for `sql.you.dedicated.earthly.dev`.

**The SQL client reports password authentication failed.** Run `lunar sql connection-string` again while logged in, then replace the complete saved connection string in your client. Re-running the command rotates a personal credential, so the previous password stops working.

**Only the apex works, or only `hub.` works.** Only one of the two records exists, and both are needed.

**Traffic works from one availability zone only.** The alias targets a zonal endpoint DNS name rather than the regional one. See [step 3](#step-3-create-the-private-hosted-zone).

**A deeper hostname resolves but fails TLS.** DNS wildcards match at any depth, so `a.b.you.dedicated.earthly.dev` resolves via your wildcard record, but the install's certificate only covers one level. Lunar only ever uses single-label names like `hub.`, so this only appears if something is calling a name Lunar doesn't publish.

**Everything works except webhooks.** Your Git platform reaches the hub by a different path from your runners. See [Decide the webhook path](#decide-the-webhook-path).


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs-lunar.earthly.dev/install/lunar-hub/dedicated/privatelink-inbound.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
