300 lines
7 KiB
Markdown
300 lines
7 KiB
Markdown
# Debian Atomic Blueprints for OSBuild Composer
|
|
|
|
## Overview
|
|
|
|
This document defines the blueprint system for creating Debian atomic images using OSBuild Composer. The blueprints are based on debos recipe patterns and adapted for OSBuild's pipeline-based architecture.
|
|
|
|
## Blueprint Structure
|
|
|
|
### Basic Debian Atomic Blueprint
|
|
|
|
```json
|
|
{
|
|
"name": "debian-atomic-base",
|
|
"description": "Debian Atomic Base System",
|
|
"version": "0.0.1",
|
|
"packages": [
|
|
{"name": "systemd"},
|
|
{"name": "systemd-sysv"},
|
|
{"name": "dbus"},
|
|
{"name": "udev"},
|
|
{"name": "ostree"},
|
|
{"name": "linux-image-amd64"}
|
|
],
|
|
"modules": [],
|
|
"groups": [],
|
|
"customizations": {
|
|
"user": [
|
|
{
|
|
"name": "debian",
|
|
"description": "Debian user",
|
|
"password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
|
|
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
|
|
"home": "/home/debian",
|
|
"shell": "/bin/bash",
|
|
"groups": ["wheel"],
|
|
"uid": 1000,
|
|
"gid": 1000
|
|
}
|
|
],
|
|
"services": {
|
|
"enabled": ["sshd", "systemd-networkd"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Debian Atomic Workstation Blueprint
|
|
|
|
```json
|
|
{
|
|
"name": "debian-atomic-workstation",
|
|
"description": "Debian Atomic Workstation",
|
|
"version": "0.0.1",
|
|
"packages": [
|
|
{"name": "systemd"},
|
|
{"name": "systemd-sysv"},
|
|
{"name": "dbus"},
|
|
{"name": "udev"},
|
|
{"name": "ostree"},
|
|
{"name": "linux-image-amd64"},
|
|
{"name": "gnome-shell"},
|
|
{"name": "gnome-session"},
|
|
{"name": "gdm3"},
|
|
{"name": "network-manager"},
|
|
{"name": "firefox-esr"}
|
|
],
|
|
"modules": [],
|
|
"groups": [
|
|
{"name": "desktop"}
|
|
],
|
|
"customizations": {
|
|
"user": [
|
|
{
|
|
"name": "debian",
|
|
"description": "Debian user",
|
|
"password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
|
|
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
|
|
"home": "/home/debian",
|
|
"shell": "/bin/bash",
|
|
"groups": ["wheel", "desktop"],
|
|
"uid": 1000,
|
|
"gid": 1000
|
|
}
|
|
],
|
|
"services": {
|
|
"enabled": ["sshd", "systemd-networkd", "gdm3", "NetworkManager"]
|
|
},
|
|
"desktop": {
|
|
"enabled": true
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Debian Atomic Server Blueprint
|
|
|
|
```json
|
|
{
|
|
"name": "debian-atomic-server",
|
|
"description": "Debian Atomic Server",
|
|
"version": "0.0.1",
|
|
"packages": [
|
|
{"name": "systemd"},
|
|
{"name": "systemd-sysv"},
|
|
{"name": "dbus"},
|
|
{"name": "udev"},
|
|
{"name": "ostree"},
|
|
{"name": "linux-image-amd64"},
|
|
{"name": "nginx"},
|
|
{"name": "postgresql"},
|
|
{"name": "redis-server"},
|
|
{"name": "fail2ban"}
|
|
],
|
|
"modules": [],
|
|
"groups": [
|
|
{"name": "server"}
|
|
],
|
|
"customizations": {
|
|
"user": [
|
|
{
|
|
"name": "debian",
|
|
"description": "Debian user",
|
|
"password": "$6$rounds=656000$YQvKxqQKqQKqQKqQ$...",
|
|
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC...",
|
|
"home": "/home/debian",
|
|
"shell": "/bin/bash",
|
|
"groups": ["wheel", "server"],
|
|
"uid": 1000,
|
|
"gid": 1000
|
|
}
|
|
],
|
|
"services": {
|
|
"enabled": ["sshd", "systemd-networkd", "nginx", "postgresql", "redis-server", "fail2ban"]
|
|
},
|
|
"firewall": {
|
|
"services": {
|
|
"enabled": ["ssh", "http", "https"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Blueprint Variables
|
|
|
|
### Architecture Support
|
|
|
|
```json
|
|
{
|
|
"variables": {
|
|
"architecture": "amd64",
|
|
"suite": "bookworm",
|
|
"variant": "minbase",
|
|
"mirror": "http://deb.debian.org/debian",
|
|
"apt_proxy": "http://192.168.1.101:3142"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Package Categories
|
|
|
|
```json
|
|
{
|
|
"package_groups": {
|
|
"base": ["systemd", "systemd-sysv", "dbus", "udev", "ostree"],
|
|
"desktop": ["gnome-shell", "gnome-session", "gdm3"],
|
|
"server": ["nginx", "postgresql", "redis-server"],
|
|
"development": ["build-essential", "git", "python3", "nodejs"],
|
|
"security": ["fail2ban", "unattended-upgrades", "rkhunter"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## OSBuild Pipeline Integration
|
|
|
|
### Debian Bootstrap Stage
|
|
|
|
```json
|
|
{
|
|
"type": "org.osbuild.debootstrap",
|
|
"options": {
|
|
"suite": "bookworm",
|
|
"mirror": "http://deb.debian.org/debian",
|
|
"arch": "amd64",
|
|
"variant": "minbase",
|
|
"apt_proxy": "http://192.168.1.101:3142"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Package Installation Stage
|
|
|
|
```json
|
|
{
|
|
"type": "org.osbuild.apt",
|
|
"options": {
|
|
"packages": ["systemd", "systemd-sysv", "dbus", "udev"],
|
|
"recommends": false,
|
|
"update": true,
|
|
"apt_proxy": "http://192.168.1.101:3142"
|
|
}
|
|
}
|
|
```
|
|
|
|
### OSTree Commit Stage
|
|
|
|
```json
|
|
{
|
|
"type": "org.osbuild.ostree.commit",
|
|
"options": {
|
|
"repo": "debian-atomic",
|
|
"branch": "debian/bookworm",
|
|
"subject": "Debian Bookworm atomic system",
|
|
"body": "Debian Bookworm minbase system with systemd and OSTree"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Blueprint Validation
|
|
|
|
### Required Fields
|
|
|
|
- `name`: Unique identifier for the blueprint
|
|
- `description`: Human-readable description
|
|
- `version`: Semantic version string
|
|
- `packages`: Array of package specifications
|
|
|
|
### Optional Fields
|
|
|
|
- `modules`: Debian modules (currently empty for atomic)
|
|
- `groups`: Package groups
|
|
- `customizations`: User, service, and system customizations
|
|
- `variables`: Blueprint variables for templating
|
|
|
|
## Usage Examples
|
|
|
|
### Creating a Blueprint
|
|
|
|
```bash
|
|
# Submit blueprint to composer
|
|
composer-cli blueprints push debian-atomic-base.json
|
|
|
|
# List available blueprints
|
|
composer-cli blueprints list
|
|
|
|
# Show blueprint details
|
|
composer-cli blueprints show debian-atomic-base
|
|
```
|
|
|
|
### Building an Image
|
|
|
|
```bash
|
|
# Start a compose
|
|
composer-cli compose start debian-atomic-base qcow2
|
|
|
|
# Check compose status
|
|
composer-cli compose status
|
|
|
|
# Download the image
|
|
composer-cli compose image <compose-id>
|
|
```
|
|
|
|
## Integration with Debian Forge
|
|
|
|
### Build Orchestration
|
|
|
|
The blueprints integrate with our build orchestration system:
|
|
|
|
1. **Blueprint Submission**: User submits blueprint via composer API
|
|
2. **Pipeline Generation**: Composer generates OSBuild pipeline from blueprint
|
|
3. **Build Execution**: Our build orchestrator executes the pipeline
|
|
4. **OSTree Composition**: Debian stages create atomic filesystem
|
|
5. **Image Generation**: Output formats (ISO, QCOW2, RAW) generated
|
|
6. **Deployment**: OSTree commits available for deployment
|
|
|
|
### Customization Points
|
|
|
|
- **Package Selection**: Via blueprint packages array
|
|
- **User Configuration**: Via blueprint customizations
|
|
- **Service Management**: Via blueprint services
|
|
- **Security Settings**: Via blueprint security groups
|
|
- **Network Configuration**: Via blueprint network settings
|
|
|
|
## Future Enhancements
|
|
|
|
### Advanced Blueprint Features
|
|
|
|
- **Template Inheritance**: Base blueprints with specialization
|
|
- **Conditional Packages**: Architecture or suite-specific packages
|
|
- **Repository Management**: Custom Debian repositories
|
|
- **Security Policies**: SELinux, AppArmor, and security modules
|
|
- **Compliance**: FIPS, Common Criteria, and security certifications
|
|
|
|
### Integration Features
|
|
|
|
- **CI/CD Integration**: GitOps workflow integration
|
|
- **Multi-Architecture**: ARM64, RISC-V support
|
|
- **Container Integration**: Bootc and container-native workflows
|
|
- **Cloud Integration**: AWS, Azure, GCP image generation
|
|
- **Edge Computing**: IoT and edge deployment scenarios
|