Project Structure

Understanding the k8s-provisioner codebase

Directory Layout

k8s-provisioner/
├── cmd/                    # CLI commands
│   ├── root.go             # Root command and flags
│   ├── provision.go        # Provision subcommands
│   ├── status.go           # Status command
│   ├── user.go             # User management commands
│   └── vbox.go             # VirtualBox management
├── internal/
│   ├── config/             # YAML config parser
│   │   └── config.go       # Configuration structs
│   ├── executor/           # Shell command executor
│   │   └── executor.go     # Command execution helpers
│   ├── installer/          # Component installers
│   │   ├── calico.go       # Calico CNI
│   │   ├── metallb.go      # MetalLB LoadBalancer
│   │   ├── istio.go        # Istio Service Mesh
│   │   ├── monitoring.go   # Prometheus + Grafana
│   │   ├── metrics.go      # Metrics Server
│   │   ├── nfs_provisioner.go  # NFS Dynamic Provisioner
│   │   ├── karpor.go       # Karpor Explorer
│   │   └── ollama.go       # Ollama AI Backend
│   └── provisioner/        # Main provisioning logic
│       └── provisioner.go  # Orchestrates installation
├── vagrant/                # Vagrant configuration
│   ├── Vagrantfile         # VM definitions
│   ├── settings.yaml       # VM settings (IPs, RAM, CPUs)
│   └── clean.sh            # Cleanup script
├── examples/               # Example manifests
│   ├── nfs-pv-pvc.yaml     # NFS storage examples
│   ├── podinfo-app.yaml    # Podinfo with Istio
│   └── karpor-usage.md     # Karpor usage guide
├── build/                  # Compiled binaries (gitignored)
├── config.yaml             # Cluster configuration
├── go.mod                  # Go module definition
├── go.sum                  # Go dependencies
├── main.go                 # Entry point
├── Makefile                # Build targets
├── VERSION                 # Current version
└── README.md               # Project documentation

Key Components

cmd/ - CLI Layer

Uses Cobra for CLI structure:

FileDescription
root.goMain command, global flags
provision.goprovision common, controlplane, worker, all
status.goCluster status display
user.goUser create, list, delete
vbox.goVirtualBox promiscuous mode

internal/config/ - Configuration

Parses config.yaml into Go structs:

type Config struct {
    Cluster    ClusterConfig
    Versions   VersionsConfig
    Network    NetworkConfig
    Storage    StorageConfig
    Nodes      []NodeConfig
    Components ComponentsConfig
    KarporAI   KarporAIConfig
    Ollama     OllamaConfig
}

internal/installer/ - Component Installers

Each component has its own installer:

InstallerComponent
calico.goCalico CNI
metallb.goMetalLB + IP Pool
istio.goIstio + Ingress Gateway
monitoring.goPrometheus Operator + Grafana + Loki
metrics.goMetrics Server
nfs_provisioner.goNFS Dynamic Provisioner
karpor.goKarpor + Helm
ollama.goOllama + Model Pull

internal/provisioner/ - Orchestration

provisioner.go orchestrates the installation order:

  1. Common packages (CRI-O, kubeadm, kubelet)
  2. Control plane initialization
  3. CNI (Calico)
  4. LoadBalancer (MetalLB)
  5. Service Mesh (Istio)
  6. Metrics Server
  7. NFS Provisioner
  8. Monitoring Stack
  9. Karpor + Ollama (if enabled)

Building

Prerequisites

  • Go 1.22+
  • Make

Build Commands

# Install dependencies
make deps

# Build for current platform
make build

# Build for all platforms
make build-all

# Build for specific platform
make build-darwin-arm64
make build-linux-amd64
make build-windows-amd64

# Run tests
make test

# Run linter
make lint

# Show current version
make version

Output Binaries

Binaries are placed in build/:

BinaryPlatform
k8s-provisioner-darwin-arm64macOS Apple Silicon
k8s-provisioner-darwin-amd64macOS Intel
k8s-provisioner-linux-arm64Linux ARM64
k8s-provisioner-linux-amd64Linux x64
k8s-provisioner-windows-amd64.exeWindows x64