# ein-plus/lain architecture

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

- Interactive diagram: https://gitdiagram.com/ein-plus/lain
- Repository: https://github.com/ein-plus/lain

## Overview

##### Project Type and Purpose
- From the README (“Lain 是一个基于 docker 的 PaaS 系统”) and the sprawling Ansible playbooks, this is an infrastructure‐as‐code project: a Docker-based PaaS bootstrap/orchestration system.
- It provides one‐click provisioning (via Vagrant for dev/test and Ansible for production), configures the control plane (etcd, DNS, registry, networking, firewall, monitoring, logging, storage) and the data plane (Docker hosts) to deliver a unified PaaS.

##### File‐Structure Analysis
- Top level:
- Vagrantfile + bootstrap scripts for local dev/test
- site.yaml + playbooks/ directory for Ansible orchestration
- bootstrap_test/ for CI tests
- playbooks/roles: dozens of Ansible roles, each encapsulating a single service or function:
- bootstrap‑* roles handle the multi‑layer initialization (layer0=infra, layer1=platform services)
- Services: etcd, Docker engine, registry, console, deployd (scheduler), swarm, calico (network), dnsmasq/tinydns, firewall, collectd (metrics), rsyslog, moosefs (storage), lainlet (node agent), SSL, etc.
- libraries/ contains custom Ansible modules (docker_pull, etcd_set_key, set_virtual_ip, etc.)
- bootstrap/: likely contains high‑level orchestrator entry points
- bootstrap_test/: pytest tests validating roles and playbooks

##### Key README Insights
- Design goals: reduce complexity, standardize dev→test→prod, support CI/CD
- Target environments: IaaS/bare‐metal or Vagrant for dev

a. Main Components
- Ansible Control Plane (Bootstrap server or CI runner)
- Inventory: host groups (bootstrap‐node, layer0, layer1)
- Infrastructure services (layer0):
– etcd cluster (key‐value store)
– DNS: tinydns + dnsmasq
– Docker registry
– Firewall rules (iptables via ansible)
– Overlay network (Calico)
- Platform services (layer1):
– deployd (application deploy scheduler)
– console (web UI)
– swarm managers & agents
– lainlet (node agent)
– monitoring (collectd + plugins)
– logging (rsyslog + relocation)
– storage (MooseFS metadata/master/chunk)
- Data plane: pool of Docker hosts running containers
- External integrations: SSL CA, external SSH key distribution, CI/CD hooks
b. Relationships & Interactions
- Ansible Control → (SSH/API) → target nodes to install/configure services
- Services communicate:
– deployd ↔ etcd
– console ↔ etcd + registry
– swarm manager ↔ Docker daemons
– lainlet ↔ deployd/console for health & scheduling
– collectd ↔ all nodes, push metrics to back‐end
– rsyslog → centralized log storage or syslog aggregator
- Overlay network spans Docker hosts; Calico agents configure routes via etcd
- Registry hosts Docker images pulled by Docker daemons
c. Architectural Patterns & Principles
- Infrastructure as Code: modular Ansible roles
- Layered bootstrap (layer0 infra → layer1 PaaS)
- Declarative state: idempotent roles, custom modules
- Separation of concerns: one role = one service/function
- High cohesion within roles, loose coupling between services via etcd + APIs
d. Key Technologies & Frameworks
- Ansible playbooks & custom modules
- Docker & Docker‑registry
- etcd (distributed key‐value store)
- Calico (container networking)
- DNS (tinydns/dnsmasq)
- Jenkins/GitLab CI (implied by bootstrap_test)
- Collectd, rsyslog, MooseFS, Swarm, Python (Ansible modules, test suite), Vagrant

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Plane
    subgraph "Control Plane"
        direction TB
        AnsibleControl["Ansible Control Node"]:::orchestration
        Inventory["Inventory Definitions"]:::orchestration
        BootstrapScripts["Bootstrap Scripts (Vagrant & bootstrap/)"]:::orchestration
        CI_CD["CI/CD & SSH Key Distribution"]:::cloud
        SSLCA["External SSL CA"]:::cloud
        ExtModules["Custom Ansible Modules"]:::orchestration
    end

    %% Data Plane
    subgraph "Data Plane"
        direction TB
        subgraph "Layer0: Infra Services"
            direction TB
            Etcd["etcd Cluster"]:::infra
            Tinydns["TinyDNS"]:::infra
            Dnsmasq["dnsmasq"]:::infra
            Registry["Docker Registry"]:::infra
            Firewall["Firewall Configuration"]:::infra
            Calico["Overlay Network (Calico)"]:::infra
        end
        subgraph "Layer1: Platform Services"
            direction TB
            Deployd["Platform Scheduler (deployd)"]:::platform
            Console["Web Console"]:::platform
            Swarm["Swarm Cluster"]:::platform
            Lainlet["Node Agent (lainlet)"]:::platform
            Collectd["Monitoring (collectd)"]:::platform
            Rsyslog["Logging (rsyslog)"]:::platform
            MooseFS["Storage (MooseFS)"]:::storage
        end
    end

    %% Connections within Control Plane
    AnsibleControl -->|"reads"| Inventory
    AnsibleControl -->|"runs playbooks"| BootstrapScripts
    AnsibleControl -->|"executes tests"| CI_CD
    AnsibleControl -->|"uses modules"| ExtModules
    AnsibleControl -->|"requests certs"| SSLCA

    %% Bootstrap sequence
    AnsibleControl -->|"bootstrap layer0"| Etcd
    AnsibleControl -->|"bootstrap layer0"| Tinydns
    AnsibleControl -->|"bootstrap layer0"| Dnsmasq
    AnsibleControl -->|"bootstrap layer0"| Registry
    AnsibleControl -->|"bootstrap layer0"| Firewall
    AnsibleControl -->|"bootstrap layer0"| Calico

    AnsibleControl -->|"bootstrap layer1"| Deployd
    AnsibleControl -->|"bootstrap layer1"| Console
    AnsibleControl -->|"bootstrap layer1"| Swarm
    AnsibleControl -->|"bootstrap layer1"| Lainlet
    AnsibleControl -->|"bootstrap layer1"| Collectd
    AnsibleControl -->|"bootstrap layer1"| Rsyslog
    AnsibleControl -->|"bootstrap layer1"| MooseFS

    %% Service communications
    Deployd <-->|"state & config"| Etcd
    Console <-->|"state & config"| Etcd
    Console <-->|"image metadata"| Registry
    Swarm <-->|"orchestrates containers"| Registry
    Calico -->|"stores routes"| Etcd
    Lainlet -->|"health & metrics"| Deployd
    Lainlet -->|"dashboard updates"| Console
    Collectd -->|"metrics push"| Collectd
    Rsyslog -->|"logs aggregation"| Rsyslog

    %% Click Events
    click AnsibleControl "https://github.com/ein-plus/lain/blob/master/playbooks/site.yaml"
    click AnsibleControl "https://github.com/ein-plus/lain/blob/master/playbooks/bootstrap.yaml"
    click Inventory "https://github.com/ein-plus/lain/tree/master/playbooks/host_vars/bootstrap-node"
    click Inventory "https://github.com/ein-plus/lain/tree/master/playbooks/host_vars"
    click BootstrapScripts "https://github.com/ein-plus/lain/tree/master/Vagrantfile"
    click BootstrapScripts "https://github.com/ein-plus/lain/tree/master/bootstrap/"
    click CI_CD "https://github.com/ein-plus/lain/blob/master/bootstrap_test/distribute_ssh_key.yaml"
    click CI_CD "https://github.com/ein-plus/lain/tree/master/bootstrap_test/"
    click Etcd "https://github.com/ein-plus/lain/tree/master/playbooks/roles/etcd/"
    click Tinydns "https://github.com/ein-plus/lain/tree/master/playbooks/roles/bootstrap-tinydns/"
    click Dnsmasq "https://github.com/ein-plus/lain/tree/master/playbooks/roles/dnsmasq/"
    click Registry "https://github.com/ein-plus/lain/tree/master/playbooks/roles/registry/"
    click Firewall "https://github.com/ein-plus/lain/tree/master/playbooks/roles/firewall/"
    click Calico "https://github.com/ein-plus/lain/tree/master/playbooks/roles/calico/"
    click Deployd "https://github.com/ein-plus/lain/tree/master/playbooks/roles/deployd/"
    click Console "https://github.com/ein-plus/lain/tree/master/playbooks/roles/console/"
    click Swarm "https://github.com/ein-plus/lain/tree/master/playbooks/roles/swarm/"
    click Lainlet "https://github.com/ein-plus/lain/tree/master/playbooks/roles/lainlet/"
    click Collectd "https://github.com/ein-plus/lain/tree/master/playbooks/roles/collectd/"
    click Rsyslog "https://github.com/ein-plus/lain/tree/master/playbooks/roles/rsyslog/"
    click MooseFS "https://github.com/ein-plus/lain/tree/master/playbooks/roles/moosefs/"
    click ExtModules "https://github.com/ein-plus/lain/tree/master/playbooks/roles/libraries/library/"
    click AnsibleControl "https://github.com/ein-plus/lain/tree/master/playbooks/roles/bootstrap-layer0/"
    click AnsibleControl "https://github.com/ein-plus/lain/tree/master/playbooks/roles/bootstrap-layer1/"
    click ExtModules "https://github.com/ein-plus/lain/blob/master/playbooks/dep-graph.py"
    click ExtModules "https://github.com/ein-plus/lain/blob/master/playbooks/dep-graph2.py"
    click ExtModules "https://github.com/ein-plus/lain/blob/master/prepare.sh"

    %% Styles
    classDef orchestration fill:#cce5ff,stroke:#004085,color:#004085;
    classDef infra fill:#d4edda,stroke:#155724,color:#155724;
    classDef platform fill:#fff3cd,stroke:#856404,color:#856404;
    classDef storage fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef cloud fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
