Grab a spot →
Skip to main content

Private connectivity over AWS PrivateLink (NLB + endpoint service)

Connect docs via MCP

Atlan supports private network connectivity to your AWS-hosted and on-premises data sources using classic AWS PrivateLink: you publish a VPC endpoint service backed by a Network Load Balancer, and Atlan consumes it through an interface VPC endpoint in your Atlan tenant's VPC. Traffic stays entirely on the AWS private network.

This is the longest-established private connectivity pattern with Atlan and the most broadly applicable one: anything an NLB can reach, including on-premises systems via Direct Connect or VPN, can be published to Atlan this way. For connecting many databases with less operational overhead, also consider PrivateLink via VPC resource gateways or AWS VPC Lattice.

note

PrivateLink connectivity requires a Single Tenant SaaS deployment of Atlan (a dedicated Atlan VPC). Contact your Atlan representative if you are unsure of your deployment type.

Building blocks​

ComponentOwned byWhat it does
Network Load Balancer (NLB)YouA Layer 4 load balancer in the same VPC as (or with a route to) your data source, with a TCP listener per database port and a target group pointing at the database.
VPC endpoint serviceYouPublishes the NLB for cross-account consumption. Produces a service name of the form com.amazonaws.vpce.<region>.vpce-svc-….
Allowed principalsYouThe allowlist on the endpoint service controlling which AWS accounts/roles may connect. Atlan's principal must be on it.
Interface VPC endpointAtlanCreated in your Atlan tenant's VPC against your service name. Places an ENI (with a vpce-… DNS name) that connectors dial.
Route 53 private hosted zone (optional)AtlanMaps your database's real hostname to the endpoint inside the Atlan VPC, required for RDS IAM authentication and for TLS certificate validation on HTTPS sources.

How Atlan connects​

The full path: connector → interface endpoint → your endpoint service → NLB listener → target group → database. Strictly one-way.

  1. You build the NLB, target groups, and endpoint service, and add Atlan's principal to the allowed principals.
  2. You share the endpoint service name and the Availability Zone IDs it's enabled in with Atlan support.
  3. Atlan creates the interface endpoint in your tenant's VPC. If your endpoint service uses manual acceptance, the connection sits in Pending acceptance until you approve it, nothing works before that.
  4. Atlan shares back the hostname to use in connections: either the endpoint's vpce-… DNS name, or, where the real hostname matters, Atlan maps your database's actual FQDN to the endpoint via a private hosted zone.
  5. When a connector runs, traffic flows through the path described here and back along it. Traffic is strictly one-way: Atlan initiates, your network never connects into Atlan.

Properties worth understanding:

  • The NLB is TLS-transparent. Listeners are plain TCP, so the NLB port-maps and forwards raw packets without touching TLS. Your database's own certificate handles encryption end-to-end; there is no certificate to manage on the NLB. (The exception is HTTPS sources fronted by an ALB behind the NLB, there, certificate names matter, and a private hosted zone is needed so the hostname Atlan dials matches the certificate.)
  • AZ IDs, not AZ names. AZ names (us-west-2a) map to different physical zones in different AWS accounts; AZ IDs (usw2-az1) don't. The endpoint on Atlan's side must be placed in subnets whose AZ IDs match where your endpoint service is enabled, or cross-zone load balancing must be on. Always exchange AZ IDs.
  • RDS IAM authentication needs the real hostname. IAM token generation validates against the genuine *.rds.amazonaws.com name and fails outright against a vpce-… hostname. If you use IAM auth, say so up front, the setup then includes the private-hosted-zone mapping from day one.
  • Authentication is a separate layer. The network path is validated first (a TCP connection to the listener port), then credentials or the cross-account IAM role (role ARN + external ID, trusting Atlan's tenant node role). A driver "login timeout" on a brand-new setup is almost always a network problem wearing an authentication costume.

Connecting multiple databases: Port-based routing​

One endpoint service can front many databases. Configure one TCP listener per database on the NLB, each on a distinct port, each forwarding to its own target group:

Listener :5432 → target group A → database 1 :5432
Listener :5433 → target group B → database 2 :5432
Listener :5434 → target group C → database 3 :5432

Atlan then reaches every database through the same endpoint, differing only by port, for each connection you supply the hostname and the specific listener port. This scales to dozens of listeners on one NLB and also works as a hub pattern: an NLB in a central networking account can forward to databases in other accounts (for example, several Redshift clusters spread across accounts, each behind its own listener port), so a single PrivateLink carries them all.

The trade-off: every listener/target-group pair is yours to keep healthy, and every new database is a coordinated change. If you're heading past a handful of databases, the resource gateway or VPC Lattice patterns remove this maintenance entirely.

Prerequisites​

  • Access to create an NLB, target groups, and a VPC endpoint service in the AWS account with network reach to your data source.
  • Atlan's principal for allowlisting, provided by Atlan support per tenant. Allowlist the tenant-specific node role ARN Atlan provides, it's scoped to your tenant, preserves tenant isolation, and differs between your production and non-production Atlan tenants. Allowlisting Atlan's AWS account root (arn:aws:iam::<atlan-account>:root) also works and is simpler to bootstrap, but it lets any principal in Atlan's account connect to your endpoint service, so treat it as an explicit exception, not the default. Neither grants any access inside your systems; the principal only permits the endpoint-service connection.
  • Your Atlan tenant's region, the endpoint service must be in the same region as the tenant. Cross-region setups are possible but handled case-by-case with Atlan support.
  • For each database: hostname/FQDN, engine, native port, and the NLB listener port you assign it.
  • On-premises sources: existing connectivity from your AWS network to the data center (Direct Connect or Site-to-Site VPN). The NLB targets the on-prem IP; for HTTP and HTTPS-based on-prem tools, an EC2 reverse proxy between the NLB and the source may be needed.

Information to share with Atlan​

When you raise the support ticket to set up PrivateLink, provide the following. Gathering it up front turns a multi-round exchange into a single handoff.

DetailExample / notes
VPC endpoint service namecom.amazonaws.vpce.<region>.vpce-svc-0a1b2c3d4e5f6a7b8, from your endpoint service
Availability Zone IDs the service is enabled inusw2-az1, usw2-az2, use AZ IDs, not names like us-west-2a (they differ per account), or confirm cross-zone load balancing is on
Region of the endpoint serviceMust match your Atlan tenant's region
Acceptance mode of the endpoint serviceManual or automatic, so Atlan knows whether to wait for your approval
Per database: hostname / FQDNmydb.abc123.us-west-2.rds.amazonaws.com
Per database: engine and native portPostgreSQL 5432, SQL Server 1433, Oracle 1521
Per database: assigned NLB listener port5432, 5433, 5434, the port Atlan dials on the endpoint for that database
Per database: authentication methodCredential-based, or a cross-account IAM role (role ARN + external ID). Flag if RDS IAM auth is required, it triggers the private-hosted-zone mapping so the real hostname resolves
Which Atlan tenantProduction or non-production, each is a separate consumer with its own endpoint, principal, and CIDR ranges

In return, Atlan provides the tenant-specific values you need on your side: the principal to allowlist on the endpoint service, and the CIDR ranges to permit if you enforce inbound rules on the NLB. Ask for these in the same ticket. Once the endpoint is created and accepted, Atlan shares back the connection hostname (the vpce-… name, or your real FQDN if a private hosted zone was set up).

Set up connection​

Step 1: Create NLB and target groups​

  1. Create a Network Load Balancer in the same VPC as your database (or a VPC with routing to it).
  2. Add a TCP listener for each database, each on its own port, forwarding to a target group whose target is the database (IP or instance target) on its native port.
  3. Confirm every target group shows healthy before proceeding, an unhealthy target is the most common producer-side cause of timeouts later.
  4. Make sure the database's security group permits inbound from the NLB's subnets on the database port.

Step 2: Create VPC endpoint service​

  1. In the VPC console, create an Endpoint service backed by the NLB.
  2. Under Allowed principals, add the Atlan principal provided by support.
  3. Decide the acceptance setting: manual acceptance gives you an approval step for every new connection; automatic acceptance avoids a stalled setup but means an allowlisted principal connects without review.
  4. If "Enforce inbound rules on PrivateLink traffic" is enabled on the NLB, ask Atlan support for your tenant's CIDR ranges and add them to the NLB security group's inbound rules on each listener port. Production and non-production tenants use different ranges, adding the wrong environment's CIDRs produces a silent hang.

Step 3: Send details to Atlan​

Raise a support ticket with everything listed in Information to share with Atlan, the endpoint service name, AZ IDs, region, acceptance mode, the per-database details, and which Atlan tenant this connects to.

Step 4: Accept and validate​

  1. Atlan creates the interface endpoint; if acceptance is manual, approve the pending connection on your endpoint service.
  2. Atlan confirms the endpoint reaches Available, then shares back the connection hostname (the vpce-… name, or your real FQDN if a private hosted zone was set up).
  3. Atlan validates TCP reachability to each listener port, then authentication, before handing over for crawling.

Keeping it healthy​

Unlike the resource-gateway patterns, a classic PrivateLink has moving parts that decay silently:

  • Target IPs go stale. RDS failovers, migrations, and IP reassignments change the addresses behind your target groups. IP-type targets keep pointing at the old addresses, the endpoint and NLB look fine, but one listener times out while its neighbors work. Monitor target-group health, and prefer automation that re-resolves the database's DNS and updates targets.
  • Acceptance can drift. A change to the acceptance setting or a manually rejected connection silently drops all traffic. If a long-working connection dies with no change on Atlan's side, check the endpoint connection state on your endpoint service first.
  • Per-listener failures are normal. Because every database has its own listener and target group, breakage is often partial, two ports dead, two fine, all on the same endpoint. That pattern always points at the specific target groups, not the PrivateLink itself.

Limitations and considerations​

  • TCP only. Listeners are Layer 4 TCP; UDP-based protocols aren't supported, and there is no Layer 7 routing.
  • vpce-… hostnames break RDS IAM auth and strict TLS validation. Use the private-hosted-zone mapping wherever the client validates the hostname.
  • Same region by default. The interface endpoint lives in your tenant's region; cross-region endpoint services are exceptions arranged with Atlan support.
  • Per-database coordination. Every database added means NLB, target-group, listener, allowlist, and Atlan-side changes. This is the pattern's real cost at scale.
  • One endpoint per Atlan environment. Production and non-production tenants are separate consumers with separate endpoints, principals, and CIDR ranges.
  • Vendor SaaS sources don't use your NLB. Snowflake and Databricks private connectivity runs over endpoint services those vendors publish; the flow is different from this document and coordinated separately with Atlan support.

Troubleshooting​

Atlan reports the endpoint service "doesn't exist." The service exists but Atlan's principal isn't on the allowed principals list, AWS deliberately returns "not found" rather than "access denied." Also check for the wrong principal: allowlisting the non-production tenant's role for a production setup (or vice versa) fails identically.

Everything created, nothing connects. Check the endpoint connection state on your endpoint service, a connection stuck in Pending acceptance carries no traffic. Nothing proceeds until it's accepted.

Connection times out; Atlan's side checks out clean. The signature producer-side failure: packets reach the endpoint ENI in the Atlan VPC in under a millisecond, then silence. Work the producer checklist in order:

  1. Endpoint connection is Accepted.
  2. The NLB target group for that specific port is healthy.
  3. The database security group permits inbound from the NLB's subnets.
  4. NLB inbound-rule enforcement (if on) includes the correct tenant's CIDRs.
  5. No NACL, firewall, or OS-level rule blocks the port along the path.

"Authentication failed" on a setup that has never worked. Database drivers report unreachable servers as login timeouts (for example, SQL Server's HYT00 fires before any credential is ever evaluated). Treat first-time "auth" failures as network failures until a TCP connection to the listener port is proven. Conversely, an explicit Access denied for user means the network is fine, fix grants, or the role ARN / external ID pairing.

"It works from my machine." A local client connects to the database directly and never touches the PrivateLink path. Only a test that traverses the endpoint validates the path Atlan actually uses.

Some databases on the endpoint work, others don't. Per-listener breakage: the failing ports' target groups are unhealthy or pointing at stale IPs (commonly after an RDS failover). The shared endpoint and NLB are exonerated by the working ports.

A long-working connection suddenly stopped. In order: endpoint connection still Accepted; target-group health on the affected port; any security-group, CIDR, or IP change on your side in the breakage window. If the connection worked hours earlier and Atlan shipped no change, the cause is almost always a producer-side change.

Choosing private connectivity pattern​

Classic PrivateLink (this page)Resource gatewayVPC Lattice
You maintainNLB, listeners, target groups, healthA resource gateway + per-DB resource configurationGateway + configurations + one service network
Target/IP churnYour problem (target groups go stale)Handled by AWSHandled by AWS
Adding a databaseListener + target group + Atlan coordinationNew RAM share + endpointSelf-service association, no handoff
Reaches on-prem / anything routableYes, NLB targets any routable IPNo, VPC-resident resources onlyNo, VPC-resident resources only
Best forA few sources; on-prem; Redshift multi-account hubs; sources needing a proxyA few AWS-native databases, minimal infraTens to hundreds of databases

Classic PrivateLink remains the right answer when the source isn't a VPC-resident AWS resource, on-premises databases over Direct Connect, sources behind a reverse proxy, or multi-account Redshift hubs. For fleets of RDS/Aurora databases, prefer the resource-gateway or Lattice patterns.

See also​