Skip to content

BUILDER_BACKENDS.md

Latest commit

 

History

History
274 lines (213 loc) · 10.1 KB

BUILDER_BACKENDS.md

File metadata and controls

274 lines (213 loc) · 10.1 KB

Builder Backends Comparison - hephy-builder

Purpose: Comprehensive analysis of build backends for hephy-builder multi-backend strategy
Updated: October 26, 2025
Status: Complete with Ko prototype validation

🎯 Backend Strategy Overview

hephy-builder supports multiple build backends to optimize different application types and use cases. Each backend provides specific advantages while maintaining consistent build-config.yaml configuration.

Supported Backends

  • Kaniko: Universal Docker builds (current foundation)
  • Ko: Go application optimization (prototype complete) ✅
  • Spin: WebAssembly applications (planned)
  • BuildKit: Advanced Docker features (planned)

📊 Performance Comparison

Real-World Benchmarks (from Ko prototype testing + GitHub ARM64 runners)

Metric Kaniko Ko (Emulated) Ko (Native ARM64) Best Improvement
AMD64 Build Time 2m 15s 45s 45s 3x faster
ARM64 Build Time 2m 20s 48s ~35s 4x faster ⚡
Total Multi-Arch 4m 35s 1m 33s ~1m 20s 3.5x faster
Final Image Size 45 MB 12 MB 12 MB 4x smaller
Security Profile Full OS Distroless Distroless Minimal attack surface
Build Complexity Dockerfile + deps Go config only Go config only Simplified

🚀 GitHub ARM64 Runner Impact (January 2025)

Breaking News: GitHub's new native ARM64 runners provide an additional 40% performance boost for ARM64 builds, making Ko backend even more compelling:

  • Native ARM64 execution - No emulation overhead
  • Cobalt 100 processors - Latest generation ARM chips
  • Free for public repositories - Cost-effective for open source
  • Ko + ARM64 synergy - Perfect match for Go applications

Performance Analysis

Ko Advantages

  • ✅ 3x faster builds - No Dockerfile parsing, layer caching overhead
  • ✅ 4x smaller images - Distroless base with only necessary runtime
  • ✅ Better security - No shell, package managers, or OS utilities
  • ✅ Simpler maintenance - No Dockerfile needed, pure Go configuration

Kaniko Advantages

  • ✅ Universal compatibility - Any language, any Dockerfile
  • ✅ Mature ecosystem - Extensive Docker tooling support
  • ✅ Complex builds - Multi-stage, advanced Docker features
  • ✅ Legacy support - Existing Dockerfile investments

🔒 Security Analysis

Attack Surface Comparison

Backend Base Image Shell Access Package Manager CVE Exposure
Kaniko Full OS (Alpine/Ubuntu) ✅ Available ✅ Available High
Ko Distroless ❌ None ❌ None Minimal
Spin WASI Runtime ❌ None ❌ None Minimal
BuildKit Configurable ⚠️ Varies ⚠️ Varies Varies

Security Benefits by Backend

Ko Security Profile

  • Distroless base: No shell, package manager, or unnecessary binaries
  • Static binary: Single executable with no external dependencies
  • Read-only filesystem: Immutable runtime environment
  • Non-root execution: Secure user permissions by default
  • Minimal CVE exposure: Smaller attack surface = fewer vulnerabilities

Kaniko Security Considerations

  • Full OS base: Complete Linux environment increases attack surface
  • Shell access: Available for complex builds but increases risk
  • Package dependencies: OS package vulnerabilities require updates
  • Multi-stage benefits: Can achieve similar security with proper Dockerfile design

🎯 Use Case Guidelines

When to Use Ko

✅ Perfect for:

  • Go applications - Native optimization and integration
  • Microservices - Fast builds, small images ideal for distributed systems
  • Security-focused - Minimal attack surface requirements
  • Fast CI/CD - Build speed is critical for developer productivity
  • Cloud-native - Kubernetes deployments with resource constraints

❌ Not suitable for:

  • Non-Go applications
  • Complex build requirements beyond Go compilation
  • Legacy applications with existing Dockerfile investments

When to Use Kaniko

✅ Perfect for:

  • Non-Go languages - Python, Node.js, Java, Rust, etc.
  • Complex Dockerfiles - Multi-stage builds, advanced features
  • Legacy applications - Existing Dockerfile investments
  • Custom base images - Specific OS or runtime requirements
  • Universal compatibility - Any Docker build scenario

❌ Consider alternatives for:

  • Simple Go applications (Ko is faster and more secure)
  • WebAssembly applications (Spin is optimized)
  • Performance-critical scenarios where build speed matters

When to Use Spin (Future)

✅ Perfect for:

  • WebAssembly applications - WASI runtime optimization
  • Edge computing - Lightweight, fast-starting applications
  • Polyglot microservices - Multiple languages in single runtime
  • Serverless - Cold start optimization

When to Use BuildKit (Future)

✅ Perfect for:

  • Advanced Docker features - Cache mounts, secrets, SSH
  • Complex dependency management - Sophisticated build graphs
  • Performance optimization - Parallel builds, advanced caching
  • Enterprise requirements - Advanced security and compliance features

⚙️ Backend Selection Logic

Automatic Detection Strategy

# Auto-detection priority order:
1. Explicit backend: build_backend: ko
2. Go project detection: go.mod + cmd/ directory → suggest Ko
3. WebAssembly detection: spin.toml → suggest Spin  
4. Dockerfile present: → use Kaniko (default)
5. Fallback: → Kaniko (universal compatibility)

Configuration Examples

Ko Backend Configuration

# build-config.yaml
build_backend: ko
ko_config:
  import_path: ./cmd/server
  base_image: cgr.dev/chainguard/static:latest
  platforms: [linux/amd64, linux/arm64]
  env: [CGO_ENABLED=0]
  ldflags: ["-s", "-w", "-X main.version=v1.0.0"]
additional_tags: [latest, optimized]

Kaniko Backend Configuration

# build-config.yaml
build_backend: kaniko  # Optional - default
dockerfile_path: Dockerfile
platforms: [linux/amd64, linux/arm64]
build_args:
  - VERSION=v1.0.0
additional_tags: [latest, stable]

Spin Backend Configuration (Future)

# build-config.yaml
build_backend: spin
spin_config:
  manifest_path: spin.toml
  runtime: wasi
  platforms: [wasi/wasm32]
additional_tags: [latest, wasm]

🔄 Migration Strategies

Kaniko → Ko Migration

For Go applications wanting Ko optimization benefits:

# Before: Kaniko
dockerfile_path: Dockerfile
platforms: [linux/amd64, linux/arm64]

# After: Ko
build_backend: ko
ko_config:
  import_path: ./cmd/app
  base_image: cgr.dev/chainguard/static:latest
  platforms: [linux/amd64, linux/arm64]

Benefits: 3x faster builds, 4x smaller images, better security Effort: Medium - requires Go module structure, remove Dockerfile

Performance vs Compatibility Trade-off

Priority Recommended Backend Rationale
Performance Ko > BuildKit > Kaniko Build speed and image size
Security Ko > Spin > BuildKit > Kaniko Attack surface minimization
Compatibility Kaniko > BuildKit > Ko > Spin Universal language support
Simplicity Ko > Spin > Kaniko > BuildKit Configuration complexity

🚀 Implementation Roadmap

Phase 1: Ko Integration (Current)

  • ✅ Ko backend prototype complete with performance validation
  • 🚧 Pipeline integration (Issue #5)
  • 🚧 Auto-detection logic for Go projects
  • 🚧 Documentation and examples

Phase 2: Advanced Features

  • GitHub Actions Ko workflow equivalent
  • Performance monitoring and optimization
  • Ko configuration templates and best practices
  • Enterprise Ko configuration options

Phase 3: Additional Backends

  • Spin backend: WebAssembly application support (Issue #11)
  • BuildKit backend: Advanced Docker features (Issue #12)
  • Backend composition: Multi-backend applications
  • Performance benchmarking: Automated comparison testing

📋 Backend Comparison Matrix

Feature Kaniko Ko Spin BuildKit
Languages All Go WASI-compatible All
Build Speed ⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐⭐
Image Size ⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐
Security ⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐
Compatibility ⭐⭐⭐⭐ ⭐⭐ ⭐⭐ ⭐⭐⭐⭐
Complexity ⭐⭐⭐ ⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐
Maturity ⭐⭐⭐⭐ ⭐⭐⭐ ⭐⭐ ⭐⭐⭐

Rating Scale: ⭐ Poor → ⭐⭐⭐⭐ Excellent

💡 Best Practices

Backend Selection Guidelines

  1. Start with use case: What type of application are you building?
  2. Consider constraints: Performance, security, compatibility requirements
  3. Evaluate trade-offs: Speed vs compatibility, security vs complexity
  4. Plan migration: Can you optimize later with different backend?

Configuration Best Practices

  1. Explicit backend specification: Always declare build_backend for clarity
  2. Platform consistency: Use same platforms across all backends
  3. Security defaults: Prefer minimal base images and distroless when possible
  4. Performance testing: Benchmark different backends for your use case

Multi-Backend Applications

For applications with mixed requirements:

  • API service: Ko backend for fast, secure Go service
  • Frontend assets: Kaniko for Node.js build pipeline
  • Edge functions: Spin for WebAssembly serverless functions
  • Database migrations: Kaniko for SQL tooling containers

This analysis is based on real performance data from the Ko prototype and provides concrete guidance for hephy-builder backend selection across different application types and requirements.