k8s-kitchen 0.2.0

Your Kubernetes cookbook for cluster management

Kitchen

Your Kubernetes cookbook for cluster management and operations.

Kitchen is a command-line tool designed to simplify Kubernetes cluster management. It provides easy-to-use commands for adding nodes, managing clusters, and performing common K8s operations.

Installation

Install using Poetry:

poetry install

Quick Start

1. Check Your Setup

kitchen setup

This checks for required tools and shows your Tailscale status.

2. Configure Your Cluster

First, set up your master node configuration:

# Initialize master node config
kitchen k8s config init --hostname master-01 \
  --ip 192.168.1.10 \
  --ip 100.64.1.5 \
  --version 1.29 \
  --cluster production

# Save cluster secrets (you'll be prompted for values)
kitchen k8s config set-secrets --cluster production

# Verify configuration
kitchen k8s config show

3. Add Worker Nodes

Step 1: Check the node

kitchen k8s node check --role worker --host user@192.168.1.100 --verbose

Step 2: Prepare the node

kitchen k8s node prepare --role worker --host user@192.168.1.100

This installs:

• Tailscale (if configured in secrets)
• CRI-O container runtime
• Kubernetes components (kubelet, kubeadm, kubectl)

Step 3: Join the node to your cluster

kitchen k8s node join --host user@192.168.1.100 --cluster production --verbose

4. View Available Commands

kitchen cookbook

This shows common recipes and usage examples.

Core Features

Cluster Configuration Management

# Initialize master node configuration
kitchen k8s config init --hostname master-01 --ip 192.168.1.10 --ip 100.64.1.5

# Save cluster secrets (join token, discovery hash, Tailscale auth key)
kitchen k8s config set-secrets --cluster my-cluster

# Show current master configuration
kitchen k8s config show

# List all configured clusters
kitchen k8s config list

# Set default cluster
kitchen k8s config set-default my-cluster

Node Management

# Run pre-flight checks on a node
kitchen k8s node check --role worker --host user@192.168.1.100 --verbose

# Prepare a node (install components)
kitchen k8s node prepare --role worker --host user@192.168.1.100 --phases tailscale,container-runtime,kube-components

# Join a worker node to the cluster
kitchen k8s node join --host user@worker-node --cluster my-cluster --verbose

# Add a node (interactive workflow - WIP)
kitchen k8s node add --master user@master-node --target user@worker-node

Available Component Phases:

• tailscale - Install and configure Tailscale for secure networking
• container-runtime - Install CRI-O container runtime
• kube-components - Install kubectl, kubelet, and kubeadm
• apiserver-cert - Configure API server certificates (master only)

The check and prepare commands accept --phases to target specific components. If omitted, sensible defaults are used based on the node role.

Tailscale Integration

Kitchen integrates with Tailscale for secure, mesh networking between Kubernetes nodes:

Benefits:

• 🔒 Secure: End-to-end encrypted mesh network
• 🌐 Easy: No complex firewall rules or VPN setup
• 📱 Accessible: Access your cluster from anywhere
• 🏷️ Named: Use friendly hostnames instead of IPs

How Kitchen Uses Tailscale:

• Kitchen can install and configure Tailscale on nodes during the prepare phase
• Automatically detects Tailscale IPs for kubelet node-ip configuration
• Uses Tailscale for secure API server communication
• Prefers Tailscale endpoints when joining nodes to the cluster

Configuration: Save your Tailscale auth key in cluster secrets:

kitchen k8s config set-secrets --cluster my-cluster
# You'll be prompted for the Tailscale auth key

Node Manager

# Deploy node manager to Kubernetes
kitchen node-manager deploy

# Check node manager status
kitchen node-manager status

# View node manager logs
kitchen node-manager logs --follow

# Access node manager API
kitchen node-manager api --port 8000

Utility Commands

# Run any command
kitchen run kubectl get pods

# Show Kitchen version
kitchen version

# View the cookbook
kitchen cookbook

Prerequisites

Kitchen requires these tools to be installed:

Required (for local machine):

• kubectl - Kubernetes command-line tool (for cluster interaction)
• kubeadm - Kubernetes cluster management (if setting up locally)
• docker - Container runtime (for local development, not required for remote node setup)

Recommended:

• tailscale - Secure mesh networking (highly recommended)
• ssh - Remote access to nodes
• sshpass - For password-based SSH automation

Note: Kitchen automatically installs CRI-O (container runtime) and Kubernetes components on remote nodes during the prepare phase. You don't need to pre-install these on worker nodes.

Run kitchen setup to check your installation and see Tailscale status.

Development

Setup Development Environment

# Install dependencies
poetry install

# Run CLI in development
poetry run kitchen --help

# Run with verbose output
poetry run kitchen --verbose k8s config show

UI

Build the Vite UI from the repository root with:

npm install npm run build

Then build the node-manager image; the Docker build expects dist/kitchen-ui to exist and will copy it into the image so the UI can be served from /ui.

Project Structure

src/kitchen/
├── main.py              # Main CLI entry point
├── ssh.py               # SSH session management
├── config/              # Configuration management
├── k8s/                 # Kubernetes operations
│   ├── main.py         # K8s CLI commands
│   ├── handlers/       # Component handlers (Tailscale, CRI-O, etc.)
│   ├── nodes/          # Pre-flight checks
│   ├── master.py       # Master node operations
│   └── worker.py       # Worker node operations
└── node_manager/       # Node monitoring service
    ├── api/            # FastAPI endpoints
    ├── cli.py          # Node manager CLI
    └── manifests/      # Kubernetes manifests

Running Tests

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=kitchen

Roadmap

• ✅ Node pre-flight checks (validate requirements before setup)
• ✅ Node preparation (automated CRI-O and Kubernetes component installation)
• ✅ Worker node joining with Tailscale support
• ✅ Cluster configuration management (multi-cluster support)
• ✅ Node manager with FastAPI and connectivity tracking
• ✅ Tailscale integration (automated installation and configuration)
• ✅ CRI-O container runtime support
• 🚧 Complete node addition workflow (interactive end-to-end)
• 🚧 Master node initialization
• 🚧 Node removal and cleanup
• 🚧 Cluster backup and restore

Troubleshooting

Common Issues

SSH Connection Issues

• Ensure SSH key permissions are correct: chmod 600 ~/.ssh/id_rsa
• Test SSH connection manually: ssh user@host
• Use --verbose flag for detailed connection logs

Node Join Failures

• Verify master config is set: kitchen k8s config show
• Check cluster secrets are saved: kitchen k8s config show-secrets
• Ensure all phases are prepared: kitchen k8s node check --role worker --host user@node
• Review join logs with --verbose flag

Tailscale Issues

• Verify Tailscale is running: tailscale status
• Check auth key is set in secrets: kitchen k8s config show-secrets
• Manually test Tailscale connectivity: ping 100.64.x.x

Container Runtime Issues

• Check CRI-O status: systemctl status crio
• View CRI-O logs: journalctl -u crio -f
• Verify container runtime socket: crictl info

Getting Help

• Run any command with --help for detailed usage
• Use --verbose flag for debugging
• Check the cookbook: kitchen cookbook
• Review command history in .github/history/ for development context

Contributing

Kitchen is designed to be your personal Kubernetes cookbook. Feel free to extend it with your own recipes and automation!

Development Guidelines:

• Follow existing code structure and patterns
• Add type hints to all functions
• Keep line length to 120 characters (use # fmt: skip for long strings)
• Use named constants instead of magic numbers
• Write comprehensive error messages with actionable suggestions