​
Customer Setup

When creating a new database instance within Springtail, that database may either be accessed via a public endpoint, or via a PrivateLink connection within AWS. Regardless of the connection type, the following steps must be performed. These steps can be performed either in AWS Web Console or using AWS CLI. Both are listed here for reference. The following steps can be performed in any order. For both deployment types, the following actions are needed to be done on the primary database.

​
1. Set the WAL_LEVEL to logical

In the RDS console, click “Parameter groups” on the left navigation. Then “Create parameter group” and create a new parameter group with the family the same as the primary database. For Aurora PostgreSQL, select the parameter type as the “cluster parameter group”. This will create a clone of the default parameter group. Then, under “edit” mode, search for the rds.logical_replication parameter and set it to 1. After saving the changes, associate the new parameter group with the primary database. You may want to apply the changes immediately if possible

​
2. Set the max_replication_slots to a reasonable value

Similar to Item 1 above, modify the max_replication_slots parameter to a value that is sufficient for the number of replication slots that will be used by the Springtail service. This number should be equal to or greater than the number of DBs in the primary database. One replication slot per replicated database is required.

​
3. Set the max_slot_wal_keep_size to a reasonable value

This should be set to a value that limits the amount of WAL (write-ahead log) that can be retained in the primary database. This is to ensure that the primary database does not run out of disk space due to the log retention. If the write-ahead log is not actively consumed, e.g., a replication slot has been created but is not in use, then the database’s disk can start to fill up with records to be replicated. Similar to the Item 1 above, modify the max_slot_wal_keep_size parameter to a value that won’t fill up the disk space of the primary database. We recommend it is set to a minimum of 2GB, but ideally to ~5% of the disk space allocated to the instance. Note: This is a worst-case scenario, and in typically usage not much of the WAL will have to be saved on disk.

​
4. Other settings that may be of interest

  • max_wal_senders and max_logical_replication_workers Set these parameters to a value that’s at least equal to the number of active logical replication slots.
  • max_worker_processes Set this parameter to a value that’s at least equal to the total of the max_logical_replication_workers, autovacuum_max_workers, and max_parallel_workers values.
External documentation: Aurora RDS Postgres Important: Pay attention to the region when performing the following actions. When using the command line, make sure to set the region using the --region flag explicitly. Or if you are running assistant scripts we provide please use AWS_REGION=<actual region> before the command.

​
1. Enable DNS Resolution and DNS Hostnames

Note: This step must be completed on all customer VPCs that are peered with us.
  • With AWS Web Console
    • Navigate to the VPC details page.
    • Click the “Actions” button and select “Edit VPC settings”.
    • In the “DNS settings” section, check both “Enable DNS resolution” and “Enable DNS hostnames” options.
  • With AWS CLI 
    $ aws ec2 modify-vpc-attribute --vpc-id {{customer_vpc_id}} --enable-dns-support
$ aws ec2 modify-vpc-attribute --vpc-id {{customer_vpc_id}} --enable-dns-hostnames

​
2. Accept VPC Peering Connection

Note: This step must be completed on all customer VPCs that are peered with us.
  • With AWS Web Console
    • Go to the VPC dashboard and select “Peering connections” from the left navigation.
    • In the main list view, select the peering connection with the ID equal to {{vpc_peering_connection_id}}.
    • Click “Actions” and select “Accept Request”.
    • Once the Peering Connection is accepted, click on the “DNS” tab for that connection, and ensure the “Allow requester VPC to resolve DNS of hosts in accepter VPC to private IP addresses” is enabled. If it isn’t, click “Edit DNS Settings” to enable it.
  • With AWS CLI 
    $ aws ec2 accept-vpc-peering-connection --vpc-peering-connection-id {{vpc_peering_connection_id}}
$ aws ec2 modify-vpc-peering-connection-options --vpc-peering-connection-id {{vpc_peering_connection_id}} --accepter-peering-connection-options 'AllowDnsResolutionFromRemoteVpc=true'

​
3. Update the Route Table

  • With AWS Web Console
    • Go to the RDS console and click on the database instance details. In the “Connectivity & security” tab, note all subnet IDs or click into the subnets.
    • For each subnet listed in the “Subnet” section under the VPC dashboard, select the subnet, click the “Route Table” tab, and then click the Route Table ID.
    • In the Route Table list view, select the route table.
    • In the “Routes” tab, click “Edit routes”.
    • Add a new route with the destination CIDR block equal to {{transit_vpc_cidr_block}} and the target as the VPC Peering Connection ID, {{vpc_peering_connection_id}}.
  • With AWS CLI 
    $ aws rds describe-db-instances --db-instance-identifier {{db_instance_identifier}} --query "DBInstances[0].[DBSubnetGroup.VpcId, DBSubnetGroup.Subnets]"
# Note the VPC ID and Subnet IDs
$ aws ec2 describe-route-tables --filters "Name=vpc-id,Values={{customer_vpc_id}}" "Name=association.subnet-id,Values={{subnet_ids}}" --query "RouteTables[*].RouteTableId"
# Note the Route Table IDs
$ aws ec2 create-route --route-table-id {{route_table_id}} --destination-cidr-block {{transit_vpc_cidr_block}} --vpc-peering-connection-id {{vpc_peering_connection_id}}

​
4. Configure Security Groups for the Primary Database

  • With AWS Web Console
    • Go to the RDS console and click on the database instance details.
    • In the “Connectivity & security” tab, note the security group ID.
    • Navigate to the EC2 console, select “Security Groups” from the left navigation.
    • In the main list view, select the security group with the ID equal to the noted security group ID.
    • In the “Inbound rules” tab, click “Edit inbound rules”.
    • Add a new rule with the following settings:
      • Type: PostgreSQL
      • Protocol: TCP
      • Port Range: {{db_port}}
      • Source: {{inbound_nlb_security_group_id}}
      • Security Group ID: {{database_security_group_id}}
  • With AWS CLI Add an ingress rule to allow connections from {{inbound_nlb_security_group_short_id}} and {{provider_account_id}} to the primary database instance security group. 
    $ aws ec2 authorize-security-group-ingress --group-id {{database_security_group_id}} --protocol tcp --port {{db_port}} --source-group {{inbound_nlb_security_group_short_id}} --group-owner {{provider_account_id}}

​
5. Associate VPC with Private Hosted Zone (for Private DNS Resolution)

Note: This step must be done for all application VPCs that are peered.
  • With AWS CLI Note: This step requires the use of AWS CLI, as there is no Web Console support. Associate the VPC with the private hosted zone created in the Provider Account. The private hosted zone ID is output as {{private_hosted_zone_id}}. 
    $ aws route53 associate-vpc-with-hosted-zone --hosted-zone-id {{private_hosted_zone_id}} --vpc VPCRegion={{customer_vpc_region}},VPCId={{customer_vpc_id}} --region {{region}}

​
6. Allow Egress from Customer Application to the Transit VPC

Note: This step must be done on all application VPCs on the customer side that are peered, to allow applications within those VPCs to access the Springtail services.
  • With AWS Web Console
    • Go to the EC2 console and select “Security Groups” from the left navigation.
    • In the main list view, select the security group used for EC2 instances or other resources that will access Springtail’s endpoint.
    • In the “Outbound rules” tab, click “Edit outbound rules”.
    • Add a new rule with the following settings:
      • Type: All traffic
      • Protocol: All
      • Port Range: All
      • Destination: {{transit_vpc_cidr_block}}
  • With AWS CLI 
    $ aws ec2 authorize-security-group-egress --group-id {{application_security_group_id}} --protocol all --port all --cidr {{transit_vpc_cidr_block}}

​
Customer IAM Role / User Permissions

Below listed an example policy the customer can use to grant the necessary permissions to their IAM role/user to perform the above actions. 
 AWS IAM Policy required for customer actions is below,
 {
     "Version": "2012-10-17",
     "Statement": [
         {
             "Effect": "Allow",
             "Action": [
                 "ec2:AcceptVpcPeeringConnection",
                 "ec2:DescribeVpcPeeringConnections",
                 "ec2:DescribeVpcAttribute",
                 "ec2:ModifyVpcAttribute",
                 "ec2:DescribeSubnets",
                 "ec2:DescribeRouteTables",
                 "ec2:CreateRoute",
                 "ec2:DeleteRoute"
                 "route53:AssociateVPCWithHostedZone",
                 "rds:DescribeDBInstances",
                 "ec2:AuthorizeSecurityGroupIngress",
                 "ec2:AuthorizeSecurityGroupEgress",
                 "ec2:DescribeSecurityGroups",
             ],
             "Resource": [
               "arn:aws:ec2:{{region}}:{{customer-account-id}}:vpc-peering-connection/{{vpc-peering-connection-id}}", # repeat this for for each customer database for each VPC peering connection
               "arn:aws:ec2:{{region}}:{{customer-account-id}}:vpc/{{vpc-id}}", # repeat this for for each customer database / application VPC
               "arn:aws:ec2:{{region}}:{{customer-account-id}}:subnet/*",
               "arn:aws:ec2:{{region}}:{{customer-account-id}}:route-table/*",
               "arn:aws:rds:{{region}}:{{customer-account-id}}:db:{{db-instance-id}}",
               "arn:aws:ec2:{{region}}:{{customer-account-id}}:security-group/*",
               "arn:aws:route53::{{service-account-id}}:hostedzone/{{hosted-zone-id}}",
             ]
         }
     ]

​
Placeholder Reference

  • {{customer_vpc_id}}: VPC ID of the customer’s VPC.
  • {{vpc_peering_connection_id}}: ID of the VPC Peering Connection between the customer VPC and the provider VPC.
  • {{db_instance_identifier}}: Database instance identifier in the RDS service.
  • {{subnet_ids}}: Comma-separated list of subnet IDs associated with the VPC.
  • {{route_table_id}}: Route Table ID in the customer VPC.
  • {{transit_vpc_cidr_block}}: CIDR block of the Transit VPC in the provider account.
  • {{db_port}}: Port on which the database is listening.
  • {{database_security_group_id}}: Security group ID of the primary database instance.
  • {{inbound_nlb_security_group_id}}: Security group ID for the inbound NLB in long format <account_id>/<security_group_id>.
  • {{inbound_nlb_security_group_short_id}}: The Security group ID part of {{inbound_nlb_security_group_id}}.
  • {{provider_account_id}}: The AWS Account part of {{inbound_nlb_security_group_id}}.
  • {{private_hosted_zone_id}}: ID of the private hosted zone returned in the VPC Config.
  • {{region}}: AWS region where the VPC or hosted zone is located.
  • {{customer_vpc_region}}: AWS region where the customer VPC for applications is located.
  • {{application_security_group_id}}: Security group ID of the customer applications.