> ## Documentation Index
> Fetch the complete documentation index at: https://hilt.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# VPC Setup Guide

> Connect your workload VPCs to Hilt so collectors can send telemetry and your team can access the dashboard.

This guide explains how to connect your network to Hilt so collectors can send telemetry and your team can access the dashboard. Everything stays inside your cloud account — no public internet exposure.

***

## What you are setting up

Hilt runs as a **single-tenant platform inside your cloud account**. Your hosts run collectors that send events to a private ingest endpoint. The dashboard is also private — reachable only from inside your network.

You do **not** need to build the platform yourself. Hilt provisions the platform VPC, ingest endpoint, and private DNS. Your job is to connect your **workload VPCs** (where your servers and Kubernetes clusters live) to that platform.

***

## Short answer: what you actually need to do

**No — you do not need to do every step in this guide.** Most of the platform is built by Hilt. What you must do depends on your layout.

| Task | Required? | Who typically does it |
| - | - | - |
| Grant cloud account access | **Yes** | You |
| Let Hilt provision the platform VPC | **Yes** (approve access) | Hilt |
| Connect workload VPC to platform | **Only if collectors run in a different VPC** | Hilt + you (firewall rules) |
| Open firewall rule (TCP 443 → ingest) | **Yes** | You |
| Associate private DNS with your VPC | **Only if collectors run in a different VPC** | Hilt or you |
| Set up VPN for dashboard access | **Yes, to use the dashboard** — not required for collectors to send data | You |
| Deploy collectors | **Yes, to see telemetry** — separate from VPC wiring | You |
| Auto-update VPC endpoints | **No** — only if you enable auto-update | Hilt (provisioned automatically) |

### Minimum for collectors to work

1. **Grant access** so Hilt can provision (Step 1).
2. **One firewall rule:** allow your hosts → ingest endpoint on TCP 443 (Step 3).
3. **DNS resolves** from your collector hosts — Hilt usually handles this; you only verify with `getent hosts` (Step 4).

If collectors run in the **same VPC** Hilt provisions (Layout A), that is usually it. No PrivateLink consumer endpoint, no extra DNS work.

If collectors run in a **different VPC** (Layout B), you also need that VPC connected to the platform — Hilt often does the endpoint and DNS association during onboarding; you still need the firewall rule.

### Separate from collector VPC

**Dashboard access (Step 5)** is its own requirement. Collectors can send telemetry even if nobody can open the dashboard yet. Your team needs VPN or a private network path to use the UI.

**Collector deployment (Step 6)** is not VPC setup — it comes after networking is working.

```text theme={null}
  YOUR CLOUD ACCOUNT
  ┌─────────────────────────────────────────────────────────────┐
  │                                                             │
  │   Workload VPC (your servers / K8s)                         │
  │   ┌──────────────┐                                          │
  │   │  Collector   │─── HTTPS 443 ───┐                        │
  │   └──────────────┘                  │                       │
  │                                     ▼                       │
  │                          PrivateLink / PSC endpoint         │
  │                                     │                       │
  │   Platform VPC (Hilt-provisioned)   ▼                       │
  │                          ┌──────────────────┐               │
  │                          │  Ingest service   │              │
  │                          └─────────┬─────────┘               │
  │                                    ▼                        │
  │                          Dashboard (internal only)          │
  │                                                             │
  └─────────────────────────────────────────────────────────────┘
```

***

## Who does what

| Task | Hilt | You |
| - | - | - |
| Create platform VPC and ingest endpoint | ✓ | |
| Grant cloud account access | | ✓ |
| Connect workload VPCs to the platform (cross-VPC only) | Often Hilt | Firewall rules: you |
| Open firewall / security group rules | Provide requirements | ✓ |
| Associate private DNS with your VPCs (cross-VPC only) | Often Hilt | Verify: you |
| Deploy collectors to your hosts | Guides | ✓ |
| Provide VPN or private path to the dashboard | | ✓ |

***

## Before you start

Gather this information before your onboarding call:

1. **Cloud account** — AWS account, GCP project, Azure subscription, or Ali Cloud account where Hilt will deploy.
2. **Region** — Where your main workloads run (e.g. `us-east-1`, `us-central1`).
3. **Workload VPCs** — List every VPC or VNet where collectors will run.
4. **CIDR ranges** — The IP ranges of those VPCs (needed for firewall rules).
5. **Dashboard access** — How your security team will reach the internal dashboard (VPN, Direct Connect, ExpressRoute, etc.).
6. **DNS** — Whether you use a custom subdomain (requires DNS delegation) or Hilt's default private zone.

Hilt will share your specific ingest URL (for example `https://<name>-ingest.hilt.ai`) after provisioning.

***

## Two common layouts

### Layout A — Collectors in the same VPC as the platform

Use this when your servers or Kubernetes nodes run in the same VPC Hilt provisions.

* Traffic stays entirely inside one VPC.
* You only need a security group rule: allow your host subnets → ingest endpoint on **TCP 443**.
* No extra PrivateLink consumer endpoint is required.

### Layout B — Collectors in a different VPC (most common)

Use this when your workloads live in separate VPCs (production, staging, EKS clusters, etc.).

* Hilt creates a **PrivateLink consumer endpoint** in each workload VPC (or you create one following Hilt's template).
* You associate the **private DNS zone** with each workload VPC so the ingest hostname resolves correctly.
* You add firewall / security group rules from your host CIDRs to the endpoint on **TCP 443**.

If you are unsure which layout applies, ask your Hilt contact — they will tell you after provisioning.

***

## Step-by-step setup

### Step 1 — Grant access and let Hilt provision (Day 1)

Hilt applies Terraform in your account and creates:

* Platform VPC with private subnets
* Ingest endpoint (PrivateLink on AWS, HTTPS Gateway on GCP, Private Link on Azure)
* Private DNS zone for the ingest hostname
* Internal dashboard load balancer
* All backend services (streaming, database, enrichment)

**Your action:** Provide IAM / RBAC permissions per your deployment guide and approve the provisioning window.

Cloud-specific provisioning details:

* [AWS](https://hilt.ai/docs/deployment/aws.md)
* [GCP](https://hilt.ai/docs/deployment/gcp.md)
* [Azure](https://hilt.ai/docs/deployment/azure.md)
* [Ali Cloud](https://hilt.ai/docs/deployment/ali-cloud.md)

***

### Step 2 — Connect your workload VPCs (cross-VPC only — skip if Layout A)

**Skip this step entirely if your collectors run in the same VPC Hilt provisions.**

After provisioning, Hilt shares connection details for each workload VPC you listed during onboarding. In many deployments Hilt creates the PrivateLink consumer endpoint and DNS association for you — you confirm it works and add firewall rules (Step 3).

#### AWS

For each workload VPC:

1. **Create or accept a VPC endpoint** (Interface type) that connects to Hilt's PrivateLink service.
2. **Associate the private Route 53 hosted zone** with your workload VPC so `getent hosts <name>-ingest.hilt.ai` resolves from your hosts.
3. **Update security groups:**
   * On the PrivateLink endpoint: allow inbound **TCP 443** from your collector source CIDRs (or the security group attached to your hosts).
   * On your hosts: allow outbound **TCP 443** to the endpoint security group or CIDR.

#### GCP

Collectors in v1 reach `{name}-ingest.hilt.ai` over the GKE HTTPS Gateway (Certificate Manager). There is no Private Service Connect ingest endpoint yet.

1. **Allow egress TCP 443** from collector subnets to the ingest Gateway (or to `0.0.0.0/0` if you have not restricted ingress CIDRs).
2. **Resolve `{name}-ingest.hilt.ai` publicly** (dns-broker). Hosts do not need a PSC endpoint or private DNS zone for ingest.
3. Optionally restrict Gateway source ranges via `ingest` / dashboard CIDR variables in `values.json` — see [GCP](https://hilt.ai/docs/deployment/gcp.md).

#### Azure

For each workload VNet:

1. **Create a Private Link endpoint** for the Hilt ingest service.
2. **Add a private DNS zone record** (or use Azure Private DNS integration) for the ingest hostname.
3. **Update NSGs:** allow outbound **TCP 443** from collector subnets to the Private Link endpoint.

#### Ali Cloud

For each workload VPC:

1. **Create a PrivateLink endpoint** in the VSwitch where collectors run.
2. **Configure private DNS** for the ingest domain.
3. **Update security groups:** allow **TCP 443** from collector source CIDRs to the endpoint.

> Hilt provides the exact service name, endpoint ID, and DNS zone details for your deployment. Do not guess these values — use what Hilt sends you.

***

### Step 3 — Open firewall rules

Every collector needs exactly **one outbound destination**: your Hilt ingest URL over **HTTPS (TCP 443)**.

| Direction | Rule | Notes |
| - | - | - |
| Outbound from collectors | Allow TCP 443 → ingest endpoint | Required |
| Inbound to collectors | None | Collectors do not listen on any port |
| Public internet | Not required | All traffic stays private |

**Example (AWS security group inbound on the PrivateLink endpoint):**

| Type | Protocol | Port | Source |
| - | - | - | - |
| HTTPS | TCP | 443 | `10.0.0.0/16` (your workload VPC CIDR) |

Replace the source with your actual collector subnet CIDRs or host security group.

This same rule applies to Linux VMs, Kubernetes DaemonSets, and macOS endpoints.

***

### Step 4 — Configure private DNS

The ingest hostname lives in a **private DNS zone**, not on the public internet. Each VPC where collectors run must be able to resolve it.

**Verify from a collector host:**

```bash theme={null}
getent hosts <name>-ingest.hilt.ai
```

You should see a private IP address (typically the PrivateLink / PSC endpoint address). If the lookup fails or returns nothing, the Route 53 / private DNS association for that VPC is missing — contact Hilt or your network team to add it.

**Important:** You do not need to configure public DNS resolvers (8.8.8.8, etc.). Resolution happens entirely inside your VPC.

***

### Step 5 — Enable dashboard access for your team

The dashboard runs behind an **internal load balancer** with no public IP. Your security analysts need a private path to reach it.

Common options:

| Method | When to use |
| - | - |
| Corporate VPN | Most common — VPN clients land inside a VPC that can reach the internal ALB |
| AWS Client VPN / GCP Cloud VPN / Azure VPN Gateway | Managed VPN into your cloud |
| Direct Connect / ExpressRoute / Cloud Interconnect | Always-on private link from on-prem |
| Bastion / jump host | Temporary access for initial validation |

Hilt shares your dashboard URL (for example `https://<name>.hilt.ai`) after provisioning. Test it from a machine on the same private network before rolling out collectors fleet-wide.

***

### Step 6 — Deploy collectors and verify

Once networking is in place, deploy collectors using the guides for your environment:

* [Deploy on VMs](https://hilt.ai/docs/linux-collector/deploy-vms.md)
* [Deploy on Kubernetes](https://hilt.ai/docs/linux-collector/deploy-kubernetes.md)
* [macOS Collector](https://hilt.ai/docs/macos-collector.md)

When installing, set the **Ship URL** to your ingest endpoint:

```yaml theme={null}
ship_url: "https://<name>-ingest.hilt.ai"
```

Use only the base domain — no path suffix.

**Verify the collector is connected:**

```bash theme={null}
# Linux VM
sudo systemctl status dag-agent
sudo journalctl -u dag-agent --no-pager -n 20

# Kubernetes
kubectl logs -l app=dag-agent --tail=20
```

Expected log line:

```text theme={null}
Ship mode: https://<name>-ingest.hilt.ai
BPF object loaded; attached N programs
```

**Verify events in the dashboard:**

1. Open the dashboard from a machine on your private network.
2. Go to **Collectors** — your host should appear as Active.
3. Go to **Investigate** — events should appear within minutes.

***

## Setup checklist

Use this checklist to confirm your VPC setup is complete:

* [ ] Hilt provisioning finished in your cloud account
* [ ] Workload VPC(s) connected via PrivateLink / PSC / Private Link
* [ ] Private DNS zone associated with every collector VPC
* [ ] `getent hosts <name>-ingest.hilt.ai` resolves from a collector host
* [ ] Firewall / security group allows TCP 443 from collectors to ingest endpoint
* [ ] Dashboard reachable from your team's VPN or private network
* [ ] At least one collector deployed and showing Active in the dashboard
* [ ] Events visible in Investigate

***

## Troubleshooting

### DNS does not resolve from collector hosts

**Symptom:** `getent hosts <name>-ingest.hilt.ai` returns nothing.

**Fix:** The private Route 53 / DNS zone is not associated with your workload VPC. Ask Hilt to associate it, or add the association in your cloud console.

***

### Collector in Ship mode but no events in dashboard

**Symptom:** Agent logs show "Ship mode" but the dashboard is empty.

Check in order:

1. **DNS** — Does `getent hosts <name>-ingest.hilt.ai` return a private IP?
2. **Connectivity** — Can you reach the endpoint? If the request hangs, the PrivateLink security group likely blocks your host's source CIDR.
3. **URL** — Is the Ship URL exactly `https://<name>-ingest.hilt.ai` with no extra path?

***

### Kubernetes collectors cannot resolve the ingest hostname

**Symptom:** DaemonSet pods fail to ship events; DNS errors in logs.

**Fix:** Ensure the DaemonSet uses `dnsPolicy: ClusterFirstWithHostNet` (this is in the shipped manifest). This lets pods resolve private Route 53 records via your VPC DNS.

***

### Dashboard unreachable

**Symptom:** Browser cannot load the dashboard URL.

**Fix:** The dashboard is internal-only. Connect via your corporate VPN or private network path first, then retry. There is no public URL.

***

## Optional — Auto-update network requirements (AWS)

If you enable the Hilt auto-update agent, your platform VPC needs outbound access to pull new container images. Hilt provisions these VPC endpoints automatically:

* `com.amazonaws.<region>.ecr.api`
* `com.amazonaws.<region>.ecr.dkr`
* `com.amazonaws.<region>.s3` (gateway)
* `com.amazonaws.<region>.ecs`

The agent also needs outbound access to the Hilt release ECR (`297433793776.dkr.ecr.us-east-1.amazonaws.com`). See the [Operational Guide](https://hilt.ai/docs/on-prem/auto-update-operations.md) for details.

This is only required for auto-update — not for basic collector telemetry.

***

## Quick reference

| Item | Value |
| - | - |
| Collector outbound port | TCP 443 (HTTPS) |
| Collector inbound ports | None |
| Ingest URL format | `https://<name>-ingest.hilt.ai` |
| Dashboard URL format | `https://<name>.hilt.ai` |
| Public internet required | No |
| DNS type | Private zone (per-VPC association) |

***

## Getting help

If you are stuck on VPC setup:

1. Run through the checklist above and note which step fails.
2. Collect output from `getent hosts <name>-ingest.hilt.ai` on an affected host.
3. Contact your Hilt representative with your cloud provider, region, and VPC IDs.

For deeper technical context, see:

* [Architecture and data flow](https://hilt.ai/docs/trust-security/architecture.md)
* [Networking and security (Linux collector)](https://hilt.ai/docs/linux-collector/networking-security.md)
* [Getting Started](https://hilt.ai/docs/getting-started.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.