# kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws architecture

> Architecture diagram of the GitHub repository kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws
- Repository: https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws

## Overview

##### Project Type and Purpose
- This is an infrastructure-as-code (IaC) project that automates the provisioning of AWS networking & compute resources (VPC, subnets, EC2s) with Pulumi (Python), Bash scripts, and a Makefile, then deploys a suite of e-commerce microservices across three EC2 hosts using Docker Compose.
- The goal is to create an overlay network (VXLAN) so that all containers—spread across three EC2 instances—share a single “br-vxlan” bridge network, enabling service-to-service calls as if they were on the same LAN.

##### File-Structure Analysis
- Top-level:
- Pulumi.yaml & src/ – IaC definitions (custom VPC, subnets, EC2 provisioning, security, network interfaces).
- scripts/ – Bash scripts to configure VXLAN, hostfile updates, cleanup.
- host_1/, host_2/, host_3/ – Per-EC2 directories containing docker-compose.yml, service code (FastAPI microservices under app/), nginx gateway configs, and environment files.
- Makefile – High-level orchestration (`make build`, `make cleanup`).
- Patterns:
- Three hosts in distinct subnets inside one VPC.
- Each host runs a Docker bridge named “br-vxlan” (external in compose).
- API gateways (nginx) in Active-Active on host_1 & host_2 behind a Route53 failover DNS record.
- Microservices communicate via the overlay network at fixed container IPs.
- Databases (PostgreSQL for inventory & users; MongoDB for product & orders) live on host_3.

##### README Insights
- Confirms 3 EC2 instances, VXLAN overlay, Active-Active API GW, all DB storage on EC2-3.
- Describes challenges and solutions (single VNI, Route53 failover, fixed IPs + /etc/hosts, external network in compose).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients & Tools
    Postman["Postman"]:::external
    PulumiCLI["Pulumi CLI"]:::external

    %% Automation & IaC
    subgraph "Automation & IaC"
        PulumiY["Pulumi Definitions"]:::automation
        MakefileNode["Makefile"]:::automation
        Scripts["VXLAN & Host Setup Scripts"]:::automation
        Helpers["Global Config & Helpers"]:::automation
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        VPC["AWS VPC & Subnets"]:::infra
        EC2Prov["EC2 Provisioning"]:::infra
        SG["Security Groups"]:::infra
        Route53["Route53 DNS (A records)"]:::infra
    end

    %% Compute Layer
    subgraph "Compute Layer"
        Host1["EC2: Host-1"]:::compute
        Host2["EC2: Host-2"]:::compute
        Host3["EC2: Host-3"]:::compute
    end

    %% Networking
    subgraph "Networking"
        VXLAN["VXLAN (UDP 4789)"]:::network
        BR["Linux Bridge br-vxlan"]:::network
    end

    %% Host-1 Containers
    subgraph "Host-1 Containers"
        Compose1["Docker Compose"]:::automation
        Nginx1["Nginx API Gateway"]:::container
        Inv["inventory-service"]:::container
        Prod["product-service"]:::container
    end

    %% Host-2 Containers
    subgraph "Host-2 Containers"
        Compose2["Docker Compose"]:::automation
        Nginx2["Nginx API Gateway"]:::container
        Order["order-service"]:::container
        User["user-service"]:::container
    end

    %% Host-3 Containers
    subgraph "Host-3 Containers"
        Compose3["Docker Compose"]:::automation
        Postgres["PostgreSQL DB"]:::container
        Mongo["MongoDB"]:::container
    end

    %% Connections: IaC
    PulumiCLI -->|uses| PulumiY
    PulumiY -->|creates| VPC
    PulumiY -->|creates| SG
    PulumiY -->|creates| EC2Prov
    MakefileNode -->|orchestrates| PulumiY
    Helpers -->|supports| Scripts
    Scripts -->|configures| Host1
    Scripts -->|configures| Host2
    Scripts -->|configures| Host3

    %% Infra to Compute
    EC2Prov -->|provisions| Host1
    EC2Prov -->|provisions| Host2
    EC2Prov -->|provisions| Host3
    Route53 -->|failover DNS| Nginx1
    Route53 -->|failover DNS| Nginx2

    %% Compute to Networking
    Host1 --> BR
    Host2 --> BR
    Host3 --> BR
    BR --> VXLAN
    VXLAN --> BR

    %% Host-1 Composition
    Host1 --> Compose1
    Compose1 --> Nginx1
    Compose1 --> Inv
    Compose1 --> Prod

    %% Host-2 Composition
    Host2 --> Compose2
    Compose2 --> Nginx2
    Compose2 --> Order
    Compose2 --> User

    %% Host-3 Composition
    Host3 --> Compose3
    Compose3 --> Postgres
    Compose3 --> Mongo

    %% External Traffic
    Postman -->|HTTP| Route53

    %% Service-to-Service Calls
    Prod -->|calls| Inv
    Order -->|calls| Inv
    Order -->|calls| Prod
    Order -->|calls| User

    %% Service to Database
    Inv -->|reads/writes| Postgres
    User -->|reads/writes| Postgres
    Prod -->|reads/writes| Mongo
    Order -->|reads/writes| Mongo

    %% Click Events
    click VPC "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/src/infrastructure/network.py"
    click EC2Prov "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/src/infrastructure/compute.py"
    click SG "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/src/infrastructure/security.py"
    click PulumiY "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/Pulumi.yaml"
    click MakefileNode "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/Makefile"
    click Scripts "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/scripts/setup-vxlan-host-1.sh"
    click Scripts "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/scripts/setup-vxlan-host-2.sh"
    click Scripts "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/scripts/setup-vxlan-host-3.sh"
    click Scripts "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/scripts/update-hostfile.sh"
    click Scripts "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/scripts/cleanup.sh"
    click Helpers "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/src/config/update_scripts.py"
    click Helpers "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/src/utils/helpers.py"
    click Compose1 "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/host_1/docker-compose.yml"
    click Nginx1 "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_1/nginx/"
    click Inv "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_1/inventory-service/"
    click Prod "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_1/product-service/"
    click Compose2 "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/host_2/docker-compose.yml"
    click Nginx2 "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_2/nginx/"
    click Order "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_2/order-service/"
    click User "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/tree/main/host_2/user-service/"
    click Compose3 "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/host_3/docker-compose.yml"
    click Postman "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/e-commerce apis.postman_collection.json"
    click README "https://github.com/kcnaiamh/distributed-microservices-using-vxlan-pulumi-bash-aws/blob/main/README.md"

    %% Styles
    classDef infra fill:#a2d2ff,stroke:#000;
    classDef network fill:#caffbf,stroke:#000;
    classDef compute fill:#ffd6a5,stroke:#000;
    classDef container fill:#ffedbf,stroke:#000;
    classDef automation fill:#d0bfff,stroke:#000;
    classDef external fill:#ffc8dd,stroke:#000;
```
