From bae257c69fb8ac84e844f709cf2348c879184e2f Mon Sep 17 00:00:00 2001 From: Stephen Morgan Date: Thu, 17 Jul 2025 08:15:37 +1200 Subject: [PATCH] chore: updated guide to privatelink (#37186) * chore: updated guide to privatelink * Rule 1 linting fixes * Added options regex to Rule 1 * fix: prettier and one more lint * fix linting on doc --- .../content/guides/platform/privatelink.mdx | 141 ++++++++++++++---- supa-mdx-lint/Rule001HeadingCase.toml | 1 + 2 files changed, 111 insertions(+), 31 deletions(-) diff --git a/apps/docs/content/guides/platform/privatelink.mdx b/apps/docs/content/guides/platform/privatelink.mdx index a20f129cdfe..9cd13f47579 100644 --- a/apps/docs/content/guides/platform/privatelink.mdx +++ b/apps/docs/content/guides/platform/privatelink.mdx @@ -35,33 +35,122 @@ To use PrivateLink with your Supabase project: - AWS VPC in the same region as your Supabase project - Appropriate permissions to accept Resource Shares, and create and manage endpoints - - -PrivateLink connections are region-specific. Your VPC and Supabase project must be in the same AWS region to establish the connection. - - - ## Getting started -PrivateLink setup requires coordination between your team and Supabase. The process involves sharing your AWS Account ID(s) and accepting a Resource Share. +#### Step 1: Contact Supabase support -### Setup process +Reach out to your Enterprise account manager or [contact our team](https://supabase.com/contact/enterprise) to initiate PrivateLink setup. During this initial contact, be prepared to provide: -1. **Contact Supabase Support**: Reach out to your Enterprise account manager or [contact our team](https://supabase.com/contact/enterprise) to initiate PrivateLink setup -2. **Provide AWS Account Details**: Share your AWS Account ID(s) with our team. Optionally specify which Supabase projects you want to enable (otherwise all projects in your organization will be included) -3. **Accept Resource Share**: Supabase will send you an AWS Resource Share containing the VPC Lattice Resource Configurations for your projects. Accept this share from your AWS console -4. **Create Connection**: In your AWS account, either [create a PrivateLink endpoint](https://docs.aws.amazon.com/vpc/latest/privatelink/privatelink-access-resources.html) or [attach the Resource Configuration](https://docs.aws.amazon.com/vpc-lattice/latest/ug/service-network-associations.html) to an existing VPC Lattice Service Network -5. **Test Connectivity**: Verify the private connection is working correctly from your VPC -6. **Update Applications**: Configure your applications to use the private connection details -7. **Disable Public Connectivity**: Optionally, disable public internet access for your database to enforce private-only connectivity +- Your Supabase organization slug +- The specific projects you want to enable PrivateLink for (optional) +- Your AWS Account ID(s) -### DNS and connectivity +#### Step 2: Accept resource share -Once PrivateLink is configured: +Supabase will send you an AWS Resource Share containing the VPC Lattice Resource Configurations for your projects. To accept this share: -- You may configure a custom DNS record to point to your PrivateLink endpoint interface or the endpoints on.aws DNS record within your VPC -- Applications will need to be updated to use the PrivateLink endpoint -- Standard database monitoring and observability tools will continue to work through the private connection +1. Login to your AWS Management Console, ensure you are in the AWS region where your Supabase project is located +2. Navigate to the AWS Resource Access Manager (RAM) console + {/* supa-mdx-lint-disable-next-line Rule004ExcludeWords */} +3. Go to [Shared with me > Resource shares](https://console.aws.amazon.com/ram/home#SharedResourceShares) +4. Locate the resource share from Supabase. + - The resource share will have the format `cust-prod-[region]-pl-[organisation]-rc-share` +5. Click on the resource share name to view details. Review the list of resource shares - it should only include resources of type vpc-lattice:ResourceConfiguration. +6. Click **Accept resource share** +7. Confirm the acceptance in the dialog box + +{/* supa-mdx-lint-disable-next-line Rule004ExcludeWords */} +After accepting, you'll see the resource configurations appear in your [Shared with me > Shared resources](https://console.aws.amazon.com/ram/home#SharedResources) section of the RAM console and the [PrivateLink and Lattice > Resource configurations](https://console.aws.amazon.com/vpcconsole/home#ResourceConfigs) section of the VPC console. + +#### Step 3: Configure security groups + +Ensure your security groups allow traffic on the appropriate ports: + +1. Navigate to the [VPC console > Security Groups](https://console.aws.amazon.com/vpcconsole/home#SecurityGroups:) +2. Create a new security group for the endpoint or service network by clicking [Create security group](https://console.aws.amazon.com/vpcconsole/home#CreateSecurityGroup:) +3. Give your security group a descriptive name and select the appropriate VPC +4. Add an inbound rule for: + - Type: Postgres (TCP, port 5432) + - Destination that is appropriate for your network. i.e. the subnet of your VPC or security group of your application instances +5. Finish creating the security group by clicking **Create security group** + +#### Step 4: Create connection + +In your AWS account, you have two options to establish connectivity: + +##### Option A: Create a PrivateLink endpoint + +1. Navigate to the VPC console in your AWS account +2. Go to [Endpoints](https://console.aws.amazon.com/vpcconsole/home#Endpoints:) in the left sidebar +3. Click [Create endpoint](https://console.aws.amazon.com/vpcconsole/home#CreateVpcEndpoint:) +4. Give your endpoint a name (e.g. `supabase-privatelink-[project name]`) +5. Under Type, select **Resources** +6. In the **Resource configurations** section select the appropriate resource configuration + - The resource configuration name will be in the format `[organisation]-[project-ref]-rc` +7. Select your VPC from the dropdown. This should match the VPC you selected for your security group in Step 3 +8. Enable the **Enable DNS name** option if you want to use a DNS record instead of the endpoints IP address(es) +9. Choose the appropriate subnets for your network + - AWS will provision a private ENI for you in each selected subnet + - IP address type should be set to IPv4 +10. Choose the security group you created in Step 3. +11. Click **Create endpoint** +12. After creation, you will see the endpoint in the [Endpoints](https://console.aws.amazon.com/vpcconsole/home#Endpoints:) section with a status of "Available" +13. For connectivity: + - The IP addresses of the endpoint will be listed in the **Subnets** section of the endpoint details + - The DNS record will be in the **Associations** section of the endpoint details in the **DNS Name** field if you enabled it in step 8 + +##### Option B: Attach resource configuration to an existing VPC lattice service network + +1. **This method is only recommended if you have an existing VPC Lattice Service Network** +2. Navigate to the VPC Lattice console in your AWS account +3. Go to [Service networks](https://console.aws.amazon.com/vpcconsole/home#ServiceNetworks) in the left sidebar and select your service network +4. In the service network details, go to the **Resource configuration associations** tab +5. Click **Create associations** +6. Select the appropriate **Resource configuration** from the dropdown +7. Click **Save changes** +8. After creation, you will see the resource configuration in the Resource configurations section of your service network with the status "Active" +9. For connectivity, click on the association details and the domain name will be listed in the **DNS entries** section + +#### Step 5: Test connectivity + +Verify the private connection is working correctly from your VPC: + +1. Launch an EC2 instance or use an existing instance in your VPC +2. Install a Postgres client (e.g., `psql`) +3. Test the connection using the private endpoint: + +```bash +psql "postgresql://[username]:[password]@[private-endpoint]:5432/postgres" +``` + +You should see a successful connection without any public internet traffic. + +#### Step 6: Update applications + +Configure your applications to use the private connection details: + +1. Update your database connection strings to use the private endpoint hostname +2. Ensure your application instances are in the same VPC or connected VPCs +3. Update any database connection pooling configurations +4. Test application connectivity thoroughly + +Example connection string update: + +``` +# Before (public) +postgresql://user:pass@db.[project-ref].supabase.co:5432/postgres + +# After (private) +postgresql://user:pass@your-private-endpoint.vpce.amazonaws.com:5432/postgres +``` + +#### Step 8: Disable public connectivity (optional) + +For maximum security, you can disable public internet access for your database: + +1. Contact Supabase support to disable public connectivity +2. Ensure all applications are successfully using the private connection +3. Update any monitoring or backup tools to use the private endpoint ## Alpha limitations @@ -72,20 +161,10 @@ During the alpha phase: ## Compatibility -The PrivateLink endpoint behaves like a standard Postgres endpoint, allowing you to connect using: +The PrivateLink endpoint is a layer 3 solution so behaves like a standard Postgres endpoint, allowing you to connect using: - Direct Postgres connections using standard tools - Third-party database tools and ORMs (with the appropriate routing) -- (PgBouncer Projects Only) Directly to the pooler. - -## Use cases - -PrivateLink is ideal for organizations requiring: - -- **Regulatory Compliance**: Meeting strict data governance requirements that mandate private network connectivity -- **Enhanced Security**: Eliminating public internet exposure for sensitive database workloads -- **Corporate Policies**: Adhering to enterprise security policies that prohibit database connections over public networks -- **Performance Optimization**: Benefiting from reduced latency through AWS's private network infrastructure ## Next steps diff --git a/supa-mdx-lint/Rule001HeadingCase.toml b/supa-mdx-lint/Rule001HeadingCase.toml index 054d7f31a2d..c5afd292546 100644 --- a/supa-mdx-lint/Rule001HeadingCase.toml +++ b/supa-mdx-lint/Rule001HeadingCase.toml @@ -4,6 +4,7 @@ # Can also specify a regex that is compatible with the [Rust regex crate](https://docs.rs/regex/latest/regex/). may_uppercase = [ "[A-Z0-9]{2,5}s?", + "Option [A-Z]", "APIs", "Add-ons?", "Amazon RDS",