# tiagodemay/vagrantcluster architecture

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

- Interactive diagram: https://gitdiagram.com/tiagodemay/vagrantcluster
- Repository: https://github.com/tiagodemay/vagrantcluster

## Overview

##### Project Type and Purpose
- This is an automated HPC cluster provisioning system using Vagrant and VirtualBox.
- Purpose: bootstrap a System Management Server (SMS) VM via Vagrant, generate OVA images, import and launch two compute-node VMs, and configure cluster services (Nagios, Ganglia, ClusterShell, NHC, xCAT sync).

##### Main Architectural Components
a. Host Machine (Ubuntu Desktop 22.04 LTS)
- Virtualization layer: VirtualBox
- Orchestration tool: Vagrant CLI + Vagrantfile
b. Provisioning Scripts (in project root)
- recipe.sh – orchestrates OS prep and software installs
- script01.sh – script04.sh – sequential setup of SMS
- add_your_user_slurm.sh, setenv.c – user/group and environment configuration
c. System Management Server (SMS) VM
- Base OS: CentOS 7.7 (downloaded by Vagrant)
- Installed services: Nagios, Ganglia, ClusterShell, NHC, xCAT sync
- Builds compute-node image via chroot → exports OVA files (openhpc-demo-client00.ova, …01.ova)
d. Compute-Node VMs
- Two clones imported from the generated OVA (compute00, compute01)
- Joined to cluster and managed by SMS
e. External Interfaces
- Vagrant SSH → user access to SMS VM
- vboxmanage CLI → import/start compute nodes

##### Component Relationships and Data Flows
1. On the Host, user runs “vagrant up”
↓
2. Vagrantfile invokes VirtualBox to spin up the SMS VM
↓
3. Provisioning scripts (recipe.sh, script0X.sh) run inside SMS VM via Vagrant’s provisioner
- Installs cluster management software
- Chroots into a fresh CentOS filesystem to assemble compute-node image
↓
4. SMS VM exports compute-node images as OVA files to Host filesystem
↓
5. Host runs “vboxmanage import openhpc-demo-client*.ova”
↓
6. Host starts compute-node VMs; they register back with SMS for job submission/monitoring

##### Architectural Patterns and Design Principles
- Infrastructure as Code: Vagrantfile + shell scripts for repeatable provisioning
- Immutable Infrastructure: compute-node images built by chroot and shipped as OVAs
- Separation of Concerns: one SMS VM handles management & image building; compute nodes remain lightweight
- Automation & Orchestration: Vagrant orchestrates VirtualBox and provisioning scripts

##### Technologies, Frameworks, Libraries
- Host OS: Ubuntu 22.04 LTS
- Virtualization: Oracle VirtualBox 7.x + Extension Pack
- Provisioner: Vagrant (HashiCorp)
- Guest OS: CentOS 7.7
- Cluster Tools: Nagios, Ganglia, ClusterShell, Node Health Check (NHC), xCAT file sync
- Shell / C: Bash scripts, setenv.c for environment setup

##### Essential Elements
- Host OS & virtualization stack
- Provisioning workflow (scripts + Vagrantfile)
- SMS VM: OS, cluster services, chroot image builder
- OVA artifacts (openhpc-demo-client00.ova, …01.ova)
- Compute nodes: two instances
- Data flows and orchestration commands

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Host Layer"
        HostOS["Ubuntu 22.04 LTS"]:::host
        VagrantCLI["Vagrant CLI"]:::host
        VirtualBox["VirtualBox 7.x"]:::host
        HostOS --> VagrantCLI
        HostOS --> VirtualBox
    end

    subgraph ".vagrant"
        VagrantState[".vagrant/machines/default/virtualbox"]:::host
        RGLoader["rgloader/loader.rb"]:::host
    end

    VagrantCLI --> VagrantState
    VagrantCLI --> RGLoader

    subgraph "Provisioning"
        Vagrantfile["Vagrantfile"]:::host
        Recipe["recipe.sh"]:::prov
        Script01["script01.sh"]:::prov
        Script02["script02.sh"]:::prov
        Script03["script03.sh"]:::prov
        Script04["script04.sh"]:::prov
        AddSlurm["add_your_user_slurm.sh"]:::prov
        SetEnv["setenv.c"]:::prov
    end

    VagrantCLI --> Vagrantfile
    Vagrantfile --> Recipe
    Recipe --> Script01
    Script01 --> Script02
    Script02 --> Script03
    Script03 --> Script04
    Script04 --> AddSlurm
    Script04 --> SetEnv

    subgraph "SMS VM (CentOS 7.7)" 
        Services["Nagios, Ganglia, ClusterShell, NHC, xCAT sync"]:::sms
        Chroot["Chroot Image Builder"]:::sms
        Services --> Chroot
    end

    Vagrantfile -->|"provision"| Services

    Chroot --> OVA00["openhpc-demo-client00.ova"]:::artifact
    Chroot --> OVA01["openhpc-demo-client01.ova"]:::artifact
    OVA00 -->|"export OVA"| HostOS
    OVA01 -->|"export OVA"| HostOS

    VirtualBox -->|"import & start"| Compute00
    VirtualBox -->|"import & start"| Compute01

    subgraph "Compute Node VMs"
        Compute00["compute00"]:::compute
        Compute01["compute01"]:::compute
    end

    Compute00 -->|"register"| Services
    Compute01 -->|"register"| Services

    click Vagrantfile "https://github.com/tiagodemay/vagrantcluster/tree/main/Vagrantfile"
    click VagrantState "https://github.com/tiagodemay/vagrantcluster/tree/main/.vagrant/machines/default/virtualbox/"
    click RGLoader "https://github.com/tiagodemay/vagrantcluster/blob/main/.vagrant/rgloader/loader.rb"
    click Recipe "https://github.com/tiagodemay/vagrantcluster/blob/main/recipe.sh"
    click Script01 "https://github.com/tiagodemay/vagrantcluster/blob/main/script01.sh"
    click Script02 "https://github.com/tiagodemay/vagrantcluster/blob/main/script02.sh"
    click Script03 "https://github.com/tiagodemay/vagrantcluster/blob/main/script03.sh"
    click Script04 "https://github.com/tiagodemay/vagrantcluster/blob/main/script04.sh"
    click AddSlurm "https://github.com/tiagodemay/vagrantcluster/blob/main/add_your_user_slurm.sh"
    click SetEnv "https://github.com/tiagodemay/vagrantcluster/blob/main/setenv.c"
    click OVA00 "https://github.com/tiagodemay/vagrantcluster/blob/main/openhpc-demo-client00.ova"
    click OVA01 "https://github.com/tiagodemay/vagrantcluster/blob/main/openhpc-demo-client01.ova"

    classDef host fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1;
    classDef prov fill:#B3E5FC,stroke:#039BE5,color:#01579B;
    classDef sms fill:#C8E6C9,stroke:#43A047,color:#1B5E20;
    classDef compute fill:#FFE0B2,stroke:#FB8C00,color:#E65100;
    classDef artifact fill:#CFD8DC,stroke:#90A4AE,color:#455A64;
```
