Skip to content

jpackagejasonc/kina

BranchesTags
 
 

Repository files navigation

kina - Kubernetes in Apple Container

CI License: MIT OR Apache-2.0 Rust Apple Container

kina is a Rust CLI tool for running local Kubernetes clusters using Apple Container technology. It provides similar functionality to kind (Kubernetes in Docker) but is optimized for macOS systems, leveraging native Apple Container technology for improved performance and integration.

📖 New to kina? Follow the complete installation and quick start guide below.

Table of Contents

Features

  • 🏗️ Native Apple Container Integration - Leverage macOS container technology for optimal performance
  • ☸️ Kubernetes API Compatibility - Full Kubernetes cluster functionality with kubectl integration
  • 🌐 CNI Plugin Support - PTP networking optimized for Apple Container, with a generic plugin selection surface for future options
  • 🔧 Traefik (Gateway API) - Built-in support for Traefik gateway controller installation and configuration
  • 📊 Metrics Server - Built-in support for Kubernetes Metrics Server installation (enables kubectl top and HPA)
  • ⚙️ Flexible Configuration - TOML-based configuration with sensible defaults
  • 📋 Comprehensive CLI - Rich command set for cluster management and operations
  • 🚀 Development Ready - Integrated development workflow with mise task automation

Requirements

System Requirements

  • macOS: 26+ (macOS 15.6 may work with limitations)
  • Apple Container: 0.5.0+ (auto-detected and validated at startup)
  • Rust: 1.70+ (for building from source)

Apple Container Installation

Apple Container is required for kina to work. Install it first:

Option A — Homebrew (recommended):

brew install container
brew services start container

# OR start the container system directly without brew
container system start

Option B — Manual:

  1. Download: Get the latest installer from Apple Container Releases
  2. Install: Double-click the .pkg file and follow the installer prompts
  3. Start Service: Run container system start to start the API server

Verify: Check installation with container --version

Note: kina requires Apple Container 0.5.0 or later. The version is automatically detected and validated when kina starts. Run kina (no arguments) to see your kina and Apple Container versions.

Kubernetes Tools

  • kubectl - Kubernetes command-line tool
  • kubectx & kubens - Context and namespace management (optional)

Development Tools (Optional)

  • mise - Development environment manager with task automation

Installation

Option 1: From Source (Recommended)

# Clone the repository
git clone https://github.com/vinnie357/kina.git
cd kina

# Install using Cargo
cargo install --path kina-cli

# OR using mise (if installed)
mise run kina:install

Option 2: Development Setup with mise

# Clone the repository
git clone https://github.com/vinnie357/kina.git
cd kina

# Build and install
mise run install

Verification

# Verify installation (shows kina and Apple Container versions)
kina

# Check Apple Container availability (REQUIRED, 0.5.0+)
mise run container:check  # If using mise
# OR manually check:
container --version
container system start  # Start the service if not running

kubectl version --client

⚠️ Important: Apple Container 0.5.0+ must be available before creating clusters. kina auto-detects and validates the version at startup. Run kina status to see Apple Container version information.

Quick Start

Create Your First Cluster

# Create a cluster with default settings
kina create my-cluster

# Export kubeconfig to connect with kubectl
kina export my-cluster --format kubeconfig --output ~/.kube/my-cluster
export KUBECONFIG=~/.kube/my-cluster

# Verify cluster is working
kubectl get nodes

Advanced Options:

# Create cluster with explicit CNI selection and wait for readiness
kina create demo --cni ptp --wait 300

Install Traefik (Gateway API)

# Install Traefik gateway controller to your cluster
kina install traefik --cluster my-cluster

This installs the Gateway API CRDs (v1.5.1, standard channel), the Traefik DaemonSet, a traefik GatewayClass, and a shared Gateway named traefik (listening on :80 and :443) in the traefik namespace. Apps in any namespace can attach HTTPRoutes to it.

Check Cluster Status

# Basic status
kina status my-cluster

# Detailed status with pods and services
kina status my-cluster --verbose

Integration Test Cluster

Option A: Using mise (if installed)

# Create an integration test cluster with Traefik and demo app
mise run test:cluster

# Validate the most recent test cluster
mise run test:cluster:validate

# Clean up all test clusters (removes clusters with 'demo-' prefix)
mise run test:cluster:cleanup

Option B: Manual setup (without mise)

# Create cluster with Traefik
kina create demo-cluster --wait 300
kina install traefik --cluster demo-cluster

# Check status
kina status demo-cluster --verbose

The demo cluster setup creates:

  • A timestamped cluster (e.g., demo-20241228-143022)
  • Traefik gateway controller installation and configuration
  • A sample web application with 2 replicas
  • Gateway API HTTPRoute for browser/curl access
  • Complete Apple Container networking setup

Verify Your Setup

After creating your first cluster, verify everything works:

# Check cluster status
kina status my-cluster

# List all pods (should show running status)
kubectl --kubeconfig ~/.kube/my-cluster get pods -A

# Verify nodes are ready
kubectl --kubeconfig ~/.kube/my-cluster get nodes

Troubleshooting: If cluster creation fails, check:

  • Apple Container CLI is available: container --version
  • Sufficient system resources (2GB+ RAM recommended)
  • Try with --retain flag to debug: kina create test-cluster --retain

Command Reference

Cluster Management

# Create a new cluster
kina create [NAME] [OPTIONS]
  --image TEXT           Container image (default: kina/node:v1.35.5)
  --config FILE          Cluster configuration file
  --wait SECONDS         Wait for cluster readiness
  --retain               Retain cluster on failure
  --cni ptp              CNI plugin (default: ptp)

# Delete a cluster
kina delete [NAME]
kina delete --all      # Delete all clusters

# List clusters
kina list              # Simple list
kina list --verbose    # Detailed information

# Show cluster status
kina status [NAME] [OPTIONS]
  --verbose              Show detailed information
  --output table|yaml|json

Resource Operations

# Get cluster information
kina get clusters [NAME]
kina get kubeconfig [NAME]
kina get nodes [NAME]

# Load container images
kina load IMAGE --cluster NAME

# Export configurations
kina export [NAME] [OPTIONS]
  --format kubeconfig|config
  --output FILE

Addon Management

# Install addons
kina install traefik --cluster NAME
kina install metrics-server --cluster NAME

Cluster Operations

# Approve kubelet Certificate Signing Requests
kina approve-csr [NAME]

# Configuration management
kina config show
kina config set KEY VALUE
kina config get KEY
kina config reset
kina config path

Configuration

Configuration File Location

kina uses TOML configuration files located at:

~/.config/kina/config.toml

Default Configuration

[cluster]
default_name = "kina"
default_image = "kina/node:v1.35.5"
default_wait_timeout = 300
data_dir = "~/.local/share/kina"
retain_on_failure = false
default_cni = "ptp"

[apple_container]
cli_path = null  # Auto-detected

[apple_container.runtime_config]
cpu_limit = null
memory_limit = "2Gi"
storage_limit = "20Gi"

[apple_container.network]
network_name = "kina"
enable_ipv6 = false
dns_servers = []

[kubernetes]
default_version = "v1.35.5"
kubectl_path = null  # Auto-detected
default_namespace = "default"
kubeconfig_dir = "~/.config/kina/kubeconfig"

[logging]
level = "info"
format = "text"
file_logging = false
log_dir = null

Environment Variables

export RUST_LOG="info"
export RUST_BACKTRACE="1"

Apple Container Integration

kina leverages Apple Container technology for running Kubernetes nodes:

Container Management

  • Native Integration: Uses Apple Container CLI for container lifecycle
  • Resource Limits: Configurable CPU, memory, and storage limits
  • Network Integration: Seamless integration with macOS networking
  • DNS Support: Automatic DNS configuration for cluster access

Cluster Architecture

┌─────────────────────────────────────────┐
│               macOS Host                │
│  ┌─────────────────────────────────────┐ │
│  │        Apple Container VM           │ │
│  │  ┌─────────────────────────────────┐ │ │
│  │  │     Kubernetes Node             │ │ │
│  │  │  • kubelet                      │ │ │
│  │  │  • containerd                   │ │ │
│  │  │  • CNI (PTP)                    │ │ │
│  │  └─────────────────────────────────┘ │ │
│  └─────────────────────────────────────┘ │
└─────────────────────────────────────────┘

CNI Support

PTP CNI (Default)

  • Compatibility: Optimized for Apple Container
  • Simplicity: Point-to-point networking with host-local IPAM
  • Performance: Minimal overhead for single-node clusters
# Create cluster with specific CNI
kina create test-ptp --cni ptp

Development

Development Environment Setup

kina uses mise for development environment management and task automation. This provides consistent tooling and streamlined workflows.

# Install all tools via mise
mise install

# Verify Apple Container CLI availability
mise run container:check

Node Image Building

kina requires custom Kubernetes node images optimized for Apple Container. These images contain the necessary components for running Kubernetes nodes in Apple Container VMs.

# Build custom kina node image
mise run image:build

# Test the built node image
mise run image:test

# Build and test in one command
mise run image:validate

# List available images
mise run image:list

# Clean up unused images
mise run image:clean

Node Image Components:

  • Base System: Debian (13-slim) with systemd for container orchestration
  • Container Runtime: containerd configured for Apple Container integration
  • Kubernetes Components: kubelet, kubeadm, kubectl (v1.35.5)
  • CNI Plugins: PTP support
  • Init Scripts: Apple Container-specific initialization and networking setup

The built images are tagged as kina/node:v1.35.5 and can be used with:

kina create my-cluster --image kina/node:v1.35.5

Pre-commit and Secret Scanning

mise run pre-commit runs formatting, linting, tests, audit, and gitleaks secret scanning before each commit. Gitleaks is also available standalone:

mise run gitleaks                # Run gitleaks secret scanner

Common Development Tasks

# Build and install
mise run build                   # Release build
mise run dev                     # Development build
mise run test                    # Run tests
mise run kina:install            # Install kina CLI from project root
mise run pre-commit              # Format, lint, test, audit, gitleaks
mise run ci                      # Run full CI pipeline locally
mise run release                 # Build optimized release binary

# Code quality
mise run fmt                     # Format code with rustfmt
mise run lint                    # Run clippy with strict settings
mise run audit                   # Security audit with cargo-audit
mise run check                   # Check code without building
mise run gitleaks                # Secret scanning with gitleaks

# Documentation and utilities
mise run docs                    # Generate and open documentation
mise run clean                   # Clean build artifacts
mise run watch                   # Watch files and rebuild on changes
mise run bench                   # Run benchmarks

# CLI testing
mise run kina -- create test     # Run kina with arguments (release build)
mise run kina:dev -- --help      # Run kina in dev mode (faster build)
mise run test:cli                # Basic CLI functionality tests

# Available tasks
mise tasks                       # List all available mise tasks

# Integration testing workflows
mise run test:cluster            # Create test cluster with Traefik and demo app
mise run test:cluster:validate   # Validate most recent test cluster
mise run test:cluster:cleanup    # Clean up all test clusters

Project Structure

kina/
├── kina-cli/                   # Main CLI application
│   ├── src/
│   │   ├── cli/               # Command implementations
│   │   ├── config/            # Configuration management
│   │   ├── core/              # Core cluster management
│   │   └── main.rs            # Application entry point
│   ├── tests/                 # Integration tests
│   ├── manifests/             # Kubernetes manifests
│   ├── images/                # Custom node image Dockerfile
│   └── Cargo.toml
├── scripts/                    # Extracted mise task scripts (Nushell)
├── docs/                       # Documentation
├── CLAUDE.md                   # AI assistant context
├── mise.toml                   # Development automation
├── Cargo.toml                  # Workspace configuration
└── README.md

Troubleshooting

Common Issues

Apple Container Not Found

# Check Apple Container installation
container --version

# Start the Apple Container service if needed
container system start

# Check if service is running
container system status

# Verify PATH configuration
echo $PATH | grep container

Solution: If Apple Container is not found, install it via Homebrew (brew install container) or from Apple Container Releases. If installed but not working, restart the service with container system restart.

Cluster Creation Fails

# Check cluster status
kina status my-cluster --verbose

# Enable verbose logging
RUST_LOG=debug kina create my-cluster --retain

# Manual cleanup
kina delete my-cluster

Kubeconfig Issues

# Check kubeconfig location
kina config path
ls ~/.kube/

# Regenerate kubeconfig
kina export my-cluster --output ~/.kube/my-cluster
export KUBECONFIG=~/.kube/my-cluster

CNI Readiness Issues

# Approve pending CSRs
kina approve-csr my-cluster

# Check node readiness
kubectl get nodes

Debug Commands

# Comprehensive cluster status
kina status my-cluster --verbose --output yaml

# Container inspection
container list
container inspect CONTAINER_NAME

# Kubernetes debugging
kubectl get events --sort-by='.lastTimestamp'
kubectl describe nodes

Getting Help

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

  1. Fork and Clone: Fork the repository and clone your fork
  2. Setup Environment: Run mise install to install all tools
  3. Create Branch: Create a feature branch for your changes
  4. Develop: Make changes with comprehensive tests
  5. Quality Checks: Run mise run pre-commit before committing (includes gitleaks)
  6. Submit PR: Create a pull request with clear description

Code Quality

  • Formatting: mise run fmt (rustfmt)
  • Linting: mise run lint (clippy with strict settings)
  • Testing: mise run test (comprehensive test suite)
  • Security: mise run audit (cargo-audit dependency scanning)

License

Licensed under either of:

at your option.

Note: kina is in active development. While functional, some features are still being implemented. See the project roadmap for current status and planned features.

About

kubernetes in apple container based on kind

Resources

Readme

License

Unknown, MIT licenses found

Licenses found

Unknown
LICENSE-APACHE
MIT
LICENSE-MIT

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Rust 84.5%
  • Nushell 11.2%
  • Shell 2.3%
  • Dockerfile 2.0%