349 lines
14 KiB
Plaintext
349 lines
14 KiB
Plaintext
# Golden Image Schema (Phase 3)
|
|
#
|
|
# Comprehensive golden image building, caching, and versioning system.
|
|
# Follows KCL idiomatic patterns: schema-first, check blocks, composition, union types.
|
|
|
|
import .lib as lib
|
|
import .settings as cfg
|
|
|
|
# Pattern 1: Direct imports (no re-exports)
|
|
# Pattern 2: Schema-first development
|
|
# Pattern 5: Explicit types (always specify)
|
|
# Pattern 8: Union types for enums
|
|
|
|
schema GoldenImageConfig:
|
|
"""
|
|
Golden image definition with pre-installed taskservs and configuration.
|
|
|
|
A golden image is a pre-built, pre-configured VM disk image that includes:
|
|
- Base OS (Ubuntu, Debian, CentOS, etc.)
|
|
- Pre-installed taskservs (Kubernetes, Docker, etc.)
|
|
- Optimized configuration
|
|
- ~5x faster VM startup (image vs base OS)
|
|
|
|
Examples:
|
|
# Web server golden image
|
|
GoldenImageConfig {
|
|
name = "web-server-golden"
|
|
base_os = "ubuntu"
|
|
os_version = "22.04"
|
|
arch = "x86_64"
|
|
taskservs = ["nginx", "postgresql", "redis"]
|
|
disk_size_gb = 30
|
|
optimize = True
|
|
}
|
|
|
|
# Kubernetes node image
|
|
GoldenImageConfig {
|
|
name = "k8s-node"
|
|
base_os = "ubuntu"
|
|
os_version = "22.04"
|
|
taskservs = ["containerd", "kubernetes", "cilium"]
|
|
disk_size_gb = 50
|
|
cache_enabled = True
|
|
cache_ttl_days = 30
|
|
}
|
|
"""
|
|
|
|
# Image Identity (Pattern 5: Explicit types)
|
|
name: str # Image name (unique)
|
|
description?: str # Image description
|
|
|
|
# Base OS Configuration
|
|
base_os: "ubuntu" | "debian" | "centos" | "fedora" | "rhel" = "ubuntu"
|
|
os_version: str = "22.04" # OS version (22.04, 20.04, etc.)
|
|
arch: "x86_64" | "aarch64" | "arm64" = "x86_64" # CPU architecture
|
|
|
|
# Taskserv Pre-installation (Pattern 8: Union types, Pattern 9: Optional fields)
|
|
taskservs?: [str] # Taskservs to pre-install
|
|
taskserv_versions?: {str: str} # Taskserv version pinning
|
|
exclude_taskservs?: [str] # Taskservs to exclude
|
|
|
|
# Image Optimization
|
|
optimize?: bool = False # Run optimizations
|
|
include_dev_tools?: bool = False # Include development tools
|
|
include_kernel_headers?: bool = False # Include kernel headers
|
|
cleanup_package_manager?: bool = True # Cleanup apt/yum caches
|
|
|
|
# Disk Configuration
|
|
disk_size_gb?: int = 30 # Disk size (10-500 GB)
|
|
disk_format?: "qcow2" | "raw" | "vmdk" = "qcow2" # Disk format
|
|
compression?: bool = True # Enable compression
|
|
|
|
# Image Caching (Pattern 9: Optional fields)
|
|
cache_enabled?: bool = True # Cache built images
|
|
cache_ttl_days?: int = 30 # Cache validity period
|
|
cache_storage?: str # Custom cache path
|
|
|
|
# Network Configuration
|
|
network_config?: str # Cloud-init network config
|
|
dns_servers?: [str] # Custom DNS servers
|
|
|
|
# Security Configuration (Pattern 4: Check blocks for validation)
|
|
security_hardening?: bool = False # Apply security hardening
|
|
auto_updates?: bool = True # Enable automatic updates
|
|
ssh_public_keys?: [str] # Pre-loaded SSH keys
|
|
|
|
# Build Configuration
|
|
build_timeout_minutes?: int = 30 # Build timeout
|
|
build_retries?: int = 3 # Retry failed builds
|
|
parallel_builds?: bool = False # Allow parallel builds
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
len(name) > 0, "Image name required"
|
|
len(name) <= 255, "Image name too long"
|
|
taskservs == Undefined or len(taskservs) <= 50, "Too many taskservs"
|
|
disk_size_gb == Undefined or (disk_size_gb >= 10 and disk_size_gb <= 500), "Disk size must be 10-500 GB"
|
|
cache_ttl_days == Undefined or (cache_ttl_days >= 1 and cache_ttl_days <= 365), "Cache TTL must be 1-365 days"
|
|
build_timeout_minutes == Undefined or build_timeout_minutes >= 5, "Build timeout must be at least 5 minutes"
|
|
|
|
|
|
schema GoldenImageBuildJob:
|
|
"""
|
|
Represents an in-progress or completed golden image build job.
|
|
|
|
Tracks build status, progress, logs, and artifacts.
|
|
"""
|
|
|
|
# Job Identity
|
|
job_id: str # Unique job identifier
|
|
image_name: str # Image being built
|
|
image_version: str # Image version
|
|
image_config: GoldenImageConfig # Build configuration
|
|
|
|
# Build Status (Pattern 8: Union types for status)
|
|
status: "queued" | "building" | "testing" | "caching" | "completed" | "failed" = "queued"
|
|
started_at?: str # Build start time (ISO 8601)
|
|
completed_at?: str # Build completion time
|
|
duration_seconds?: int # Build duration
|
|
|
|
# Progress Tracking (Pattern 9: Optional fields)
|
|
progress_percent?: int # Build progress (0-100)
|
|
current_step?: str # Current build step
|
|
current_step_progress?: int # Step progress (0-100)
|
|
|
|
# Build Results
|
|
output_path?: str # Path to built image
|
|
image_size_gb?: float # Final image size
|
|
checksum?: str # SHA256 checksum
|
|
|
|
# Error Handling
|
|
error_message?: str # Error message if failed
|
|
retry_count?: int = 0 # Retry attempts
|
|
last_error?: str # Last error encountered
|
|
|
|
# Logging
|
|
build_log_path?: str # Path to build log
|
|
test_log_path?: str # Path to test log
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
len(job_id) > 0, "Job ID required"
|
|
len(image_name) > 0, "Image name required"
|
|
progress_percent == Undefined or (progress_percent >= 0 and progress_percent <= 100), "Progress must be 0-100"
|
|
duration_seconds == Undefined or duration_seconds >= 0, "Duration must be non-negative"
|
|
|
|
|
|
schema GoldenImageVersion:
|
|
"""
|
|
Version metadata for a golden image with tracking and rollback support.
|
|
|
|
Enables image versioning, rollback to previous versions, and tracking
|
|
of which VMs use which versions.
|
|
"""
|
|
|
|
# Version Identity
|
|
image_name: str # Image name
|
|
version: str # Semantic version (1.0.0)
|
|
build_number?: int # Build number for same version
|
|
|
|
# Metadata
|
|
created_at: str # Creation timestamp (ISO 8601)
|
|
created_by?: str # User who created
|
|
description?: str # Version description
|
|
|
|
# Content
|
|
image_path: str # Path to image file
|
|
image_size_gb: float # Image file size
|
|
checksum: str # SHA256 checksum
|
|
|
|
# Build Information
|
|
base_image_version?: str # Base image version used
|
|
taskserv_versions?: {str: str} # Taskserv versions included
|
|
build_job_id?: str # Build job that created this
|
|
|
|
# Tracking
|
|
usage_count?: int = 0 # Number of VMs using
|
|
vm_instances?: [str] # VMs using this version
|
|
last_used_at?: str # Last VM creation time
|
|
|
|
# Deprecation (Pattern 9: Optional fields)
|
|
deprecated?: bool = False # Mark as deprecated
|
|
replacement_version?: str # Recommended replacement
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
len(image_name) > 0, "Image name required"
|
|
len(version) > 0, "Version required"
|
|
len(checksum) == 64, "SHA256 checksum must be 64 characters"
|
|
|
|
|
|
schema GoldenImageCache:
|
|
"""
|
|
Image cache metadata and management.
|
|
|
|
Tracks cached images, storage locations, and cleanup policies.
|
|
"""
|
|
|
|
# Cache Identity
|
|
cache_id: str # Cache identifier
|
|
image_name: str # Cached image name
|
|
image_version: str # Image version
|
|
|
|
# Cache Storage
|
|
storage_path: str # Local cache path
|
|
storage_format: "qcow2" | "raw" | "compressed" = "qcow2"
|
|
disk_size_gb: float # Disk space used
|
|
|
|
# Timestamps
|
|
cached_at: str # When cached (ISO 8601)
|
|
accessed_at?: str # Last access time
|
|
expires_at?: str # Cache expiration time
|
|
ttl_days?: int # Time-to-live in days
|
|
|
|
# Cache Validity
|
|
is_valid: bool = True # Cache is still valid
|
|
checksum: str # SHA256 checksum
|
|
last_verification?: str # Last verification time
|
|
|
|
# Usage Tracking
|
|
access_count?: int = 0 # Number of uses
|
|
hit_count?: int = 0 # Cache hits
|
|
last_vm_created?: str # Last VM from cache
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
len(cache_id) > 0, "Cache ID required"
|
|
len(checksum) == 64, "SHA256 checksum must be 64 characters"
|
|
access_count == Undefined or access_count >= 0, "Access count must be non-negative"
|
|
|
|
|
|
schema ImageBuildSteps:
|
|
"""
|
|
Detailed build step definitions for golden image construction.
|
|
|
|
Pattern 3: Composition (used within build jobs)
|
|
"""
|
|
|
|
# Preparation Phase
|
|
prepare_base?: bool = True # Prepare base OS
|
|
update_packages?: bool = True # Update packages
|
|
install_dependencies?: bool = True # Install dependencies
|
|
|
|
# Taskserv Installation Phase
|
|
install_taskservs?: bool = True # Install taskservs
|
|
install_order?: [str] # Installation order
|
|
parallel_install?: bool = False # Parallel installation
|
|
|
|
# Configuration Phase
|
|
apply_config?: bool = True # Apply configuration
|
|
apply_security_hardening?: bool = False # Security hardening
|
|
apply_optimizations?: bool = False # Performance optimizations
|
|
|
|
# Testing Phase
|
|
run_tests?: bool = True # Run tests
|
|
test_scripts?: [str] # Custom test scripts
|
|
|
|
# Cleanup Phase
|
|
cleanup_caches?: bool = True # Cleanup package caches
|
|
cleanup_temp_files?: bool = True # Cleanup temp files
|
|
remove_build_artifacts?: bool = True # Remove build artifacts
|
|
|
|
# Final Steps
|
|
compress_image?: bool = True # Compress final image
|
|
generate_checksums?: bool = True # Generate checksums
|
|
verify_image?: bool = True # Verify image integrity
|
|
|
|
|
|
schema ImageBuildPolicy:
|
|
"""
|
|
Global policy for image building and caching.
|
|
|
|
Pattern 10: Reusable configurations
|
|
"""
|
|
|
|
# Build Defaults
|
|
default_os: str = "ubuntu"
|
|
default_version: str = "22.04"
|
|
default_arch: str = "x86_64"
|
|
default_disk_size_gb: int = 30
|
|
|
|
# Build Constraints
|
|
max_parallel_builds: int = 3 # Max concurrent builds
|
|
max_build_time_minutes: int = 60 # Maximum build time
|
|
max_image_size_gb: int = 100 # Maximum image size
|
|
|
|
# Cache Defaults
|
|
cache_enabled: bool = True
|
|
cache_location: str # Cache directory path
|
|
default_cache_ttl_days: int = 30
|
|
max_cache_size_gb: int = 500 # Max cache disk space
|
|
|
|
# Cleanup Policies
|
|
auto_cleanup_expired: bool = True # Auto-cleanup old caches
|
|
cleanup_interval_hours: int = 24
|
|
min_disk_free_percent: int = 10 # Keep 10% free
|
|
|
|
# Versioning
|
|
auto_create_versions: bool = True # Auto-version builds
|
|
version_naming: str = "semantic" # semantic, timestamp, sequential
|
|
|
|
# Optimization Defaults
|
|
default_optimize: bool = False
|
|
default_compression: bool = True
|
|
default_security_hardening: bool = False
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
max_parallel_builds > 0, "Max parallel builds must be positive"
|
|
max_build_time_minutes >= 5, "Max build time must be >= 5 minutes"
|
|
max_image_size_gb >= 10, "Max image size must be >= 10 GB"
|
|
max_cache_size_gb >= 50, "Max cache size must be >= 50 GB"
|
|
default_cache_ttl_days >= 1, "Cache TTL must be >= 1 day"
|
|
min_disk_free_percent >= 5 and min_disk_free_percent <= 50, "Free percent must be 5-50%"
|
|
|
|
|
|
schema GoldenImageRegistry:
|
|
"""
|
|
Registry of all golden images with versions and metadata.
|
|
|
|
Pattern 3: Composition (contains Image, BuildJob, Cache)
|
|
"""
|
|
|
|
# Registry Metadata
|
|
registry_id: str # Registry identifier
|
|
location: str # Registry storage path
|
|
created_at: str # Creation timestamp
|
|
|
|
# Images (Pattern 3: Composition)
|
|
images: {str: GoldenImageConfig} # Images by name
|
|
versions: [GoldenImageVersion] # All versions
|
|
builds: [GoldenImageBuildJob] # Build history
|
|
cache: [GoldenImageCache] # Cached images
|
|
|
|
# Policy
|
|
policy: ImageBuildPolicy # Build policy
|
|
policy_version?: str # Policy version
|
|
|
|
# Statistics
|
|
total_images?: int # Total unique images
|
|
total_versions?: int # Total versions
|
|
total_cached_gb?: float # Total cache size
|
|
total_builds?: int # Build count
|
|
|
|
# Validation (Pattern 4: Check blocks)
|
|
check:
|
|
len(registry_id) > 0, "Registry ID required"
|
|
len(location) > 0, "Location required"
|