chore: updated guide to privatelink (supabase#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

Author: doublethink

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
 
-<Admonition type="caution">
+## Getting started
 
-PrivateLink connections are region-specific. Your VPC and Supabase project must be in the same AWS region to establish the connection.
+#### Step 1: Contact Supabase support
 
-</Admonition>
+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:
 
-## Getting started
+- Your Supabase organization slug
+- The specific projects you want to enable PrivateLink for (optional)
+- Your AWS Account ID(s)
+
+#### Step 2: Accept resource share
+
+Supabase will send you an AWS Resource Share containing the VPC Lattice Resource Configurations for your projects. To accept this share:
+
+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
 
-PrivateLink setup requires coordination between your team and Supabase. The process involves sharing your AWS Account ID(s) and accepting a Resource Share.
+##### Option B: Attach resource configuration to an existing VPC lattice service network
 
-### Setup process
+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
 
-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
+#### Step 5: Test connectivity
 
-### DNS and connectivity
+Verify the private connection is working correctly from your VPC:
 
-Once PrivateLink is configured:
+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:
 
-- 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
+```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:[email protected]: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
 

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",