Edmund AI Documentation
/SETUP GUIDES

Setup

Building the load balancer and endpoint service, creating the database user, and accepting Edmund's connection, with example values throughout.

Setup is done once, by the customer’s AWS administrators, in the account that holds the database. It needs permissions for Elastic Load Balancing, EC2 security groups and VPC endpoint services in that account.

Each step names the console location and gives the AWS CLI commands. The commands build on each other through shell variables, so they can be run in order in one terminal session.

1. Values

Edmund connects from the account below. These are the values for the Shared Cloud Deployment (SaaS).

ValueShared Cloud Deployment (SaaS)
Edmund’s AWS account ID285021992921
Edmund’s regioneu-west-1
Allowed principalarn:aws:iam::285021992921:root
Note

Other deployment models, such as Private SaaS, connect from a different account. For those, Edmund sends its account ID and region before setup starts.

Warning

Database in a different region from Edmund? If the region of the database is not Edmund’s region (eu-west-1 for the Shared Cloud Deployment (SaaS)), the connection is cross-Region. AWS then requires four things:

  1. The Network Load Balancer is enabled in at least two Availability Zones (AZs). The database itself can stay in one AZ; turn on cross-zone load balancing (step 3).
  2. Edmund’s region is added to the Supported Regions of the endpoint service (step 5).
  3. The load balancer keeps the default TCP idle timeout (step 3).
  4. Whoever creates the endpoint service has the vpce:AllowMultiRegion permission (step 5).

A few Availability Zones outside Europe don’t support cross-Region access; check the AZ IDs of your subnets against the list on the AWS page below.

See Cross-Region access in the AWS documentation.

The examples for your side use the values below. Replace them with your own. 444455556666 is AWS’s documentation example account ID.

ValueExample
Your AWS account ID444455556666
Region of the databaseeu-west-1
VPC of the databasevpc-0a1b2c3d4e5f67890
Subnets for the load balancersubnet-0aa11bb22cc33dd44, subnet-0ee55ff66aa77bb88
DatabaseAmazon RDS for PostgreSQL, plant-db.c1a2b3c4d5e6.eu-west-1.rds.amazonaws.com
Database private IP and port10.20.1.25, 5432
Database security groupsg-0d1b2c3d4e5f60718
Database name and schemaplant, maintenance

Set them once:

export AWS_REGION=eu-west-1
EDMUND_ACCOUNT=285021992921
EDMUND_REGION=eu-west-1
VPC_ID=vpc-0a1b2c3d4e5f67890
SUBNETS="subnet-0aa11bb22cc33dd44 subnet-0ee55ff66aa77bb88"
DB_IP=10.20.1.25
DB_PORT=5432
DB_SG=sg-0d1b2c3d4e5f60718

The private IP of an RDS database is what its endpoint resolves to:

dig +short plant-db.c1a2b3c4d5e6.eu-west-1.rds.amazonaws.com

2. Create a target group for the database

The target group tells the load balancer where the database is. In the console: EC2 → Target Groups → Create target group, target type IP addresses, protocol TCP.

TG_ARN=$(aws elbv2 create-target-group \
  --name edmund-db \
  --protocol TCP --port "$DB_PORT" \
  --target-type ip \
  --vpc-id "$VPC_ID" \
  --query 'TargetGroups[0].TargetGroupArn' --output text)

aws elbv2 register-targets \
  --target-group-arn "$TG_ARN" \
  --targets Id="$DB_IP",Port="$DB_PORT"
Warning

RDS and Aurora can change their IP address after a failover or maintenance. The target group keeps the old address, and Edmund cannot connect until it is updated. Keep the target current with AWS’s automated target update, or put RDS Proxy in front of the database and target its addresses instead.

3. Create the internal Network Load Balancer

In the console: EC2 → Load Balancers → Create load balancer → Network Load Balancer, scheme Internal, the database’s VPC, and a listener on the database port forwarding to the target group.

The load balancer gets its own security group, so the database firewall can refer to it in the next step.

For the Shared Cloud Deployment (SaaS), Edmund’s endpoint uses all three Availability Zones (AZs) of eu-west-1, so any AZ works when the database is also in eu-west-1. Two AZs are still recommended for availability. For other deployment models, Edmund confirms its AZs before setup, by AZ ID, because zone names differ between AWS accounts. If the database is in a different region, $SUBNETS must contain subnets in at least two AZs. Leave the TCP idle timeout at its default.

LB_SG=$(aws ec2 create-security-group \
  --group-name edmund-db-nlb \
  --description "Edmund PrivateLink load balancer" \
  --vpc-id "$VPC_ID" \
  --query GroupId --output text)

LB_ARN=$(aws elbv2 create-load-balancer \
  --name edmund-db \
  --type network \
  --scheme internal \
  --subnets $SUBNETS \
  --security-groups "$LB_SG" \
  --query 'LoadBalancers[0].LoadBalancerArn' --output text)

aws elbv2 create-listener \
  --load-balancer-arn "$LB_ARN" \
  --protocol TCP --port "$DB_PORT" \
  --default-actions Type=forward,TargetGroupArn="$TG_ARN"

If the load balancer has a zone without the database, turn on cross-zone load balancing, so the load balancer node in that zone can forward to the database. This is always the case for a cross-Region connection to a database in one AZ. With cross-zone load balancing on, AWS charges for data transfer between AZs. In the console: the load balancer’s Attributes tab → Edit → Cross-zone load balancing.

aws elbv2 modify-load-balancer-attributes \
  --load-balancer-arn "$LB_ARN" \
  --attributes Key=load_balancing.cross_zone.enabled,Value=true

Turn off inbound rule enforcement for PrivateLink traffic. Access is controlled by the endpoint service in step 5; with enforcement on, the load balancer drops Edmund’s connections. In the console: the load balancer’s Security tab → Edit → clear Enforce inbound rules on PrivateLink traffic.

aws elbv2 set-security-groups \
  --load-balancer-arn "$LB_ARN" \
  --security-groups "$LB_SG" \
  --enforce-security-group-inbound-rules-on-private-link-traffic off

4. Allow the load balancer through the database firewall

Add one inbound rule to the database’s security group: TCP on the database port, from the load balancer’s security group.

aws ec2 authorize-security-group-ingress \
  --group-id "$DB_SG" \
  --protocol tcp --port "$DB_PORT" \
  --source-group "$LB_SG"

Check the target’s health:

aws elbv2 describe-target-health \
  --target-group-arn "$TG_ARN" \
  --query 'TargetHealthDescriptions[0].TargetHealth.State' --output text
Success

The output is healthy within a few minutes.

5. Create the endpoint service and allow Edmund

In the console: VPC → Endpoint services → Create endpoint service, load balancer type Network, Acceptance required on. Then Allow principals on the new service.

If the database is in a different region from Edmund, add --supported-regions "$EDMUND_REGION" to the create command below. Whoever runs it needs the vpce:AllowMultiRegion IAM permission. In the console, select Edmund’s region under Service Regions in the create form.

If an endpoint service for this database already exists, skip the create-vpc-endpoint-service-configuration command and set SVC_ID to the existing service instead, for example SVC_ID=vpce-svc-0123456789abcdef0. Then run the remaining commands of the block: allow the principal and print the service name. If the database is in a different region from Edmund, first prepare the service as described in the note at the end of this step.

SVC_ID=$(aws ec2 create-vpc-endpoint-service-configuration \
  --network-load-balancer-arns "$LB_ARN" \
  --acceptance-required \
  --query 'ServiceConfiguration.ServiceId' --output text)

aws ec2 modify-vpc-endpoint-service-permissions \
  --service-id "$SVC_ID" \
  --add-allowed-principals "arn:aws:iam::${EDMUND_ACCOUNT}:root"

aws ec2 describe-vpc-endpoint-service-configurations \
  --service-ids "$SVC_ID" \
  --query 'ServiceConfigurations[0].ServiceName' --output text

The last command prints the service name, for example com.amazonaws.vpce.eu-west-1.vpce-svc-0123456789abcdef0.

Note

For an existing endpoint service in a different region from Edmund, do the following in this order:

  1. Set LB_ARN to the ARN of the existing load balancer of the service:

    LB_ARN=arn:aws:elasticloadbalancing:eu-west-1:444455556666:loadbalancer/net/edmund-db/0123456789abcdef
  2. Make sure the load balancer uses the default TCP idle timeout. Cross-Region access does not support a custom one.

  3. If the load balancer is in only one AZ, add a subnet in a second AZ to it. set-subnets replaces the subnet list, so list all subnets, the existing ones and the new one:

    aws elbv2 set-subnets \
      --load-balancer-arn "$LB_ARN" \
      --subnets subnet-0aa11bb22cc33dd44 subnet-0ee55ff66aa77bb88

    If the database stays in one AZ, also turn on cross-zone load balancing (step 3). The existing target group must not turn it off: its attribute load_balancing.cross_zone.enabled must be use_load_balancer_configuration (the default) or true.

    A new AZ is not enabled for the endpoint service automatically. Wait a few minutes until the load balancer’s new AZ is ready, then enable it. In the console: select the endpoint service → Actions → Associate or disassociate load balancers → Save changes.

    aws ec2 modify-vpc-endpoint-service-configuration --service-id "$SVC_ID"

    Check that both AZs are listed on the endpoint service’s Details tab.

  4. Only then add Edmund’s region. Whoever does this needs the vpce:AllowMultiRegion IAM permission too.

    aws ec2 modify-vpc-endpoint-service-configuration \
      --service-id "$SVC_ID" \
      --add-supported-regions "$EDMUND_REGION"

    You don’t need to list the endpoint service’s own region; it is always supported. In the console: select the endpoint service → Actions → Modify supported Regions. See Cross-Region access in the AWS documentation.

6. Create a read-only database user

Edmund only reads. For PostgreSQL, as the owner of the schema:

CREATE ROLE edmund_readonly LOGIN PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE plant TO edmund_readonly;
GRANT USAGE ON SCHEMA maintenance TO edmund_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA maintenance TO edmund_readonly;

Other engines are covered in specific database considerations.

7. Send the values to Edmund

Success

Five values. The password goes separately, through the channel agreed with your Edmund contact, never in the same message as the rest.

ValueExample
Service namecom.amazonaws.vpce.eu-west-1.vpce-svc-0123456789abcdef0
Regioneu-west-1
Database type and portPostgreSQL, 5432
Database name and schemaplant, maintenance
Useredmund_readonly

8. Accept Edmund’s connection request

Edmund creates its interface endpoint, which appears on your endpoint service as a pending connection. In the console: the endpoint service’s Endpoint connections tab → Actions → Accept endpoint connection request.

Check that the owner is Edmund’s account before accepting:

aws ec2 describe-vpc-endpoint-connections \
  --filters Name=service-id,Values="$SVC_ID" \
  --query 'VpcEndpointConnections[].[VpcEndpointId,VpcEndpointOwner,VpcEndpointState]' \
  --output text
vpce-0fedcba9876543210    285021992921    pendingAcceptance
aws ec2 accept-vpc-endpoint-connections \
  --service-id "$SVC_ID" \
  --vpc-endpoint-ids vpce-0fedcba9876543210

The state changes to available.

9. Connection test

Edmund connects as edmund_readonly, checks that the schema and its tables are visible, and runs a test query. Edmund confirms the result to your contact. In the database logs, the connections come from the load balancer’s private addresses.

Revoking access

Rejecting the connection cuts Edmund off immediately. Removing the principal prevents a new request.

aws ec2 reject-vpc-endpoint-connections \
  --service-id "$SVC_ID" \
  --vpc-endpoint-ids vpce-0fedcba9876543210

aws ec2 modify-vpc-endpoint-service-permissions \
  --service-id "$SVC_ID" \
  --remove-allowed-principals "arn:aws:iam::${EDMUND_ACCOUNT}:root"