# vhgalvez/flatcarmicrocloud architecture

> Architecture diagram of the GitHub repository vhgalvez/flatcarmicrocloud, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vhgalvez/flatcarmicrocloud
- Repository: https://github.com/vhgalvez/flatcarmicrocloud

## Overview

##### Main Components
- Physical Infrastructure:
- ProLiant DL380 G7 server with dedicated specs (CPU, RAM, storage)
- KVM hypervisor with Libvirt/KVM networking support.
- Virtualization and Network Layers:
- Virtual networks defined by Terraform (br0_network, nat_network_02, nat_network_03)
- pfSense VMs for firewall/NAT and routing.
- WireGuard VPN for secure remote access.
- Kubernetes Cluster:
- Control Plane (“Master” nodes running on Flatcar Container Linux with K3s and etcd)
- Worker nodes executing microservices/apps.
- Dedicated VMs for roles like FreeIPA (DNS and central authentication), PostgreSQL (database), and storage nodes.
- Load Balancing & Ingress:
- Load Balancer nodes (Traefik based) and HAProxy + Keepalived for high availability (k8s-api-lb VIP).
- Automation and Provisioning:
- Terraform modules and scripts to set up networks and VMs.
- Ansible playbooks for configuring FreeIPA, NTP, HAProxy/Keepalived, K3s, Ingress (Traefik), and storage clusters.
- External Interfaces:
- Cloudflare CDN, external HTTPS access, and monitoring/CI pipelines.

##### Relationships and Interactions
- External Clients (users, public Internet) connect via HTTPS (with the help of Cloudflare and VPN gateways).
- Ingress flows via the WireGuard VPN and pfSense firewall before reaching the load balancers.
- Load Balancers (Traefik and HAProxy+Keepalived) route requests to the Kubernetes control plane (Master nodes).
- Within the Kubernetes cluster:
- Master nodes manage the API, etcd, and cluster state.
- Worker nodes run containerized services with supporting microservices (Apache Kafka, MQTT, Redis, etc.).
- Persistent storage is configured via NFS/Longhorn on designated VMs.
- FreeIPA provides DNS and authentication services, with PostgreSQL running on its own VM supporting microservice data needs.
- Automation tools (Terraform, Ansible) have “control flows”—they provision and then configure these various components, ensuring consistency across the infrastructure.

##### Architectural Patterns and Design Principles
- Infrastructure as Code (Terraform manifests per network and VM).
- Ansible-based automated configuration deployments ensuring repeatability.
- Kubernetes High Availability:
- Multiple masters and workers with an external load balancing layer.
- Network segmentation with NAT and Bridge (isolating different environments and roles).
- Separation of concerns through dedicated VMs for DNS (FreeIPA), databases (PostgreSQL), load balancing, and storage.
- Use of both light and secure container OS (Flatcar Container Linux) for minimal attack surface.

##### Relevant Technologies, Frameworks, and Tools
- Operating Systems: Rocky Linux 9.5, AlmaLinux 9.4, Flatcar Container Linux.
- Virtualization: KVM, Libvirt.
- Orchestration: Kubernetes (K3s) with etcd-managed masters.
- Network Management: Terraform for networking, pfSense, WireGuard, iptables/nftables.
- Load Balancing: Traefik, HAProxy, Keepalived.
- Automation: Ansible.
- Monitoring & Logging: Prometheus, Grafana, ELK stack.
- Additional Tools: Apache Kafka, MQTT Mosquitto, Redis, Jenkins/GitHub Actions for CI/CD.

- Physical infrastructure with its network interfaces.
- Virtualized networks (each NAT network as its own submodule).
- Kubernetes cluster (control plane and worker nodes, persistent storage).
- External services (Cloudflare, VPN, external monitoring).
- The goal is to avoid oversimplification by splitting the project into as many well-defined components as possible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    ExtClients("External Clients / Cloudflare"):::external

    %% VPN and Firewall Layer
    WireGuard("WireGuard VPN"):::vpn
    pfSense("pfSense Firewall/Router"):::firewall
    pfSense2("pfSense Secondary"):::firewall

    %% Load Balancers & Ingress
    subgraph "Load Balancing & Ingress"
        LB1("Load Balancer 1"):::loadbalancer
        LB2("Load Balancer 2"):::loadbalancer
        LBDocs("Load Balancer Docs"):::loadbalancer
    end

    %% Kubernetes Cluster
    subgraph "Kubernetes Cluster"
        Masters("K3s Masters"):::k8s
        Workers("K3s Workers"):::k8s
        Storage("Storage Nodes"):::k8s
        K8sTemplates("Kubernetes Node Templates"):::k8s
        ClusterDocs("Cluster Docs"):::k8s
        ClusterDraft("Cluster Doc Draft"):::k8s
    end

    %% FreeIPA Service
    subgraph "FreeIPA Service"
        FreeIPA("FreeIPA DNS/Auth"):::freeipa
        FreeIPADocs("FreeIPA Docs"):::freeipa
    end

    %% Physical and Virtual Infrastructure
    subgraph "Physical & Virtual Infrastructure"
        Physical("ProLiant DL380 G7"):::physical
        Hypervisor("KVM Hypervisor"):::virtualization
        subgraph "Virtual Networks (Terraform)"
            BR0("br0_network (Terraform)"):::virtualNetworks
            Nat02("nat_network_02 (Terraform)"):::virtualNetworks
            Nat03("nat_network_03 (Terraform for K8s)"):::virtualNetworks
        end
    end

    %% Automation & Provisioning
    subgraph "Automation & Provisioning"
        Terraform("Terraform Automation"):::automation
        Ansible("Ansible Automation"):::automation
    end

    %% Connections - External flow
    ExtClients -->|"connects"| WireGuard
    WireGuard -->|"routes"| pfSense
    WireGuard --> pfSense2
    pfSense -->|"forwards"| LB1
    pfSense2 -->|"forwards"| LB2
    LB1 -->|"routes"| Masters
    LB2 -->|"routes"| Masters

    %% Internal Kubernetes flow
    Masters -->|"manages"| Workers
    Masters -->|"manages"| Storage

    %% Connections - Infrastructure provisioning
    Physical -->|"hosts"| Hypervisor
    Hypervisor -->|"provides virtualization for"| BR0
    Hypervisor --> Nat02
    Hypervisor --> Nat03

    %% Automation influence arrows
    Terraform ---|"provisions"| BR0
    Terraform --- Nat02
    Terraform --- Nat03
    Terraform --- pfSense
    Terraform --- pfSense2
    Ansible ---|"configures"| FreeIPA
    Ansible --- LBDocs
    Ansible --- Masters

    %% Kubernetes additional docs connection
    K8sTemplates ---|"templates used by"| Masters
    K8sTemplates --- Workers
    K8sTemplates --- Storage
    ClusterDocs --- Masters
    ClusterDraft --- Masters

    %% FreeIPA connection to infrastructure
    Nat02 ---> FreeIPA

    %% Styling Classes
    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef vpn fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef firewall fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef loadbalancer fill:#f2b3ff,stroke:#333,stroke-width:2px;
    classDef k8s fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef physical fill:#ff9999,stroke:#333,stroke-width:2px;
    classDef virtualization fill:#ffcc99,stroke:#333,stroke-width:2px;
    classDef virtualNetworks fill:#ffff99,stroke:#333,stroke-width:2px;
    classDef freeipa fill:#d9ffb3,stroke:#333,stroke-width:2px;
    classDef automation fill:#d2b4de,stroke:#333,stroke-width:2px;

    %% Click Events
    click Physical "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/additional_resources/documentacion/server_rocky_linux_ProLiant_DL380_G7"
    click Hypervisor "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/additional_resources/documentacion/virtualizacion"
    click BR0 "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/br0_network"
    click Nat02 "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/nat_network_02"
    click Nat03 "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/nat_network_03"
    click pfSense "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/pfsense"
    click pfSense2 "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/pfsense_02"
    click WireGuard "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/br0_network/vpn-wireguard/wg0.conf"
    click K8sTemplates "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/nat_network_03/configs"
    click LB1 "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/nat_network_02/config/load_balancer1-user-data.tpl"
    click LB2 "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/nat_network_02/config/load_balancer2-user-data.tpl"
    click LBDocs "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/additional_resources/documentacion/load_balancer"
    click FreeIPA "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/nat_network_02/config/freeipa1-user-data.tpl"
    click FreeIPADocs "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/additional_resources/documentacion/freeipa"
    click Terraform "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/additional_resources/documentacion/documentacion_borrador/Documentacion/code_terraform.md"
    click Ansible "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/additional_resources/documentacion/configuracion_red/borrador/ansible.md"
    click ClusterDocs "https://github.com/vhgalvez/flatcarmicrocloud/tree/main/additional_resources/documentacion/cluster"
    click ClusterDraft "https://github.com/vhgalvez/flatcarmicrocloud/blob/main/additional_resources/documentacion/documentacion_borrador/Documentacion/cluster_proyecto.md"
```
