# 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"