From 34e867a9a594a9ee0a6de3f78fd0c5b1ba5b828b Mon Sep 17 00:00:00 2001 From: Benita Volkmann Date: Thu, 14 May 2026 13:38:52 +0200 Subject: [PATCH] Document self-serve flow in the dashboard, and polish existing wording according to our writing standards --- configuration/source-db/private-endpoints.mdx | 199 ++++++++++-------- resources/security.mdx | 2 - 2 files changed, 109 insertions(+), 92 deletions(-) diff --git a/configuration/source-db/private-endpoints.mdx b/configuration/source-db/private-endpoints.mdx index d34cdeb5..87592cb0 100644 --- a/configuration/source-db/private-endpoints.mdx +++ b/configuration/source-db/private-endpoints.mdx @@ -3,11 +3,7 @@ title: "Private Endpoints" description: "Connect PowerSync Cloud to your database over AWS PrivateLink without public internet exposure." --- -## PowerSync Cloud: AWS Private Endpoints - -To avoid exposing a database in AWS to the public internet, using AWS Private Endpoints ([AWS PrivateLink](https://aws.amazon.com/privatelink/)) is an option that provides private networking between the source database and the PowerSync Service. Private Endpoints are currently available on our [Team and Enterprise plans](https://www.powersync.com/pricing). - -We use Private Endpoints instead of VPC peering to ensure that no other resources are exposed between the VPCs. +Private Endpoints use [AWS PrivateLink](https://aws.amazon.com/privatelink/) to provide private networking between your source database and the PowerSync Service, without exposing the database to the public internet. They are available on our [Team and Enterprise plans](https://www.powersync.com/pricing) and can be managed in the [PowerSync Dashboard](https://dashboard.powersync.com/) under **Organization settings**. Do not rely on Private Endpoints as the only form of security. Always use strong database passwords, and use client certificates if additional security is required. @@ -16,30 +12,39 @@ Do not rely on Private Endpoints as the only form of security. Always use strong ## Current Limitations 1. Private Endpoints are currently only supported for Postgres and MongoDB instances. [Contact us](/resources/contact-us) if you need this for MySQL or SQL Server. -2. Self-service is not yet available on the PowerSync side — [contact PowerSync support](/resources/contact-us) to configure the instance. -3. Only AWS is supported currently — other cloud providers are not supported yet. -4. The **"Test Connection"** function on the [PowerSync Dashboard](https://dashboard.powersync.com/) is not supported yet — the instance has to be deployed to test the connection. +2. Only AWS is supported currently. Other cloud providers are not supported yet. +3. Private Endpoints can currently only be managed in the Dashboard. CLI support is not yet available. ## Concepts -* [AWS PrivateLink](https://aws.amazon.com/privatelink/) is the overarching feature on AWS. +* [AWS PrivateLink](https://aws.amazon.com/privatelink/) is the overarching AWS feature. -* **VPC/Private Endpoint Service** is the service that exposes the database, and lives in the same VPC as the source database. It provides a one-way connection to the database without exposing other resources in the VPC. +* **VPC/Private Endpoint Service** is the service that exposes the database. It lives in the same VPC as the source database and provides a one-way connection without exposing other resources in the VPC. - * **Endpoint Service Name** is a unique identifier for this Endpoint Service. + * **Service Name** is the unique identifier for the Endpoint Service, in the form `com.amazonaws.vpce..vpce-svc-`. * Each Endpoint Service may have multiple Private Endpoints in different VPCs. -* **VPC/Private Endpoint** is the endpoint in the PowerSync VPC. This is what the PowerSync instance connects to. +* **VPC/Private Endpoint** is the endpoint in the PowerSync VPC that the PowerSync instance connects to. + + * **VPC Endpoint ID** is the identifier of this endpoint, in the form `vpce-`. You use this ID to accept the connection on the Endpoint Service side. For custom Endpoint Services for Postgres: -* **Network Load Balancer (NLB)** is a load balancer that exposes the source database to the Endpoint Service. - * **Target Group** specifies the IPs and ports for the Network Load Balancer to expose. - * **Listener** for the Network Load Balancer is what describes the incoming port on the Network Load Balancer (the port that the PowerSync instance connects to). + +* **Network Load Balancer (NLB)** forwards traffic from the Endpoint Service to the source database. + * **Target Group** specifies the IPs and ports the NLB exposes. + * **Listener** describes the incoming port on the NLB (the port the PowerSync instance connects to). ## Private Endpoint Setup - - +The flow is the same for both supported source databases: configure an Endpoint Service in front of your database, create a matching Private Endpoint in the PowerSync Dashboard, accept the connection, then point your database connection at the endpoint. + + + + +Set up an Endpoint Service in front of your source database and copy its **Service Name**. + + + MongoDB Atlas supports creating an Endpoint Service per project for AWS. @@ -47,119 +52,133 @@ MongoDB Atlas supports creating an Endpoint Service per project for AWS. 1. Only Atlas clusters in AWS are supported. 2. The Atlas cluster must be in one of the PowerSync [AWS regions](#aws-regions). Cross-region endpoints are not yet supported by MongoDB Atlas. -3. This is only supported for _Atlas_ clusters — PowerSync does not support PrivateLink for MongoDB clusters self-hosted in AWS. +3. PowerSync does not support PrivateLink for MongoDB clusters self-hosted in AWS, only Atlas clusters. -### 1. Configure the Endpoint Service +To configure the Endpoint Service: 1. In the Atlas project dashboard, go to **Network Access** → **Private Endpoint** → **Dedicated Cluster**. 2. Select **Add Private Endpoint**. 3. Select **AWS** and the relevant AWS region. 4. Wait for the **Endpoint Service** to be created. -5. "Your VPC ID" and "Your Subnet IDs" are not relevant for PowerSync - leave those blank. -6. Avoid running the command to create the "VPC Interface Endpoint"; this step is handled by PowerSync. -7. Note the **Endpoint Service Name**. This is displayed in the command to run, as the `--service-name` option. - -The Service Name should look something like `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`. +5. Leave "Your VPC ID" and "Your Subnet IDs" blank. They are not relevant for PowerSync. +6. Do not run the command to create the "VPC Interface Endpoint". PowerSync handles this step. +7. Note the **Endpoint Service Name** displayed in the command, as the `--service-name` option. It should look like `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`. -Skip the final step of configuring the "VPC Endpoint ID" — this will be done later. +Skip the final step of configuring the "VPC Endpoint ID". You will provide this in a later step. -### 2. PowerSync Setup + + -On PowerSync Cloud, create a new instance, but do not configure the connection yet. Copy the **Instance ID**. +To expose a Postgres database via PrivateLink, you need a Network Load Balancer that forwards traffic to the database. This works for Postgres running on EC2 or RDS. -[Contact us](/resources/contact-us) and provide: -1. The **Endpoint Service Name**. -2. The PowerSync **Instance ID**. - -We will then configure the instance to use the Endpoint Service for the database connection, and provide you with a **VPC Endpoint ID**, in the form `vpce-12346`. - -### 3. Finish Atlas Endpoint Service Setup - -On the Atlas Private Endpoint Configuration, in the final step, specify the **VPC Endpoint ID** from above. -If you have already closed the dialog, go through the process of creating a Private Endpoint again. It should have the same Endpoint Service Name as before. - -Check that the **Endpoint Status** changes to _Available_. - -### 4. Get the Connection String + +For AWS RDS, the steps below do not handle dynamic IPs if the RDS instance's IP changes. This is specifically relevant when using an RDS cluster with failover support. See this [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) for handling IP changes automatically. + -1. On the Atlas cluster, select **Connect**. -2. Select **Private Endpoint** as the connection type, and select the provisioned endpoint. -3. Select **Drivers** as the connection method, and copy the connection string. +1. **Create a Target Group**: + 1. Obtain the RDS instance's private IP address. Make sure this points to a writable instance. + 2. Create a **Target Group** with IP addresses as the target type, using the IP from above. Use TCP protocol and the database port (typically `5432` for Postgres). +2. **Create a Network Load Balancer (NLB)**: + 1. Select the same VPC as your RDS instance. + 2. Select at least two subnets in different availability zones. + 3. Configure a TCP listener on a port of your choice (for example, `5432`). + 4. Associate the listener with the target group from the previous step. +3. **Modify the security group** associated with your RDS instance to permit traffic from the load balancer IP range. +4. **Create a VPC Endpoint Service**: + 1. In the AWS Management Console, go to the VPC service and select **Endpoint Services**. + 2. Click **Create Endpoint Service**. + 3. Select the Network Load Balancer from the previous step. + 4. If the load balancer is in one of the PowerSync [AWS regions](#aws-regions), you do not need to select any "Supported Region". If the load balancer is in a different region, select the region corresponding to your PowerSync instance. Cross-region support incurs additional AWS charges. + 5. Decide whether to require acceptance for endpoint connections. Disabling acceptance simplifies the process but reduces control over connections. + 6. Under **Supported IP address types**, select both IPv4 and IPv6. + 7. Note the **Service Name**. You will use this when creating the Private Endpoint in the PowerSync Dashboard. + 8. Configure the Endpoint Service to accept connections from the principal `arn:aws:iam::131569880293:root`. See the [AWS documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for details. -The connection string should look something like `mongodb+srv://:@your-cluster-pl-0.abcde.mongodb.net/`. + + -### 5. Deploy + -Once the Private Endpoint has been created on the PowerSync side, it will be visible in the instance settings -under the connection details, as **VPC Endpoint Hostname**. + -Configure the instance the connection string from the previous step, then deploy. -Monitor the logs to ensure the instance can connect after deploying. +In the [PowerSync Dashboard](https://dashboard.powersync.com/), open your organization's **Settings** and locate the **Private Endpoints** section. - - +1. Click **Create**. +2. Provide the following details: + * **Name**: a recognizable name for the endpoint (for example, `my-private-endpoint`). + * **Service Name**: the Endpoint Service Name from the previous step (for example, `com.amazonaws.vpce.us-east-1.vpce-svc-0123456`). + * **Region**: the AWS region of your Endpoint Service. This must match the region of the PowerSync instance you plan to use the endpoint with. +3. Click **Create**. -To configure a Private Endpoint Service, a network load balancer is required to forward traffic to the database. + +A Private Endpoint can only be used by PowerSync instances in the same region. Endpoints in other regions will not appear in the connection form. + -This can be used with a Postgres database running on an EC2 instance, or an RDS instance. +The endpoint is created in a `Pending` state. Once PowerSync provisions the VPC Endpoint in its VPC, the status transitions to `Pending acceptance` and the **VPC Endpoint ID** (in the form `vpce-`) becomes available on the endpoint's card. -For AWS RDS, the guide below does not handle dynamic IPs if the RDS instance's IP changes. This needs additional work to automatically update the IP — see this [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) on the topic. This is specifically relevant if using an RDS cluster with failover support. + -Use the following steps to configure the Endpoint Service: + -### 1. Create a Target Group +Copy the **VPC Endpoint ID** from the endpoint's card in the Dashboard and use it to accept the connection on the Endpoint Service side. -1. Obtain the RDS instance's private IP address. Make sure this points to a writable instance. -2. Create a **Target Group** with IP addresses as target type, using the IP address from above. Use TCP protocol, and specify the database port (typically `5432` for Postgres). + + -Note: The IP address of your RDS instance may change over time. To maintain a consistent connection, consider implementing automation to monitor and update the target group's IP address as needed. See the [AWS blog post](https://aws.amazon.com/blogs/database/access-amazon-rds-across-vpcs-using-aws-privatelink-and-network-load-balancer/) on the topic. +In the Atlas Private Endpoint configuration, complete the final step by entering the **VPC Endpoint ID** from the PowerSync Dashboard. -### 2. Create a Network Load Balancer (NLB) +If you have already closed the configuration dialog in Atlas, start the Private Endpoint creation process again. The wizard should show the same Endpoint Service Name as before. -1. Select the same VPC as your RDS instance. -2. Select at least two subnets in different availability zones. -3. Configure a TCP listener and pick a port (for example `5432` again). -4. Associate the listener with the target group created earlier. + + -### 3. Modify the Security Group +If you required acceptance when creating the Endpoint Service, go to **VPC** → **Endpoint Services** in the AWS Management Console, select your service, and accept the connection request matching the **VPC Endpoint ID**. -1. Modify the security group associated with your RDS instance to permit traffic from the load balancer IP range. +If you disabled acceptance, the connection is accepted automatically and no action is needed here. -### 4. Create a VPC Endpoint Service + + -1. In the AWS Management Console, navigate to the VPC service and select **Endpoint Services**. -2. Click on **Create Endpoint Service**. -3. Select the Network Load Balancer created in the previous step. -4. If the load balancer is in one of the PowerSync regions (see below), it is not required to select any "Supported Region". If the load balancer is in a different region, select the region corresponding to your PowerSync instance here. Note that this will incur additional AWS charges for the cross-region support. -5. Decide whether to require acceptance for endpoint connections. Disabling acceptance can simplify the process but may reduce control over connections. -6. Under **Supported IP address types**, select both IPv4 and IPv6. -7. After creating the endpoint service, note the **Service Name**. This identifier will be used when configuring PowerSync to connect via PrivateLink. -8. Configure the Endpoint Service to accept connections from the principal `arn:aws:iam::131569880293:root`. See the [AWS documentation](https://docs.aws.amazon.com/vpc/latest/privatelink/configure-endpoint-service.html#add-remove-permissions) for details. + + -### 5. PowerSync Setup +The endpoint's status in the Dashboard reflects the AWS connection state: -On PowerSync Cloud, create a new instance, but do not configure the connection yet. +| Status | Meaning | +| --- | --- | +| `Pending` | The endpoint is being provisioned. | +| `Pending acceptance` | Waiting for you to accept the connection on the Endpoint Service. | +| `Available` | Ready to use. | +| `Rejected` | The connection was rejected by the Endpoint Service. | +| `Failed` | Endpoint creation failed. | -[Contact us](/resources/contact-us) and provide the Service Name from above, as well as the PowerSync instance ID created above. We will then configure the instance to use the Endpoint Service for the database connection. +Once the status changes to `Available`, the endpoint can be selected when configuring a database connection. -### 6. Deploy + -Once the Private Endpoint has been created on the PowerSync side, it will be visible in the instance settings -under the connection details, as **VPC Endpoint Hostname**. + -Verify the connection details, and deploy the instance. Monitor the logs to ensure the instance can connect after deploying. +1. In the Dashboard, open the PowerSync instance and go to the **Database Connections** view. +2. Click **Connect to Source Database** (or edit an existing connection) and select the **Postgres** or **MongoDB** tab. +3. In the **Private Endpoint** dropdown, select your endpoint. Only endpoints in the same region as the instance with status `Available` are selectable. +4. Fill in the rest of the connection details: + * **For Postgres**: enter your database connection details as usual. PowerSync routes traffic through the Private Endpoint to your load balancer. + * **For MongoDB Atlas**: on the Atlas cluster, click **Connect**, choose **Private Endpoint** as the connection type, select the provisioned endpoint, choose **Drivers** as the connection method, and copy the resulting connection string. It should look something like `mongodb+srv://:@your-cluster-pl-0.abcde.mongodb.net/`. Paste it into the **URI** field in the Dashboard. +5. Click **Test Connection** and resolve any errors. +6. Click **Save Connection**. +PowerSync deploys and configures an isolated cloud environment for you, which can take a few minutes. Monitor the logs to confirm the instance connects. - - + + ## AWS Regions PowerSync Cloud currently runs in the AWS regions below. Make sure the region matching your PowerSync instance is supported by the Endpoint Service. - 1. US: `us-east-1` - 2. EU: `eu-west-1` - 3. BR: `sa-east-1` - 4. JP: `ap-northeast-1` - 5. AU: `ap-southeast-2` +1. US: `us-east-1` +2. EU: `eu-west-1` +3. BR: `sa-east-1` +4. JP: `ap-northeast-1` +5. AU: `ap-southeast-2` diff --git a/resources/security.mdx b/resources/security.mdx index dabae338..0760e720 100644 --- a/resources/security.mdx +++ b/resources/security.mdx @@ -23,8 +23,6 @@ SOC 2 Type 2 audit reports are available to customers on the [Team and Enterpris See [Private Endpoints](/configuration/source-db/private-endpoints) for using a private network to your database using AWS PrivateLink. -We use Private Endpoints instead of VPC peering, to ensure that no other resources are exposed between VPCs. - ### HIPAA Compliance PowerSync Cloud is HIPAA compliant. You can sync Protected Health Information (PHI) or electronic PHI (ePHI) using PowerSync Cloud provided that you fulfill your obligations under our shared responsibility model. Refer to our [HIPAA Compliance](/resources/hipaa) page for details.