Skip to content

Docs 551 AWS Hub and Spoke deployment guide #1124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Chr1st0ph3rTurn3r wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Docs 551 AWS Hub and Spoke deployment guide #1124

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3f4a2b5
creating AWS conductor deployment guide
Chr1st0ph3rTurn3r Aug 20, 2026
e8e0ea9
text edits for first draft of AWS conductor deployment guide
Chr1st0ph3rTurn3r Aug 20, 2026
19ca327
creating AWS hub and spoke deployment guides
Chr1st0ph3rTurn3r Aug 20, 2026
3c6b3de
updating sizing/scaling tables
Chr1st0ph3rTurn3r Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/_deploy_aws_conductor_network_design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
<!--- AWS Conductor Deployment Guide - Network Design Reference --->

The following IP addressing and naming scheme is used consistently throughout this guide. Substitute your own values when configuring your environment.

| Parameter | Example Value | Description |
|-----------|--------------|-------------|
| Authority Name | `Authority128` | Organizational authority name |
| Conductor Name | `Conductor` | Conductor system name |
| Conductor Node Name | `node0` | Conductor node name |
| Conductor Instance Type | `c5.xlarge` | AWS EC2 instance size |
| Conductor VPC CIDR | `10.0.0.0/16` | AWS VPC for the conductor |
| Conductor Subnet CIDR | `10.0.1.0/24` | Control subnet within the conductor VPC |
| Conductor Private IP | `10.0.1.10` | Private IP assigned to the conductor ENI |
| Conductor Elastic IP | `203.0.113.10` | AWS Elastic IP — the address managed routers use to reach this conductor |
| SSR Version | `7.1.4` | SSR software version installed via BYOL |
| Tenant Name | `corp` | LAN-side user tenant |
| Service Name | `Internet-Traffic` | Internet breakout service |
| Service Address | `0.0.0.0/0` | All internet-bound traffic |
| Router Name | `aws-branch1` | Example router name |
| Router Node Name | `node0` | Router node name |
| Router Instance Type | `c5.xlarge` | AWS EC2 instance size |
| Router WAN Subnet | `10.1.1.0/24` | WAN (public) subnet in the router VPC |
| Router LAN Subnet | `10.1.2.0/24` | LAN (private) subnet in the router VPC |
| Router WAN Elastic IP | `203.0.113.20` | Elastic IP on the router WAN ENI (external peering address) |
| Router LAN IP | `10.1.2.1` | Static LAN gateway address on the router |
34 changes: 34 additions & 0 deletions docs/_deploy_aws_hub_spoke_network_design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<!--- AWS Hub and Spoke Router Deployment Guide - Network Design Reference --->

The following IP addressing and naming scheme is used consistently throughout this guide. Substitute your own values when configuring your environment.

| Parameter | Example Value | Description |
|-----------|--------------|-------------|
| Authority Name | `Authority128` | Organizational authority name |
| Conductor Name | `Conductor` | Pre-existing conductor system name |
| Conductor Elastic IP | `203.0.113.10` | AWS Elastic IP — the address managed routers use to reach this conductor |
| SSR Version | `7.1.4` | SSR software version installed via BYOL |
| Tenant Name | `corp` | LAN-side user tenant (authority-wide) |
| Service Name | `Internet-Traffic` | Internet breakout service (authority-wide) |
| Service Address | `0.0.0.0/0` | All internet-bound traffic |
| Neighborhood Name | `internet` | Shared SVR neighborhood name |
| Hub Router Name | `aws-hub1` | Hub router system name |
| Hub Node Name | `node0` | Hub router node name |
| Hub Instance Type | `c5.xlarge` | AWS EC2 instance size |
| Hub VPC CIDR | `10.2.0.0/16` | AWS VPC for the hub router |
| Hub WAN Subnet | `10.2.1.0/24` | WAN (public) subnet in the hub VPC |
| Hub LAN Subnet | `10.2.2.0/24` | LAN (private) subnet in the hub VPC |
| Hub WAN Elastic IP | `203.0.113.30` | Elastic IP on the hub WAN ENI (external peering address) |
| Hub LAN IP | `10.2.2.1` | Static LAN gateway address on the hub |
| Hub WAN PCI Address | `0000:00:06.0` | PCI address of the hub WAN ENI (`eth1`) |
| Hub LAN PCI Address | `0000:00:07.0` | PCI address of the hub LAN ENI (`eth2`) |
| Spoke Router Name | `aws-spoke1` | Spoke router system name |
| Spoke Node Name | `node0` | Spoke router node name |
| Spoke Instance Type | `c5.xlarge` | AWS EC2 instance size |
| Spoke VPC CIDR | `10.1.0.0/16` | AWS VPC for the spoke router |
| Spoke WAN Subnet | `10.1.1.0/24` | WAN (public) subnet in the spoke VPC |
| Spoke LAN Subnet | `10.1.2.0/24` | LAN (private) subnet in the spoke VPC |
| Spoke WAN Elastic IP | `203.0.113.20` | Elastic IP on the spoke WAN ENI (external peering address) |
| Spoke LAN IP | `10.1.2.1` | Static LAN gateway address on the spoke |
| Spoke WAN PCI Address | `0000:00:06.0` | PCI address of the spoke WAN ENI (`eth1`) |
| Spoke LAN PCI Address | `0000:00:07.0` | PCI address of the spoke LAN ENI (`eth2`) |
29 changes: 29 additions & 0 deletions docs/_deploy_aws_router_instance_steps.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<!--- AWS Router EC2 Instance — shared post-deployment steps --->
<!--- Imported by deploy_aws_hub_router_instance.mdx and deploy_aws_spoke_router_instance.mdx --->

## Disable Source / Destination Check

AWS enables source/destination checking on all ENIs by default. This check drops packets where the EC2 instance is not the packet source or destination, which prevents the SSR from forwarding transit traffic. You must disable this check on the **WAN and LAN ENIs**.

1. In the EC2 console, navigate to **Instances** and select the router instance.
2. Select the **Networking** tab.
3. Under **Network Interfaces**, click on the WAN ENI (second interface, `eth1`).
4. Select **Actions → Change Source/Destination Check**.
5. Select **Stop** and click **Save**.

![Source/Destination Check](/img/AWS-bootstrap2.png)

6. Repeat steps 3–5 for the LAN ENI (`eth2`).

:::important
Failing to disable source/destination checking prevents the SSR from forwarding any transit traffic. Complete this step before committing the router configuration.
:::

## Associate the Elastic IP with the WAN Interface

1. In the EC2 console, navigate to **Elastic IPs**.
2. If you have not already done so, allocate a new Elastic IP.
3. Select the address and click **Actions → Associate Elastic IP Address**.
4. Select the router instance's WAN ENI (`eth1`) and click **Associate**.

Record this Elastic IP. You will reference it as the `external-nat-address` when configuring the WAN interface neighborhood in the router configuration step.
204 changes: 204 additions & 0 deletions docs/deploy_appendix_aws_conductor.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,204 @@
---
title: "Appendix: AWS Configuration"
sidebar_label: "Appendix: AWS Configuration"
---
import NetworkDesign from './_deploy_aws_conductor_network_design.md';

This appendix contains the complete SSR PCLI configuration for the `Conductor` and `aws-branch1` described in this guide. This configuration reflects the final state after completing all steps through [Step 5 — Configure the Router on the Conductor](deploy_aws_router_config.mdx).

:::important
- Replace `203.0.113.10` with your actual conductor Elastic IP.
- Replace `203.0.113.20` with your actual router WAN Elastic IP.
- The PCI addresses `0000:00:06.0` (WAN) and `0000:00:07.0` (LAN) are the defaults for EC2 instances deployed with the BYOL CloudFormation template when a management subnet is provided. Verify these against your specific instance using `sudo dpdk-devbind.py --status` before applying the router configuration.
:::

## Network Design Reference

<NetworkDesign/>

## Applying This Configuration

This configuration can be applied to a freshly initialized conductor using the PCLI import function.

1. Save the configuration below to a file — for example, `aws-conductor.cfg`.

2. Copy the file to the conductor:

```bash
scp aws-conductor.cfg admin@203.0.113.10:/tmp/
```

3. Log in to the conductor PCLI:

```bash
ssh admin@203.0.113.10
```

4. Enter configuration mode and import:

```text
admin@node0.Conductor# import config /tmp/aws-conductor.cfg
```

5. Review any validation warnings, then commit:

```text
admin@node0.Conductor (config)# commit
Are you sure you want to commit the candidate config? [y/N]: y
```

Alternatively, copy and paste each block into the PCLI while in `configure` → `edit` mode.

## Complete Configuration

```text
config
authority
name Authority128

conductor-address 203.0.113.10

tenant corp
name corp
exit

service Internet-Traffic
name Internet-Traffic
scope public
security internal

access-policy corp
source corp
exit

address 0.0.0.0/0
exit

router Conductor
name Conductor
inter-node-security internal

node node0
name node0
role conductor

device-interface mgmt-dev
name mgmt-dev
type ethernet
pci-address 0000:00:05.0
forwarding false

network-interface mgmt-intf
name mgmt-intf
type management

address 10.0.1.10
ip-address 10.0.1.10
prefix-length 24
gateway 10.0.1.1
exit
exit
exit
exit
exit

router aws-branch1
name aws-branch1
inter-node-security internal

node node0
name node0
role combo

device-interface wan-dev
name wan-dev
type ethernet
pci-address 0000:00:06.0
forwarding true

network-interface wan1
name wan1
global-id 1
type external
conductor true
management true
default-route true
source-nat true
dhcp v4

management-vector
name mgmt-vec-wan
priority 100
exit

neighborhood internet
name internet
topology spoke
external-nat-address 203.0.113.20
exit
exit
exit

device-interface lan-dev
name lan-dev
type ethernet
pci-address 0000:00:07.0
forwarding true

network-interface lan1
name lan1
global-id 2
type external
tenant corp
source-nat true
dhcp disabled

address 10.1.2.1
ip-address 10.1.2.1
prefix-length 24
exit
exit
exit
exit

service-route internet-route
name internet-route
service-name Internet-Traffic

next-hop node0 wan1
node-name node0
interface wan1
exit
exit

dns-config static
address 1.1.1.1
address 8.8.8.8
exit
exit
exit
exit
```

## Interface Summary

| Interface | Device Interface | PCI Address | Type | Configuration |
|-----------|-----------------|-------------|------|---------------|
| `wan1` | `wan-dev` | `0000:00:06.0` | External | DHCP v4, conductor, management, default-route, source-nat, neighborhood `internet` with external-nat-address `203.0.113.20` |
| `lan1` | `lan-dev` | `0000:00:07.0` | External | tenant `corp`, static `10.1.2.1/24`, source-nat |

## Service Route Summary

| Service Route | Service | Type | Next Hop |
|--------------|---------|------|---------|
| `internet-route` | `Internet-Traffic` | `service-agent` | `node0 / wan1` |

## Design Notes

**AWS NAT and External NAT Address** — AWS performs 1:1 NAT between each Elastic IP and the private IP assigned to the corresponding ENI. The `external-nat-address` setting in the `internet` neighborhood tells the SSR to advertise the Elastic IP (`203.0.113.20`) to peers rather than the private DHCP address. Without this, SVR peer connections cannot be established because the private IP is not routable from outside the VPC.

**Management over Forwarding** — The `wan1` interface carries both internet traffic and conductor management sessions simultaneously. Management traffic originating from the host OS at `169.254.x.x` link-local addresses is source-NAT'd to the WAN DHCP address before leaving the interface. The `default-route: true` setting ensures Linux routes all outbound OS traffic through the SSR forwarding engine so the auto-generated `management-conductor` service route applies.

**Management Interface (eth0)** — The first ENI (`eth0` / `ge-0-0`) is not configured in SSR. Linux manages it for out-of-band SSH access. This is the recommended pattern for AWS deployments, as it preserves SSH reachability when the SSR service is offline for maintenance or upgrades.

**Source / Destination Check** — The WAN and LAN ENIs on the router EC2 instance must have source/destination checking disabled. This is an AWS-specific requirement that allows the SSR to forward packets where it is not the source or destination.
Loading