Transit Gateway + VPC Peering

Build an enterprise-style multi-VPC network on LocalEmu: four VPCs wired into a hub-and-spoke fabric with a Transit Gateway, plus one VPC peering connection, and verify the data plane with a 10-assertion connectivity matrix, including the non-transitive deny that peering enforces.

Topology

                    +-----------------------+
                    |        mgmt           |
                    |     (10.99.0.0/16)    |
                    |  host-mgmt (bastion)  |
                    +-----------+-----------+
                                |
                                |  VPC peering
                                |  (auto-accepted)
                                |
                    +-----------v-----------+
                    |    shared-services    |
                    |     (10.0.0.0/16)     |
                    |  host-shared :8080    |
                    +-----------+-----------+
                                |
                                |  Transit Gateway
                                |  (default RT; assoc + prop enabled)
                                |
             +------------------+------------------+
             |                                     |
   +---------v----------+              +-----------v---------+
   |      prod-app      |              |      prod-data      |
   |   (10.1.0.0/16)    |              |    (10.2.0.0/16)    |
   |     host-app       |              |     host-data       |
   +--------------------+              +---------------------+

Step-by-Step Walkthrough

EC2_VM_MANAGER=docker localemu start

$ awsx ec2 create-vpc --cidr-block 10.0.0.0/16 \
    --tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=shared-services}]' \
    --query Vpc.VpcId --output text
vpc-db07a67d8807065d3

$ awsx ec2 create-vpc --cidr-block 10.1.0.0/16 ...  # prod-app
$ awsx ec2 create-vpc --cidr-block 10.2.0.0/16 ...  # prod-data
$ awsx ec2 create-vpc --cidr-block 10.99.0.0/16 ... # mgmt

# One /24 subnet per VPC in us-east-1a
$ awsx ec2 create-subnet --vpc-id $SHARED_VPC \
    --cidr-block 10.0.1.0/24 --availability-zone us-east-1a

$ awsx ec2 create-transit-gateway \
    --description enterprise-hub \
    --options 'AmazonSideAsn=64512,AutoAcceptSharedAttachments=enable,\
DefaultRouteTableAssociation=enable,DefaultRouteTablePropagation=enable' \
    --query TransitGateway.TransitGatewayId --output text
tgw-6db3bd5b57deb0f1d

$ awsx ec2 create-transit-gateway-vpc-attachment \
    --transit-gateway-id $TGW_ID --vpc-id $SHARED_VPC --subnet-ids $SHARED_SUBNET \
    --query TransitGatewayVpcAttachment.TransitGatewayAttachmentId --output text
tgw-attach-b43dfaa15582fca4c

# Repeat for prod-app and prod-data (3 attachments total)

$ awsx ec2 create-vpc-peering-connection \
    --vpc-id $MGMT_VPC --peer-vpc-id $SHARED_VPC \
    --query VpcPeeringConnection.VpcPeeringConnectionId --output text
pcx-73dcb8b0d31ae4a6a

$ awsx ec2 accept-vpc-peering-connection \
    --vpc-peering-connection-id $PCX_ID
VpcPeeringConnection:
  Status:
    Code: active

# TGW routes: shared/app/data reach each other via the TGW fabric
$ awsx ec2 create-route --route-table-id $SHARED_RT \
    --destination-cidr-block 10.1.0.0/16 --transit-gateway-id $TGW_ID
Return: true

$ awsx ec2 create-route --route-table-id $APP_RT \
    --destination-cidr-block 10.0.0.0/16 --transit-gateway-id $TGW_ID
Return: true

# Peering routes: mgmt <-> shared (non-transitive: no route to app or data)
$ awsx ec2 create-route --route-table-id $MGMT_RT \
    --destination-cidr-block 10.0.0.0/16 --vpc-peering-connection-id $PCX_ID
Return: true

$ awsx ec2 run-instances \
    --image-id ami-ubuntu-22.04 --instance-type t2.micro --count 1 \
    --subnet-id $SHARED_SUBNET --security-group-ids $SHARED_SG \
    --key-name enterprise-key \
    --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=host-shared}]' \
    --query Instances[0].InstanceId --output text
i-1b15f9cecd3e8a7ce

# Repeat for host-app, host-data, host-mgmt (4 instances total)

$ awsx ec2 wait instance-running --instance-ids $SHARED_INST $APP_INST $DATA_INST $MGMT_INST

$ awsx ec2 describe-instances --instance-ids $SHARED_INST $APP_INST $DATA_INST $MGMT_INST \
    --query 'Reservations[].Instances[].[Tags[?Key==`Name`]|[0].Value,PrivateIpAddress]' \
    --output text
host-shared  10.0.0.3
host-app     10.1.0.3
host-data    10.2.0.3
host-mgmt    10.99.0.3

# SendCommand over SSM, no SSH keys, no open port
$ awsx ssm send-command --instance-ids $SHARED_INST \
    --document-name AWS-RunShellScript \
    --parameters 'commands=["echo hello from shared-services > /tmp/index.html",
                             "nohup python3 -m http.server 8080 --directory /tmp &"]'

$ awsx ssm send-command --instance-ids $SHARED_INST \
    --document-name AWS-RunShellScript \
    --parameters 'commands=["curl -sS http://127.0.0.1:8080/index.html"]'

StandardOutputContent: hello from shared-services

# --- TGW fabric (spoke ↔ spoke) ---
  ✓ [allow] app -> data (10.2.0.3)
  ✓ [allow] app -> shared (10.0.0.3)
  ✓ [allow] data -> shared (10.0.0.3)
  ✓ [allow] data -> app (10.1.0.3)

# --- VPC peering (mgmt ↔ shared) ---
  ✓ [allow] mgmt -> shared (10.0.0.3)
  ✓ [allow] shared -> mgmt (10.99.0.3)

# --- Non-transitive peering (must deny) ---
  ✓ [deny ] mgmt -> app (10.1.0.3) correctly blocked
  ✓ [deny ] mgmt -> data (10.2.0.3) correctly blocked

# --- Application call (curl via TGW) ---
  hello from shared-services
  ✓ prod-app read content from shared-services through TGW

# --- Operations call (curl via peering) ---
  hello from shared-services
  ✓ mgmt read content from shared-services through peering

$ ./scripts/teardown.sh
== Cleanup ==
  Terminating EC2 instances
  Deleting TGW attachments
  Deleting VPC peering
  Deleting TGW
  Deleting subnets + VPCs
  Deleting key pair
  ✓ Cleanup complete.

What the run proves

The non-transitive denies are the key: they are what makes AWS peering different from TGW attachments, and they are a frequent source of confusion when operators try to use peering as a shortcut into an otherwise TGW-only fabric. LocalEmu honors the rule, mgmt's route table simply has no entry for the production CIDRs, so packets destined for them are dropped before they ever reach the fabric.

How LocalEmu implements this

Full source: lib/common.sh

The shared helper library every infra/*.sh script sources. Wraps the AWS CLI to always hit the LocalEmu endpoint, ships an SSM exec helper that polls until the command finishes, and writes ids into .state/ids.env so later steps do not re-query.

#!/usr/bin/env bash
# Shared helpers for the tutorial scripts. Sourced by every infra/*.sh.

# Fail fast, preserve pipe exit codes, surface undefined variables.
set -Eeuo pipefail

# ---- LocalEmu endpoint ------------------------------------------------------

: "${AWS_ENDPOINT_URL:=http://localhost:4566}"
: "${AWS_REGION:=us-east-1}"
: "${AWS_DEFAULT_REGION:=us-east-1}"
: "${AWS_ACCESS_KEY_ID:=AKIAIOSFODNN7EXAMPLE}"
: "${AWS_SECRET_ACCESS_KEY:=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY}"
export AWS_ENDPOINT_URL AWS_REGION AWS_DEFAULT_REGION
export AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY

# ---- State ------------------------------------------------------------------
# Each script writes ids into $STATE_DIR/*.env so later scripts can source them
# without re-querying AWS.

TUTORIAL_ROOT="${TUTORIAL_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
export TUTORIAL_ROOT
STATE_DIR="${STATE_DIR:-${TUTORIAL_ROOT}/.state}"
export STATE_DIR
mkdir -p "${STATE_DIR}"

# ---- Logging ----------------------------------------------------------------
# Prefix every line so mixed step output is readable when piped together.

_color() { printf '\033[%sm%s\033[0m\n' "$1" "$2"; }
log()   { _color '36' "[$(date +%H:%M:%S)] $*"; }
ok()    { _color '32' "  ✓ $*"; }
warn()  { _color '33' "  ! $*"; }
fail()  { _color '31' "  ✗ $*"; exit 1; }

# ---- AWS CLI wrapper --------------------------------------------------------
# Always targets the LocalEmu endpoint. Use instead of `aws` directly.

awsx() {
  aws --endpoint-url "${AWS_ENDPOINT_URL}" --region "${AWS_REGION}" "$@"
}

# ---- Retry primitive --------------------------------------------------------
# retry <max_tries> <sleep_seconds> <cmd...>
# Runs the command up to max_tries times with a short delay between attempts.
# Exits 0 on first success, non-zero if all attempts fail.

retry() {
  local max="$1"; local delay="$2"; shift 2
  local attempt=1 rc
  while true; do
    if "$@"; then return 0; fi
    rc=$?
    if (( attempt >= max )); then
      return "${rc}"
    fi
    sleep "${delay}"
    attempt=$(( attempt + 1 ))
  done
}

# ---- Wait-for helpers -------------------------------------------------------

wait_instance_running() {
  local iid="$1"; local timeout="${2:-60}"
  local deadline=$(( $(date +%s) + timeout ))
  while (( $(date +%s) < deadline )); do
    local s
    s=$(awsx ec2 describe-instances --instance-ids "${iid}" \
          --query 'Reservations[0].Instances[0].State.Name' --output text 2>/dev/null || echo "?")
    [[ "${s}" == "running" ]] && return 0
    sleep 1
  done
  return 1
}

# ---- SSM exec ---------------------------------------------------------------
# ssm_run <instance-id> <shell-cmd>
#   Sends a shell command to the instance via SSM. Prints stdout only when
#   the invocation finishes Success; non-zero exit with stderr otherwise.
#   Usage: out=$(ssm_run i-abc "hostname")

ssm_run() {
  local iid="$1"; shift
  local cmd="$*"
  local cid
  cid=$(awsx ssm send-command \
          --document-name AWS-RunShellScript \
          --instance-ids "${iid}" \
          --parameters "commands=[$(printf '%s' "${cmd}" | python3 -c 'import sys,json;print(json.dumps(sys.stdin.read()))')]" \
          --query 'Command.CommandId' --output text)
  local deadline=$(( $(date +%s) + 30 ))
  while (( $(date +%s) < deadline )); do
    local status output rc
    status=$(awsx ssm get-command-invocation \
              --command-id "${cid}" --instance-id "${iid}" \
              --query 'Status' --output text 2>/dev/null || echo "Pending")
    case "${status}" in
      Success)
        awsx ssm get-command-invocation \
          --command-id "${cid}" --instance-id "${iid}" \
          --query 'StandardOutputContent' --output text
        return 0
        ;;
      Failed|TimedOut|Cancelled)
        output=$(awsx ssm get-command-invocation \
                  --command-id "${cid}" --instance-id "${iid}" \
                  --query 'StandardErrorContent' --output text 2>/dev/null || echo "")
        rc=$(awsx ssm get-command-invocation \
                  --command-id "${cid}" --instance-id "${iid}" \
                  --query 'ResponseCode' --output text 2>/dev/null || echo "-1")
        echo "${output}" >&2
        return "${rc}"
        ;;
    esac
    sleep 1
  done
  echo "SSM timeout" >&2
  return 124
}

# ---- Kick-off helpers -------------------------------------------------------

need_healthy_localemu() {
  if ! curl -s -m 3 "${AWS_ENDPOINT_URL}/_localemu/health" >/dev/null; then
    fail "LocalEmu is not responding at ${AWS_ENDPOINT_URL}. Start it first: 'localemu start'"
  fi
}

state_set() { printf 'export %s=%q\n' "$1" "$2" >> "${STATE_DIR}/ids.env"; }
state_load() { [[ -f "${STATE_DIR}/ids.env" ]] && source "${STATE_DIR}/ids.env" || true; }

Full demo output

Captured from a clean run on LocalEmu v0.1.dev133 with EC2_VM_MANAGER=docker. ANSI color codes stripped for readability.

[15:27:03] == Step 01: network plane ==
[15:27:03] Creating VPC shared-services (10.0.0.0/16)
  ✓ shared-services vpc-7aeeed09f04eddd47, subnet subnet-f5a28cd9b3d9fede7
[15:27:05] Creating VPC prod-app (10.1.0.0/16)
  ✓ prod-app vpc-bd3a241ed2df7ea07, subnet subnet-cf153dd34efd28b25
[15:27:05] Creating VPC prod-data (10.2.0.0/16)
  ✓ prod-data vpc-8b8f73129e1836831, subnet subnet-c217a0db499d48e36
[15:27:06] Creating VPC mgmt (10.99.0.0/16)
  ✓ mgmt vpc-caae142aaf49a4176, subnet subnet-5a3ba71128217934e
[15:27:07] Creating security groups
  ✓ SGs: shared=sg-60e10a2368df0b7b6 app=sg-4980145f0dd30d5f7 data=sg-c9d9a35d108b73610 mgmt=sg-379e601d251db17fb
[15:27:11] Creating Transit Gateway
  ✓ TGW tgw-a4fa197f5a23eb3cc
[15:27:12] Attaching shared-services, prod-app, prod-data to TGW
  ✓ TGW attachments: shared=tgw-attach-7dc24112abb013f41 app=tgw-attach-0a3c22e178c0a9859 data=tgw-attach-6757129b59573df97
[15:27:13] Creating VPC peering mgmt <-> shared-services
  ✓ VPC peering pcx-d8cde14bc38c38021 established
[15:27:13] Programming routing tables
  ✓ Routes wired
[15:27:17] Network plane ready. Ids in ./.state/ids.env
[15:27:17] == Step 02: compute ==
[15:27:17] Creating key pair enterprise-key-30822
  ✓ Key pair created (pem saved to ./.state/enterprise-key-30822.pem)
[15:27:18] Launching shared-services host
[15:27:19] Launching prod-app host
[15:27:21] Launching prod-data host
[15:27:23] Launching mgmt host
[15:27:24] Waiting for instances to reach running state
  ✓ shared i-e60d2176a266a0329 running
  ✓ app i-b8230bc5c5981380b running
  ✓ data i-242b4aa4383a95e83 running
  ✓ mgmt i-628446ba9113e4d4f running
  ✓ Private IPs:
      shared=10.0.0.3  app=10.1.0.3  data=10.2.0.3  mgmt=10.99.0.3
[15:27:27] Compute plane ready.
[15:27:27] == Step 03: bring up HTTP service on shared-services ==
[15:27:27] Writing content
  ✓ Content written
[15:27:28] Starting http server on :8080 (background, via nohup)
      SERVER_UP
  ✓ Server listening on 0.0.0.0:8080
[15:27:30] Self-check: curl from shared-services itself
      hello from shared-services (10.0.1.0/24)
  ✓ Service healthy
[15:27:31] == Step 04: connectivity matrix ==
[15:27:31] -- TGW fabric (spoke ↔ spoke) --
  ✓ [allow] app -> data (10.2.0.3)
  ✓ [allow] app -> shared (10.0.0.3)
  ✓ [allow] data -> shared (10.0.0.3)
  ✓ [allow] data -> app (10.1.0.3)
[15:27:40] -- VPC peering mgmt ↔ shared --
  ✓ [allow] mgmt -> shared (10.0.0.3)
  ✓ [allow] shared -> mgmt (10.99.0.3)
[15:27:44] -- Non-transitive peering (must deny) --
  ✓ [deny ] mgmt -> app (10.1.0.3) correctly blocked
  ✓ [deny ] mgmt -> data (10.2.0.3) correctly blocked
[15:27:54] -- Application call (curl via TGW) --
      hello from shared-services (10.0.1.0/24)
  ✓ prod-app read content from shared-services through TGW
[15:27:54] -- Operations call (curl via peering) --
      hello from shared-services (10.0.1.0/24)
  ✓ mgmt read content from shared-services through peering
[15:27:55] All connectivity assertions passed.

→ demo complete. Run scripts/teardown.sh when done.

Files

Repository layout you get when you clone the examples repo.

18-transit-gateway-demo/
├── README.md
├── scripts/
│   ├── demo.sh
│   └── teardown.sh
├── lib/
│   └── common.sh         (awsx wrapper, ssm_run, state helpers)
└── infra/
    ├── 01_network.sh     (VPCs, subnets, SGs, TGW, peering, routes)
    ├── 02_compute.sh     (one EC2 per VPC)
    ├── 03_service.sh     (python http.server on shared-services)
    └── 04_connectivity.sh (the 10-assertion matrix)