rootfs module (need better spec) #10

New issue

Open

opened 2025-12-21 11:39:10 +00:00 by thabeta · 1 comment

thabeta commented

2025-12-21 11:39:10 +00:00

Owner

Module Overview

The rootfs module provides comprehensive root filesystem building capabilities for , supporting multiple Linux distributions and customizing them for cloud deployments. This module handles the complex process of creating bootable root filesystems from scratch, including package management, service configuration, and cloud-init integration for first-boot customization.

The module is designed to create minimal, secure, and cloud-optimized root filesystems that can be deployed across various cloud providers and virtualization platforms. It integrates with cloud-init to enable dynamic configuration at boot time, allowing instances to customize themselves based on user data, metadata, and other cloud-specific information.

Functionality

Multi-distribution support: Build root filesystems for various Linux distributions including Ubuntu, Alpine with their respective package managers
Package management and customization: Install specific packages, remove unnecessary ones, and configure package repositories for optimized images
Cloud-init integration: Install and configure cloud-init/or its alternative heroinit for first-boot setup, user provisioning, and dynamic configuration
Security hardening: Apply security configurations, manage user accounts, and configure access controls
Filesystem optimization: Create optimized filesystem layouts with proper permissions, ownership, and structure for cloud deployments

Module API

RootFS Building

RootFSBuilder::new(distro: LinuxDistro) -> Self - Create a new root filesystem builder for the specified distribution
create_base_rootfs(distro: LinuxDistro, arch: Architecture) -> Result<RootFSBuilder, RootFSError> - Initialize a base root filesystem
bootstrap_packages(&mut self, packages: Vec<&str>) -> Result<(), RootFSError> - Bootstrap essential packages for the distribution
install_package(&mut self, package: &str) -> &mut Self - Install a specific package in the root filesystem
add_file(&mut self, path: &Path, content: &[u8]) -> &mut Self - Add a file with specified content to the filesystem
set_hostname(&mut self, hostname: &str) -> &mut Self - Set the system hostname for the root filesystem
configure_systemd(&mut self, services: Vec<SystemdService>) -> &mut Self - Configure systemd services and units
setup_networking(&mut self, config: NetworkConfig) -> &mut Self - Configure network interfaces and settings
install_cloud_init(&mut self, version: &str) -> Result<(), RootFSError> - Install cloud-init package and dependencies
build(&self, format: FileSystemFormat) -> Result<PathBuf, RootFSError> - Build the final root filesystem image

Cloud-Init Config

CloudInitBuilder::new() -> Self - Create a new cloud-init configuration builder
set_ssh_keys(&mut self, keys: Vec<String>) -> &mut Self - Configure SSH keys for user access
configure_user(&mut self, user: UserConfig) -> &mut Self - Set up user accounts and permissions
add_script(&mut self, script: CloudInitScript) -> &mut Self - Add initialization scripts to run at boot
set_network_config(&mut self, config: NetworkConfig) -> &mut Self - Configure network settings for cloud-init
build(&self) -> Result<CloudInitConfig, CloudInitError> - Build the cloud-init configuration
write_user_data(&self, path: &Path) -> Result<(), CloudInitError> - Write user-data configuration to file
write_meta_data(&self, path: &Path) -> Result<(), CloudInitError> - Write meta-data configuration to file
generate_iso(&self, path: &Path) -> Result<(), CloudInitError> - Generate cloud-init ISO image for attachment

## Module Overview The rootfs module provides comprehensive root filesystem building capabilities for , supporting multiple Linux distributions and customizing them for cloud deployments. This module handles the complex process of creating bootable root filesystems from scratch, including package management, service configuration, and cloud-init integration for first-boot customization. The module is designed to create minimal, secure, and cloud-optimized root filesystems that can be deployed across various cloud providers and virtualization platforms. It integrates with cloud-init to enable dynamic configuration at boot time, allowing instances to customize themselves based on user data, metadata, and other cloud-specific information. ## Functionality - **Multi-distribution support**: Build root filesystems for various Linux distributions including Ubuntu, Alpine with their respective package managers - **Package management and customization**: Install specific packages, remove unnecessary ones, and configure package repositories for optimized images - **Cloud-init integration**: Install and configure cloud-init/or its alternative heroinit for first-boot setup, user provisioning, and dynamic configuration - **Security hardening**: Apply security configurations, manage user accounts, and configure access controls - **Filesystem optimization**: Create optimized filesystem layouts with proper permissions, ownership, and structure for cloud deployments ## Module API ### RootFS Building - `RootFSBuilder::new(distro: LinuxDistro) -> Self` - Create a new root filesystem builder for the specified distribution - `create_base_rootfs(distro: LinuxDistro, arch: Architecture) -> Result<RootFSBuilder, RootFSError>` - Initialize a base root filesystem - `bootstrap_packages(&mut self, packages: Vec<&str>) -> Result<(), RootFSError>` - Bootstrap essential packages for the distribution - `install_package(&mut self, package: &str) -> &mut Self` - Install a specific package in the root filesystem - `add_file(&mut self, path: &Path, content: &[u8]) -> &mut Self` - Add a file with specified content to the filesystem - `set_hostname(&mut self, hostname: &str) -> &mut Self` - Set the system hostname for the root filesystem - `configure_systemd(&mut self, services: Vec<SystemdService>) -> &mut Self` - Configure systemd services and units - `setup_networking(&mut self, config: NetworkConfig) -> &mut Self` - Configure network interfaces and settings - `install_cloud_init(&mut self, version: &str) -> Result<(), RootFSError>` - Install cloud-init package and dependencies - `build(&self, format: FileSystemFormat) -> Result<PathBuf, RootFSError>` - Build the final root filesystem image ### Cloud-Init Config - `CloudInitBuilder::new() -> Self` - Create a new cloud-init configuration builder - `set_ssh_keys(&mut self, keys: Vec<String>) -> &mut Self` - Configure SSH keys for user access - `configure_user(&mut self, user: UserConfig) -> &mut Self` - Set up user accounts and permissions - `add_script(&mut self, script: CloudInitScript) -> &mut Self` - Add initialization scripts to run at boot - `set_network_config(&mut self, config: NetworkConfig) -> &mut Self` - Configure network settings for cloud-init - `build(&self) -> Result<CloudInitConfig, CloudInitError>` - Build the cloud-init configuration - `write_user_data(&self, path: &Path) -> Result<(), CloudInitError>` - Write user-data configuration to file - `write_meta_data(&self, path: &Path) -> Result<(), CloudInitError>` - Write meta-data configuration to file - `generate_iso(&self, path: &Path) -> Result<(), CloudInitError>` - Generate cloud-init ISO image for attachment