Kubernetes at Home - From Docker Compose to K3s

Are you running a bunch of containers with Docker Compose at home and feeling like you’ve outgrown it? Maybe you’re curious about Kubernetes but worried it might be overkill for your home setup? Well, you’re in for a treat! Today, we’re going to explore how to level up your home lab by migrating from Docker Compose to K3s, a lightweight Kubernetes distribution that’s perfect for home environments.

Understanding the Shift: Why Move to K3s?

If Docker Compose has been your trusty companion for running containers at home, you might wonder why you should even consider switching to K3s. While Docker Compose is fantastic for simple container orchestration, it has limitations that become apparent as your home lab grows:

• Limited scaling capabilities: Docker Compose works well for single-host deployments but becomes unwieldy when you want to spread your services across multiple machines.
• Basic service discovery: While functional, the service discovery in Docker Compose isn’t as robust as what Kubernetes offers.
• Restricted orchestration features: You miss out on advanced features like rolling updates, automated rollbacks, and sophisticated health checks.

Enter K3s, a certified Kubernetes distribution designed specifically for resource-constrained environments. It offers:

• Lightweight footprint: Requires only 512MB of RAM to run
• Simple installation: Single binary installation process
• Full Kubernetes compatibility: Access to the entire Kubernetes ecosystem
• Perfect for home labs: Optimized for ARM64 and ARMv7 devices (hello, Raspberry Pi!)

Prerequisites for Migration

Before we dive into the migration process, let’s make sure you have everything you need:

System Requirements

• A Linux system with at least:
  • 1 CPU core (2+ recommended)
  • 512MB RAM (1GB+ recommended)
  • 1GB storage space
• Docker installed (for running existing containers)
• curl or wget for downloading K3s
• Basic familiarity with YAML and command-line operations

Recommended Tools

• kubectl: The Kubernetes command-line tool
• k9s (optional): A terminal-based UI for managing Kubernetes clusters
• Lens (optional): A powerful Kubernetes IDE

Preparing Your Environment

Let’s start by setting up K3s and preparing for the migration.

Installing K3s

# Download and install K3s
curl -sfL https://get.k3s.io | sh -

# Wait for the service to start
sudo systemctl status k3s

# Set up kubectl configuration
mkdir ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config

Backing Up Docker Compose Configuration

Before making any changes, let’s back up your existing Docker Compose setup:

# Create a backup directory
mkdir ~/docker-backup
# Copy your docker-compose files
cp docker-compose.yml ~/docker-backup/
# Export any volumes if needed
docker run --rm -v [volume-name]:/volume -v ~/docker-backup:/backup alpine tar -czf /backup/volume-backup.tar.gz /volume

Migration Steps from Docker Compose to K3s

1. Converting Docker Compose to Kubernetes Manifests

You have two approaches:

Using Kompose (Automated Conversion)

Kompose is a conversion tool that can automatically transform Docker Compose files to Kubernetes manifests:

# Install Kompose
curl -L https://github.com/kubernetes/kompose/releases/download/v1.26.1/kompose-linux-amd64 -o kompose
chmod +x kompose
sudo mv ./kompose /usr/local/bin/kompose

# Convert your docker-compose.yml
kompose convert -f docker-compose.yml

Manual Conversion (Recommended for Learning)

Here’s an example of converting a simple web application:

Docker Compose:

version: '3'
services:
  webapp:
    image: nginx
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html

Kubernetes Deployment and Service:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: webapp
spec:
  replicas: 1
  selector:
    matchLabels:
      app: webapp
  template:
    metadata:
      labels:
        app: webapp
    spec:
      containers:
      - name: webapp
        image: nginx
        ports:
        - containerPort: 80
---
apiVersion: v1
kind: Service
metadata:
  name: webapp
spec:
  type: NodePort
  ports:
  - port: 80
    targetPort: 80
  selector:
    app: webapp

2. Deploying to K3s

Apply your new Kubernetes manifests:

kubectl apply -f webapp-deployment.yaml
kubectl apply -f webapp-service.yaml

# Verify deployment
kubectl get pods
kubectl get services

Best Practices for K3s in Home Labs

Resource Management

• Use resource limits in your deployments to prevent any single service from consuming too many resources:

resources:
  limits:
    memory: "128Mi"
    cpu: "500m"

Storage Configuration

• Use Longhorn for distributed storage:

kubectl apply -f https://raw.githubusercontent.com/longhorn/longhorn/master/deploy/longhorn.yaml

Monitoring

Set up basic monitoring with Prometheus and Grafana:

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install prometheus prometheus-community/kube-prometheus-stack

Here’s a practical example of migrating a Plex media server from Docker Compose to K3s:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: plex
spec:
  replicas: 1
  selector:
    matchLabels:
      app: plex
  template:
    metadata:
      labels:
        app: plex
    spec:
      containers:
      - name: plex
        image: plexinc/pms-docker
        ports:
        - containerPort: 32400
        volumeMounts:
        - name: media
          mountPath: /data
      volumes:
      - name: media
        hostPath:
          path: /mnt/media
---
apiVersion: v1
kind: Service
metadata:
  name: plex
spec:
  type: NodePort
  ports:
  - port: 32400
    targetPort: 32400
    nodePort: 32400
  selector:
    app: plex

Conclusion: Embracing the Future

Transitioning from Docker Compose to K3s might seem daunting at first, but the benefits are worth it. You’ll gain access to powerful Kubernetes features while maintaining a lightweight footprint suitable for home use. The migration process also provides an excellent opportunity to learn Kubernetes concepts hands-on.

Useful Resources for Further Learning

• K3s Official Documentation
• Kubernetes Basics
• r/homelab - A great community for home lab enthusiasts
• awesome-home-kubernetes - A curated list of home Kubernetes projects

Remember, the key to a successful migration is taking it one service at a time. Start with non-critical services, learn from any mistakes, and gradually move your entire stack to K3s. Happy clustering! 🚀