Setting Up AWS PrivateLink for DataHub Cloud GMS Access – DataHub Customer Support Portal

Area: Deployment Issues

Sub-Area: AWS PrivateLink / VPC Endpoint Configuration

Issue

When connecting multiple AWS accounts to a DataHub Cloud instance via AWS PrivateLink, users often encounter confusion about what principal ARN to provide, how the allowlisting mechanism works, and how to correctly configure VPC Interface Endpoints. Additional complications can arise from availability zone (AZ) ID mismatches between the customer's account and the DataHub-managed endpoint service, as well as routing issues that produce HTTP 404 responses even after the PrivateLink connection appears healthy at the network layer.

Error Messages

InvalidParameter: The VPC endpoint service <service-name> does not support the availability zone of the subnet: <subnet-id>.
HTTP/2 404 — server: awselb/2.0 (returned when curling the GMS health or GraphQL endpoint over PrivateLink)

You Might Be Asking

Does DataHub need to assume a cross-account IAM role in my AWS account to set up PrivateLink?
What principal ARN format should I provide to DataHub Support to be allowlisted?
Can multiple AWS accounts share a single PrivateLink endpoint service?
Why do I get an AZ mismatch error even though my subnet is in us-east-1c?
Why am I getting 404s on /gms/health or /api/graphql even though TCP and TLS connections succeed over PrivateLink?

Solution

Step 1 — Understand the PrivateLink Architecture

DataHub Cloud operates as the provider of a VPC Endpoint Service backed by a Network Load Balancer (NLB). You act as the consumer who creates VPC Interface Endpoints in your own AWS account(s) that connect to DataHub's endpoint service.

DataHub does not assume any IAM role in your account.
DataHub does not require cross-account access of any kind.
DataHub adds your principal ARN(s) to the AllowedPrincipals list on its endpoint service, which permits your account(s) to create VPC Interface Endpoints pointing at that service.
Multiple AWS accounts can be allowlisted on the same endpoint service — you do not need a separate PrivateLink per account.

Step 2 — Provide Your Principal ARN(s) to DataHub Support

Open a support ticket and provide one of the following ARN formats for each AWS account that requires access:

IAM Role ARN (recommended): the role that will be used to create and manage the VPC endpoint in your account.
AWS Account root ARN: allows any principal in the account to create the endpoint.
IAM User ARN: for a dedicated service user (less common).

# IAM Role ARN (most common and most secure)
arn:aws:iam::<your-account-id>:role/<role-name>

# AWS Account root ARN
arn:aws:iam::<your-account-id>:root

# IAM User ARN
arn:aws:iam::<your-account-id>:user/<user-name>

Also include the AWS region(s) where you will be creating the VPC endpoints (e.g., us-east-1).

Step 3 — Receive the Endpoint Service Details from DataHub Support

After DataHub Support adds your ARN(s) to the allowlist, they will provide you with:

The VPC Endpoint Service Name (e.g., com.amazonaws.vpce.<region>.vpce-svc-<id>)
The private DNS hostname for your DataHub Cloud instance (e.g., <your-instance>.acryl.io)
The supported AZ IDs for the endpoint service (see Step 4)

Step 4 — Resolve Availability Zone ID Mismatches

AWS AZ names (e.g., us-east-1c) are not consistent across accounts — the same AZ name in two different accounts may map to different physical zones. AZ IDs (e.g., use1-az1) are consistent and must be used for matching.

Run the following command in each of your AWS accounts to map AZ names to AZ IDs:

aws ec2 describe-availability-zones \
  --region <your-region> \
  --query 'AvailabilityZones[].{ZoneName:ZoneName,ZoneId:ZoneId}' \
  --output table

Compare the output against the AZ IDs provided by DataHub Support. Select subnets that fall within the supported AZ IDs only. Subnets in unsupported AZ IDs will produce the following error:

InvalidParameter: The VPC endpoint service <service-name> does not support
the availability zone of the subnet: <subnet-id>.

Step 5 — Create the VPC Interface Endpoint

Create a VPC Interface Endpoint in each AWS account using the service name provided by DataHub Support. The example below uses Terraform:

resource "aws_vpc_endpoint" "datahub_privatelink" {
  vpc_id              = "<your-vpc-id>"
  service_name        = "com.amazonaws.vpce.<region>.vpce-svc-<id>"
  vpc_endpoint_type   = "Interface"
  subnet_ids          = [
    # Use only subnet IDs whose AZ IDs match those supported by DataHub's endpoint service
    "<subnet-in-supported-az-1>",
    "<subnet-in-supported-az-2>"
  ]
  security_group_ids  = ["<your-security-group-id>"]
  private_dns_enabled = true

  tags = {
    Name = "datahub-privatelink-endpoint"
  }
}

Ensure the security group attached to the endpoint allows inbound TCP 443 from any hosts or services that need to reach DataHub.

Step 6 — Verify Connectivity

After the endpoint is active, validate the connection from a host inside your VPC:

# 1. Confirm DNS resolves to a private (RFC-1918) IP address
getent hosts <your-instance>.acryl.io

# 2. Confirm TCP 443 is reachable
bash -c 'exec 3<>/dev/tcp/<your-instance>.acryl.io/443 && echo "TCP 443 OPEN" && exec 3>&-'

# 3. Confirm TLS handshake succeeds and resolves to a private IP
python3 - <<'EOF'
import socket, ssl
host, port = "<your-instance>.acryl.io", 443
ip = socket.gethostbyname(host)
print("resolved:", ip, "(should be a private 10.x VPC IP)")
ctx = ssl.create_default_context()
with socket.create_connection((host, port), timeout=5) as s:
    print("tcp: connected to", s.getpeername())
    with ctx.wrap_socket(s, server_hostname=host) as ss:
        print("tls:", ss.version(), "cn/san ok")
EOF

# 4. Test the GMS health endpoint
curl -i https://<your-instance>.acryl.io/gms/health

A successful result will show a private IP address (e.g., 10.x.x.x) for DNS resolution and an HTTP 200 response from the health endpoint.

Step 7 — Troubleshoot HTTP 404 Responses Over an Otherwise Healthy Connection

If TCP and TLS succeed but all HTTP requests to /gms/health or /api/graphql return HTTP 404 from awselb/2.0, the root cause is typically a routing misconfiguration on the DataHub side — specifically, the ALB listener rules for your tenant may not have been configured to route traffic correctly through the PrivateLink endpoint. This is not a problem you can resolve on your own.

Open or update a support ticket with DataHub and provide the output of your connectivity tests above.
Confirm with DataHub Support that the ALB routing rules for your tenant are correctly wired to the PrivateLink endpoint service.
DataHub Support will verify and update the backend routing configuration as needed.

Additional Notes

AZ ID mismatches are the most common cause of endpoint creation failures. Always use AZ IDs (not AZ names) to select subnets, and confirm the supported AZ IDs with DataHub Support before creating endpoints.
Multiple accounts, one endpoint service: All of your AWS accounts can be allowlisted on the same DataHub-managed endpoint service. Each account creates its own VPC Interface Endpoint pointing at the same service name.
No cross-account IAM configuration required: DataHub does not need any IAM permissions in your account. The only action required from you is providing your principal ARN(s) for allowlisting.
HTTP 404 after successful TLS is always a server-side routing issue and must be escalated to DataHub Support for backend correction.
This feature is available to DataHub Cloud (managed) customers. Self-hosted DataHub deployments handle their own networking configuration.