From 64f39ad16bc932d8d32be0650da049b51204a328 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 17:28:38 +0000 Subject: [PATCH 1/9] Initial plan From 7b18860b227b5775b560adf5bf845b69bd6e00bf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 26 Aug 2025 17:39:20 +0000 Subject: [PATCH 2/9] Fix encoding issues and remove unprintable characters from markdown files Co-authored-by: danielbodnar <1790726+danielbodnar@users.noreply.github.com> --- STACK.md | Bin 15653 -> 15122 bytes specs/ARCHITECTURE.md | Bin 20138 -> 14751 bytes specs/DESIGN.md | Bin 17260 -> 15304 bytes 3 files changed, 0 insertions(+), 0 deletions(-) diff --git a/STACK.md b/STACK.md index dbaa0b7c500dc6a0d50567f65f8445319bfc69ce..3477ec84d6261d125f9411cdb499d06801b07ef5 100644 GIT binary patch delta 1762 zcmaJ?OH30%7!H<4TWO0e6lh5qv;r!-R9gr^L=TFun0WAD;=yd&p^WT-Y+X#>R&9{I^Xo^>?F zlB8o#4fOv+2(p3nD34=!)I#c8M97-NBy0tH;aQ-si@WQl3T?q5_!by~KY_V(TxSog zps9#k+5<}_z~(^;HB8Pv~ac7Fn@1BKCX84LSED8+H_82sd!&-Gn{e9v>8sj;@j|q zk6ZV`8G%Rh<6*n?t{H-kWh@z9Hp1=5$!nI`ejMCRUFSTYk#MjR5hvVq_H1lm?Z~ns zG~f(ZdZyBD0ADSE!&u`y$JN%r%bxS_t7iy8N4_@U%@-ZTIw2WNSWE4_dh@kg-Ld7u zBi1aHh|0PmDxobFt_c8i%DK!;hF{f=-d{Op^ehz&$CEG`i%mK)H3EBCjclzKM%az@ z!dC2P7}fEy`XTnDtqB{g@9Y@QFM2bu_ZBF?PT%pUev|Pf0lT39{OnK8@%(wBx@FN4 z)mB_4P{mwxn+Z?mPNFr|Cnf2rXQ@xwm8ie232^h(Z!S!4!f^O-g d#Qq|TSt}GC7%Q6i#X-{vnB-bl2S`5Vj?#73ywMlZL274IqA0fm8`qLJ9)0w#Uwr{jqk( zPQoQejzEVKT*?6sAfcjMI3gjqR7kBvj~wW!;($QniqiRJcgE|Vy^QDmeDA$)-g~~) z`}(6hleyfJ6BBGQ_mVhY&RrAdQSMc7{+!#&X%iF2C%JbggioS0Kgn5OnUrLSj!_Yyeq{m(X4M3x6VNZHj=(* zgh9(~+lP+t2_j+rRk5l8Hf}_22W(+Nmj2r7*ZX+`Qv?|v04VTflvbS&*TKfRONPt^`oJZU23H}-LP`#d1|oDnbVh_U0zlLKl;&c0|2m^~~%Sc2I|KPbWtR?()} zUzNqC1w#ZwjD!-dG8?Ul~t);dq*Z%cY}fK%v~CG z#4AY)>UR&60Lk@SU)=Fqy^>6DJFi!S76N==u}udO%7(7~cVuYWs48N3ZZj%3j&$5KK0PZK`S0>2ahkOY;(VjF otRvLT$Zhk#`1q>Y*SBj+?33EOu)1Bd#Q9roMeOi@Yv&4&0YVqY9RL6T diff --git a/specs/ARCHITECTURE.md b/specs/ARCHITECTURE.md index 5c739fc1f3109882cbe8c70818f191e255f6101c..fb6a70bd0bb7e88d1c1e64dd2d7336c556d96247 100644 GIT binary patch literal 14751 zcmb_jTW=gkc7C5)s6g!&(ITmIRMmx6`*~C^byf`q=YMeC z8ktmKRhJ*Wxu~jDxwE~UEazM0BGGAFZYBBlG>qqZ+g}l!6nR`nRg!0K+`N9O!+0Ic z3$3%iD64g<|9qB)RZ#w<4h#KO19qNNi+Z{h<;(49QcVTnfHr8J77qQl2+hg5tn_lf zfw2)aGb^}x>-L`n)3nwvM5APwF`bO}xR+GHgVoE9PqS!Ra2!_2g%0u}%;qoN=<@P% z3un$(;M7eT5o zbgIHehQn0lIQT`PFO@+3{A&__Uz#!Jftds7Z``^2#@_8WZr=@BU;+z<_7dq)X}H!! z$<$dDNfsrmRF`I(@BdYukMrd!&xjSiCeR5W&@$q0q6zdkhu*niu&2^R$keltpZ%3O z-w&%$-A(h$9^@D!!3-lk$OqXhFP0)DG(oMx3cxc9_nS`vSFh51&C=6FId(%m$lfYQ zQdsGE;^^?~Yju8rL(K7>M4$_n4rs=DaPK@J{JU}2ulN{Ac2CO{JyOi44l^LG3d}zRdBQj<7B=pcgQZ0VS4tZDAtJ` zA**B`aP*d0QhPenvjiAJ$c%j=qttwDKZz)c+zf{Y&a^_|JkttVz)0m~r5;RF6lPgo zsi{`WJWggr^{`S!omI(FW8R%KSthWwP$O9GSu(GU`ou*tt42y^ix8%~R3*$~L6R>> zz%~qr)`TB5CY(3lP16oEaTc-j6j%u!t@08ss9+sdk6__QZ-GWtMJW0!u z!mD%|Mvrl#l~qDQ<@q;%PiizAim8l^4c{e8#cYaQFZb z7f%S&bgfEO5{3iiPa&i1@!Fhk96LjL`ZM4H2}?3WYXpNWU8)(%eQ@t%Fbt-XTsMwX zB^c*PWb(>-waSZ14)p~9jp2_{U17%m1`7Xeax@xk_Zf259b&YRG>Axs;$~`ELj>>J?B1|$!)(Ei>q7kU>NPUnOkJCJiO99k27XbOyKa&cz zUwh{@x-wFSNmf6BY!{h^e%=p@_!3dHdejOGWseR)RS>+-ff~r+lZM~Zarh;li)OY_ z;W7Th5xmDIHA~WT=bFATyEW6^3`=Plp1rMa&2D+aypLIWdv;6T_Qu*8ig*jPUN(SfmFz^bUupa0w6klC{H;M(vuK<3G__w&n) zZJyfSH|r=SdN2X>U;dAck9evJq&(9FhL9n~;cj(EQRGBBn`)FQZ5|pxS%VmlY zW=ueKVkO(yWq&h-fzal>D6Ok7hf??4h&TPw(PR}~W`HV&+fv|SS<-vovphPIb;lFC z1n$Gm&wA6H`;b*9ASh+obikh~`(&wLyouu}+j8O`zo9Su1{RMZ0CKSMmEQ_4_$~jD zXC5-7@4j~A?hY8bHn0o;0pwNxDFPtHf-SWW;zcUa&H>4RBXVC zQ)68){%RJ*@lBo}V@yjkc6&OF|I8aRG&SDr##HM+^+pX@Wi-AKy`%lLmQXSr-HO82 za6>GafSvVh>Or>zGsEO&BX8IvikWdUp2aNyBFVch%AUvO zWle%cPH;G6{XeM-|SW~v+sM@F_`C{ z{*z+fHz7GIH@$b!S2(3Gk^P+;#977RAnMQIc;O4(7&{H}i<-(bkyP-Ic{4ROMXHS( zFf`)=T;D3bF44%sB0R|8>^rXOY8Ux3>YX5K+`iP)MV>!aIBw%)*D6A0JJ+Qn%p-&g zh>N|%#)6B0_r+)aXYsPZUJskV`oCV#gY*h%m46(UJc0s;R$;{KGc;oR(+y)@_xLXK z`Tw50S?CDh@IMYw|5+hjYU&(r%u$3Ya8+Z5j*+e*U+a?@y1Wa`zlYrT z)jXQnipWd-lbY^m_LC4bkR^Lj($%YuaH=E5ffqwoEe{D{OkeW?)Ui4<49SIhF zD@%c>f6}u9nfduY+7SLAqr5Ycf&xRv(S!G??z5xjINz!+7a+|ypYkAHV~`HBgJhXq z&Grg@2Q!|2$1`XQQyAMFbz%L?9}ymi25=yr#^acGcCG*D3HY7v=LSez#%H&PLPdiT1v4jUD4{gTB%QZi_M-7uCm6BsnW!1(V#O;D^?ba4K{f4xKBUr&o9 zhKlBOe8u(;GBi@?Wm2Nlx8dJOJw-$-5SSj`wHzJ4RPVj#vy9&X+lHS2%JS9$PX43g zGukuWG(E@U(w9HsRH_^@+4Y0&M@apFB!Mx^62|Go> z=tht06|FIJutOUk9dWPOa*sOF@Ol(a8&Yp1o{g7zvQ-+ss;~+|+nVDV)wTL*9<7?1 zM`$ZaF>anw*5-ek9>5x>(qy~Pn(|^?Jr>*flKLAi8#^dFs^hy8^G!XN{uqS;roCNA zLmR$h&a3d*u0$oVIfc5a*+A^6ckgDp3*`JQ_i6=1?7Env8}>kCiP;?C1>38){gGpj zoR93KUTY^N0574{Y^ZHSi%U$U#wQPV)H_Puco&gufpUvdr@IJjZoGRB41V{Wdvxb! zj=rOAUB6DRZ{jAd;Uki%JTRMf^qP3hn;SQXhpzn7>JqLDUc{Wt|7dKe|F-v?b|(WZ zT@M}e)thZzG>NzgOs|?~-@grLonclpKOzC{Za7QhSIgr`r?*#XsaZTKF62YBU zSGUTDX6&L8h8DOJWRr9abAMNsJJ={r6xCFRtidu_#{T!e=+msDBd}J;*o*(N0(d;M zHt?(nXR{;{sgckU6*On245kK$4x*bBnaE^j-%#euP5T8=g~+*)mB}JRkAh=~+ZA_x zAxAlWw)f+g()oxcEp9YLbPka$znqcsq+FZEe5v zK!co*3PLt(Gr)0FR^1~O!5qdrxC^n3k?k92YH^}6S&b{c9WXc2D_m*PTk@v*3A#Xb z6eJ71F$j0Ckp+{qnt&8;f#Z_eHltP{fZKXFfp85y7j;V4Pqr?;MSEH7X*1j~NMjZ5 zRjG-@6}8pE)Xe#w80Ak}Qbkuy$Vq1!u1kgo+-=2y&V_!E;qZjIf1snZ$IIG~k|m|O zh$=1C)R{zAQzfd2C?ryYsqGM=2AJXSSkEE50{s-ljs!jkQ>F;ubui_#_t0+m}cwXxinL%j9EAa7HLq(y4R6*6TX?fzqw7J$4 z)Oy@`hyns(QFsk0gi?v~fGFl308IkuyhTx#&c>YbF@7Z$aTk@>lLZch<=Rnwq-Nog zYPto4E~ldC)odVqOHS}q=yfxW)C$!KR8Jw*glDICeuW~*T}o`*g{AN7)v0epg3zHV zWJ76Il1|UF-yYWE1b4YBq#y<(1x=T)3Zk??Vu>Cv^dCS1apRAxm!`qzl^Ae{`Wwf! z)0cFmLFGwhsVS|;gEQ&?gjKLq6D>k3CKdUUDK~y!CG0lwA>N=p z-mhy;4(Tf45*bOkDqv-Wt(*q}sX6WiNK$=w(6q&h44Wp|9l2}-L;5b5d^z&(5@<+X zYm*c5K6^E^n~*?32=Rp!Nw_>m{sN^RdDC?)>_ySzPu;h2G%~&IRwCFPZY4s=y~weH z5nz%i?gTNi;ZAS|eKS?CFa0z9V@Oy4(N{c?Fh^UE)#}H;RBeH)~LmGKW#YB zqcRmCaQW=419u}4lJMx;WbE(d%QKF3&osfIzsZq<;Ezt8pEkP8gn5Y;6)WOXRC`9U4jO}`@y zL=#e_g*T@kv)Hz26eRdJDlN>$NfFhM&pp@?NTFb6iqNVvh_Fn#B0_}fC*+g5m9<~FYYJfP7G?w-VxOpq84?WVgd<9C9D2>cbXa-6 zFCDiX=4T)rFLFR!a#BE?n zlp`^8KkC|2gaeF?p+ybnir^5f#y~$Qk#jd}a)fY^9S}m8fM0Nx9H7Nu58nuaR@g*h zW^}Qs2HylfKOoD?9g)i^{nUVrAjPBj*;z(E`=VBR*AEYKjf=^q$)5)42Mo*!2o&9! zyVR%oL0*fRlydZ2?$LrT#KI8~01-ui6pJEvf)J?+NfhK)BytGLT^c4OL#v|v5&#D= zzXfW}j-$cSahE*;ooX%Ap5e!hB?X44VP4U5Pav+6a4=VdgMT7GLSURS%JUGr61RXl bMt2Fz9|7VZouABoI_`cH{mR5$P;dPXCNvj& literal 20138 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 QTPLyUL}6p1--LPa{|^+2fdBvi diff --git a/specs/DESIGN.md b/specs/DESIGN.md index d93d5c7fe29408f64cfbf82ba2a20f8bb02daf7c..a48bd0099e6abb9c751b9849c752df2eed387cc7 100644 GIT binary patch delta 1511 zcmah}%}*0S6iJd0*CEg%fzWTF5M`QBDJWkyUcb-RYnLw zVDMcvT#~I=d6K2}rje&8U!<09xnxea^dhwdGN;?7VXfm@fyYWtkY8?=~pF6Lj+xF*w{Vaz4d zS&rx5r0(j~%>=KXQ4F?<_qK001liaqJd6#%`&jfWYRJ-S$VdEwYYMcf{g6`k;6T-& zJ0A6J#Ct+e(gxtE*6;0WiO>!yJGRtXF)X=2YqB~jm+5vz7&VQR>Tz(LYXYQ|i9aqA za%n8?8&wE(^FGRHlV>$0c#~i)BwjRJR&saNkUBUF4QWb{TxxG*urY zUnH5#F^kt6`yHy)+SBo@P3wkPw&{3a8fU)&+{Ps1{=}+eXr66S8}o*kblx=@c|mdO J9j5L!`~d^6euV%4 delta 3581 zcmb_eO>7%Q6kczT5?dfy5KJGiK`4aiEMWVGW3}zR|8=z1uf+y$dlh zR@+@!-8K2 zHni)O-k#MpmyXYg=J%=3`fq5ZB8^$oX~&p0iv)zq5Rnyl`%611_dxZQUju$CYPZog zBfd#KccO#GnH2dng)_-=rW7I*R=je3X>M+LW_fOwX|6KjyTQ^#M`+soVMDBGe-GLd zZ6Rrfd2Or@Gvd#4164>i#VP+Z&*x*?v~Gf|YgHIep7AQE+F+u68iwYb95ysd%^Ns- zEp`Z_*e5!STZe>^5e$Wk$9zzdQ)p?jOO3!?t;o`Z<*773y+{){$rh)tqJXBf1qwcM zs3fPN#B_uOOX5a&6xP0BoQZb{lGaF~U7I3%dMF=9p&1=M%rqBHr+c1&HXmp0$)kSl zc6FIZQSq2VC{+<`dc-L4c6j!t6yBppQHqA z=PyuyFF!&31J&=^Cq&kIfs!_5S=4V>@BbfQo)-UOjZr^r%OsX;i{vkCoBCaQocagQ zV<5eS0`)H!-T~TS+>GsG{~lji_x%l}il^u!jR-1Pj z8r1^BP!(Sl5VY7&wGbN;l^_{gs#mKxuOMgE9k0Ui4nGQ{jyS!wRo!_U;zv;>eq59~ zWQhmv8ezu!4%_#wGL>o0pY2J!a+lrk>w)J~S1o=UU!L&XyUUgWf0Kvnyk1k;hCNcC zs>B+`Uh~t5mlBOurWB~Wu{)J;0_s6I?^hsUCR*>|v9x^aNmNh7(JhZqJzg+xts<$yZYRZM$F0@_{zmJdXeYRV z^YD{b6k{Lo+6n>zI;H@D+EFn0_yd4xXcX5nFZ Date: Tue, 26 Aug 2025 17:47:44 +0000 Subject: [PATCH 3/9] Enhance all markdown files with GFM styling, emojis, badges, and visual improvements Co-authored-by: danielbodnar <1790726+danielbodnar@users.noreply.github.com> --- README.md | 379 ++++++++++++++++++++++++++++++++---------------- README2.md | 105 ++++++++------ STACK.md | 144 ++++++++++-------- specs/DESIGN.md | 86 ++++++----- 4 files changed, 449 insertions(+), 265 deletions(-) diff --git a/README.md b/README.md index 102a5b0..9567fd7 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,149 @@ -# BitBuilder Hypervisor - -A git-ops-based, multi-tenant hypervisor platform built on systemd technologies for secure, isolated, and declaratively managed virtualization environments. - -## Overview - -BitBuilder Hypervisor is a next-generation hypervisor system that leverages the full power of systemd's virtualization and containerization capabilities to provide secure, isolated multi-tenant environments. Each tenant's configuration is version-controlled in Git repositories, enabling true infrastructure-as-code workflows with automatic provisioning and updates at boot time. - -## Key Features - -- **Git-Ops Native**: All configurations stored in Git repositories, pulled at boot time -- **Multi-Tenant Isolation**: Complete separation between tenants using systemd's security features -- **Immutable Host OS**: Read-only host system with all changes applied through git-controlled overlays -- **Declarative Configuration**: Everything defined as code, no manual configuration required -- **Zero-Trust Architecture**: Each tenant runs in completely isolated environments -- **Dynamic Provisioning**: Automatic tenant setup and teardown based on git repository state - -## Core Technologies - -### Systemd Components - -- **systemd-boot**: UEFI boot manager for secure boot chain -- **systemd-import-generator**: Automatic EFI image download and boot management -- **systemd-vmspawn**: Lightweight VM spawning for tenant isolation -- **systemd-nspawn**: Container spawning for application isolation -- **systemd-networkd**: Network configuration and isolation -- **systemd-homed**: User home directory management with encryption -- **Portable Services**: Self-contained service images -- **sysext/confext**: System and configuration extensions via overlayfs -- **Varlink**: IPC protocol for service communication - -### Linux Userspace API Specifications - -BitBuilder Hypervisor implements and adheres to the [Linux Userspace API Specifications](https://uapi-group.org/specifications/): - -- [**Configuration Files Specification**](https://uapi-group.org/specifications/specs/configuration_files_specification/): Standardized locations for configuration management -- [**Discoverable Partitions Specification (DPS)**](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/): Auto-discovery of partition semantics -- [**Discoverable Disk Image (DDI)**](https://uapi-group.org/specifications/specs/discoverable_disk_image/): Self-describing system images -- [**Extension Image**](https://uapi-group.org/specifications/specs/extension_image/): Layered extensions to base images - - **sysext**: System Extension Images overlaid on `/usr/` and `/opt/` - - **confext**: Configuration Extension Images overlaid on `/etc/` -- [**Unified Kernel Image (UKI)**](https://uapi-group.org/specifications/specs/unified_kernel_image/): Combined kernel, initrd, and boot configuration -- [**Boot Loader Specification (BLS)**](https://uapi-group.org/specifications/specs/boot_loader_specification/): Standardized boot configuration - -## Architecture Highlights - -- **Immutable Host**: The host OS boots from an immutable image downloaded via systemd-import-generator -- **Tenant Isolation**: Each tenant runs in isolated systemd-vmspawn/nspawn instances -- **Git-Based Configuration**: All tenant configurations pulled from dedicated Git repositories -- **Dynamic Mount Generation**: Custom systemd generators create tenant-specific mount points -- **Layered Extensions**: System capabilities extended through sysext/confext layers - -## Tenant Management +# πŸš€ BitBuilder Hypervisor + +[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE) +[![SystemD](https://img.shields.io/badge/SystemD-258+-blue?style=flat-square)](https://systemd.io/) +[![Git-Ops](https://img.shields.io/badge/Git--Ops-Native-orange?style=flat-square)](https://www.gitops.tech/) +[![UEFI](https://img.shields.io/badge/UEFI-Secure%20Boot-green?style=flat-square)](https://uefi.org/) + +> **πŸ”₯ A revolutionary git-ops-based, multi-tenant hypervisor platform built on systemd technologies for secure, isolated, and declaratively managed virtualization environments.** + +--- + +## 🌟 Overview + +**BitBuilder Hypervisor** is a next-generation hypervisor system that leverages the full power of systemd's virtualization and containerization capabilities to provide secure, isolated multi-tenant environments. Each tenant's configuration is version-controlled in Git repositories, enabling true infrastructure-as-code workflows with automatic provisioning and updates at boot time. + +--- + +## ✨ Key Features + +| Feature | Description | Benefits | +|---------|-------------|----------| +| πŸ“š **Git-Ops Native** | All configurations stored in Git repositories, pulled at boot time | Version control, atomic deployments, rollback capability | +| 🏠 **Multi-Tenant Isolation** | Complete separation between tenants using systemd's security features | Zero trust architecture, cryptographic boundaries | +| πŸ›‘οΈ **Immutable Host OS** | Read-only host system with all changes applied through git-controlled overlays | Eliminates configuration drift, enhanced security | +| 🎯 **Declarative Configuration** | Everything defined as code, no manual configuration required | Infrastructure as Code, automated provisioning | +| πŸ” **Zero-Trust Architecture** | Each tenant runs in completely isolated environments | Hardware-backed security, namespace isolation | +| ⚑ **Dynamic Provisioning** | Automatic tenant setup and teardown based on git repository state | Scalable operations, automated lifecycle management | + +--- + +## πŸ”§ Core Technologies + +### πŸ–₯️ Systemd Components + +| Component | Purpose | Features | +|-----------|---------|----------| +| πŸš€ **systemd-boot** | UEFI boot manager for secure boot chain | Secure boot, UKI support, boot management | +| ⬇️ **systemd-import-generator** | Automatic EFI image download and boot management | DDI support, automatic updates, verification | +| πŸ–₯️ **systemd-vmspawn** | Lightweight VM spawning for tenant isolation | Hardware virtualization, resource isolation | +| πŸ“¦ **systemd-nspawn** | Container spawning for application isolation | Namespace isolation, security boundaries | +| 🌐 **systemd-networkd** | Network configuration and isolation | Software-defined networking, tenant isolation | +| 🏠 **systemd-homed** | User home directory management with encryption | Encrypted homes, hardware-backed auth | +| 🎁 **Portable Services** | Self-contained service images | Application portability, dependency isolation | +| πŸ“‹ **sysext/confext** | System and configuration extensions via overlayfs | Layered filesystems, immutable updates | +| πŸ”— **Varlink** | IPC protocol for service communication | Type-safe IPC, service discovery | + +### πŸ“‹ Linux Userspace API Specifications + +BitBuilder Hypervisor implements and adheres to the [**Linux Userspace API Specifications**](https://uapi-group.org/specifications/): + +| Specification | Purpose | Implementation | +|---------------|---------|----------------| +| πŸ“„ [**Configuration Files Specification**](https://uapi-group.org/specifications/specs/configuration_files_specification/) | Standardized locations for configuration management | `/etc`, `/usr/lib`, `/run` hierarchy | +| πŸ’½ [**Discoverable Partitions Specification (DPS)**](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/) | Auto-discovery of partition semantics | GPT partition type GUIDs | +| πŸ“€ [**Discoverable Disk Image (DDI)**](https://uapi-group.org/specifications/specs/discoverable_disk_image/) | Self-describing system images | Unified disk images with metadata | +| πŸ”§ [**Extension Image**](https://uapi-group.org/specifications/specs/extension_image/) | Layered extensions to base images | Overlay filesystem extensions | +| β”œβ”€β”€ **sysext** | System Extension Images overlaid on `/usr/` and `/opt/` | Runtime system extensions | +| └── **confext** | Configuration Extension Images overlaid on `/etc/` | Runtime configuration extensions | +| πŸš€ [**Unified Kernel Image (UKI)**](https://uapi-group.org/specifications/specs/unified_kernel_image/) | Combined kernel, initrd, and boot configuration | Single-file bootable images | +| πŸ₯Ύ [**Boot Loader Specification (BLS)**](https://uapi-group.org/specifications/specs/boot_loader_specification/) | Standardized boot configuration | systemd-boot integration | + +--- + +## πŸ—οΈ Architecture Highlights + +| Component | Description | Technology | +|-----------|-------------|------------| +| πŸ›‘οΈ **Immutable Host** | The host OS boots from an immutable image downloaded via systemd-import-generator | DDI images, systemd-import | +| 🏠 **Tenant Isolation** | Each tenant runs in isolated systemd-vmspawn/nspawn instances | Hardware virtualization, namespaces | +| πŸ“š **Git-Based Configuration** | All tenant configurations pulled from dedicated Git repositories | Git-ops, declarative config | +| πŸ—‚οΈ **Dynamic Mount Generation** | Custom systemd generators create tenant-specific mount points | systemd generators, overlay mounts | +| πŸ”§ **Layered Extensions** | System capabilities extended through sysext/confext layers | Extension images, overlayfs | + +--- + +## 🏠 Tenant Management + +Each tenant in the BitBuilder Hypervisor follows a complete lifecycle management approach: + +```mermaid +graph LR + A[πŸ“š Git Repository] --> B[πŸ” Discovery] + B --> C[⚑ Provisioning] + C --> D[πŸ–₯️ VM/Container] + D --> E[πŸ”„ Updates] + E --> A + + style A fill:#e3f2fd + style B fill:#f3e5f5 + style C fill:#e8f5e8 + style D fill:#fff3e0 + style E fill:#fce4ec +``` -Each tenant in the BitBuilder Hypervisor: +### πŸ”„ Tenant Lifecycle + +| Step | Process | Details | +|------|---------|---------| +| **1️⃣** | **Dedicated Git Repository** | Each tenant has its own configuration repository | +| **2️⃣** | **Automatic Provisioning** | Boot-time provisioning via `setup-tenant@.service` | +| **3️⃣** | **Isolated Execution** | Runs in systemd-vmspawn or systemd-nspawn instances | +| **4️⃣** | **Custom Extensions** | Can have tenant-specific sysext/confext layers | +| **5️⃣** | **Network Isolation** | Complete network isolation via systemd-networkd | +| **6️⃣** | **Automatic Updates** | Updates automatically when Git repository changes | + +--- + +## πŸš€ Boot Process + +```mermaid +sequenceDiagram + participant UEFI as πŸ”Œ UEFI Boot + participant Boot as πŸš€ systemd-boot + participant Import as ⬇️ systemd-import-gen + participant Host as πŸ–₯️ Host OS + participant Git as πŸ“š Git Sync + participant Discovery as πŸ” Tenant Discovery + participant Provision as ⚑ Tenant Provisioning + + UEFI->>Boot: Load boot configuration + Boot->>Import: Download and verify EFI image + Import->>Host: Start immutable host OS + Host->>Git: Pull system configurations + Git->>Discovery: Scan for tenant configs + Discovery->>Provision: For each tenant: + Note over Provision: β€’ Clone/pull tenant repo
β€’ Mount tenant directories
β€’ Apply sysext/confext layers
β€’ Start VM/container
β€’ Execute provisioning units +``` -1. Has a dedicated Git repository containing all configuration -2. Gets provisioned automatically at boot via `setup-tenant@.service` -3. Runs in isolated systemd-vmspawn or systemd-nspawn instances -4. Can have custom sysext/confext layers for additional functionality -5. Has complete network isolation via systemd-networkd -6. Gets automatic updates when Git repository changes +### πŸ”„ Boot Sequence Details -## Boot Process +| Phase | Component | Action | Result | +|-------|-----------|---------|---------| +| **1️⃣** | πŸ”Œ **UEFI Boot** | systemd-boot loads the boot configuration | Secure boot validation | +| **2️⃣** | ⬇️ **Image Import** | systemd-import-generator downloads and verifies the host EFI image | DDI image verification | +| **3️⃣** | πŸ–₯️ **Host Boot** | Immutable host OS starts with minimal services | Base system ready | +| **4️⃣** | πŸ“š **Git Sync** | System-level configurations pulled from Git repositories | Configuration sync | +| **5️⃣** | πŸ” **Tenant Discovery** | Scan for tenant configurations in Git | Tenant enumeration | +| **6️⃣** | ⚑ **Tenant Provisioning** | For each discovered tenant: provision resources | Multi-tenant setup | -1. **UEFI Boot**: systemd-boot loads the boot configuration -2. **Image Import**: systemd-import-generator downloads and verifies the host EFI image -3. **Host Boot**: Immutable host OS starts with minimal services -4. **Git Sync**: System-level configurations pulled from Git repositories -5. **Tenant Discovery**: Scan for tenant configurations in Git -6. **Tenant Provisioning**: For each tenant: - - Clone/pull tenant Git repository - - Mount tenant-specific directories - - Apply sysext/confext layers - - Start tenant VM/container via systemd-vmspawn/nspawn - - Execute pre/post provisioning units +--- -## Configuration Structure +## πŸ—οΈ Configuration Structure -### Host Filesystem Hierarchy +### πŸ—‚οΈ Host Filesystem Hierarchy -``` +```bash / β”œβ”€β”€ /boot/ # Boot partition (read-only) β”‚ └── efi/ # EFI System Partition @@ -144,23 +208,62 @@ Each tenant in the BitBuilder Hypervisor: └── tenants/ # Runtime tenant data ``` -## Security Model +--- + +## πŸ›‘οΈ Security Model + +### πŸ”’ Core Security Principles + +| Security Layer | Technology | Implementation | Benefit | +|----------------|------------|----------------|---------| +| πŸ—οΈ **Immutable Infrastructure** | DDI, overlayfs | Host OS cannot be modified at runtime | Eliminates configuration drift | +| πŸ“š **Git-Only Changes** | Git-ops workflow | All modifications through Git commits | Audit trail, rollback capability | +| 🏠 **Tenant Isolation** | systemd security | Complete separation using multiple boundaries | Defense in depth | +| πŸ” **Encrypted Storage** | systemd-homed, LUKS | Optional encryption for tenant data | Data protection at rest | +| πŸš€ **Secure Boot** | UEFI, TPM | Full secure boot chain support | Boot integrity verification | + +### πŸ” Multi-Layer Isolation + +```mermaid +graph TB + subgraph "🏠 Tenant A" + VM1[πŸ–₯️ VM Instance] + NS1[πŸ“¦ Container] + end + + subgraph "🏠 Tenant B" + VM2[πŸ–₯️ VM Instance] + NS2[πŸ“¦ Container] + end + + subgraph "πŸ›‘οΈ Security Boundaries" + PID[πŸ”’ PID Namespaces] + NET[🌐 Network Isolation] + MOUNT[πŸ’Ύ Mount Namespaces] + USER[πŸ‘€ User Namespaces] + CGROUP[βš™οΈ Resource Limits] + CAP[πŸ”§ Capabilities] + MAC[πŸ›‘οΈ SELinux/AppArmor] + end + + VM1 --- PID + VM2 --- PID + NS1 --- NET + NS2 --- NET + VM1 --- MOUNT + VM2 --- USER + NS1 --- CGROUP + NS2 --- CAP + VM1 --- MAC +``` -- **Immutable Infrastructure**: Host OS cannot be modified at runtime -- **Git-Only Changes**: All modifications must go through Git commits -- **Tenant Isolation**: Complete separation using systemd security features: - - Separate namespaces (PID, network, mount, user) - - Resource limits via cgroups - - Capability restrictions - - SELinux/AppArmor contexts -- **Encrypted Storage**: Optional encryption for tenant data via systemd-homed -- **Secure Boot**: Full UEFI secure boot chain support +--- -## Git Repository Structure +## πŸ“ Git Repository Structure -### System Repository +### πŸ—οΈ System Repository -``` +```bash bitbuilder-system/ β”œβ”€β”€ .gitops/ β”‚ └── config.yaml # Git-ops configuration @@ -186,9 +289,9 @@ bitbuilder-system/ └── registry.json # Active tenants list ``` -### Tenant Configuration Repository +### 🏠 Tenant Configuration Repository -``` +```bash tenant-/ β”œβ”€β”€ metadata.json # Tenant metadata and requirements β”œβ”€β”€ infrastructure/ # Infrastructure manager config @@ -222,59 +325,85 @@ tenant-/ └── health-check.sh # Health monitoring script ``` -### Template Repositories +### πŸ“‹ Template Repositories BitBuilder provides standard templates for creating new tenants and resources: -- **`tenant-infra-template`**: Infrastructure manager VM template -- **`tenant-machine-template`**: VM instance template (systemd-vmspawn) -- **`tenant-container-template`**: Container template (systemd-nspawn) -- **`tenant-homed-template`**: User home directory template -- **`sysext-template`**: System extension template -- **`confext-template`**: Configuration extension template +| Template | Purpose | Technology | Use Case | +|----------|---------|------------|----------| +| πŸ—οΈ **`tenant-infra-template`** | Infrastructure manager VM template | systemd-vmspawn | Tenant orchestration | +| πŸ–₯️ **`tenant-machine-template`** | VM instance template | systemd-vmspawn | Application VMs | +| πŸ“¦ **`tenant-container-template`** | Container template | systemd-nspawn | Containerized apps | +| 🏠 **`tenant-homed-template`** | User home directory template | systemd-homed | User environments | +| πŸ”§ **`sysext-template`** | System extension template | Extension images | System augmentation | +| βš™οΈ **`confext-template`** | Configuration extension template | Extension images | Config management | + +> πŸ“– See [**STACK.md**](STACK.md) for detailed template specifications and implementation details. -See [STACK.md](STACK.md) for detailed template specifications. +--- -## Advantages +## 🎯 Advantages -- **Version Control**: All infrastructure changes tracked in Git -- **Rollback Capability**: Easy reversion to previous configurations -- **Audit Trail**: Complete history of all changes -- **Declarative Management**: Define desired state, not procedures -- **Scalability**: Add/remove tenants by updating Git repositories -- **Consistency**: Identical deployments from the same Git commits -- **Testing**: Test configurations in staging before production +| Advantage | Description | Impact | +|-----------|-------------|---------| +| πŸ“š **Version Control** | All infrastructure changes tracked in Git | Complete change history, diff capabilities | +| πŸ”„ **Rollback Capability** | Easy reversion to previous configurations | Zero-downtime rollbacks, safety net | +| πŸ“‹ **Audit Trail** | Complete history of all changes | Compliance, security, accountability | +| 🎯 **Declarative Management** | Define desired state, not procedures | Reduced complexity, predictable outcomes | +| πŸ“ˆ **Scalability** | Add/remove tenants by updating Git repositories | Horizontal scaling, resource optimization | +| ⚑ **Consistency** | Identical deployments from the same Git commits | Reproducible infrastructure, dev/prod parity | +| πŸ§ͺ **Testing** | Test configurations in staging before production | Risk reduction, validation workflows | -## Use Cases +--- -- **Multi-Tenant Hosting**: Secure isolation for multiple customers -- **Development Environments**: Reproducible developer workspaces -- **Edge Computing**: Lightweight virtualization for edge deployments -- **CI/CD Infrastructure**: Dynamic test environments -- **Application Isolation**: Run untrusted workloads safely -- **Compliance Environments**: Auditable, immutable infrastructure +## 🎯 Use Cases -## Requirements +| Use Case | Industry | Benefits | Technology Stack | +|----------|----------|----------|------------------| +| 🏒 **Multi-Tenant Hosting** | Cloud Providers | Secure isolation for multiple customers | systemd-vmspawn, networking | +| πŸ‘¨β€πŸ’» **Development Environments** | Software Development | Reproducible developer workspaces | systemd-nspawn, git-ops | +| 🌐 **Edge Computing** | IoT, CDN | Lightweight virtualization for edge deployments | Minimal footprint, secure boot | +| πŸ”„ **CI/CD Infrastructure** | DevOps | Dynamic test environments | Automated provisioning, git integration | +| πŸ”’ **Application Isolation** | Security | Run untrusted workloads safely | Namespace isolation, capabilities | +| πŸ“‹ **Compliance Environments** | Finance, Healthcare | Auditable, immutable infrastructure | Immutable OS, audit trails | -- UEFI-capable hardware -- systemd 258+ with all virtualization features enabled -- Git client -- Network connectivity for Git repository access -- Sufficient resources for tenant VMs/containers +--- -## Documentation +## πŸ“‹ Requirements -- [Technical Design](specs/DESIGN.md) - Detailed design documentation -- [Architecture](specs/ARCHITECTURE.md) - System architecture overview +### πŸ–₯️ Hardware Requirements -## License +| Component | Minimum | Recommended | Purpose | +|-----------|---------|-------------|---------| +| πŸ”Œ **UEFI Firmware** | UEFI 2.0+ | UEFI 2.8+ with Secure Boot | Boot integrity, hardware security | +| βš™οΈ **systemd Version** | 258+ | 260+ | All virtualization features enabled | +| πŸ“š **Git Client** | 2.30+ | Latest stable | Repository operations, authentication | +| 🌐 **Network Connectivity** | Basic | High-bandwidth | Git repository access, updates | +| πŸ’Ύ **Resources** | 8GB RAM, 100GB storage | 32GB RAM, 1TB NVMe SSD | Tenant VMs/containers | + +--- + +## πŸ“– Documentation + +| Document | Description | Audience | +|----------|-------------|----------| +| 🎯 [**Technical Design**](specs/DESIGN.md) | Detailed design documentation | Architects, Developers | +| πŸ›οΈ [**Architecture**](specs/ARCHITECTURE.md) | System architecture overview | Technical Leaders, Ops | + +--- + +## πŸ“„ License \[License details to be added\] -## Contributing +--- + +## 🀝 Contributing \[Contribution guidelines to be added\] -## Support +--- + +## πŸ†˜ Support \[Support information to be added\] diff --git a/README2.md b/README2.md index 5fb0dc5..9a350fc 100644 --- a/README2.md +++ b/README2.md @@ -1,37 +1,50 @@ -# BitBuilder Hypervisor +# πŸš€ BitBuilder Hypervisor -**A Git-Ops Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration** +[![Advanced Architecture](https://img.shields.io/badge/Architecture-Advanced-red?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) +[![SystemD Ecosystem](https://img.shields.io/badge/SystemD-Ecosystem-blue?style=flat-square)](https://systemd.io/) +[![Git-Ops Native](https://img.shields.io/badge/Git--Ops-Native-orange?style=flat-square)](https://www.gitops.tech/) +[![Multi-Tenant](https://img.shields.io/badge/Multi--Tenant-Secure-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) -BitBuilder Hypervisor implements a declarative, immutable infrastructure paradigm through git-ops methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns. +> **πŸ”₯ A Git-Ops Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration** -## Core Architecture Principles +**BitBuilder Hypervisor** implements a declarative, immutable infrastructure paradigm through git-ops methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns. -**Immutable Infrastructure**: The host operating system maintains complete immutability, with all configuration state externalized through git repository synchronization patterns and systemd generator composition. +--- -**Declarative Tenant Management**: Each tenant's computational environment is defined through version-controlled configuration repositories, enabling atomic deployments, rollback capabilities, and audit trails through standard git operations. +## 🎯 Core Architecture Principles -**Cryptographic Isolation**: Multi-tenant security boundaries are enforced through systemd's namespace isolation primitives (systemd-nspawn, systemd-vmspawn), supplemented by cryptographic identity management via systemd-homed integration. +### πŸ›‘οΈ Foundation Pillars -## Technical Implementation Stack +| Principle | Implementation | Benefits | +|-----------|----------------|----------| +| πŸ—οΈ **Immutable Infrastructure** | Host OS with complete immutability, configuration externalized through git repositories | Configuration drift elimination, enhanced security | +| 🎯 **Declarative Tenant Management** | Version-controlled configuration repositories for each tenant | Atomic deployments, rollback capabilities, audit trails | +| πŸ” **Cryptographic Isolation** | systemd namespace isolation with cryptographic identity management | Hardware-backed security boundaries, zero-trust architecture | -### SystemD Subsystem Integration +--- -- **systemd-generators**: Dynamic unit file generation for tenant-specific service orchestration -- **systemd-import-generator**: Automated EFI image acquisition and boot environment preparation -- **systemd-boot**: UEFI boot manager providing secure boot chain validation -- **systemd-vmspawn**: Hardware-assisted virtualization for tenant isolation -- **systemd-nspawn**: Container-based namespace isolation for lightweight tenants -- **systemd-networkd**: Software-defined networking with tenant-scoped network namespaces -- **systemd-homed**: Cryptographic user identity and home directory management -- **Portable Services**: Tenant application deployment through self-contained service bundles -- **Extension Images (sysext/confext)**: Immutable system and configuration layer composition +## πŸ”§ Technical Implementation Stack -### Inter-Process Communication +### βš™οΈ SystemD Subsystem Integration -- **Varlink**: Type-safe, schema-validated IPC for service coordination and management interfaces -- **D-Bus**: Legacy compatibility and systemd service lifecycle management +| Component | Purpose | Advanced Features | +|-----------|---------|-------------------| +| πŸ”§ **systemd-generators** | Dynamic unit file generation for tenant-specific service orchestration | Template-based unit generation, dependency resolution | +| ⬇️ **systemd-import-generator** | Automated EFI image acquisition and boot environment preparation | DDI verification, cryptographic validation | +| πŸš€ **systemd-boot** | UEFI boot manager providing secure boot chain validation | UKI support, secure boot integration | +| πŸ–₯️ **systemd-vmspawn** | Hardware-assisted virtualization for tenant isolation | QEMU integration, resource management | +| πŸ“¦ **systemd-nspawn** | Container-based namespace isolation for lightweight tenants | Advanced namespace features, security contexts | +| 🌐 **systemd-networkd** | Software-defined networking with tenant-scoped network namespaces | Advanced routing, network isolation | +| 🏠 **systemd-homed** | Cryptographic user identity and home directory management | Hardware-backed authentication, encrypted storage | +| 🎁 **Portable Services** | Tenant application deployment through self-contained service bundles | Application isolation, portable deployment | +| πŸ“‹ **Extension Images** | Immutable system and configuration layer composition (sysext/confext) | Overlay filesystem management, atomic updates | -### Git-Ops Orchestration Workflow +### πŸ”— Inter-Process Communication + +- πŸ”— **Varlink**: Type-safe, schema-validated IPC for service coordination and management interfaces +- πŸ”„ **D-Bus**: Legacy compatibility and systemd service lifecycle management + +### πŸ”„ Git-Ops Orchestration Workflow 1. **Boot-time Repository Synchronization**: systemd-import-generator fetches immutable EFI images 2. **Tenant Configuration Acquisition**: Git repository cloning/pulling for each tenant's declarative configuration @@ -39,38 +52,38 @@ BitBuilder Hypervisor implements a declarative, immutable infrastructure paradig 4. **Isolated Environment Provisioning**: systemd-vmspawn/systemd-nspawn instantiation with cryptographic boundaries 5. **Extension Layer Composition**: sysext/confext mounting for tenant-specific software stacks -## Features +## ✨ Features -### Advanced Multi-Tenancy +### 🏠 Advanced Multi-Tenancy - **Cryptographic Tenant Isolation**: Each tenant operates within cryptographically-isolated namespaces - **Resource Quotas and Limits**: Comprehensive resource control through systemd slice units and cgroups v2 - **Network Segmentation**: Software-defined networking with tenant-specific VLANs and firewall policies - **Storage Isolation**: Encrypted per-tenant storage volumes with key management integration -### Git-Ops Configuration Management +### πŸ“š Git-Ops Configuration Management - **Declarative Infrastructure as Code**: Complete tenant environments defined through version-controlled repositories - **Atomic Deployments**: Git commit-based deployment atomicity with automatic rollback capabilities - **Configuration Drift Detection**: Continuous monitoring of actual vs. desired state through git comparison - **Audit Trail**: Complete change history through git commit logs and cryptographic signatures -### Portable Service Architecture +### 🎁 Portable Service Architecture - **Self-Contained Application Bundles**: Applications packaged as portable systemd services with dependency isolation - **Extension Image Composition**: Layered filesystem approach for efficient storage and rapid provisioning - **Runtime Environment Abstraction**: Applications remain agnostic to underlying tenant infrastructure -### Advanced Security Model +### πŸ›‘οΈ Advanced Security Model - **Hardware Security Module Integration**: TPM 2.0 support for attestation and key management - **Secure Boot Chain**: Complete boot process validation from UEFI through tenant initialization - **Cryptographic Identity Management**: systemd-homed integration for hardware-backed user authentication - **Network Security**: Mandatory access controls and network policy enforcement -## System Requirements +## πŸ“‹ System Requirements -### Hardware Prerequisites +### πŸ–₯️ Hardware Prerequisites - **UEFI Firmware**: Modern UEFI implementation with Secure Boot support - **TPM 2.0**: Hardware security module for attestation and cryptographic operations @@ -78,16 +91,16 @@ BitBuilder Hypervisor implements a declarative, immutable infrastructure paradig - **Memory**: Minimum 16GB RAM (32GB+ recommended for production workloads) - **Storage**: NVMe SSD storage recommended for optimal I/O performance -### Software Dependencies +### πŸ’Ώ Software Dependencies - **Linux Kernel**: 6.1+ with systemd 254+ integration - **systemd**: Version 254+ with complete subsystem availability - **Git**: 2.40+ for repository operations and cryptographic signature validation - **Bun Runtime**: Latest stable release for TypeScript-based management tooling -## Quick Start +## πŸš€ Quick Start -### Host System Preparation +### πŸ—οΈ Host System Preparation ```bash # Configure systemd-boot with BitBuilder integration @@ -102,7 +115,7 @@ systemctl enable bitbuilder-bootstrap.service systemctl enable bitbuilder-tenant-monitor.timer ``` -### Tenant Configuration +### 🏠 Tenant Configuration Create tenant repository structure: @@ -124,7 +137,7 @@ tenant-example/ └── keys/ ``` -### Management Interface +### πŸŽ›οΈ Management Interface ```bash # Deploy new tenant configuration @@ -137,9 +150,9 @@ bitbuilder monitor --tenant=example --metrics=cpu,memory,network,storage bitbuilder migrate --tenant=example --target-host=node-02.cluster.local ``` -## Configuration Architecture +## πŸ—οΈ Configuration Architecture -### Repository Structure +### πŸ“ Repository Structure BitBuilder implements a hierarchical configuration approach with three distinct repository types: @@ -149,7 +162,7 @@ BitBuilder implements a hierarchical configuration approach with three distinct **Extension Repositories**: Shared extension images and portable services available across multiple tenants. -### Service Generation Patterns +### βš™οΈ Service Generation Patterns SystemD generators dynamically create service definitions based on tenant configurations: @@ -158,9 +171,9 @@ SystemD generators dynamically create service definitions based on tenant config - **tenant-storage@.service**: Encrypted storage volume mounting and key management - **tenant-monitor@.service**: Resource monitoring and policy enforcement -## Security Model +## πŸ” Security Model -### Cryptographic Boundaries +### πŸ”’ Cryptographic Boundaries Each tenant operates within a cryptographically-isolated environment: @@ -169,22 +182,22 @@ Each tenant operates within a cryptographically-isolated environment: - **Network Segmentation**: Mandatory access control policies enforced at packet level - **Process Isolation**: Hardware-assisted virtualization with nested namespace boundaries -### Audit and Compliance +### πŸ“‹ Audit and Compliance - **Immutable Audit Log**: All configuration changes tracked through git commit signatures - **Real-time Monitoring**: Continuous security policy validation and violation detection - **Compliance Reporting**: Automated generation of security posture reports and attestations -## Monitoring and Observability +## πŸ“Š Monitoring and Observability -### Metrics Collection +### πŸ“ˆ Metrics Collection - **Resource Utilization**: Per-tenant CPU, memory, storage, and network metrics - **Security Events**: Authentication attempts, policy violations, and privilege escalations - **Performance Metrics**: Service startup times, git synchronization latency, and I/O throughput - **Health Checks**: Automated tenant environment validation and dependency verification -### Management Interface +### πŸŽ›οΈ Management Interface BitBuilder provides a comprehensive management interface through: @@ -193,7 +206,7 @@ BitBuilder provides a comprehensive management interface through: - **Web Dashboard**: Real-time monitoring and configuration management interface - **Git Hooks**: Automated validation and deployment triggers -## Contributing +## 🀝 Contributing BitBuilder follows strict Unix Philosophy principles and modern TypeScript development practices. All contributions must: @@ -203,11 +216,11 @@ BitBuilder follows strict Unix Philosophy principles and modern TypeScript devel - Follow semantic versioning and conventional commit standards - Maintain backward compatibility with existing tenant configurations -## License +## πŸ“„ License BitBuilder Hypervisor is released under the MIT License. See LICENSE file for complete terms and conditions. -## Documentation +## πŸ“– Documentation - [Technical Design](specs/DESIGN.md): Comprehensive system design and implementation details - [System Architecture](specs/ARCHITECTURE.md): Detailed architectural patterns and component interactions diff --git a/STACK.md b/STACK.md index 3477ec8..93377a1 100644 --- a/STACK.md +++ b/STACK.md @@ -1,38 +1,66 @@ -# BitBuilder Hypervisor Stack Architecture +# πŸ—οΈ BitBuilder Hypervisor Stack Architecture -## Table of Contents +[![Stack Architecture](https://img.shields.io/badge/Stack-Architecture-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) +[![Templates](https://img.shields.io/badge/Templates-Multi--Tenant-blue?style=flat-square)](https://uapi-group.org/) +[![Compliance](https://img.shields.io/badge/UAPI-Compliant-orange?style=flat-square)](https://uapi-group.org/specifications/) -1. [Template System Overview](#template-system-overview) -2. [Tenant Templates](#tenant-templates) -3. [Extension Image Templates](#extension-image-templates) -4. [Network Templates](#network-templates) -5. [Systemd Generators](#systemd-generators) -6. [Tenant Instantiation Flow](#tenant-instantiation-flow) -7. [Directory Structure Compliance](#directory-structure-compliance) +> **🧩 Comprehensive template system for creating fully compliant, multi-tenant rootfs filesystems with layered architecture and systemd integration.** -## Template System Overview +--- -BitBuilder Hypervisor uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the Linux Userspace API specifications. +## πŸ“‹ Table of Contents -### Template Categories +| Section | Description | +|---------|-------------| +| 🎯 [Template System Overview](#-template-system-overview) | Layered template architecture | +| 🏠 [Tenant Templates](#-tenant-templates) | Infrastructure, VM, container templates | +| πŸ”§ [Extension Image Templates](#-extension-image-templates) | sysext and confext templates | +| 🌐 [Network Templates](#-network-templates) | Networking configuration patterns | +| βš™οΈ [Systemd Generators](#%EF%B8%8F-systemd-generators) | Dynamic unit generation | +| πŸ”„ [Tenant Instantiation Flow](#-tenant-instantiation-flow) | Provisioning workflow | +| βœ… [Directory Structure Compliance](#-directory-structure-compliance) | UAPI compliance validation | -``` -Templates - Infrastructure Templates # Management layer for each tenant - Machine Templates # VM templates (systemd-vmspawn) - Container Templates # Container templates (systemd-nspawn) - Homed Templates # User home directory templates - Network Templates # Network configuration templates -``` +--- -## Tenant Templates +## 🎯 Template System Overview -### 1. Tenant Infrastructure Manager Template (`tenant-infra-template`) +**BitBuilder Hypervisor** uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the [**Linux Userspace API specifications**](https://uapi-group.org/specifications/). -The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources. +### 🧩 Template Categories -**Repository Structure:** +```mermaid +graph TB + T[πŸ“¦ Templates] --> I[πŸ—οΈ Infrastructure Templates] + T --> M[πŸ–₯️ Machine Templates] + T --> C[πŸ“¦ Container Templates] + T --> H[🏠 Homed Templates] + T --> N[🌐 Network Templates] + + I --> IT[Management layer for each tenant] + M --> MT[VM templates - systemd-vmspawn] + C --> CT[Container templates - systemd-nspawn] + H --> HT[User home directory templates] + N --> NT[Network configuration templates] + + style T fill:#e3f2fd + style I fill:#f3e5f5 + style M fill:#e8f5e8 + style C fill:#fff3e0 + style H fill:#fce4ec + style N fill:#f1f8e9 ``` + +--- + +## 🏠 Tenant Templates + +### 1️⃣ Tenant Infrastructure Manager Template (`tenant-infra-template`) + +> 🎯 **Purpose**: The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources. + +#### πŸ—‚οΈ Repository Structure + +```bash tenant-infra-template/ metadata.json # Template metadata rootfs/ # Compliant root filesystem @@ -71,7 +99,7 @@ tenant-infra-template/ health-check.sh # Health monitoring ``` -**metadata.json:** +#### πŸ“‹ metadata.json Configuration ```json { "template": { @@ -98,7 +126,7 @@ tenant-infra-template/ } ``` -### 2. Tenant Machine Template (`tenant-machine-template`) +### 2️⃣ Tenant Machine Template (`tenant-machine-template`) Template for creating tenant VMs using systemd-vmspawn. @@ -133,7 +161,7 @@ tenant-machine-template/ monitoring.confext.raw ``` -### 3. Tenant Container Template (`tenant-container-template`) +### 3️⃣ Tenant Container Template (`tenant-container-template`) Template for creating tenant containers using systemd-nspawn. @@ -160,7 +188,7 @@ tenant-container-template/ container-init.sh ``` -**nspawn-settings.conf:** +#### βš™οΈ nspawn-settings.conf ```ini [Exec] Boot=yes @@ -177,7 +205,7 @@ PrivateUsersChown=yes BindReadOnly=/usr/lib/extensions ``` -### 4. Tenant Homed Template (`tenant-homed-template`) +### 4️⃣ Tenant Homed Template (`tenant-homed-template`) Template for user home directories managed by systemd-homed. @@ -201,9 +229,9 @@ tenant-homed-template/ home-provision.sh ``` -## Extension Image Templates +## πŸ”§ Extension Image Templates -### System Extension (sysext) Template +### πŸ”§ System Extension (sysext) Template ``` base-tools.sysext/ @@ -220,7 +248,7 @@ base-tools.sysext/ tools/ ``` -**extension-release.base-tools:** +#### πŸ“‹ extension-release.base-tools ```ini ID=bitbuilder VERSION_ID=1.0 @@ -228,7 +256,7 @@ SYSEXT_LEVEL=1.0 ARCHITECTURE=x86-64 ``` -### Configuration Extension (confext) Template +### βš™οΈ Configuration Extension (confext) Template ``` network-policies.confext/ @@ -241,11 +269,11 @@ network-policies.confext/ extension-release.network-policies ``` -## Network Templates +## 🌐 Network Templates -### 1. Bridge Network Template +### 1️⃣ Bridge Network Template -**/etc/systemd/network/10-tenant-bridge.netdev:** +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev:** ```ini [NetDev] Name=br-tenant-%i @@ -259,7 +287,7 @@ HelloTimeSec=2 MaxAgeSec=20 ``` -**/etc/systemd/network/10-tenant-bridge.network:** +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network:** ```ini [Match] Name=br-tenant-%i @@ -279,9 +307,9 @@ DNS=10.%i.0.1 EmitRouter=yes ``` -### 2. WireGuard VPN Template +### 2️⃣ WireGuard VPN Template -**/etc/systemd/network/20-wg-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev:** ```ini [NetDev] Name=wg-tenant-%i @@ -298,7 +326,7 @@ Endpoint=${PEER_ENDPOINT}:51820 PersistentKeepalive=25 ``` -**/etc/systemd/network/20-wg-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network:** ```ini [Match] Name=wg-tenant-%i @@ -311,9 +339,9 @@ Destination=10.%i.100.0/24 Scope=link ``` -### 3. VXLAN Overlay Template +### 3️⃣ VXLAN Overlay Template -**/etc/systemd/network/30-vxlan-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev:** ```ini [NetDev] Name=vxlan-tenant-%i @@ -326,7 +354,7 @@ DestinationPort=4789 MacLearning=yes ``` -**/etc/systemd/network/30-vxlan-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network:** ```ini [Match] Name=vxlan-tenant-%i @@ -339,9 +367,9 @@ PVID=1 EgressUntagged=1 ``` -### 4. VLAN Segmentation Template +### 4️⃣ VLAN Segmentation Template -**/etc/systemd/network/40-vlan-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev:** ```ini [NetDev] Name=vlan-tenant-%i @@ -351,7 +379,7 @@ Kind=vlan Id=%i ``` -**/etc/systemd/network/40-vlan-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network:** ```ini [Match] Name=vlan-tenant-%i @@ -365,7 +393,7 @@ RouteMetric=200 UseDomains=route ``` -### 5. Network Namespace Template +### 5️⃣ Network Namespace Template **/usr/lib/systemd/system/netns-tenant@.service:** ```ini @@ -384,9 +412,9 @@ ExecStop=/usr/bin/ip netns delete tenant-%i WantedBy=multi-user.target ``` -## Systemd Generators +## βš™οΈ Systemd Generators -### 1. Tenant Discovery Generator +### 1️⃣ Tenant Discovery Generator **/usr/lib/systemd/system-generators/tenant-generator:** ```bash @@ -468,7 +496,7 @@ if [[ -f "$TENANT_REGISTRY" ]]; then fi ``` -### 2. Mount Generator +### 2️⃣ Mount Generator **/usr/lib/systemd/system-generators/mount-generator:** ```bash @@ -525,16 +553,16 @@ if [[ -d "$TENANT_BASE" ]]; then fi ``` -## Tenant Instantiation Flow +## πŸ”„ Tenant Instantiation Flow -### 1. Enable Tenant +### 1️⃣ Enable Tenant ```bash # Enable and start a new tenant systemctl enable --now tenant@tenant123.service ``` -### 2. Instantiation Process +### 2️⃣ Instantiation Process ```mermaid graph TD @@ -549,7 +577,7 @@ graph TD I --> J[Start tenant workloads] ``` -### 3. Generated Unit Hierarchy +### 3️⃣ Generated Unit Hierarchy ``` tenant@tenant123.service @@ -563,9 +591,9 @@ tenant@tenant123.service br-tenant-123.netdev ``` -## Directory Structure Compliance +## βœ… Directory Structure Compliance -### Linux File System Hierarchy Compliance +### πŸ“ Linux File System Hierarchy Compliance Each template ensures compliance with the Linux File System Hierarchy specification: @@ -584,7 +612,7 @@ Each template ensures compliance with the Linux File System Hierarchy specificat - Proper certificate fingerprint naming - ASCII-armored OpenPGP files -### Template Validation +### βœ… Template Validation Each template includes a validation script: @@ -611,7 +639,7 @@ validate_rootfs() { } ``` -## Conclusion +## 🎯 Conclusion This template system provides: diff --git a/specs/DESIGN.md b/specs/DESIGN.md index a48bd00..dde47de 100644 --- a/specs/DESIGN.md +++ b/specs/DESIGN.md @@ -1,54 +1,68 @@ -# BitBuilder Hypervisor - Technical Design Document +# 🎯 BitBuilder Hypervisor - Technical Design Document -## Table of Contents +[![Technical Design](https://img.shields.io/badge/Design-Technical-blue?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) +[![SystemD Native](https://img.shields.io/badge/SystemD-Native-green?style=flat-square)](https://systemd.io/) +[![Git-Ops](https://img.shields.io/badge/Git--Ops-Workflow-orange?style=flat-square)](https://www.gitops.tech/) +[![Multi-Tenant](https://img.shields.io/badge/Multi--Tenant-Design-red?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) -1. [Introduction](#introduction) -2. [Design Principles](#design-principles) -3. [System Architecture](#system-architecture) -4. [Core Components](#core-components) -5. [Boot Process Design](#boot-process-design) -6. [Tenant Management Design](#tenant-management-design) -7. [Security Architecture](#security-architecture) -8. [Networking Design](#networking-design) -9. [Storage Architecture](#storage-architecture) -10. [Extension System Design](#extension-system-design) -11. [Git-Ops Workflow](#git-ops-workflow) -12. [Monitoring and Observability](#monitoring-and-observability) -13. [Performance Considerations](#performance-considerations) -14. [Failure Recovery](#failure-recovery) +> **πŸš€ Paradigm shift in hypervisor design through systemd's advanced virtualization capabilities and git-ops-native architecture.** -## Introduction +--- -BitBuilder Hypervisor represents a paradigm shift in hypervisor design, leveraging systemd's advanced virtualization capabilities to create a git-ops-native, multi-tenant virtualization platform. This document outlines the technical design decisions, architectural patterns, and implementation strategies that form the foundation of the system. +## πŸ“‹ Table of Contents -## Design Principles +| Section | Description | Focus Area | +|---------|-------------|------------| +| πŸ“– [Introduction](#-introduction) | System overview and paradigm shift | Conceptual foundation | +| 🎯 [Design Principles](#-design-principles) | Core design philosophy | Architectural guidelines | +| πŸ—οΈ [System Architecture](#%EF%B8%8F-system-architecture) | Overall system design | Structural patterns | +| 🧩 [Core Components](#-core-components) | Key system components | Implementation details | +| πŸš€ [Boot Process Design](#-boot-process-design) | System initialization | Boot workflow | +| 🏠 [Tenant Management Design](#-tenant-management-design) | Multi-tenant orchestration | Tenant lifecycle | +| πŸ›‘οΈ [Security Architecture](#%EF%B8%8F-security-architecture) | Security implementation | Protection mechanisms | +| 🌐 [Networking Design](#-networking-design) | Network architecture | Connectivity patterns | +| πŸ’Ύ [Storage Architecture](#-storage-architecture) | Storage management | Data persistence | +| πŸ”§ [Extension System Design](#-extension-system-design) | Extensibility framework | Plugin architecture | +| πŸ“š [Git-Ops Workflow](#-git-ops-workflow) | Configuration management | Version control integration | +| πŸ“Š [Monitoring and Observability](#-monitoring-and-observability) | System monitoring | Operational insights | +| ⚑ [Performance Considerations](#-performance-considerations) | Performance optimization | Efficiency patterns | +| πŸ†˜ [Failure Recovery](#-failure-recovery) | Error handling and recovery | Resilience design | -### 1. Immutability First +--- + +## πŸ“– Introduction + +**BitBuilder Hypervisor** represents a paradigm shift in hypervisor design, leveraging systemd's advanced virtualization capabilities to create a git-ops-native, multi-tenant virtualization platform. +This document outlines the technical design decisions, architectural patterns, and implementation strategies that form the foundation of the system. + +## 🎯 Design Principles + +### 1️⃣ Immutability First - Host OS remains immutable after boot - All changes applied through layered overlays - Configuration drift eliminated by design -### 2. Declarative Configuration +### 2️⃣ Declarative Configuration - State declared in Git repositories - System converges to desired state automatically - No imperative configuration management -### 3. Security by Isolation +### 3️⃣ Security by Isolation - Defense-in-depth architecture - Multiple isolation boundaries per tenant - Principle of least privilege throughout -### 4. Git as Single Source of Truth +### 4️⃣ Git as Single Source of Truth - All configuration versioned in Git - Audit trail built into the system - Rollback capability inherent to design -### 5. Composability +### 5️⃣ Composability - Small, focused components - Standard interfaces (Varlink, D-Bus) - Layered architecture with clear boundaries -## System Architecture +## πŸ—οΈ System Architecture ### Host System Layer @@ -86,7 +100,7 @@ $ ``` -## Core Components +## 🧩 Core Components ### 1. systemd-import-generator @@ -164,7 +178,7 @@ Generates: - Target units for tenant dependencies - Timer units for periodic sync -## Boot Process Design +## πŸš€ Boot Process Design ### Stage 1: UEFI Boot 1. UEFI firmware loads systemd-boot @@ -196,7 +210,7 @@ Generates: 4. Start systemd-vmspawn/nspawn instances 5. Execute post-provision scripts -## Tenant Management Design +## 🏠 Tenant Management Design ### Tenant Metadata Schema @@ -280,7 +294,7 @@ Generates: 4. Resources deallocated 5. Data archived/deleted per policy -## Security Architecture +## πŸ›‘οΈ Security Architecture ### Defense in Depth @@ -326,7 +340,7 @@ Multiple security layers protect each tenant: (UID/GID/PID) ``` -## Networking Design +## 🌐 Networking Design ### Network Architecture @@ -399,7 +413,7 @@ EmitDNS=yes DNS=10.0.0.1 ``` -## Storage Architecture +## πŸ’Ύ Storage Architecture ### Storage Layers @@ -445,7 +459,7 @@ $ runtime/ # Ephemeral runtime data ``` -## Extension System Design +## πŸ”§ Extension System Design ### System Extensions (sysext) @@ -505,7 +519,7 @@ portable-service.raw/ config.conf ``` -## Git-Ops Workflow +## πŸ“š Git-Ops Workflow ### Repository Structure @@ -577,7 +591,7 @@ tenant-/ 3. Snapshot restore for data rollback 4. A/B boot partitions for OS rollback -## Monitoring and Observability +## πŸ“Š Monitoring and Observability ### Metrics Collection @@ -615,7 +629,7 @@ systemd-journal journald-exporter Prometheus Local Store Central Syslog S3 Archive ``` -## Performance Considerations +## ⚑ Performance Considerations ### Resource Management @@ -651,7 +665,7 @@ systemd-journal journald-exporter Prometheus - Parallel Git operations - Async service startup -## Failure Recovery +## πŸ†˜ Failure Recovery ### Failure Detection From 957bb861cb3d90bfc75f8159bd29071b938310ea Mon Sep 17 00:00:00 2001 From: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> Date: Tue, 26 Aug 2025 14:34:35 -0500 Subject: [PATCH 4/9] Update STACK.md --- STACK.md | 653 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 653 insertions(+) diff --git a/STACK.md b/STACK.md index e69de29..5bcb0b3 100644 --- a/STACK.md +++ b/STACK.md @@ -0,0 +1,653 @@ +# πŸ—οΈ BitBuilder Hypervisor Stack Architecture + +[![Stack Architecture](https://img.shields.io/badge/Stack-Architecture-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) +[![Templates](https://img.shields.io/badge/Templates-Multi--Tenant-blue?style=flat-square)](https://uapi-group.org/) +[![Compliance](https://img.shields.io/badge/UAPI-Compliant-orange?style=flat-square)](https://uapi-group.org/specifications/) + +> **🧩 Comprehensive template system for creating fully compliant, multi-tenant rootfs filesystems with layered architecture and systemd integration.** + +--- + +## πŸ“‹ Table of Contents + +| Section | Description | +|---------|-------------| +| 🎯 [Template System Overview](#-template-system-overview) | Layered template architecture | +| 🏠 [Tenant Templates](#-tenant-templates) | Infrastructure, VM, container templates | +| πŸ”§ [Extension Image Templates](#-extension-image-templates) | sysext and confext templates | +| 🌐 [Network Templates](#-network-templates) | Networking configuration patterns | +| βš™οΈ [Systemd Generators](#%EF%B8%8F-systemd-generators) | Dynamic unit generation | +| πŸ”„ [Tenant Instantiation Flow](#-tenant-instantiation-flow) | Provisioning workflow | +| βœ… [Directory Structure Compliance](#-directory-structure-compliance) | UAPI compliance validation | + +--- + +## 🎯 Template System Overview + +**BitBuilder Hypervisor** uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the [**Linux Userspace API specifications**](https://uapi-group.org/specifications/). + +### 🧩 Template Categories + +```mermaid +graph TB + T[πŸ“¦ Templates] --> I[πŸ—οΈ Infrastructure Templates] + T --> M[πŸ–₯️ Machine Templates] + T --> C[πŸ“¦ Container Templates] + T --> H[🏠 Homed Templates] + T --> N[🌐 Network Templates] + + I --> IT[Management layer for each tenant] + M --> MT[VM templates - systemd-vmspawn] + C --> CT[Container templates - systemd-nspawn] + H --> HT[User home directory templates] + N --> NT[Network configuration templates] + + style T fill:#e3f2fd + style I fill:#f3e5f5 + style M fill:#e8f5e8 + style C fill:#fff3e0 + style H fill:#fce4ec + style N fill:#f1f8e9 +``` + +--- + +## 🏠 Tenant Templates + +### 1️⃣ Tenant Infrastructure Manager Template (`tenant-infra-template`) + +> 🎯 **Purpose**: The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources. + +#### πŸ—‚οΈ Repository Structure + +```bash +tenant-infra-template/ + metadata.json # Template metadata + rootfs/ # Compliant root filesystem + etc/ + os-release # Required OS identification + systemd/ + system/ + multi-user.target.wants/ + infra-manager.service + git-sync.service + git-sync.timer + varlink-api.service + network/ + 10-management.network + 10-management.netdev + extension-release.d/ # Extension compatibility + usr/ + lib/ + os-release -> ../../etc/os-release + systemd/system/ # Vendor units + bitbuilder/ + infra-manager # Management binary + lib/ # Shared libraries + share/ + bitbuilder/ + schemas/ # JSON schemas + var/ + lib/ + infra/ # Persistent infra data + run/ # Runtime directory (empty) + config/ # Default configuration + infra-config.yaml + resource-limits.yaml + scripts/ + provision.sh # Provisioning script + health-check.sh # Health monitoring +``` + +#### πŸ“‹ metadata.json Configuration +```json +{ + "template": { + "type": "infrastructure", + "version": "1.0.0", + "name": "tenant-infra-template" + }, + "requirements": { + "systemd_version": ">=258", + "kernel": ">=6.0", + "features": ["vmspawn", "varlink", "networkd"] + }, + "defaults": { + "resources": { + "cpu": 2, + "memory": "2G", + "storage": "10G" + }, + "network": { + "mode": "private", + "management_interface": true + } + } +} +``` + +### 2️⃣ Tenant Machine Template (`tenant-machine-template`) + +Template for creating tenant VMs using systemd-vmspawn. + +**Repository Structure:** +``` +tenant-machine-template/ + metadata.json + disk-image/ # Base disk image + efi/ # EFI partition + EFI/ + systemd/ + systemd-bootx64.efi + boot/ # Boot partition + vmlinuz # Kernel + initrd.img # Initial ramdisk + rootfs/ # Root filesystem + etc/ + os-release + machine-id # Empty (generated) + systemd/ + system/ + network/ + usr/ # Minimal userspace + var/ + config/ + vm-config.yaml + cloud-init/ # Cloud-init templates + user-data + meta-data + extensions/ # VM-specific extensions + development.sysext.raw + monitoring.confext.raw +``` + +### 3️⃣ Tenant Container Template (`tenant-container-template`) + +Template for creating tenant containers using systemd-nspawn. + +**Repository Structure:** +``` +tenant-container-template/ + metadata.json + rootfs/ # Container root filesystem + etc/ + os-release + systemd/ + system/ + container-init.service + network/ + 80-container.network + usr/ + bin/ # Essential binaries + lib/ + var/ + lib/ + config/ + nspawn-settings.conf # systemd-nspawn settings + scripts/ + container-init.sh +``` + +#### βš™οΈ nspawn-settings.conf +```ini +[Exec] +Boot=yes +ProcessTwo=yes +NotifyReady=yes + +[Network] +Private=yes +VirtualEthernet=yes +Bridge=br-tenant + +[Files] +PrivateUsersChown=yes +BindReadOnly=/usr/lib/extensions +``` + +### 4️⃣ Tenant Homed Template (`tenant-homed-template`) + +Template for user home directories managed by systemd-homed. + +**Repository Structure:** +``` +tenant-homed-template/ + metadata.json + home-skeleton/ # Default home structure + .config/ + systemd/ + user/ # User services + .local/ + bin/ # User binaries + share/ + .ssh/ # SSH configuration + authorized_keys.template + config/ + homed-config.json # systemd-homed config + user-record.json # User record template + scripts/ + home-provision.sh +``` + +## πŸ”§ Extension Image Templates + +### πŸ”§ System Extension (sysext) Template + +``` +base-tools.sysext/ + usr/ # Only /usr and /opt allowed + bin/ + htop + tmux + vim + lib/ + extension-release.d/ + extension-release.base-tools + opt/ + bitbuilder/ + tools/ +``` + +#### πŸ“‹ extension-release.base-tools +```ini +ID=bitbuilder +VERSION_ID=1.0 +SYSEXT_LEVEL=1.0 +ARCHITECTURE=x86-64 +``` + +### βš™οΈ Configuration Extension (confext) Template + +``` +network-policies.confext/ + etc/ # Only /etc allowed + systemd/ + network/ + 20-wireguard.netdev + 20-wireguard.network + extension-release.d/ + extension-release.network-policies +``` + +## 🌐 Network Templates + +### 1️⃣ Bridge Network Template + +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev:** +```ini +[NetDev] +Name=br-tenant-%i +Kind=bridge + +[Bridge] +STP=yes +Priority=32768 +ForwardDelaySec=15 +HelloTimeSec=2 +MaxAgeSec=20 +``` + +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network:** +```ini +[Match] +Name=br-tenant-%i + +[Network] +DHCP=no +IPv6AcceptRA=no +IPForward=yes +IPMasquerade=yes +Address=10.%i.0.1/24 + +[DHCPServer] +PoolOffset=100 +PoolSize=100 +EmitDNS=yes +DNS=10.%i.0.1 +EmitRouter=yes +``` + +### 2️⃣ WireGuard VPN Template + +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev:** +```ini +[NetDev] +Name=wg-tenant-%i +Kind=wireguard + +[WireGuard] +PrivateKeyFile=/var/lib/tenants/%i/network/wireguard.key +ListenPort=51820 + +[WireGuardPeer] +PublicKey=${PEER_PUBLIC_KEY} +AllowedIPs=10.%i.100.0/24 +Endpoint=${PEER_ENDPOINT}:51820 +PersistentKeepalive=25 +``` + +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network:** +```ini +[Match] +Name=wg-tenant-%i + +[Network] +Address=10.%i.100.1/24 + +[Route] +Destination=10.%i.100.0/24 +Scope=link +``` + +### 3️⃣ VXLAN Overlay Template + +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev:** +```ini +[NetDev] +Name=vxlan-tenant-%i +Kind=vxlan + +[VXLAN] +VNI=%i +Group=239.0.0.1 +DestinationPort=4789 +MacLearning=yes +``` + +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network:** +```ini +[Match] +Name=vxlan-tenant-%i + +[Network] +Bridge=br-tenant-%i + +[BridgeVLAN] +PVID=1 +EgressUntagged=1 +``` + +### 4️⃣ VLAN Segmentation Template + +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev:** +```ini +[NetDev] +Name=vlan-tenant-%i +Kind=vlan + +[VLAN] +Id=%i +``` + +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network:** +```ini +[Match] +Name=vlan-tenant-%i + +[Network] +DHCP=yes +IPv6AcceptRA=yes + +[DHCP] +RouteMetric=200 +UseDomains=route +``` + +### 5️⃣ Network Namespace Template + +**/usr/lib/systemd/system/netns-tenant@.service:** +```ini +[Unit] +Description=Network namespace for tenant %i +After=network.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/bin/ip netns add tenant-%i +ExecStart=/usr/bin/ip netns exec tenant-%i ip link set lo up +ExecStop=/usr/bin/ip netns delete tenant-%i + +[Install] +WantedBy=multi-user.target +``` + +## βš™οΈ Systemd Generators + +### 1️⃣ Tenant Discovery Generator + +**/usr/lib/systemd/system-generators/tenant-generator:** +```bash +#!/bin/bash +# Discovers tenants from Git repositories and generates systemd units + +GENERATOR_DIR="$1" +TENANT_REGISTRY="/var/lib/bitbuilder/tenants.json" + +generate_tenant_units() { + local tenant_id="$1" + local tenant_config="$2" + + # Generate main tenant service + cat > "${GENERATOR_DIR}/tenant@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-infra@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-network@${tenant_id}.service" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-sysext.mount" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-confext.mount" < B[Tenant Generator] + B --> C[Read tenant registry] + C --> D[Clone Git repositories] + D --> E[Generate systemd units] + E --> F[Setup network namespace] + F --> G[Mount extensions] + G --> H[Start infra manager VM] + H --> I[Provision tenant resources] + I --> J[Start tenant workloads] +``` + +### 3️⃣ Generated Unit Hierarchy + +``` +tenant@tenant123.service + Requires: tenant-network@tenant123.service + Wants: tenant-infra@tenant123.service + After: network-online.target + Triggers: + var-lib-tenants-tenant123-sysext.mount + var-lib-tenants-tenant123-confext.mount + netns-tenant@tenant123.service + br-tenant-123.netdev +``` + +## βœ… Directory Structure Compliance + +### πŸ“ Linux File System Hierarchy Compliance + +Each template ensures compliance with the Linux File System Hierarchy specification: + +1. **Root Filesystem Requirements:** + - `/etc/os-release` or `/usr/lib/os-release` present + - Proper symlink from `/usr/lib/os-release` to `/etc/os-release` + - No files in `/` root directory itself + +2. **Extension Image Requirements:** + - sysext: Only `/usr/` and `/opt/` directories + - confext: Only `/etc/` directory + - Proper `extension-release` files in correct locations + +3. **Verification Structure:** + - VOA hierarchy at `/etc/voa/` and `/usr/share/voa/` + - Proper certificate fingerprint naming + - ASCII-armored OpenPGP files + +### βœ… Template Validation + +Each template includes a validation script: + +```bash +#!/bin/bash +# validate-template.sh + +validate_rootfs() { + local rootfs="$1" + + # Check for required files + [[ -f "$rootfs/etc/os-release" ]] || error "Missing /etc/os-release" + [[ -L "$rootfs/usr/lib/os-release" ]] || error "Missing /usr/lib/os-release symlink" + + # Validate directory structure + for dir in etc usr var proc sys dev run tmp; do + [[ -d "$rootfs/$dir" ]] || error "Missing /$dir directory" + done + + # Check permissions + [[ $(stat -c %a "$rootfs/tmp") == "1777" ]] || error "Invalid /tmp permissions" + + echo "Template validation successful" +} +``` + +## 🎯 Conclusion + +This template system provides: + +1. **Standardization**: All tenants use consistent, validated templates +2. **Compliance**: Full adherence to Linux Userspace API specifications +3. **Flexibility**: Multiple template types for different use cases +4. **Security**: Layered isolation with proper namespace separation +5. **Automation**: Systemd generators handle all instantiation logic +6. **Networking**: Comprehensive network isolation and connectivity options + +The combination of Git-based configuration, systemd integration, and compliant filesystem templates creates a robust, secure, and manageable multi-tenant hypervisor platform. From 239a89ec5979660b3d33179faf6cabeaaf376b04 Mon Sep 17 00:00:00 2001 From: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> Date: Tue, 26 Aug 2025 15:59:46 -0500 Subject: [PATCH 5/9] docs(stack): format repository structure diagrams --- STACK.md | 1280 ++++++++++++++++++++++++++---------------------------- 1 file changed, 627 insertions(+), 653 deletions(-) diff --git a/STACK.md b/STACK.md index 5bcb0b3..5833873 100644 --- a/STACK.md +++ b/STACK.md @@ -1,653 +1,627 @@ -# πŸ—οΈ BitBuilder Hypervisor Stack Architecture - -[![Stack Architecture](https://img.shields.io/badge/Stack-Architecture-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) -[![Templates](https://img.shields.io/badge/Templates-Multi--Tenant-blue?style=flat-square)](https://uapi-group.org/) -[![Compliance](https://img.shields.io/badge/UAPI-Compliant-orange?style=flat-square)](https://uapi-group.org/specifications/) - -> **🧩 Comprehensive template system for creating fully compliant, multi-tenant rootfs filesystems with layered architecture and systemd integration.** - ---- - -## πŸ“‹ Table of Contents - -| Section | Description | -|---------|-------------| -| 🎯 [Template System Overview](#-template-system-overview) | Layered template architecture | -| 🏠 [Tenant Templates](#-tenant-templates) | Infrastructure, VM, container templates | -| πŸ”§ [Extension Image Templates](#-extension-image-templates) | sysext and confext templates | -| 🌐 [Network Templates](#-network-templates) | Networking configuration patterns | -| βš™οΈ [Systemd Generators](#%EF%B8%8F-systemd-generators) | Dynamic unit generation | -| πŸ”„ [Tenant Instantiation Flow](#-tenant-instantiation-flow) | Provisioning workflow | -| βœ… [Directory Structure Compliance](#-directory-structure-compliance) | UAPI compliance validation | - ---- - -## 🎯 Template System Overview - -**BitBuilder Hypervisor** uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the [**Linux Userspace API specifications**](https://uapi-group.org/specifications/). - -### 🧩 Template Categories - -```mermaid -graph TB - T[πŸ“¦ Templates] --> I[πŸ—οΈ Infrastructure Templates] - T --> M[πŸ–₯️ Machine Templates] - T --> C[πŸ“¦ Container Templates] - T --> H[🏠 Homed Templates] - T --> N[🌐 Network Templates] - - I --> IT[Management layer for each tenant] - M --> MT[VM templates - systemd-vmspawn] - C --> CT[Container templates - systemd-nspawn] - H --> HT[User home directory templates] - N --> NT[Network configuration templates] - - style T fill:#e3f2fd - style I fill:#f3e5f5 - style M fill:#e8f5e8 - style C fill:#fff3e0 - style H fill:#fce4ec - style N fill:#f1f8e9 -``` - ---- - -## 🏠 Tenant Templates - -### 1️⃣ Tenant Infrastructure Manager Template (`tenant-infra-template`) - -> 🎯 **Purpose**: The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources. - -#### πŸ—‚οΈ Repository Structure - -```bash -tenant-infra-template/ - metadata.json # Template metadata - rootfs/ # Compliant root filesystem - etc/ - os-release # Required OS identification - systemd/ - system/ - multi-user.target.wants/ - infra-manager.service - git-sync.service - git-sync.timer - varlink-api.service - network/ - 10-management.network - 10-management.netdev - extension-release.d/ # Extension compatibility - usr/ - lib/ - os-release -> ../../etc/os-release - systemd/system/ # Vendor units - bitbuilder/ - infra-manager # Management binary - lib/ # Shared libraries - share/ - bitbuilder/ - schemas/ # JSON schemas - var/ - lib/ - infra/ # Persistent infra data - run/ # Runtime directory (empty) - config/ # Default configuration - infra-config.yaml - resource-limits.yaml - scripts/ - provision.sh # Provisioning script - health-check.sh # Health monitoring -``` - -#### πŸ“‹ metadata.json Configuration -```json -{ - "template": { - "type": "infrastructure", - "version": "1.0.0", - "name": "tenant-infra-template" - }, - "requirements": { - "systemd_version": ">=258", - "kernel": ">=6.0", - "features": ["vmspawn", "varlink", "networkd"] - }, - "defaults": { - "resources": { - "cpu": 2, - "memory": "2G", - "storage": "10G" - }, - "network": { - "mode": "private", - "management_interface": true - } - } -} -``` - -### 2️⃣ Tenant Machine Template (`tenant-machine-template`) - -Template for creating tenant VMs using systemd-vmspawn. - -**Repository Structure:** -``` -tenant-machine-template/ - metadata.json - disk-image/ # Base disk image - efi/ # EFI partition - EFI/ - systemd/ - systemd-bootx64.efi - boot/ # Boot partition - vmlinuz # Kernel - initrd.img # Initial ramdisk - rootfs/ # Root filesystem - etc/ - os-release - machine-id # Empty (generated) - systemd/ - system/ - network/ - usr/ # Minimal userspace - var/ - config/ - vm-config.yaml - cloud-init/ # Cloud-init templates - user-data - meta-data - extensions/ # VM-specific extensions - development.sysext.raw - monitoring.confext.raw -``` - -### 3️⃣ Tenant Container Template (`tenant-container-template`) - -Template for creating tenant containers using systemd-nspawn. - -**Repository Structure:** -``` -tenant-container-template/ - metadata.json - rootfs/ # Container root filesystem - etc/ - os-release - systemd/ - system/ - container-init.service - network/ - 80-container.network - usr/ - bin/ # Essential binaries - lib/ - var/ - lib/ - config/ - nspawn-settings.conf # systemd-nspawn settings - scripts/ - container-init.sh -``` - -#### βš™οΈ nspawn-settings.conf -```ini -[Exec] -Boot=yes -ProcessTwo=yes -NotifyReady=yes - -[Network] -Private=yes -VirtualEthernet=yes -Bridge=br-tenant - -[Files] -PrivateUsersChown=yes -BindReadOnly=/usr/lib/extensions -``` - -### 4️⃣ Tenant Homed Template (`tenant-homed-template`) - -Template for user home directories managed by systemd-homed. - -**Repository Structure:** -``` -tenant-homed-template/ - metadata.json - home-skeleton/ # Default home structure - .config/ - systemd/ - user/ # User services - .local/ - bin/ # User binaries - share/ - .ssh/ # SSH configuration - authorized_keys.template - config/ - homed-config.json # systemd-homed config - user-record.json # User record template - scripts/ - home-provision.sh -``` - -## πŸ”§ Extension Image Templates - -### πŸ”§ System Extension (sysext) Template - -``` -base-tools.sysext/ - usr/ # Only /usr and /opt allowed - bin/ - htop - tmux - vim - lib/ - extension-release.d/ - extension-release.base-tools - opt/ - bitbuilder/ - tools/ -``` - -#### πŸ“‹ extension-release.base-tools -```ini -ID=bitbuilder -VERSION_ID=1.0 -SYSEXT_LEVEL=1.0 -ARCHITECTURE=x86-64 -``` - -### βš™οΈ Configuration Extension (confext) Template - -``` -network-policies.confext/ - etc/ # Only /etc allowed - systemd/ - network/ - 20-wireguard.netdev - 20-wireguard.network - extension-release.d/ - extension-release.network-policies -``` - -## 🌐 Network Templates - -### 1️⃣ Bridge Network Template - -#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev:** -```ini -[NetDev] -Name=br-tenant-%i -Kind=bridge - -[Bridge] -STP=yes -Priority=32768 -ForwardDelaySec=15 -HelloTimeSec=2 -MaxAgeSec=20 -``` - -#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network:** -```ini -[Match] -Name=br-tenant-%i - -[Network] -DHCP=no -IPv6AcceptRA=no -IPForward=yes -IPMasquerade=yes -Address=10.%i.0.1/24 - -[DHCPServer] -PoolOffset=100 -PoolSize=100 -EmitDNS=yes -DNS=10.%i.0.1 -EmitRouter=yes -``` - -### 2️⃣ WireGuard VPN Template - -#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev:** -```ini -[NetDev] -Name=wg-tenant-%i -Kind=wireguard - -[WireGuard] -PrivateKeyFile=/var/lib/tenants/%i/network/wireguard.key -ListenPort=51820 - -[WireGuardPeer] -PublicKey=${PEER_PUBLIC_KEY} -AllowedIPs=10.%i.100.0/24 -Endpoint=${PEER_ENDPOINT}:51820 -PersistentKeepalive=25 -``` - -#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network:** -```ini -[Match] -Name=wg-tenant-%i - -[Network] -Address=10.%i.100.1/24 - -[Route] -Destination=10.%i.100.0/24 -Scope=link -``` - -### 3️⃣ VXLAN Overlay Template - -#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev:** -```ini -[NetDev] -Name=vxlan-tenant-%i -Kind=vxlan - -[VXLAN] -VNI=%i -Group=239.0.0.1 -DestinationPort=4789 -MacLearning=yes -``` - -#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network:** -```ini -[Match] -Name=vxlan-tenant-%i - -[Network] -Bridge=br-tenant-%i - -[BridgeVLAN] -PVID=1 -EgressUntagged=1 -``` - -### 4️⃣ VLAN Segmentation Template - -#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev:** -```ini -[NetDev] -Name=vlan-tenant-%i -Kind=vlan - -[VLAN] -Id=%i -``` - -#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network:** -```ini -[Match] -Name=vlan-tenant-%i - -[Network] -DHCP=yes -IPv6AcceptRA=yes - -[DHCP] -RouteMetric=200 -UseDomains=route -``` - -### 5️⃣ Network Namespace Template - -**/usr/lib/systemd/system/netns-tenant@.service:** -```ini -[Unit] -Description=Network namespace for tenant %i -After=network.target - -[Service] -Type=oneshot -RemainAfterExit=yes -ExecStart=/usr/bin/ip netns add tenant-%i -ExecStart=/usr/bin/ip netns exec tenant-%i ip link set lo up -ExecStop=/usr/bin/ip netns delete tenant-%i - -[Install] -WantedBy=multi-user.target -``` - -## βš™οΈ Systemd Generators - -### 1️⃣ Tenant Discovery Generator - -**/usr/lib/systemd/system-generators/tenant-generator:** -```bash -#!/bin/bash -# Discovers tenants from Git repositories and generates systemd units - -GENERATOR_DIR="$1" -TENANT_REGISTRY="/var/lib/bitbuilder/tenants.json" - -generate_tenant_units() { - local tenant_id="$1" - local tenant_config="$2" - - # Generate main tenant service - cat > "${GENERATOR_DIR}/tenant@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-infra@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-network@${tenant_id}.service" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-sysext.mount" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-confext.mount" < B[Tenant Generator] - B --> C[Read tenant registry] - C --> D[Clone Git repositories] - D --> E[Generate systemd units] - E --> F[Setup network namespace] - F --> G[Mount extensions] - G --> H[Start infra manager VM] - H --> I[Provision tenant resources] - I --> J[Start tenant workloads] -``` - -### 3️⃣ Generated Unit Hierarchy - -``` -tenant@tenant123.service - Requires: tenant-network@tenant123.service - Wants: tenant-infra@tenant123.service - After: network-online.target - Triggers: - var-lib-tenants-tenant123-sysext.mount - var-lib-tenants-tenant123-confext.mount - netns-tenant@tenant123.service - br-tenant-123.netdev -``` - -## βœ… Directory Structure Compliance - -### πŸ“ Linux File System Hierarchy Compliance - -Each template ensures compliance with the Linux File System Hierarchy specification: - -1. **Root Filesystem Requirements:** - - `/etc/os-release` or `/usr/lib/os-release` present - - Proper symlink from `/usr/lib/os-release` to `/etc/os-release` - - No files in `/` root directory itself - -2. **Extension Image Requirements:** - - sysext: Only `/usr/` and `/opt/` directories - - confext: Only `/etc/` directory - - Proper `extension-release` files in correct locations - -3. **Verification Structure:** - - VOA hierarchy at `/etc/voa/` and `/usr/share/voa/` - - Proper certificate fingerprint naming - - ASCII-armored OpenPGP files - -### βœ… Template Validation - -Each template includes a validation script: - -```bash -#!/bin/bash -# validate-template.sh - -validate_rootfs() { - local rootfs="$1" - - # Check for required files - [[ -f "$rootfs/etc/os-release" ]] || error "Missing /etc/os-release" - [[ -L "$rootfs/usr/lib/os-release" ]] || error "Missing /usr/lib/os-release symlink" - - # Validate directory structure - for dir in etc usr var proc sys dev run tmp; do - [[ -d "$rootfs/$dir" ]] || error "Missing /$dir directory" - done - - # Check permissions - [[ $(stat -c %a "$rootfs/tmp") == "1777" ]] || error "Invalid /tmp permissions" - - echo "Template validation successful" -} -``` - -## 🎯 Conclusion - -This template system provides: - -1. **Standardization**: All tenants use consistent, validated templates -2. **Compliance**: Full adherence to Linux Userspace API specifications -3. **Flexibility**: Multiple template types for different use cases -4. **Security**: Layered isolation with proper namespace separation -5. **Automation**: Systemd generators handle all instantiation logic -6. **Networking**: Comprehensive network isolation and connectivity options - -The combination of Git-based configuration, systemd integration, and compliant filesystem templates creates a robust, secure, and manageable multi-tenant hypervisor platform. +# πŸ—οΈ BitBuilder Hypervisor Stack Architecture + +[![Stack Architecture](https://img.shields.io/badge/Stack-Architecture-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) +[![Templates](https://img.shields.io/badge/Templates-Multi--Tenant-blue?style=flat-square)](https://uapi-group.org/) +[![Compliance](https://img.shields.io/badge/UAPI-Compliant-orange?style=flat-square)](https://uapi-group.org/specifications/) + +> **🧩 Comprehensive template system for creating fully compliant, multi-tenant rootfs filesystems with layered architecture and systemd integration.** + +--- + +## πŸ“‹ Table of Contents + +| Section | Description | +|---------|-------------| +| 🎯 [Template System Overview](#-template-system-overview) | Layered template architecture | +| 🏠 [Tenant Templates](#-tenant-templates) | Infrastructure, VM, container templates | +| πŸ”§ [Extension Image Templates](#-extension-image-templates) | sysext and confext templates | +| 🌐 [Network Templates](#-network-templates) | Networking configuration patterns | +| βš™οΈ [Systemd Generators](#%EF%B8%8F-systemd-generators) | Dynamic unit generation | +| πŸ”„ [Tenant Instantiation Flow](#-tenant-instantiation-flow) | Provisioning workflow | +| βœ… [Directory Structure Compliance](#-directory-structure-compliance) | UAPI compliance validation | + +--- + +## 🎯 Template System Overview + +**BitBuilder Hypervisor** uses a layered template system that creates fully compliant rootfs filesystems for each tenant component. Each template is a Git repository that contains a complete filesystem hierarchy adhering to the [**Linux Userspace API specifications**](https://uapi-group.org/specifications/). + +### 🧩 Template Categories + +```mermaid +graph TB + T[πŸ“¦ Templates] --> I[πŸ—οΈ Infrastructure Templates] + T --> M[πŸ–₯️ Machine Templates] + T --> C[πŸ“¦ Container Templates] + T --> H[🏠 Homed Templates] + T --> N[🌐 Network Templates] + + I --> IT[Management layer for each tenant] + M --> MT[VM templates - systemd-vmspawn] + C --> CT[Container templates - systemd-nspawn] + H --> HT[User home directory templates] + N --> NT[Network configuration templates] + + style T fill:#e3f2fd + style I fill:#f3e5f5 + style M fill:#e8f5e8 + style C fill:#fff3e0 + style H fill:#fce4ec + style N fill:#f1f8e9 +``` + +--- + +## 🏠 Tenant Templates + +### 1️⃣ Tenant Infrastructure Manager Template (`tenant-infra-template`) + +> 🎯 **Purpose**: The infrastructure manager runs as a privileged systemd-vmspawn VM within each tenant's namespace and manages all tenant resources. + +#### πŸ—‚οΈ Repository Structure + +```bash +tenant-infra-template/ +β”œβ”€β”€ metadata.json # Template metadata +β”œβ”€β”€ rootfs/ # Compliant root filesystem +β”‚ β”œβ”€β”€ etc/ +β”‚ β”‚ β”œβ”€β”€ os-release # Required OS identification +β”‚ β”‚ β”œβ”€β”€ systemd/ +β”‚ β”‚ β”‚ β”œβ”€β”€ system/ +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ multi-user.target.wants/ +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ infra-manager.service +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ git-sync.service +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ git-sync.timer +β”‚ β”‚ β”‚ β”‚ └── varlink-api.service +β”‚ β”‚ β”‚ └── network/ +β”‚ β”‚ β”‚ β”œβ”€β”€ 10-management.network +β”‚ β”‚ β”‚ └── 10-management.netdev +β”‚ β”‚ └── extension-release.d/ # Extension compatibility +β”‚ β”œβ”€β”€ usr/ +β”‚ β”‚ β”œβ”€β”€ lib/ +β”‚ β”‚ β”‚ β”œβ”€β”€ os-release -> ../../etc/os-release +β”‚ β”‚ β”‚ β”œβ”€β”€ systemd/system/ # Vendor units +β”‚ β”‚ β”‚ └── bitbuilder/ +β”‚ β”‚ β”‚ β”œβ”€β”€ infra-manager # Management binary +β”‚ β”‚ β”‚ └── lib/ # Shared libraries +β”‚ β”‚ └── share/ +β”‚ β”‚ └── bitbuilder/ +β”‚ β”‚ └── schemas/ # JSON schemas +β”‚ β”œβ”€β”€ var/ +β”‚ β”‚ └── lib/ +β”‚ β”‚ └── infra/ # Persistent infra data +β”‚ └── run/ # Runtime directory (empty) +β”œβ”€β”€ config/ # Default configuration +β”‚ β”œβ”€β”€ infra-config.yaml +β”‚ └── resource-limits.yaml +└── scripts/ + β”œβ”€β”€ provision.sh # Provisioning script + └── health-check.sh # Health monitoring +``` + +#### πŸ“‹ metadata.json Configuration +```json +{ + "template": { + "type": "infrastructure", + "version": "1.0.0", + "name": "tenant-infra-template" + }, + "requirements": { + "systemd_version": ">=258", + "kernel": ">=6.0", + "features": ["vmspawn", "varlink", "networkd"] + }, + "defaults": { + "resources": { + "cpu": 2, + "memory": "2G", + "storage": "10G" + }, + "network": { + "mode": "private", + "management_interface": true + } + } +} +``` + +### 2️⃣ Tenant Machine Template (`tenant-machine-template`) + +Template for creating tenant VMs using systemd-vmspawn. + +**Repository Structure:** +``` + +``` + +### 3️⃣ Tenant Container Template (`tenant-container-template`) + +Template for creating tenant containers using systemd-nspawn. + +**Repository Structure:** +``` +tenant-container-template/ + metadata.json + rootfs/ # Container root filesystem + etc/ + os-release + systemd/ + system/ + container-init.service + network/ + 80-container.network + usr/ + bin/ # Essential binaries + lib/ + var/ + lib/ + config/ + nspawn-settings.conf # systemd-nspawn settings + scripts/ + container-init.sh +``` + +#### βš™οΈ nspawn-settings.conf +```ini +[Exec] +Boot=yes +ProcessTwo=yes +NotifyReady=yes + +[Network] +Private=yes +VirtualEthernet=yes +Bridge=br-tenant + +[Files] +PrivateUsersChown=yes +BindReadOnly=/usr/lib/extensions +``` + +### 4️⃣ Tenant Homed Template (`tenant-homed-template`) + +Template for user home directories managed by systemd-homed. + +**Repository Structure:** +``` +tenant-homed-template/ + metadata.json + home-skeleton/ # Default home structure + .config/ + systemd/ + user/ # User services + .local/ + bin/ # User binaries + share/ + .ssh/ # SSH configuration + authorized_keys.template + config/ + homed-config.json # systemd-homed config + user-record.json # User record template + scripts/ + home-provision.sh +``` + +## πŸ”§ Extension Image Templates + +### πŸ”§ System Extension (sysext) Template + +``` +base-tools.sysext/ + usr/ # Only /usr and /opt allowed + bin/ + htop + tmux + vim + lib/ + extension-release.d/ + extension-release.base-tools + opt/ + bitbuilder/ + tools/ +``` + +#### πŸ“‹ extension-release.base-tools +```ini +ID=bitbuilder +VERSION_ID=1.0 +SYSEXT_LEVEL=1.0 +ARCHITECTURE=x86-64 +``` + +### βš™οΈ Configuration Extension (confext) Template + +``` +network-policies.confext/ + etc/ # Only /etc allowed + systemd/ + network/ + 20-wireguard.netdev + 20-wireguard.network + extension-release.d/ + extension-release.network-policies +``` + +## 🌐 Network Templates + +### 1️⃣ Bridge Network Template + +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev:** +```ini +[NetDev] +Name=br-tenant-%i +Kind=bridge + +[Bridge] +STP=yes +Priority=32768 +ForwardDelaySec=15 +HelloTimeSec=2 +MaxAgeSec=20 +``` + +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network:** +```ini +[Match] +Name=br-tenant-%i + +[Network] +DHCP=no +IPv6AcceptRA=no +IPForward=yes +IPMasquerade=yes +Address=10.%i.0.1/24 + +[DHCPServer] +PoolOffset=100 +PoolSize=100 +EmitDNS=yes +DNS=10.%i.0.1 +EmitRouter=yes +``` + +### 2️⃣ WireGuard VPN Template + +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev:** +```ini +[NetDev] +Name=wg-tenant-%i +Kind=wireguard + +[WireGuard] +PrivateKeyFile=/var/lib/tenants/%i/network/wireguard.key +ListenPort=51820 + +[WireGuardPeer] +PublicKey=${PEER_PUBLIC_KEY} +AllowedIPs=10.%i.100.0/24 +Endpoint=${PEER_ENDPOINT}:51820 +PersistentKeepalive=25 +``` + +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network:** +```ini +[Match] +Name=wg-tenant-%i + +[Network] +Address=10.%i.100.1/24 + +[Route] +Destination=10.%i.100.0/24 +Scope=link +``` + +### 3️⃣ VXLAN Overlay Template + +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev:** +```ini +[NetDev] +Name=vxlan-tenant-%i +Kind=vxlan + +[VXLAN] +VNI=%i +Group=239.0.0.1 +DestinationPort=4789 +MacLearning=yes +``` + +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network:** +```ini +[Match] +Name=vxlan-tenant-%i + +[Network] +Bridge=br-tenant-%i + +[BridgeVLAN] +PVID=1 +EgressUntagged=1 +``` + +### 4️⃣ VLAN Segmentation Template + +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev:** +```ini +[NetDev] +Name=vlan-tenant-%i +Kind=vlan + +[VLAN] +Id=%i +``` + +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network:** +```ini +[Match] +Name=vlan-tenant-%i + +[Network] +DHCP=yes +IPv6AcceptRA=yes + +[DHCP] +RouteMetric=200 +UseDomains=route +``` + +### 5️⃣ Network Namespace Template + +**/usr/lib/systemd/system/netns-tenant@.service:** +```ini +[Unit] +Description=Network namespace for tenant %i +After=network.target + +[Service] +Type=oneshot +RemainAfterExit=yes +ExecStart=/usr/bin/ip netns add tenant-%i +ExecStart=/usr/bin/ip netns exec tenant-%i ip link set lo up +ExecStop=/usr/bin/ip netns delete tenant-%i + +[Install] +WantedBy=multi-user.target +``` + +## βš™οΈ Systemd Generators + +### 1️⃣ Tenant Discovery Generator + +**/usr/lib/systemd/system-generators/tenant-generator:** +```bash +#!/bin/bash +# Discovers tenants from Git repositories and generates systemd units + +GENERATOR_DIR="$1" +TENANT_REGISTRY="/var/lib/bitbuilder/tenants.json" + +generate_tenant_units() { + local tenant_id="$1" + local tenant_config="$2" + + # Generate main tenant service + cat > "${GENERATOR_DIR}/tenant@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-infra@${tenant_id}.service" < "${GENERATOR_DIR}/tenant-network@${tenant_id}.service" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-sysext.mount" < "${GENERATOR_DIR}/var-lib-tenants-${tenant_id}-confext.mount" < B[Tenant Generator] + B --> C[Read tenant registry] + C --> D[Clone Git repositories] + D --> E[Generate systemd units] + E --> F[Setup network namespace] + F --> G[Mount extensions] + G --> H[Start infra manager VM] + H --> I[Provision tenant resources] + I --> J[Start tenant workloads] +``` + +### 3️⃣ Generated Unit Hierarchy + +``` +tenant@tenant123.service + Requires: tenant-network@tenant123.service + Wants: tenant-infra@tenant123.service + After: network-online.target + Triggers: + var-lib-tenants-tenant123-sysext.mount + var-lib-tenants-tenant123-confext.mount + netns-tenant@tenant123.service + br-tenant-123.netdev +``` + +## βœ… Directory Structure Compliance + +### πŸ“ Linux File System Hierarchy Compliance + +Each template ensures compliance with the Linux File System Hierarchy specification: + +1. **Root Filesystem Requirements:** + - `/etc/os-release` or `/usr/lib/os-release` present + - Proper symlink from `/usr/lib/os-release` to `/etc/os-release` + - No files in `/` root directory itself + +2. **Extension Image Requirements:** + - sysext: Only `/usr/` and `/opt/` directories + - confext: Only `/etc/` directory + - Proper `extension-release` files in correct locations + +3. **Verification Structure:** + - VOA hierarchy at `/etc/voa/` and `/usr/share/voa/` + - Proper certificate fingerprint naming + - ASCII-armored OpenPGP files + +### βœ… Template Validation + +Each template includes a validation script: + +```bash +#!/bin/bash +# validate-template.sh + +validate_rootfs() { + local rootfs="$1" + + # Check for required files + [[ -f "$rootfs/etc/os-release" ]] || error "Missing /etc/os-release" + [[ -L "$rootfs/usr/lib/os-release" ]] || error "Missing /usr/lib/os-release symlink" + + # Validate directory structure + for dir in etc usr var proc sys dev run tmp; do + [[ -d "$rootfs/$dir" ]] || error "Missing /$dir directory" + done + + # Check permissions + [[ $(stat -c %a "$rootfs/tmp") == "1777" ]] || error "Invalid /tmp permissions" + + echo "Template validation successful" +} +``` + +## 🎯 Conclusion + +This template system provides: + +1. **Standardization**: All tenants use consistent, validated templates +2. **Compliance**: Full adherence to Linux Userspace API specifications +3. **Flexibility**: Multiple template types for different use cases +4. **Security**: Layered isolation with proper namespace separation +5. **Automation**: Systemd generators handle all instantiation logic +6. **Networking**: Comprehensive network isolation and connectivity options + +The combination of Git-based configuration, systemd integration, and compliant filesystem templates creates a robust, secure, and manageable multi-tenant hypervisor platform. From 0150c8cbb7f186c03c8f65acb64ddfd3e814eb82 Mon Sep 17 00:00:00 2001 From: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> Date: Tue, 26 Aug 2025 16:38:42 -0500 Subject: [PATCH 6/9] style(docs): fix indentation and formatting in documentation --- README.md | 44 ++++---- STACK.md | 152 ++++++++++++++++----------- specs/DESIGN.md | 270 ++++++++++++++++++++---------------------------- 3 files changed, 223 insertions(+), 243 deletions(-) diff --git a/README.md b/README.md index 9567fd7..f3bd1b3 100644 --- a/README.md +++ b/README.md @@ -269,12 +269,12 @@ bitbuilder-system/ β”‚ └── config.yaml # Git-ops configuration β”œβ”€β”€ generators/ # Custom systemd generators β”‚ β”œβ”€β”€ tenant-generator # Tenant discovery and instantiation -β”‚ └── mount-generator # Extension mount generation -β”œβ”€β”€ units/ # System service units -β”‚ β”œβ”€β”€ tenant@.service # Tenant instantiation template -β”‚ β”œβ”€β”€ tenant-infra@.service # Infrastructure manager template -β”‚ └── tenant-network@.service # Network setup template -β”œβ”€β”€ network/ # Network configuration templates +β”‚ └── mount-generator # Extension mount generation +β”œβ”€β”€ units/ # System service units +β”‚ β”œβ”€β”€ tenant@.service # Tenant instantiation template +β”‚ β”œβ”€β”€ tenant-infra@.service # Infrastructure manager template +β”‚ └── tenant-network@.service # Network setup template +β”œβ”€β”€ network/ # Network configuration templates β”‚ β”œβ”€β”€ 10-tenant-bridge.netdev β”‚ β”œβ”€β”€ 10-tenant-bridge.network β”‚ β”œβ”€β”€ 20-wg-tenant.netdev @@ -285,8 +285,8 @@ bitbuilder-system/ β”‚ β”œβ”€β”€ base-tools.sysext.raw β”‚ β”œβ”€β”€ monitoring.sysext.raw β”‚ └── security.confext.raw -└── tenants/ # Tenant registry - └── registry.json # Active tenants list +└── tenants/ # Tenant registry + └── registry.json # Active tenants list ``` ### 🏠 Tenant Configuration Repository @@ -296,33 +296,33 @@ tenant-/ β”œβ”€β”€ metadata.json # Tenant metadata and requirements β”œβ”€β”€ infrastructure/ # Infrastructure manager config β”‚ β”œβ”€β”€ config.yaml # Infra manager configuration -β”‚ └── resource-limits.yaml # Resource quotas +β”‚ └── resource-limits.yaml # Resource quotas β”œβ”€β”€ network/ # Network configuration β”‚ β”œβ”€β”€ topology.yaml # Network topology definition -β”‚ β”œβ”€β”€ wireguard/ # VPN configurations -β”‚ └── firewall/ # Firewall rules +β”‚ β”œβ”€β”€ wireguard/ # VPN configurations +β”‚ └── firewall/ # Firewall rules β”œβ”€β”€ machines/ # VM definitions β”‚ └── / -β”‚ β”œβ”€β”€ config.yaml # VM configuration -β”‚ └── cloud-init/ # Cloud-init data +β”‚ β”œβ”€β”€ config.yaml # VM configuration +β”‚ └── cloud-init/ # Cloud-init data β”œβ”€β”€ containers/ # Container definitions β”‚ └── / -β”‚ β”œβ”€β”€ config.yaml # Container configuration -β”‚ └── rootfs-overlay/ # Filesystem overlays +β”‚ β”œβ”€β”€ config.yaml # Container configuration +β”‚ └── rootfs-overlay/ # Filesystem overlays β”œβ”€β”€ extensions/ # Tenant-specific extensions -β”‚ β”œβ”€β”€ sysext/ # System extensions +β”‚ β”œβ”€β”€ sysext/ # System extensions β”‚ β”‚ └── *.sysext.raw -β”‚ └── confext/ # Configuration extensions +β”‚ └── confext/ # Configuration extensions β”‚ └── *.confext.raw β”œβ”€β”€ services/ # Portable service definitions β”‚ └── *.portable.raw -β”œβ”€β”€ users/ # User definitions +β”œβ”€β”€ users/ # User definitions β”‚ └── / -β”‚ └── homed-config.json # systemd-homed configuration +β”‚ └── homed-config.json # systemd-homed configuration └── scripts/ - β”œβ”€β”€ pre-provision.sh # Pre-provisioning script - β”œβ”€β”€ post-provision.sh # Post-provisioning script - └── health-check.sh # Health monitoring script + β”œβ”€β”€ pre-provision.sh # Pre-provisioning script + β”œβ”€β”€ post-provision.sh # Post-provisioning script + └── health-check.sh # Health monitoring script ``` ### πŸ“‹ Template Repositories diff --git a/STACK.md b/STACK.md index 5833873..8d0bbb3 100644 --- a/STACK.md +++ b/STACK.md @@ -132,7 +132,33 @@ Template for creating tenant VMs using systemd-vmspawn. **Repository Structure:** ``` - +tenant-machine-template/ +β”œβ”€β”€ metadata.json +β”œβ”€β”€ disk-image/ # Base disk image +β”‚ β”œβ”€β”€ efi/ # EFI partition +β”‚ β”‚ └── EFI/ +β”‚ β”‚ └── systemd/ +β”‚ β”‚ └── systemd-bootx64.efi +β”‚ β”œβ”€β”€ boot/ # Boot partition +β”‚ β”‚ β”œβ”€β”€ vmlinuz # Kernel +β”‚ β”‚ └── initrd.img # Initial ramdisk +β”‚ └── rootfs/ # Root filesystem +β”‚ β”œβ”€β”€ etc/ +β”‚ β”‚ β”œβ”€β”€ os-release +β”‚ β”‚ β”œβ”€β”€ machine-id # Empty (generated) +β”‚ β”‚ └── systemd/ +β”‚ β”‚ β”œβ”€β”€ system/ +β”‚ β”‚ └── network/ +β”‚ β”œβ”€β”€ usr/ # Minimal userspace +β”‚ └── var/ +β”œβ”€β”€ config/ +β”‚ β”œβ”€β”€ vm-config.yaml +β”‚ └── cloud-init/ # Cloud-init templates +β”‚ β”œβ”€β”€ user-data +β”‚ └── meta-data +└── extensions/ # VM-specific extensions + β”œβ”€β”€ development.sysext.raw + └── monitoring.confext.raw ``` ### 3️⃣ Tenant Container Template (`tenant-container-template`) @@ -142,24 +168,24 @@ Template for creating tenant containers using systemd-nspawn. **Repository Structure:** ``` tenant-container-template/ - metadata.json - rootfs/ # Container root filesystem - etc/ - os-release - systemd/ - system/ - container-init.service - network/ - 80-container.network - usr/ - bin/ # Essential binaries - lib/ - var/ - lib/ - config/ - nspawn-settings.conf # systemd-nspawn settings - scripts/ - container-init.sh +β”œβ”€β”€ metadata.json +β”œβ”€β”€ rootfs/ # Container root filesystem +β”‚ β”œβ”€β”€ etc/ +β”‚ β”‚ β”œβ”€β”€ os-release +β”‚ β”‚ └── systemd/ +β”‚ β”‚ β”œβ”€β”€ system/ +β”‚ β”‚ β”‚ └── container-init.service +β”‚ β”‚ └── network/ +β”‚ β”‚ └── 80-container.network +β”‚ β”œβ”€β”€ usr/ +β”‚ β”‚ β”œβ”€β”€ bin/ # Essential binaries +β”‚ β”‚ └── lib/ +β”‚ └── var/ +β”‚ └── lib/ +β”œβ”€β”€ config/ +β”‚ └── nspawn-settings.conf # systemd-nspawn settings +└── scripts/ + └── container-init.sh ``` #### βš™οΈ nspawn-settings.conf @@ -186,21 +212,21 @@ Template for user home directories managed by systemd-homed. **Repository Structure:** ``` tenant-homed-template/ - metadata.json - home-skeleton/ # Default home structure - .config/ - systemd/ - user/ # User services - .local/ - bin/ # User binaries - share/ - .ssh/ # SSH configuration - authorized_keys.template - config/ - homed-config.json # systemd-homed config - user-record.json # User record template - scripts/ - home-provision.sh +β”œβ”€β”€ metadata.json +β”œβ”€β”€ home-skeleton/ # Default home structure +β”‚ β”œβ”€β”€ .config/ +β”‚ β”‚ └── systemd/ +β”‚ β”‚ └── user/ # User services +β”‚ β”œβ”€β”€ .local/ +β”‚ β”‚ β”œβ”€β”€ bin/ # User binaries +β”‚ β”‚ └── share/ +β”‚ └── .ssh/ # SSH configuration +β”‚ └── authorized_keys.template +β”œβ”€β”€ config/ +β”‚ β”œβ”€β”€ homed-config.json # systemd-homed config +β”‚ └── user-record.json # User record template +└── scripts/ + └── home-provision.sh ``` ## πŸ”§ Extension Image Templates @@ -209,17 +235,17 @@ tenant-homed-template/ ``` base-tools.sysext/ - usr/ # Only /usr and /opt allowed - bin/ - htop - tmux - vim - lib/ - extension-release.d/ - extension-release.base-tools - opt/ - bitbuilder/ - tools/ +β”œβ”€β”€ usr/ # Only /usr and /opt allowed +β”‚ β”œβ”€β”€ bin/ +β”‚ β”‚ β”œβ”€β”€ htop +β”‚ β”‚ β”œβ”€β”€ tmux +β”‚ β”‚ └── vim +β”‚ └── lib/ +β”‚ └── extension-release.d/ +β”‚ └── extension-release.base-tools +└── opt/ + └── bitbuilder/ + └── tools/ ``` #### πŸ“‹ extension-release.base-tools @@ -234,20 +260,20 @@ ARCHITECTURE=x86-64 ``` network-policies.confext/ - etc/ # Only /etc allowed - systemd/ - network/ - 20-wireguard.netdev - 20-wireguard.network - extension-release.d/ - extension-release.network-policies +└── etc/ # Only /etc allowed + β”œβ”€β”€ systemd/ + β”‚ └── network/ + β”‚ β”œβ”€β”€ 20-wireguard.netdev + β”‚ └── 20-wireguard.network + └── extension-release.d/ + └── extension-release.network-policies ``` ## 🌐 Network Templates ### 1️⃣ Bridge Network Template -#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev:** +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev: ```ini [NetDev] Name=br-tenant-%i @@ -261,7 +287,7 @@ HelloTimeSec=2 MaxAgeSec=20 ``` -#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network:** +#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.network: ```ini [Match] Name=br-tenant-%i @@ -283,7 +309,7 @@ EmitRouter=yes ### 2️⃣ WireGuard VPN Template -#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.netdev: ```ini [NetDev] Name=wg-tenant-%i @@ -300,7 +326,7 @@ Endpoint=${PEER_ENDPOINT}:51820 PersistentKeepalive=25 ``` -#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/20-wg-tenant.network: ```ini [Match] Name=wg-tenant-%i @@ -315,7 +341,7 @@ Scope=link ### 3️⃣ VXLAN Overlay Template -#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.netdev: ```ini [NetDev] Name=vxlan-tenant-%i @@ -328,7 +354,7 @@ DestinationPort=4789 MacLearning=yes ``` -#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/30-vxlan-tenant.network: ```ini [Match] Name=vxlan-tenant-%i @@ -343,7 +369,7 @@ EgressUntagged=1 ### 4️⃣ VLAN Segmentation Template -#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev:** +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.netdev: ```ini [NetDev] Name=vlan-tenant-%i @@ -353,7 +379,7 @@ Kind=vlan Id=%i ``` -#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network:** +#### πŸ“„ /usr/lib/systemd/system/40-vlan-tenant.network: ```ini [Match] Name=vlan-tenant-%i @@ -571,17 +597,17 @@ tenant@tenant123.service Each template ensures compliance with the Linux File System Hierarchy specification: -1. **Root Filesystem Requirements:** +1. **Root Filesystem Requirements: - `/etc/os-release` or `/usr/lib/os-release` present - Proper symlink from `/usr/lib/os-release` to `/etc/os-release` - No files in `/` root directory itself -2. **Extension Image Requirements:** +2. **Extension Image Requirements: - sysext: Only `/usr/` and `/opt/` directories - confext: Only `/etc/` directory - Proper `extension-release` files in correct locations -3. **Verification Structure:** +3. **Verification Structure: - VOA hierarchy at `/etc/voa/` and `/usr/share/voa/` - Proper certificate fingerprint naming - ASCII-armored OpenPGP files diff --git a/specs/DESIGN.md b/specs/DESIGN.md index dde47de..f3d184e 100644 --- a/specs/DESIGN.md +++ b/specs/DESIGN.md @@ -32,7 +32,7 @@ ## πŸ“– Introduction -**BitBuilder Hypervisor** represents a paradigm shift in hypervisor design, leveraging systemd's advanced virtualization capabilities to create a git-ops-native, multi-tenant virtualization platform. +**BitBuilder Hypervisor** represents a paradigm shift in hypervisor design, leveraging systemd's advanced virtualization capabilities to create a git-ops-native, multi-tenant virtualization platform. This document outlines the technical design decisions, architectural patterns, and implementation strategies that form the foundation of the system. ## 🎯 Design Principles @@ -69,17 +69,15 @@ This document outlines the technical design decisions, architectural patterns, a The host system operates as a minimal, immutable foundation: ``` - - UEFI Firmware -$ - systemd-boot (UKI) -$ - Immutable Host OS (Downloaded DDI) -$ - systemd-import-generator systemd generators systemd -$ - Git Sync Service Tenant Manager Varlink - + UEFI Firmware +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + systemd-boot (UKI) +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Immutable Host OS (Downloaded DDI) +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + systemd-import-generator systemd generators systemd +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Git Sync Service Tenant Manager Varlink ``` ### Tenant Layer Architecture @@ -87,17 +85,15 @@ $ Each tenant operates in complete isolation: ``` - - Tenant Git Repo -$ - Tenant Configuration (metadata.json) -$ - sysext layers confext layers Services -$ - systemd-vmspawn / systemd-nspawn instance -$ - Network Namespace Mount Namespace PID Namespace - + Tenant Git Repo +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Tenant Configuration (metadata.json) +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + sysext layers confext layers Services +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + systemd-vmspawn / systemd-nspawn instance +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Network Namespace Mount Namespace PID Namespace ``` ## 🧩 Core Components @@ -332,11 +328,11 @@ Multiple security layers protect each tenant: #### Service Authentication ``` - Varlink - Tenant ΔΊ Host Service - - - SO_PEERCRED + Varlink + Tenant ΔΊ Host Service + + + SO_PEERCRED (UID/GID/PID) ``` @@ -346,22 +342,22 @@ Multiple security layers protect each tenant: ``` - Physical Network + Physical Network , - + 4 - systemd-networkd + systemd-networkd , - + < - + 4 4 4 - Bridge VLAN NAT + Bridge VLAN NAT , , , - - - Network Namespaces - + + + Network Namespaces + ``` ### Network Isolation Strategies @@ -418,17 +414,14 @@ DNS=10.0.0.1 ### Storage Layers ``` - - Physical Storage (Block) -$ - LVM/Btrfs/ZFS -$ - Per-Tenant Logical Volumes -$ - Root FS Data FS Config FS - + Physical Storage (Block) +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + LVM/Btrfs/ZFS +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Per-Tenant Logical Volumes +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” + Root FS Data FS Config FS ``` - ### Storage Management #### Thin Provisioning @@ -450,13 +443,13 @@ $ ``` /var/lib/tenants// - config/ # Git repository (read-only bind mount) - data/ # Persistent data (read-write) - extensions/ # sysext/confext images - sysext/ - confext/ - services/ # Portable service images - runtime/ # Ephemeral runtime data +β”œβ”€β”€ config/ # Git repository (read-only bind mount) +β”œβ”€β”€ data/ # Persistent data (read-write) +β”œβ”€β”€ extensions/ # sysext/confext images +β”‚ β”œβ”€β”€ sysext/ +β”‚ └── confext/ +β”œβ”€β”€ services/ # Portable service images +└── runtime/ # Ephemeral runtime data ``` ## πŸ”§ Extension System Design @@ -467,9 +460,9 @@ Extend `/usr` and `/opt` hierarchies: ``` /usr/lib/extensions/ - base-tools.raw # Common tools extension - monitoring.raw # Monitoring stack - security-tools.raw # Security utilities +β”œβ”€β”€ base-tools.raw # Common tools extension +β”œβ”€β”€ monitoring.raw # Monitoring stack +└── security-tools.raw # Security utilities ``` **Creation**: @@ -486,9 +479,9 @@ Extend `/etc` hierarchy: ``` /usr/lib/confext/ - network-policies.raw # Network configurations - security-policies.raw # Security settings - monitoring-config.raw # Monitoring configs +β”œβ”€β”€ network-policies.raw # Network configurations +β”œβ”€β”€ security-policies.raw # Security settings +└── monitoring-config.raw # Monitoring configs ``` ### Extension Metadata @@ -507,16 +500,16 @@ Self-contained service bundles: ``` portable-service.raw/ - usr/ - bin/ - service-binary - lib/ - systemd/ - system/ - service.service - etc/ - service/ - config.conf +β”œβ”€β”€ usr/ +β”‚ β”œβ”€β”€ bin/ +β”‚ β”‚ └── service-binary +β”‚ └── lib/ +β”‚ └── systemd/ +β”‚ └── system/ +β”‚ └── service.service +└── etc/ + └── service/ + └── config.conf ``` ## πŸ“š Git-Ops Workflow @@ -526,109 +519,70 @@ portable-service.raw/ #### System Repository ``` bitbuilder-system/ - .gitops/ - config.yaml # Git-ops configuration - generators/ # Custom systemd generators - units/ # Systemd service units - network/ # Network configurations - extensions/ # System-wide extensions - tenants/ # Tenant registry - registry.json # Active tenants list +β”œβ”€β”€ .gitops/ +β”‚ └── config.yaml # Git-ops configuration +β”œβ”€β”€ generators/ # Custom systemd generators +β”œβ”€β”€ units/ # Systemd service units +β”œβ”€β”€ network/ # Network configurations +β”œβ”€β”€ extensions/ # System-wide extensions +└── tenants/ # Tenant registry + └── registry.json # Active tenants list ``` #### Tenant Repository ``` tenant-/ - .gitops/ - config.yaml # Tenant git-ops config - metadata.json # Tenant metadata - network/ # Network configurations - services/ # Service definitions - units/ # Custom systemd units - extensions/ # Tenant extensions - scripts/ # Lifecycle scripts - secrets/ # Encrypted secrets - sealed-secrets.yaml +β”œβ”€β”€ .gitops/ +β”‚ └── config.yaml # Tenant git-ops config +β”œβ”€β”€ metadata.json # Tenant metadata +β”œβ”€β”€ network/ # Network configurations +β”œβ”€β”€ services/ # Service definitions +β”œβ”€β”€ units/ # Custom systemd units +β”œβ”€β”€ extensions/ # Tenant extensions +β”œβ”€β”€ scripts/ # Lifecycle scripts +└── secrets/ # Encrypted secrets + └── sealed-secrets.yaml ``` ### Continuous Deployment ``` Git Push - - - Webhook - - - Validation - Stage -, - - - Pull - Changes -, - - + Webhook - Apply - Changes -, - - - Verify - State -``` + Validation + Stage +, -### Rollback Mechanism -1. Automatic rollback on failure -2. Git revert for configuration rollback -3. Snapshot restore for data rollback -4. A/B boot partitions for OS rollback -## πŸ“Š Monitoring and Observability + Pull + Changes +, -### Metrics Collection -``` -systemd-journal journald-exporter Prometheus - - Elasticsearch/Loki -``` -### Key Metrics + Apply + Changes +, -- **Host Metrics** - - CPU, Memory, Disk, Network utilization - - systemd unit states - - Git sync status -- **Tenant Metrics** - - Resource usage per tenant - - Service health status - - Network traffic patterns -### Logging Architecture + Verify + State ``` - - Tenant Logs journald - , - - - Log Router - , - - < - - Local Store Central Syslog S3 Archive -``` +### Rollback Mechanism + +1. Automatic rollback on failure +2. Git revert for configuration rollback +3. Snapshot restore for data rollback +4. A/B boot partitions for OS rollback ## ⚑ Performance Considerations ### Resource Management @@ -671,23 +625,23 @@ systemd-journal journald-exporter Prometheus ``` Health Check Loop - - - Monitor - Services + + + Monitor + Services , - + Failure? - + 4 - Yes + Yes , - - - Recovery - Action + + + Recovery + Action ``` @@ -730,4 +684,4 @@ Health Check Loop ## Conclusion -The BitBuilder Hypervisor design represents a fundamental shift toward immutable, declarative infrastructure management. By leveraging systemd's advanced capabilities and git-ops principles, the system provides unprecedented levels of security, reproducibility, and operational simplicity while maintaining the flexibility required for multi-tenant environments. \ No newline at end of file +The BitBuilder Hypervisor design represents a fundamental shift toward immutable, declarative infrastructure management. By leveraging systemd's advanced capabilities and git-ops principles, the system provides unprecedented levels of security, reproducibility, and operational simplicity while maintaining the flexibility required for multi-tenant environments. From b10e5103dfa502c28399076350b77f6742013555 Mon Sep 17 00:00:00 2001 From: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> Date: Sun, 16 Nov 2025 16:13:26 -0600 Subject: [PATCH 7/9] Update STACK.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> --- STACK.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STACK.md b/STACK.md index 8d0bbb3..0652d10 100644 --- a/STACK.md +++ b/STACK.md @@ -273,7 +273,7 @@ network-policies.confext/ ### 1️⃣ Bridge Network Template -#### πŸ“„ /usr/lib/systemd/system/10-tenant-bridge.netdev: +#### πŸ“„ /usr/lib/systemd/network/10-tenant-bridge.netdev: ```ini [NetDev] Name=br-tenant-%i From 4c46e102a51e19491754ce6ef89b382cd475ae4e Mon Sep 17 00:00:00 2001 From: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> Date: Sun, 16 Nov 2025 16:14:47 -0600 Subject: [PATCH 8/9] Update README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Daniel Bodnar <1790726+danielbodnar@users.noreply.github.com> --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f3bd1b3..9efbd3a 100644 --- a/README.md +++ b/README.md @@ -54,8 +54,8 @@ BitBuilder Hypervisor implements and adheres to the [**Linux Userspace API Speci | πŸ’½ [**Discoverable Partitions Specification (DPS)**](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/) | Auto-discovery of partition semantics | GPT partition type GUIDs | | πŸ“€ [**Discoverable Disk Image (DDI)**](https://uapi-group.org/specifications/specs/discoverable_disk_image/) | Self-describing system images | Unified disk images with metadata | | πŸ”§ [**Extension Image**](https://uapi-group.org/specifications/specs/extension_image/) | Layered extensions to base images | Overlay filesystem extensions | -| β”œβ”€β”€ **sysext** | System Extension Images overlaid on `/usr/` and `/opt/` | Runtime system extensions | -| └── **confext** | Configuration Extension Images overlaid on `/etc/` | Runtime configuration extensions | +| β”œβ”€β”€ πŸ—‚οΈ **sysext** | System Extension Images overlaid on `/usr/` and `/opt/` | Runtime system extensions | +| └── πŸ› οΈ **confext** | Configuration Extension Images overlaid on `/etc/` | Runtime configuration extensions | | πŸš€ [**Unified Kernel Image (UKI)**](https://uapi-group.org/specifications/specs/unified_kernel_image/) | Combined kernel, initrd, and boot configuration | Single-file bootable images | | πŸ₯Ύ [**Boot Loader Specification (BLS)**](https://uapi-group.org/specifications/specs/boot_loader_specification/) | Standardized boot configuration | systemd-boot integration | From 1b1a6b0888fa5f6fe481244695dca26686ba44f8 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Sun, 16 Nov 2025 16:17:36 -0600 Subject: [PATCH 9/9] [WIP] Fix implementation based on feedback for PR #7 (#9) * Initial plan * style(docs): standardize GitOps terminology in README2.md Co-authored-by: danielbodnar <1790726+danielbodnar@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: danielbodnar <1790726+danielbodnar@users.noreply.github.com> --- README2.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README2.md b/README2.md index 9a350fc..64f0b47 100644 --- a/README2.md +++ b/README2.md @@ -2,12 +2,12 @@ [![Advanced Architecture](https://img.shields.io/badge/Architecture-Advanced-red?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) [![SystemD Ecosystem](https://img.shields.io/badge/SystemD-Ecosystem-blue?style=flat-square)](https://systemd.io/) -[![Git-Ops Native](https://img.shields.io/badge/Git--Ops-Native-orange?style=flat-square)](https://www.gitops.tech/) +[![GitOps Native](https://img.shields.io/badge/GitOps-Native-orange?style=flat-square)](https://www.gitops.tech/) [![Multi-Tenant](https://img.shields.io/badge/Multi--Tenant-Secure-green?style=flat-square)](https://github.com/bitbuilder-io/bitbuilder-hypervisor) -> **πŸ”₯ A Git-Ops Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration** +> **πŸ”₯ A GitOps Orchestrated Multi-Tenant Hypervisor Leveraging Advanced systemd Ecosystem Integration** -**BitBuilder Hypervisor** implements a declarative, immutable infrastructure paradigm through git-ops methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns. +**BitBuilder Hypervisor** implements a declarative, immutable infrastructure paradigm through GitOps methodology, providing secure multi-tenant virtualization environments via comprehensive systemd subsystem orchestration. The architecture implements tenant isolation through cryptographically-secured namespace boundaries, leveraging systemd's advanced service management, portable service architectures, and extension image composition patterns. --- @@ -44,7 +44,7 @@ - πŸ”— **Varlink**: Type-safe, schema-validated IPC for service coordination and management interfaces - πŸ”„ **D-Bus**: Legacy compatibility and systemd service lifecycle management -### πŸ”„ Git-Ops Orchestration Workflow +### πŸ”„ GitOps Orchestration Workflow 1. **Boot-time Repository Synchronization**: systemd-import-generator fetches immutable EFI images 2. **Tenant Configuration Acquisition**: Git repository cloning/pulling for each tenant's declarative configuration @@ -61,7 +61,7 @@ - **Network Segmentation**: Software-defined networking with tenant-specific VLANs and firewall policies - **Storage Isolation**: Encrypted per-tenant storage volumes with key management integration -### πŸ“š Git-Ops Configuration Management +### πŸ“š GitOps Configuration Management - **Declarative Infrastructure as Code**: Complete tenant environments defined through version-controlled repositories - **Atomic Deployments**: Git commit-based deployment atomicity with automatic rollback capabilities @@ -106,7 +106,7 @@ # Configure systemd-boot with BitBuilder integration bootctl install --make-machine-id-directory=yes -# Initialize git-ops repository structure +# Initialize GitOps repository structure git clone https://github.com/your-org/bitbuilder-config.git /etc/bitbuilder cd /etc/bitbuilder && git submodule update --init --recursive