pkg/

Package Documentation

This directory contains reusable Go packages that implement the core functionality of iknite.

Package Overview

Core Packages

alpine/

Alpine Linux specific utilities for managing services, kernel modules, and IP addresses.

Key functionality:

• IP address management (ip.go)
• OpenRC service control (service.go)
• Kernel module loading (modules.go)

provision/

Cluster provisioning and initialization logic.

Key functionality:

• Base provisioning workflow (base.go)
• Common provisioning utilities (common.go)

k8s/

Kubernetes cluster management and operations.

Key functionality:

• Cluster lifecycle management
• Kubeadm integration
• Resource application and monitoring

API Packages

apis/

Kubernetes API definitions and custom resource types.

Structure:

• iknite/v1alpha1/ - Iknite v1alpha1 API
  • types.go - API type definitions
  • defaults.go - Default values
  • register.go - API registration
  • zz_generated.* - Generated code (client, deepcopy, etc.)

Note: Generated code is created by hack/update-codegen.sh.

Command Packages

cmd/

CLI command implementations using Cobra.

Key commands:

• start.go - Start the Kubernetes cluster
• init.go - Initialize cluster configuration
• root.go - Root command and global flags
• options/ - Command-line options and flags

Utility Packages

config/

Configuration management and parsing.

Functionality:

• Load and parse configuration files
• Merge configuration from multiple sources
• Validate configuration

constants/

Project-wide constants and defaults.

Contains:

• Version information
• Default values
• File paths and directories

cri/

Container Runtime Interface (CRI) utilities.

Functionality:

• CRI client management
• Container runtime interaction
• Image management

utils/

General-purpose utilities.

Key functionality:

• Command execution (executor.go)
• Common helper functions (common.go)

testutils/

Testing utilities and helpers.

Purpose:

• Shared test fixtures
• Test helper functions
• Mock implementations

Package Guidelines

Import Paths

All packages use the base import path:

import "github.com/kaweezle/iknite/pkg/<package>"

Example:

import (
    "github.com/kaweezle/iknite/pkg/alpine"
    "github.com/kaweezle/iknite/pkg/k8s"
)

Package Organization

Packages follow these principles:

1. Single Responsibility: Each package has a clear, focused purpose
2. No Circular Dependencies: Packages do not import each other in cycles
3. Minimal External Dependencies: Prefer standard library when possible
4. API Stability: Public APIs should be stable and well-documented

Visibility Rules

• Exported (public): Capitalized names are part of the public API
• Unexported (private): Lowercase names are internal implementation

Example:

// Public - can be used by other packages
func StartCluster() error { ... }

// Private - only used within this package
func parseConfig() (*Config, error) { ... }

Package Dependencies

Dependency Graph

cmd/
  └── imports: alpine, k8s, provision, config, constants

k8s/
  └── imports: cri, utils, constants

provision/
  └── imports: k8s, alpine, cri, utils

alpine/
  └── imports: utils (minimal external dependencies)

utils/
  └── imports: (standard library only)

External Dependencies

Major external dependencies (see go.mod):

• Kubernetes: k8s.io/client-go, k8s.io/api, k8s.io/apimachinery
• CLI: github.com/spf13/cobra, github.com/spf13/viper
• Logging: github.com/sirupsen/logrus
• Testing: github.com/stretchr/testify

Testing

Running Tests

Run all package tests:

go test ./pkg/...

Run specific package:

go test ./pkg/alpine/...
go test ./pkg/k8s/...

Run with coverage:

go test -coverprofile=coverage.out ./pkg/...
go tool cover -html=coverage.out

Test Files

Test files follow Go conventions:

• Named *_test.go
• Located alongside source files
• Use testutils/ for shared test utilities

Example:

pkg/alpine/
├── ip.go
├── ip_test.go        ← Tests for ip.go
├── service.go
└── service_test.go   ← Tests for service.go

Code Generation

Some packages contain generated code:

apis/iknite/v1alpha1/zz_generated.*

Generated by Kubernetes code-generator:

./hack/update-codegen.sh

Never edit these files manually. Regenerate after API changes.

Documentation

Package Documentation

Each package should have a doc comment:

// Package alpine provides utilities for Alpine Linux system management.
// It includes functions for IP address management, OpenRC service control,
// and kernel module loading.
package alpine

Function Documentation

Public functions must be documented:

// StartService starts an OpenRC service by name.
// It returns an error if the service fails to start.
func StartService(name string) error { ... }

Godoc

View package documentation:

godoc -http=:6060
# Open http://localhost:6060/pkg/github.com/kaweezle/iknite/pkg/

Adding New Packages

When adding a new package:

1. Choose appropriate location: Place under pkg/
2. Create package directory: pkg/newpackage/
3. Add package documentation: Doc comment at top of main file
4. Write tests: Add *_test.go files
5. Update this README: Document the new package
6. Check dependencies: Avoid circular imports

Example:

mkdir -p pkg/newpackage
cat > pkg/newpackage/newpackage.go <<EOF
// Package newpackage provides functionality for...
package newpackage

// NewFunction does something useful.
func NewFunction() error {
    return nil
}
EOF

cat > pkg/newpackage/newpackage_test.go <<EOF
package newpackage

import "testing"

func TestNewFunction(t *testing.T) {
    err := NewFunction()
    if err != nil {
        t.Errorf("NewFunction() error = %v", err)
    }
}
EOF

Common Patterns

Error Handling

if err != nil {
    return fmt.Errorf("failed to start service: %w", err)
}

Logging

import log "github.com/sirupsen/logrus"

log.WithFields(log.Fields{
    "service": name,
}).Info("Starting service")

Configuration

import "github.com/kaweezle/iknite/pkg/config"

cfg, err := config.Load()
if err != nil {
    return err
}

Related Documentation

• STRUCTURE.md - Overall project structure
• BUILD.md - Build process
• CONTRIBUTING.md - Contribution guidelines
• Go Package Layout