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

# Connect to Collate over AWS PrivateLink

> Configure an interface VPC endpoint in your AWS account to reach your Collate instance privately, without traversing the public internet.

# Connect to Collate over AWS PrivateLink

AWS PrivateLink lets you reach your Collate instance over private AWS networking instead of the public internet. Traffic stays on the AWS backbone, and your VPC doesn't need an internet gateway, NAT gateway, or public IP addresses to reach Collate.

Collate hosts the **endpoint service**. You create an **interface VPC endpoint** in your own AWS account that connects to it. This page covers the steps you perform on your side.

<Note>
  PrivateLink is available for Collate SaaS instances. Contact your Collate representative to have it enabled for your instance before you begin.
</Note>

## How it works

* Collate creates a VPC endpoint service in front of your Collate instance and associates it with your instance's public DNS name (for example, `yourcompany.getcollate.io`).
* You create an interface endpoint in your VPC that points at that service.
* Collate approves your connection request.
* With private DNS enabled, your existing Collate URL resolves to private IP addresses inside your VPC. Clients and ingestion jobs keep using the same hostname — no application changes are required.

## What PrivateLink covers

PrivateLink secures traffic going **into** Collate. It supports:

* Users reaching the Collate web interface
* Applications reaching the Collate API
* Ingestion services running on Hybrid SaaS

It does **not** cover connections in the other direction — Collate reaching resources inside your network. If you need Collate to read from on-premises or otherwise private data sources, use one of these instead:

* The [Hybrid Runner](/how-to-guides/deployment/hybrid-runner), which runs ingestion inside your own environment so credentials and data never leave it.
* Public interfaces restricted to Collate's dedicated outbound IP for your instance. Ask your Collate representative for that address.

Collate only accepts connections over TLS. PrivateLink adds a layer of network isolation on top of HTTPS — it doesn't replace it, and there's no unencrypted option.

## Before you begin

Exchange the following information with Collate.

**Collate provides you with:**

| Item                      | Example                                                   |
| ------------------------- | --------------------------------------------------------- |
| VPC endpoint service name | `com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0` |
| Private DNS name          | `yourcompany.getcollate.io`                               |
| Service region            | `us-east-1`                                               |

**You provide Collate with:**

| Item                              | Why it's needed                                                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Your AWS account ID               | Collate adds it to the endpoint service allow list. Without this, the service isn't visible to your account. |
| The region you'll connect from    | Collate enables that region on the endpoint service.                                                         |
| The Availability Zones you'll use | Confirms subnet coverage for same-region connections.                                                        |

<Warning>
  Collate must add your AWS account to the endpoint service allow list before you can create the endpoint. If you try to create it first, AWS reports that the service name doesn't exist.
</Warning>

You also need permissions in your AWS account to create VPC endpoints and security groups (`ec2:CreateVpcEndpoint`, `ec2:DescribeVpcEndpointServices`, and related actions).

## Connecting from a different region

You don't have to connect from the same region your Collate instance runs in. AWS PrivateLink supports cross-region interface endpoints, and Collate's endpoint services support it.

Tell Collate which region you'll connect from so they can enable it on the endpoint service. Then note these differences:

* You must explicitly enable cross-region connectivity on the endpoint and specify the service region.
* Availability Zones don't need to align with Collate's. You can use any AZs in your region.
* Private DNS is still supported, so your Collate hostname resolves normally.
* Both regions must be in the same AWS partition. For example, a commercial region can't reach a GovCloud region.
* Cross-region traffic incurs AWS inter-region data transfer charges in addition to standard PrivateLink charges.

## Step 1: Create the interface endpoint

<Tabs>
  <Tab title="AWS Console">
    1. Open the [Amazon VPC console](https://console.aws.amazon.com/vpc/) and choose **Endpoints** > **Create endpoint**.
    2. For **Name tag**, enter something identifiable, such as `collate-privatelink`.
    3. For **Type**, choose **Endpoint services that use NLBs and GWLBs**.
    4. If you're connecting from a different region than Collate, select **Enable cross-region endpoint** and choose Collate's **Service region**.
    5. For **Service name**, enter the service name Collate gave you, then choose **Verify service**. You should see *Service name verified*.
    6. For **VPC**, choose the VPC that needs access to Collate.
    7. For **Subnets**, select one subnet per Availability Zone you want to reach Collate from — you can't select two subnets in the same AZ. AWS creates an endpoint network interface in each. Choose at least two AZs for resiliency.
       * For **IP address type**, choose **IPv4**.
       * AWS assigns IPs from each subnet's range automatically. To pin them, select **Designate IP addresses** and enter an address from each subnet's range.
    8. For **Security groups**, select a security group that allows inbound HTTPS. See [Step 2](#step-2-configure-the-security-group).
    9. Leave **Enable DNS name** unchecked for now. You'll enable it in [Step 4](#step-4-enable-private-dns), after Collate accepts the connection.
    10. Choose **Create endpoint**.
  </Tab>

  <Tab title="AWS CLI">
    Same-region connection:

    ```bash theme={null}
    aws ec2 create-vpc-endpoint \
      --region us-east-1 \
      --vpc-endpoint-type Interface \
      --vpc-id vpc-0123456789abcdef0 \
      --service-name com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0 \
      --subnet-ids subnet-aaaaaaaa subnet-bbbbbbbb \
      --security-group-ids sg-0123456789abcdef0 \
      --no-private-dns-enabled \
      --tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=collate-privatelink}]'
    ```

    Cross-region connection — add `--service-region` with the region where Collate hosts the service:

    ```bash theme={null}
    aws ec2 create-vpc-endpoint \
      --region us-west-2 \
      --vpc-endpoint-type Interface \
      --vpc-id vpc-0123456789abcdef0 \
      --service-name com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0 \
      --service-region us-east-1 \
      --subnet-ids subnet-aaaaaaaa subnet-bbbbbbbb \
      --security-group-ids sg-0123456789abcdef0 \
      --no-private-dns-enabled \
      --tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=collate-privatelink}]'
    ```

    In the cross-region example, `--region` is where *your* endpoint is created and `--service-region` is where *Collate's* service lives.
  </Tab>
</Tabs>

<Note>
  Create the endpoint with private DNS disabled. Enabling it while the connection is still pending causes the request to fail, because AWS can't associate the private hosted zone until the connection is accepted.
</Note>

## Step 2: Configure the security group

The security group attached to the endpoint controls which clients can reach it. It needs to allow inbound HTTPS from the resources that talk to Collate.

| Direction | Protocol | Port | Source                                                                                               |
| --------- | -------- | ---- | ---------------------------------------------------------------------------------------------------- |
| Inbound   | TCP      | 443  | Your VPC CIDR, or the security groups of the clients and ingestion workloads that connect to Collate |

Scope the source as tightly as your network policy allows. If your ingestion runners live in a specific set of subnets or security groups, reference those instead of the whole VPC CIDR.

## Step 3: Wait for Collate to accept the connection

Collate's endpoint service requires manual acceptance. After you create the endpoint it sits in the `pendingAcceptance` state until Collate approves it.

Let your Collate contact know the endpoint has been created. You can check the state at any time:

```bash theme={null}
aws ec2 describe-vpc-endpoints \
  --region us-west-2 \
  --vpc-endpoint-ids vpce-0123456789abcdef0 \
  --query 'VpcEndpoints[].State' \
  --output text
```

Wait until this returns `available` before continuing.

### Validate the endpoint before enabling DNS

Before you turn on private DNS, confirm the endpoint itself carries traffic. This isolates a connectivity problem from a DNS problem, and it's much easier to debug in this order.

Find the endpoint's private IPs under **Endpoints** > your endpoint > **Subnets** > **IPv4 addresses**. Then, from a host in the same VPC, send a request straight to one of those IPs with the Collate hostname in the `Host` header:

```bash theme={null}
curl -H "Host: yourcompany.getcollate.io" -k -v https://10.6.0.75
```

The server should present a TLS certificate for `yourcompany.getcollate.io` and return `200`.

<Note>
  `-k` skips certificate validation, which is expected here — you're connecting by IP, so the certificate name won't match the address. This flag is only for this one-off check. Don't carry it into normal client configuration.
</Note>

## Step 4: Enable private DNS

Once the endpoint is `available`, enable private DNS so your existing Collate hostname resolves to the endpoint.

<Tabs>
  <Tab title="AWS Console">
    1. In the VPC console, choose **Endpoints** and select your endpoint.
    2. Choose **Actions** > **Modify private DNS name**.
    3. Select **Enable private DNS name**, then save.
  </Tab>

  <Tab title="AWS CLI">
    ```bash theme={null}
    aws ec2 modify-vpc-endpoint \
      --region us-west-2 \
      --vpc-endpoint-id vpce-0123456789abcdef0 \
      --private-dns-enabled
    ```
  </Tab>
</Tabs>

Your VPC must have **DNS resolution** and **DNS hostnames** enabled for private DNS to work. Both are on by default. To confirm:

```bash theme={null}
aws ec2 describe-vpc-attribute --vpc-id vpc-0123456789abcdef0 --attribute enableDnsSupport
aws ec2 describe-vpc-attribute --vpc-id vpc-0123456789abcdef0 --attribute enableDnsHostnames
```

## Step 5: Verify connectivity

From an instance inside the VPC, confirm the Collate hostname now resolves to private addresses:

```bash theme={null}
nslookup yourcompany.getcollate.io
```

The answer should be private IP addresses from your subnet ranges (for example, `10.x.x.x`), not public ones.

Then confirm Collate responds over the private path:

```bash theme={null}
curl -sS -o /dev/null -w '%{http_code}\n' https://yourcompany.getcollate.io
```

You should get `200`.

Once this succeeds, existing clients, browsers, and ingestion workloads inside the VPC reach Collate over PrivateLink automatically. No configuration changes are needed on their side.

## Troubleshooting

<Accordion title="Service name not found or cannot be verified">
  Your AWS account hasn't been added to the endpoint service allow list yet, or you're connecting from a region Collate hasn't enabled.

  Confirm with Collate that they've allow-listed your exact AWS account ID and enabled your region on the endpoint service. Also double-check the service name for typos — it includes Collate's region, which may differ from yours.
</Accordion>

<Accordion title="Endpoint stuck in pendingAcceptance">
  This is expected until Collate accepts the connection request. Contact your Collate representative. The endpoint won't pass traffic and private DNS can't be enabled until the state is `available`.
</Accordion>

<Accordion title="Private DNS option is greyed out or fails to enable">
  Private DNS can only be enabled after the connection is accepted. Confirm the endpoint state is `available`, and that `enableDnsSupport` and `enableDnsHostnames` are both `true` on your VPC.
</Accordion>

<Accordion title="Hostname still resolves to a public IP">
  DNS may be cached. Flush the resolver cache on the client, or wait for the previous record's TTL to expire.

  Also confirm you're testing from inside the VPC associated with the endpoint. Resources outside that VPC — including on-premises hosts reaching your VPC over a VPN or Direct Connect — continue to resolve the public address unless you forward DNS to your VPC's Route 53 Resolver.
</Accordion>

<Accordion title="Connection times out">
  This is almost always the security group. Confirm the endpoint's security group allows inbound TCP 443 from the client's IP range or security group, and that the client's own outbound rules allow HTTPS to the endpoint.
</Accordion>

<Accordion title="On-premises clients can't resolve the Collate hostname">
  Private DNS only applies within the VPC. To resolve the name from on-premises networks, create a Route 53 Resolver inbound endpoint in the VPC and forward the Collate domain to it from your on-premises DNS servers.
</Accordion>