gobridge

AWS Deployment Overview

GoBridge runs on AWS as ECS Fargate services with file or DynamoDB configuration, SSM Parameter Store for secrets, and an optional DynamoDB-coordinated HA profile. This page covers the end-to-end architecture; the topologies, storage, image, CDK constructs, and IAM policies each have their own page, listed under Page map below.

For generic deployment considerations, see Deployment Guide. For configuration details specific to AWS, see Configuration on AWS.

Architecture

The diagram below shows the shared AWS components and the two config choices. Tasks use the source selected in bootstrap, not both. Every component is created or referenced by the CDK constructs described in CDK Construct Library.

flowchart TD
    subgraph VPC["VPC (private subnets)"]
        subgraph ECS["ECS Fargate"]
            T1[Task 1\ngobridge-aws]
            T2[Task N\ngobridge-aws]
        end

        EFS[(EFS\nbridge.yaml)]
        ALB[Application\nLoad Balancer]
    end

    ECR[ECR\nContainer Registry] --> ECS
    DDB[(DynamoDB\nconfig item)] -. dynamodb source .-> ECS
    SSM[SSM Parameter Store\nSecureString secrets] --> ECS
    CW[CloudWatch Logs\n& Metrics] --- ECS

    ALB --> T1
    ALB --> T2
    T1 -. file source: NFS mount .-> EFS
    T2 -. file source: NFS mount .-> EFS

    Client([External Clients]) --> ALB

    style EFS fill:#f5a623,stroke:#333,color:#000
    style SSM fill:#4a90d9,stroke:#333,color:#fff
    style ECR fill:#4a90d9,stroke:#333,color:#fff
    style CW fill:#4a90d9,stroke:#333,color:#fff
Component Role
Container image ImageFromGoBuild builds a compatible published Go module into an ECR asset with embedded initial config. Registry/ECR constructors use a consumer-built image unchanged.
VPC Isolates the Fargate tasks in private subnets with NAT egress.
ECS Fargate Runs the bridge container without EC2 instance management.
EFS Provides the watched file config and any SQLite store paths. Omitted when neither needs a filesystem.
DynamoDB config table Optional alternative to file config for Single and DynamoDB HA: one versioned document, CAS updates, and poll or Streams observation. Separate from HA message-state tables.
ALB Terminates TLS and routes HTTP traffic to the admin, monitor, or transport ports.
SSM Parameter Store Holds API keys and credentials as SecureString parameters.
CloudWatch Collects structured logs and optional custom metrics.

Empty config_source defaults to file in all topologies. The filesystem-replicated topology supports file only. DynamoDB HA with DynamoDB config and DynamoDB data stores uses no EFS.

With valid bootstrap, missing config leaves the control plane live and the data plane idle, not ready. Only control may create an absent target from optional embedded config; existing documents are never overwritten by initialization, and workers remain read-only. No configuration seeder container or S3 config asset is required. See initial configuration.

Page map

This overview covers the architecture and points at the rest. Each page below is self-contained.

Page Covers
Deployment Topologies Single, cluster, and DynamoDB-coordinated HA; identity rules, task roles, alarms, failover proof.
Compute and Runtime Metrics Why ECS Fargate, task sizing, and the runtime metrics backend.
Storage and Secrets File or DynamoDB configuration, conditional EFS, SSM secrets, DynamoDB data stores, DevMode guard.
Container Image Published-module and local image builds, embedded config, and the ECR lifecycle policy.
CDK Construct Library Construct overview, props, and a complete usage example.
IAM Least Privilege Task-role and execution-role policies, statement by statement.

Beyond the pages in the map above.

Guide Description
Configuration on AWS Bridge YAML reference with AWS-specific settings.
Hot-reload and production config updates How a live reload reaches every task, and the procedure for changing config in production.
Monitoring and Observability The CloudWatch exporter and the complete metric catalogue.
CloudWatch alarms What the CDK bundle provisions, what DefaultAlarms() provisions, what nobody does, and the rollup metrics they all need.
Logging, dashboards and tracing Structured logging, dashboard layout, ADOT/X-Ray tracing, log-metric filters, Grafana.
HTTP API and Networking ALB target groups, security groups, and TLS termination.
API Gateway and custom domains Fronting the admin API with API Gateway, and putting a custom domain in front of it.
Total Cost of Ownership Fargate, EFS, and SSM cost breakdown with worked examples.
Cost optimization checklist The actionable savings, in the order worth doing them.
Running the Deployment Suite Locally Deploying and driving this profile with no AWS account: what it proves, what it does not, and the measured emulation gaps.
CDK Scenarios Complete, runnable CDK deployment examples.
Deployment Guide Platform-agnostic deployment considerations.
This site is open source. Improve this page.