Skip to content

Commit 5d0f8c3

Browse files
bsod90Frank-TXS
bsod90
authored and
Frank-TXS
committed
docs(byoc): A doc explaining PrivateLink connectivity for AWS BYOC (cube-js#9783)
1 parent d596468 commit 5d0f8c3

File tree

5 files changed

+150
-0
lines changed

5 files changed

+150
-0
lines changed

‎docs/pages/product/deployment/cloud/byoc/_meta.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
module.exports = {
22
"aws": "AWS",
3+
"aws-privatelink": "AWS PrivateLink",
34
"azure": "Azure",
45
}

‎docs/pages/product/deployment/cloud/byoc/aws/_meta.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
module.exports = {
2+
deployment: "Deployment",
3+
privatelink: "Private Connectivity",
4+
};

‎docs/pages/product/deployment/cloud/byoc/aws.mdx‎ renamed to ‎docs/pages/product/deployment/cloud/byoc/aws/deployment.mdx‎

File renamed without changes.

‎docs/pages/product/deployment/cloud/byoc/aws/privatelink.mdx‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Private Connectivity with AWS PrivateLink
2+
3+
Cube Cloud BYOC deployments on AWS support private connectivity for Cube API endpoints using AWS PrivateLink. This enables secure, private access to your Cube deployment without exposing endpoints to the public internet.
4+
5+
<SuccessBox>
6+
7+
Private connectivity via AWS PrivateLink is available in Cube Cloud on the
8+
[Enterprise Premier](https://cube.dev/pricing) product tier with BYOC deployments.
9+
[Contact us](https://cube.dev/contact) for details.
10+
11+
</SuccessBox>
12+
13+
## Overview
14+
15+
In a private setup, Cube Cloud BYOC deployments can be configured to:
16+
- Keep HTTP and SQL load balancers private within the BYOC VPC
17+
- Expose API endpoints through AWS PrivateLink services
18+
- Enable secure connectivity from your VPCs and corporate networks
19+
20+
This approach ensures that all traffic between your applications and Cube Cloud remains within the AWS network backbone, never traversing the public internet.
21+
22+
## Architecture
23+
24+
With private connectivity enabled, Cube Cloud exposes two AWS PrivateLink services:
25+
- **HTTP API Service**: For REST API and GraphQL endpoints
26+
- **SQL API Service**: For PostgreSQL-compatible SQL interface connections
27+
28+
Your Cube deployment APIs are available on dedicated hostnames following this pattern:
29+
- HTTP API: `<deployment-id>.<byoc-region>.cubecloudapp.dev`
30+
- SQL API: `<deployment-id>.sql.<byoc-region>.cubecloudapp.dev`
31+
32+
<Screenshot src="https://ucarecdn.com/98e38433-3bb8-4f37-afea-7986170c63be/" />
33+
34+
## Setting up PrivateLink connections
35+
36+
### Step 1: Obtain PrivateLink service details
37+
38+
Contact Cube Cloud support to obtain the PrivateLink service details for your BYOC deployment. You'll receive:
39+
- HTTP NLB PrivateLink service name
40+
- SQL NLB PrivateLink service name
41+
- Your deployment ID and infrastructure region
42+
43+
### Step 2: Create VPC endpoints
44+
45+
In your AWS account, create two VPC endpoints for the Cube Cloud services:
46+
47+
1. Navigate to **AWS Console** → **VPC** → **Endpoints**
48+
2. Click **Create Endpoint**
49+
3. For the HTTP API endpoint:
50+
- **Service category**: Other endpoint services
51+
- **Service name**: Enter the HTTP NLB service name provided by Cube support
52+
- **VPC**: Select your target VPC
53+
- **Subnets**: Select appropriate subnets
54+
- **Security Group**: Create or select a security group allowing HTTPS traffic (port 443)
55+
4. Repeat for the SQL API endpoint:
56+
- Use the SQL NLB service name
57+
- Configure security group to allow PostgreSQL traffic (port 5432)
58+
59+
### Step 3: Configure DNS resolution
60+
61+
To enable proper hostname resolution, create a private Route 53 hosted zone:
62+
63+
1. Navigate to **AWS Console** → **Route 53** → **Hosted zones**
64+
2. Click **Create hosted zone**
65+
3. Configure the zone:
66+
- **Domain name**: `<byoc-region>.cubecloudapp.dev`
67+
- **Type**: Private hosted zone
68+
- **VPCs**: Associate with your target VPC(s)
69+
4. Create the following DNS records in the zone:
70+
71+
| Record Name | Type | Value |
72+
|------------|------|--------|
73+
| `*.<byoc-region>.cubecloudapp.dev` | A | Alias to HTTP VPC endpoint |
74+
| `*.sql.<byoc-region>.cubecloudapp.dev` | A | Alias to SQL VPC endpoint |
75+
| `sql.<byoc-region>.cubecloudapp.dev` | A | Alias to SQL VPC endpoint |
76+
77+
### Step 4: Verify connectivity
78+
79+
To test the connection from within your VPC, obtain the test connection commands from the Cube Cloud UI:
80+
1. Navigate to your deployment in Cube Cloud
81+
2. Access the connection details section
82+
3. Use the provided commands to verify HTTP API and SQL connectivity
83+
84+
## Enabling Cube Cloud UI access
85+
86+
The Cube Cloud web interface requires access to live Cube APIs to function properly. In a private setup, these APIs aren't accessible from user browsers by default, which would limit Cube Cloud functionality.
87+
88+
### Solution: Corporate network integration
89+
90+
To enable full Cube Cloud UI functionality, you need to establish PrivateLink endpoints within your corporate network:
91+
92+
1. **Create PrivateLink endpoints in your corporate VPC**: Follow the same process as above, but create the endpoints in a VPC that's accessible from your corporate network
93+
2. **Configure DNS resolution**: Choose one of these approaches:
94+
- **Cube-hosted DNS**: We can host the PrivateLink endpoint IPs in our public DNS records (contact Cube support)
95+
- **Corporate DNS override**: If you control DNS resolution within your corporate network, create private DNS overrides similar to the Route 53 configuration
96+
97+
<Screenshot src="https://ucarecdn.com/186b888f-ca1a-487b-aa41-968714ebce2f/" />
98+
99+
## Limitations
100+
101+
### No custom domain support
102+
103+
Cube Cloud's [custom domains feature][custom-domains] is not compatible with PrivateLink connectivity. This limitation exists because:
104+
105+
- Custom domains require automatic SSL certificate provisioning via Let's Encrypt
106+
- Let's Encrypt uses HTTP-01 challenges that require public internet accessibility
107+
- PrivateLink endpoints are not accessible from the public internet
108+
109+
If you require custom domains, consider using Cube Cloud's standard public endpoints with appropriate security controls.
110+
111+
## Troubleshooting
112+
113+
### Common issues
114+
115+
**DNS resolution failures**
116+
- Verify Route 53 hosted zone is associated with the correct VPC
117+
- Check that DNS records point to the correct VPC endpoints
118+
- Test resolution using `nslookup` or `dig` from within the VPC
119+
120+
**Connection timeouts**
121+
- Verify security groups allow traffic on required ports (443 for HTTP, 5432 for SQL)
122+
- Check that VPC endpoints are in "Available" state
123+
- Ensure network ACLs aren't blocking traffic
124+
125+
**Certificate errors**
126+
- Cube Cloud uses valid SSL certificates for `*.cubecloudapp.dev` domains
127+
- Ensure your client trusts standard certificate authorities
128+
- For SQL connections, configure your client to use SSL/TLS
129+
130+
### Getting help
131+
132+
For assistance with PrivateLink setup:
133+
1. Gather the following information:
134+
- VPC endpoint IDs
135+
- Security group configurations
136+
- DNS test results (`nslookup` output)
137+
- Any error messages from connection attempts
138+
2. Contact Cube Cloud support with your deployment ID and collected information
139+
140+
[custom-domains]: /product/deployment/cloud/custom-domains

‎docs/redirects.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,9 @@
11
[
2+
{
3+
"source": "/product/deployment/cloud/byoc/aws",
4+
"destination": "/product/deployment/cloud/byoc/deployment",
5+
"permanent": true
6+
},
27
{
38
"source": "/product/apis-integrations/rest-api/real-time-data-fetch",
49
"destination": "/product/apis-integrations/recipes/real-time-data-fetch",

0 commit comments

Comments
 (0)