Building a Kubernetes Homelab from Scratch: A Complete Guide

Setting up your own Kubernetes cluster at home has never been easier. Today I'll walk you through creating a complete homelab setup that gives you a production-like environment for learning and development, all running on a single Ubuntu server.

What We're Building

By the end of this guide, you'll have:

• A dedicated Ubuntu server running Kubernetes

• A development environment with all the tools you need

• A web dashboard to manage your cluster

• The ability to deploy and manage applications

The Hardware Setup

For this project, I used a small PC that I had lying around. Really, any computer that can run Ubuntu will work fine. Here's what you need:

• A small PC or even a Raspberry Pi

• At least 4GB RAM (8GB+ recommended)

• 50GB+ storage space

• Network connection

I installed Ubuntu Server 24.04 LTS with just the SSH server option. No GUI needed since everything runs headlessly.

Architecture Overview

Here's how everything fits together:

graph TB
    A[Your Mac/Laptop] -->|SSH + kubectl| B[Ubuntu Server]
    A -->|Web Browser| C[Kubernetes Dashboard]

    subgraph "Ubuntu Server (10.0.0.20)"
        B --> D[Development Tools]
        B --> E[Docker]
        B --> F[MicroK8s Cluster]

        D --> D1[Zsh + Oh My Zsh]
        D --> D2[Node.js via NVM]
        D --> D3[Vim + Tmux]

        F --> F1[DNS Addon]
        F --> F2[Storage Addon]
        F --> F3[Ingress Controller]
        F --> F4[Container Registry]
        C --> F5[Dashboard Addon]
    end

Step 1: Initial Server Setup

First, I set up SSH access from my Mac to the Ubuntu server. This involved copying my SSH public key to the server so I could connect without typing passwords every time.

# Copy your SSH key to the server
ssh-copy-id -i ~/.ssh/id_ed25519.pub chattes@10.0.0.20

# Test passwordless connection
ssh chattes@10.0.0.20

I also configured the server user to have passwordless sudo access, which makes automation much easier:

# Add user to sudoers without password
echo "chattes ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers

Step 2: Automating Everything with Ansible

Rather than installing everything manually, I created an Ansible playbook that automates the entire setup. This approach has several benefits:

• Reproducible: I can recreate the exact same environment on any Ubuntu server

• Version controlled: All configurations are stored in Git

• Shareable: Others can use the same setup

• Maintainable: Easy to update or modify the configuration

The Ansible project structure looks like this:

k8s-homelab-setup/
├── ansible.cfg
├── inventory/hosts.yml
├── playbooks/setup-k8s-homelab.yml
├── roles/
│   ├── common/          # Basic system setup
│   ├── dev-tools/       # Development environment
│   └── kubernetes/      # Kubernetes installation
└── Makefile            # Convenience commands

Step 3: Development Environment Setup

The automation installs a complete development environment:

Shell and Terminal Tools

• Zsh with Oh My Zsh: A modern shell with great autocompletion and themes

• Tmux: Terminal multiplexer for managing multiple sessions

• Vim: Configured with sensible defaults for editing

Node.js Development

• NVM: Node Version Manager for easily switching Node.js versions

• Node.js LTS: The latest long-term support version

• Global packages: nodemon, pm2, yarn, TypeScript, and other useful tools

Container Development

• Docker: For building and running containers

• Proper permissions: User added to docker group for sudo-free usage

Step 4: Kubernetes with MicroK8s

For the Kubernetes setup, I chose MicroK8s because it's:

• Easy to install: Single snap package

• Lightweight: Perfect for single-node setups

• Feature complete: Includes all the addons you need

• Production ready: Same Kubernetes you'd use in production

The setup automatically enables these essential addons:

• DNS: For service discovery within the cluster

• Storage: Persistent volumes for your applications

• Ingress: Smart routing for external access to services

• Dashboard: Web UI for managing the cluster

• Registry: Local container registry for your images

Step 5: Accessing Your Cluster

Once everything is installed, you can interact with your Kubernetes cluster in two ways:

Command Line Access

I set up kubectl on my Mac so I can control the cluster remotely:

# Download the kubeconfig from the server
scp chattes@10.0.0.20:~/.kube/config ~/.kube/config

# Now you can control your cluster from your Mac
kubectl get nodes
kubectl get pods --all-namespaces

Web Dashboard

The Kubernetes dashboard provides a nice visual interface. I configured it to run persistently using a systemd service, so it's always available at https://10.0.0.20:8443.

For authentication, you can use either:

• Kubeconfig file: Upload the same config file kubectl uses

• Access token: Generate temporary tokens for access

# Generate a 24-hour access token
kubectl -n kube-system create token admin-user --duration=24h

What You Can Do Now

With this setup complete, you have a professional-grade Kubernetes environment where you can:

Learn Kubernetes Concepts

• Deploy applications using manifests

• Experiment with services, ingress, and storage

• Practice troubleshooting and debugging

Develop Applications

• Build Node.js applications locally

• Containerize them with Docker

• Deploy them to your Kubernetes cluster

Test Production Scenarios

• Set up multiple environments (dev, staging)

• Practice CI/CD workflows

• Test scaling and load balancing

Real World Example

Here's how you might deploy a simple Node.js application:

# Create a simple deployment
kubectl create deployment hello-app --image=node:alpine

# Expose it as a service
kubectl expose deployment hello-app --port=3000 --type=NodePort

# Check your deployment
kubectl get pods
kubectl get services

The Power of Infrastructure as Code

The best part about this approach is that everything is automated and reproducible. If I need to rebuild the server or set up additional nodes, I just run:

make setup

And in about 20 minutes, I have a completely configured Kubernetes environment.

Cost and Requirements

This entire setup runs on:

• Hardware: Any old PC or even a Raspberry Pi 4

• Software: All open source and free

• Network: Just needs internet access for downloads

• Maintenance: Minimal, mostly automated

What's Next

Now that you have a working Kubernetes homelab, here are some ideas for next steps:

• Deploy real applications: Try running a database, web server, or API

• Set up monitoring: Add Prometheus and Grafana for observability

• Practice GitOps: Use tools like ArgoCD for automated deployments

• Add more nodes: Scale your cluster across multiple machines

• Experiment with operators: Try operators for databases or other services

Wrapping Up

Building a Kubernetes homelab gives you hands-on experience with the same tools used in production environments. The automated setup means you can focus on learning Kubernetes concepts rather than fighting with configuration issues.

The combination of Ansible for automation, MicroK8s for Kubernetes, and a thoughtful development environment creates a platform that's both educational and practical. Whether you're just starting with Kubernetes or want a sandbox for testing ideas, this setup provides a solid foundation.

Most importantly, everything is contained in your home network, so you can experiment freely without worrying about cloud costs or breaking production systems. Happy learning!

---