cluster

Cluster Management

This package provides interfaces and implementations for managing local Kubernetes clusters.

Design Philosophy

Following Caproni's Pluggable Backends principle, the cluster management is designed with:

• Interface-based design: cluster.Manager defines the contract
• Swappable implementations: Different drivers (Colima, k3d, minikube) can be used
• Minimal surface area: Simple Start/Stop/Status operations

Interface

type Manager interface {
    Start(ctx context.Context, cfg config.ClusterConfig) error
    Stop(ctx context.Context) error
    Status(ctx context.Context) (*Status, error)
}

Usage

Creating a Cluster Manager

Drivers are automatically registered via their init() functions. Simply import the driver package and use the registry to create a manager:

import (
    "context"

    "gitlab.com/gitlab-org/caproni/internal/cluster"
    "gitlab.com/gitlab-org/caproni/internal/config"

    // Import auto driver to register auto, colima, and k3d
    _ "gitlab.com/gitlab-org/caproni/internal/cluster/auto"
)

// Create a manager using the registry ("auto" selects colima on macOS, k3d on Linux)
manager, err := cluster.NewManager("auto", "caproni-dev")
if err != nil {
    log.Fatalf("Failed to create manager: %v", err)
}

// With driver: auto, always provide both sections so the config works on any platform
cfg := config.ClusterConfig{
    Driver: "auto",
    Colima: &config.ColimaConfig{
        Memory: "10GiB",
        Cores:  4,
    },
    K3d: &config.K3dConfig{
        Agents:  0,
        Servers: 1,
    },
}

ctx := context.Background()

Listing Available Drivers

import "gitlab.com/gitlab-org/caproni/internal/cluster"

// Get all registered drivers
drivers := cluster.ListDrivers()
fmt.Printf("Available drivers: %v\n", drivers)
// Output: Available drivers: [colima k3d]

Starting a Cluster

// Start the cluster
if err := manager.Start(ctx, cfg); err != nil {
    log.Fatalf("Failed to start cluster: %v", err)
}

// Starting an already-running cluster with matching config is a no-op
// Starting with different config returns cluster.ErrConfigMismatch

Checking Cluster Status

status, err := manager.Status(ctx)
if err != nil {
    log.Fatalf("Failed to get status: %v", err)
}

fmt.Printf("State: %s\n", status.State)
fmt.Printf("Driver: %s\n", status.Driver)
fmt.Printf("Kubernetes Version: %s\n", status.KubernetesVersion)

Stopping a Cluster

if err := manager.Stop(ctx); err != nil {
    log.Fatalf("Failed to stop cluster: %v", err)
}

// Stopping an already-stopped cluster is a no-op

Available Drivers

Colima

The Colima driver (internal/cluster/colima) uses Colima as the backend for running Kubernetes clusters.

Requirements:

• Colima must be installed and available in PATH
• Supports macOS and Linux
• Supports both arm64 and amd64 architectures

Features:

• Profile-based isolation (multiple Colima instances)
• Kubernetes-enabled clusters
• Configuration verification (prevents starting with mismatched config)

k3d

The k3d driver (internal/cluster/k3d) uses k3d as the backend for running Kubernetes clusters.

Requirements:

• k3d must be installed and available in PATH
• Supports macOS, Linux, and Windows
• Runs on any architecture supported by Docker

Features:

• Lightweight Kubernetes clusters using k3s
• Fast cluster creation and deletion
• Profile-based isolation (multiple k3d clusters)

Error Handling

The package defines several sentinel errors:

• cluster.ErrClusterNotRunning - Operation requires a running cluster
• cluster.ErrClusterAlreadyRunning - Cluster is already running
• cluster.ErrConfigMismatch - Running cluster config doesn't match requested config
• cluster.ErrDriverNotFound - Specified driver is not available
• cluster.ErrClusterNotReady - Cluster is running but not ready for workloads

Example:

err := manager.Start(ctx, cfg)
if errors.Is(err, cluster.ErrConfigMismatch) {
    log.Println("Cluster is running with different configuration")
    log.Println("Stop the cluster first or adjust your config")
}

Driver Registry

The cluster package uses a registry pattern for driver management. Drivers self-register in their init() functions, allowing new drivers to be added without modifying the core registry code.

How It Works

1. Driver Package Init: Each driver package registers itself on import
2. Factory Pattern: Drivers register a factory function that creates instances
3. Auto-Detection: The auto driver package registers itself and selects colima on macOS or k3d on Linux
4. Lookup via Registry: NewManager() looks up the driver in the registry
5. Compile-Time Selection: Only imported driver packages are included in the binary

Benefits

• Extensibility: Add new drivers without touching registry code
• Modularity: Each driver is self-contained in its own package
• Flexible Compilation: Control which drivers to include via imports
• Thread-Safe: Registry uses mutex protection for concurrent access

Adding New Drivers

To add support for a new cluster driver:

1. Create a new package under internal/cluster/<driver-name>/

2. Implement the cluster.Manager interface:

   type Driver struct {
       // driver-specific fields
   }
   
   func (d *Driver) Start(ctx context.Context, cfg config.ClusterConfig) error
   func (d *Driver) Stop(ctx context.Context) error
   func (d *Driver) Status(ctx context.Context) (*cluster.Status, error)
   

3. Register in init() function:

   func init() {
       cluster.RegisterDriver("driver-name", func(profileName string) cluster.Manager {
           return NewDriver(profileName)
       })
   }
   

4. Add comprehensive tests

5. Import in main package to enable the driver:

   import _ "path/to/your/driver"
   

Example: New Driver Layout

internal/cluster/
├── registry.go         # Driver registry
├── interface.go        # Manager interface definition
├── errors.go           # Common errors
├── auto/               # Auto-detection driver (selects colima or k3d by OS)
│   ├── driver.go
│   └── driver_test.go
├── colima/
│   ├── driver.go       # Colima implementation
│   └── driver_test.go
├── k3d/
│   ├── driver.go       # k3d implementation
│   └── driver_test.go
└── mock/               # Test-only mock driver
    ├── driver.go
    └── driver_test.go

k3d/driver.go:

package k3d

import (
    "context"
    "gitlab.com/gitlab-org/caproni/internal/cluster"
    "gitlab.com/gitlab-org/caproni/internal/config"
)

func init() {
    // Auto-register on import
    cluster.RegisterDriver("k3d", func(profileName string) cluster.Manager {
        return NewDriver(profileName)
    })
}

type Driver struct {
    profileName string
}

func NewDriver(profileName string) *Driver {
    return &Driver{profileName: profileName}
}

func (d *Driver) Start(ctx context.Context, cfg config.ClusterConfig) error {
    // Implementation
}

func (d *Driver) Stop(ctx context.Context) error {
    // Implementation
}

func (d *Driver) Status(ctx context.Context) (*cluster.Status, error) {
    // Implementation
}

Future Enhancements

Potential additions to the cluster management interface:

• Restart(ctx context.Context) error - Restart the cluster
• Version(ctx context.Context) (string, error) - Get Kubernetes version
• Exec(ctx context.Context, cmd string) error - Execute command in cluster
• Profile management (list, delete profiles)
• Resource usage monitoring
• Health checks and diagnostics