DEV Community: Precious Okpor

How to Properly Set Up K3s on Your Homelab or Server (2026 Edition)

Precious Okpor — Sat, 13 Jun 2026 12:46:59 +0000

I recently migrated my homelab from Docker + Jenkins to K3S because it was my production infrastructure that runs K3S on AWS, and my homelab should mirror that same flow.

This guide documents exactly how I set up K3S, MetalLB, Traefik, cert-manager with Let's Encrypt, and ArgoCD. All on a single Ubuntu 26.04 VM.

One important thing most 2025 tutorials won't tell you is that ingress-nginx was archived on March 24, 2026, which means no more releases or security patches. The good news is K3S ships Traefik v3 as its default ingress controller, so you get a maintained, production-grade ingress out of the box.

What We're Building

Component	Role
K3s v1.33	Lightweight Kubernetes runtime
MetalLB v0.16.1	LoadBalancer IP assignment for bare metal
Traefik v3	Ingress controller (bundled with K3s)
cert-manager	Automated TLS certificate management
Let's Encrypt (HTTP-01)	Free, trusted certificates
ArgoCD	GitOps continuous delivery
Helm 3	Package manager

Prerequisites

A VM or server running Ubuntu 24.04 and above
A public domain with an A record pointing to your server's public IP (Optional)
Port 80 and 443 open on your server/firewall (required for Let's Encrypt HTTP-01 challenge)
A local IP subnet for MetalLB (e.g. 192.168.1.0/24) — adjust to match your network

Step 1: System Prep

Before installing anything, get the system into the right state.

# Update system
sudo apt update && sudo apt upgrade -y

# Install dependencies
sudo apt install -y curl wget git open-iscsi nfs-common

# Disable swap (Kubernetes requires this)
sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# Load required kernel modules
sudo modprobe overlay
sudo modprobe br_netfilter

# Persist kernel modules across reboots
cat <<EOF | sudo tee /etc/modules-load.d/k3s.conf
overlay
br_netfilter
EOF

# Set required sysctl parameters
cat <<EOF | sudo tee /etc/sysctl.d/k3s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

sudo sysctl --system

Step 2: Install K3s

K3s ships with its own built-in ServiceLB (Klipper). We disable it because MetalLB will handle LoadBalancer IP assignment instead. Traefik stays on.

curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -s - \
  --disable servicelb \
  --write-kubeconfig-mode 644

# Wait for node to be ready
sudo kubectl wait --for=condition=ready node --all --timeout=120s

# Verify
sudo kubectl get nodes
sudo kubectl get pods -A

Set up kubeconfig for your non-root user:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
chmod 600 ~/.kube/config

# Persist in shell
echo 'export KUBECONFIG=~/.kube/config' >> ~/.bashrc
source ~/.bashrc

# Confirm it works
kubectl get nodes

You should see your node in Ready state.

Step 3: Install Helm

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

# Verify
helm version

Step 4: Install MetalLB

On bare metal and VMs, LoadBalancer type services stay stuck in <pending> forever without a load balancer controller. MetalLB fixes this by assigning real IPs from a pool you define.

# Add the MetalLB Helm repo
helm repo add metallb https://metallb.github.io/metallb
helm repo update

# Install
helm install metallb metallb/metallb \
  --namespace metallb-system \
  --create-namespace \
  --wait

# Confirm pods are running
kubectl get pods -n metallb-system

Now configure the IP address pool. Pick a range from your local subnet that is outside your router's DHCP range to avoid conflicts. Adjust 192.168.1.200-192.168.1.220 to match your network:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: homelab-pool
  namespace: metallb-system
spec:
  addresses:
  - 192.168.1.200-192.168.1.220
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: homelab-l2
  namespace: metallb-system
spec:
  ipAddressPools:
  - homelab-pool
EOF

# Verify
kubectl get ipaddresspool -n metallb-system
kubectl get l2advertisement -n metallb-system

Step 5: Verify Traefik

K3S already installed Traefik v3 during setup. You don't need to install it separately. Just confirm it's running and that MetalLB has assigned it an IP:

# Traefik should be running in kube-system
kubectl get pods -n kube-system | grep traefik

# The service should now have an EXTERNAL-IP from your MetalLB pool
kubectl get svc traefik -n kube-system

You should see an IP in the 192.168.1.200-220 range (or whichever range you set) in the EXTERNAL-IP column. That's MetalLB doing its job.

Step 6: Install cert-manager

cert-manager automates the full lifecycle of TLS certificates — requesting, renewing, and storing them as Kubernetes secrets. We use the HTTP-01 challenge, which means Let's Encrypt will verify your domain by making an HTTP request to your server.

# Add the Jetstack Helm repo
helm repo add jetstack https://charts.jetstack.io
helm repo update

# Install cert-manager with CRDs
helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true \
  --wait

# Verify all 3 pods are running: controller, cainjector, webhook
kubectl get pods -n cert-manager

Now create a ClusterIssuer to tell cert-manager how to obtain certificates:

cat <<EOF | kubectl apply -f -
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your@email.com        # ← replace with your email
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
    - http01:
        ingress:
          class: traefik
EOF

# Verify the issuer is ready
kubectl get clusterissuer letsencrypt-prod

The STATUS should show True under READY.

Step 7: Install ArgoCD

ArgoCD gives you GitOps-based deployments — your cluster state is driven by Git, not manual kubectl apply commands. It's the right pattern for a homelab that mirrors how production should work.

# Add the Argo Helm repo
helm repo add argo https://argoproj.github.io/argo-helm
helm repo update

# Install ArgoCD
helm install argocd argo/argo-cd \
  --namespace argocd \
  --create-namespace \
  --set server.service.type=LoadBalancer \
  --wait

# Verify pods are running
kubectl get pods -n argocd

# Get the external IP (assigned by MetalLB)
kubectl get svc argocd-server -n argocd

# Get the initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret \
  -o jsonpath="{.data.password}" | base64 -d && echo

Access the ArgoCD UI at https://<EXTERNAL-IP> with username admin and the password above. Change the password after the first login.

Step 8: Smoke Test

Deploy a quick test app to confirm the full stack is working end to end:

# Deploy a test nginx pod
kubectl create deployment test-app --image=nginx:alpine

# Expose it as a LoadBalancer service
kubectl expose deployment test-app \
  --port=80 \
  --type=LoadBalancer \
  --name=test-app-svc

# Watch for MetalLB to assign an external IP
kubectl get svc test-app-svc --watch

# Once an IP appears, curl it
curl http://<EXTERNAL-IP>

# Clean up
kubectl delete deployment test-app
kubectl delete svc test-app-svc

If you get an nginx welcome page, everything is wired up correctly.

How to Deploy an App with TLS

Once you deploy a real app, here's what an Ingress resource looks like using Traefik + cert-manager. Just add the annotation, and cert-manager handles the certificate request automatically:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app
  namespace: default
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
spec:
  ingressClassName: traefik
  rules:
  - host: myapp.yourdomain.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: my-app-svc
            port:
              number: 80
  tls:
  - hosts:
    - myapp.yourdomain.com
    secretName: myapp-tls

Apply it, and cert-manager will automatically:

Detect the cert-manager.io/cluster-issuer annotation
Create a Certificate resource
Complete the HTTP-01 challenge with Let's Encrypt
Store the issued cert in the myapp-tls secret
Renew it automatically before expiry

What's Next

With this foundation in place, here's what I'd layer on next:

Prometheus + Grafana: observability for the cluster (you already have prom-client experience, this maps directly)
Gitea + Woodpecker CI: lightweight self-hosted CI that replaces Jenkins
Harbor: private container registry running inside the cluster
Longhorn: persistent storage for stateful workloads

The goal is a homelab that serves as a direct rehearsal environment for production.

Summary

System prep → K3s → Helm → MetalLB → Traefik (built-in) → cert-manager → ArgoCD

Every piece here is actively maintained in 2026. No ingress-nginx, no Klipper ServiceLB conflicts, no Jenkins.

If this helped you, drop a comment with what you're running on your homelab. Always curious what other engineers are self-hosting.

How I Containerised 5 Monoliths and Deployed Them to EKS

Precious Okpor — Wed, 08 Apr 2026 15:18:55 +0000

There's a blog post I've always found frustrating: the kind that shows you a perfect Dockerfile, a clean terraform apply, and a screenshot of everything working on the first try. No errors. No wrong turns.

This isn't that post.

I'm a DevOps and Cloud Engineer — in practice, I do DevOps and SRE work: Kubernetes clusters, CI/CD pipelines, AWS infrastructure. I containerise things regularly. But I'd never sat down and worked through five different stacks back to back, treating each one as a distinct challenge.

So I did. Here's what I built, what broke, and what I learned.

The Setup

Five demo apps. Each represents a different monolith archetype. Each has a /health endpoint and one meaningful route — simple enough that the app isn't the distraction. AI helped with creating the apps so I could focus on the DevOps aspects of the project.

App	Stack	What it teaches
`app-node-api`	Node.js + Express	`node_modules`, `.dockerignore` discipline
`app-python-api`	Python + Flask	Slim vs Alpine tradeoffs
`app-nestjs-api`	NestJS (TypeScript)	Three-stage builds: deps → compile → runtime
`app-react-spa`	React + Nginx	Static asset serving, SPA routing
`app-go-service`	Go	Distroless images, static binaries

The full repo: eks-monolith-migration — IaC, Dockerfiles, k8s manifests, CI/CD, all of it.

Phase 1: The Dockerfiles

App 1 — Node.js: The `.dockerignore` Wake-Up Call

Node.js is where most people make the biggest beginner mistake: not using .dockerignore, so Docker sends your entire node_modules as build context on every build.

My .dockerignore:

node_modules
npm-debug.log
.env
.git

My Dockerfile: two-stage. Install deps in stage one, copy only what runs in stage two.

FROM node:24-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:24-alpine AS runtime
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY src/ ./src/
ENV NODE_ENV=production
USER node
EXPOSE 3001
CMD ["node", "src/index.js"]

USER node is easy to forget and almost never done in tutorials. Running as root inside a container means a container escape gives an attacker root on the host. One line fixes it.

Image size: 235MB vs 1.1GB naive.

App 2 — Python/Flask: The Alpine Trap

My first instinct: python:3.12-alpine. Alpine is tiny. Tiny equals good.

The problem: Alpine uses musl libc. Many Python packages with C extensions (numpy, psycopg2, cryptography) either have no Alpine-compatible wheels or compile from source — turning a 30-second build into a 5-minute build. Sometimes it just breaks.

Use python:3.12-slim instead. Debian-based, glibc, pre-compiled wheels.

FROM python:3.12-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /install /usr/local
COPY app.py .
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1
RUN useradd -m appuser && USER appuser
EXPOSE 3002
CMD ["gunicorn", "--bind", "0.0.0.0:3002", "app:app"]

Two things worth noting:

PYTHONUNBUFFERED=1 — without this, stdout is buffered. Your logs go missing in Kubernetes until the buffer flushes.
gunicorn instead of Flask's dev server — the dev server is single-threaded and literally prints "do not use in production" on startup. Take it at its word.

Image size: 186MB.

App 3 — NestJS: The Three-Stage Build

NestJS is TypeScript. TypeScript compiles to JavaScript. That means your build process is: install deps → compile → run. Three distinct stages.

The trap: carrying your TypeScript compiler, devDependencies, and .ts source files into the production image.

FROM node:24-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:24-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:24-alpine AS runtime
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY --from=build /app/dist ./dist
ENV NODE_ENV=production
USER node
EXPOSE 3003
CMD ["node", "dist/main.js"]

The runtime stage does its own npm ci --only=production. It doesn't copy node_modules from the build stage — those include devDependencies. Fresh install, production only, then just the compiled dist/.

Your TypeScript source never touches the production image. Your test runner isn't there. Your type definitions aren't there.

Image size: 295MB.

App 4 — React + Nginx: The SPA Routing Gotcha

React apps are static files. After npm run build, you have an index.html and some JS bundles. You don't need Node at runtime — you need a web server.

Everyone knows this in theory. Fewer people get the Nginx config right.

The issue: React Router. If a user navigates directly to /about or refreshes on /dashboard, Nginx looks for a file at that path. There isn't one. 404.

The fix is one directive: try_files $uri $uri/ /index.html;

server {
    listen 3004;
    root /usr/share/nginx/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx/nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 3004

Image size: 74.4MB. Smallest of the five — Nginx Alpine is tiny and we're just serving static files.

App 5 — Go: The Satisfying One

Go compiles to a single static binary. No runtime, no interpreter, no VM. Just a binary.

This means you can build in one container and copy the binary into a container that has almost nothing — gcr.io/distroless/static.

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o server .

FROM gcr.io/distroless/static-debian12 AS runtime
WORKDIR /app
COPY --from=builder /app/server .
EXPOSE 3005
CMD ["/app/server"]

CGO_ENABLED=0 disables C bindings. GOOS=linux targets Linux explicitly. Together they ensure the binary is truly static and will run in distroless.

No shell in that container. No ls, no curl, no package manager. kubectl exec into it and try to run bash — nothing. This is the point. Near-zero attack surface.

Image size: 8.88MB.

The Before vs. After Table

App	Naive	Optimized
Node.js API	~1.1GB	235MB
Python API	~920MB	186MB
NestJS API	~1.3GB	295MB
React SPA	~400MB	74.4MB
Go Service	~800MB	8.88MB

The Go number is not a typo. I was surprised myself.

Phase 2: Infrastructure with Terraform

Three modules: vpc, eks, ecr.

The VPC creates public subnets for the load balancer, private subnets for worker nodes, and a NAT gateway so private nodes can pull images. Standard layout.

The EKS module provisions a managed node group (t3.medium — the minimum that comfortably runs EKS system pods alongside workloads) and enables OIDC, which is what makes IRSA work.

IRSA — IAM Roles for Service Accounts — is how you give pods AWS permissions without credentials anywhere. An IAM role attaches to a Kubernetes service account. Pods get temporary credentials via OIDC token exchange. No AWS_ACCESS_KEY_ID in your manifests.

The ECR module creates five repos with lifecycle policies:

policy = jsonencode({
  rules = [{
    rulePriority = 1
    description  = "Keep last 10 images"
    selection = {
      tagStatus   = "any"
      countType   = "imageCountMoreThan"
      countNumber = 10
    }
    action = { type = "expire" }
  }]
})

Without lifecycle policies, ECR accumulates images indefinitely. Ten images covers comfortable rollback. More than that is sentiment, not operations.

What broke: The AWS Load Balancer Controller IAM policy. The controller needs a specific IAM policy to provision ALBs. If the IRSA annotation on the controller's service account doesn't match the IAM role ARN exactly, the controller runs but your Ingress resources never get an ADDRESS. I spent an hour on this.

Phase 3: Kubernetes Manifests

Two things I enforced on every deployment that most tutorials skip:

Resource requests and limits:

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "500m"

Without requests, the scheduler can't place your pod intelligently. Without limits, a misbehaving pod starves everything else on the node.

Minimum two replicas via HPA:

spec:
  minReplicas: 2
  maxReplicas: 5

One replica is a single point of failure. A node rotation takes down your service. Two replicas means you survive a pod restart gracefully.

Phase 4: GitOps with ArgoCD

ArgoCD watches your Git repository for manifest changes and syncs them to the cluster. The cluster pulls its desired state from Git — Git is the source of truth. A rogue kubectl apply directly on the cluster? ArgoCD reverts it on the next sync cycle.

I used a single ApplicationSet instead of five separate Application resources:

apiVersion: argoproj.io/v1alpha1
kind: ApplicationSet
metadata:
  name: monolith-apps
  namespace: argocd
spec:
  generators:
    - list:
        elements:
          - app: app-node-api
          - app: app-python-api
          - app: app-nestjs-api
          - app: app-react-spa
          - app: app-go-service
  template:
    metadata:
      name: '{{app}}'
    spec:
      source:
        path: 'k8s/apps/{{app}}'
      syncPolicy:
        automated:
          prune: true
          selfHeal: true

One manifest. Five apps. Adding a sixth is one line in the elements list.

Seeing all five apps show Synced and Healthy simultaneously in the ArgoCD dashboard was genuinely satisfying.

Phase 5: GitHub Actions CI/CD

Two workflows:

ci-build-push.yml — triggers on push to main. Matrix build across all five apps, tags each image with the git commit SHA, pushes to ECR. Authenticates with AWS via OIDC — no static credentials stored anywhere.

cd-update-manifests.yml — runs after the build. Updates the image tag in k8s/apps/<app>/deployment.yaml, commits back to the repo. ArgoCD detects the drift and syncs within 30 seconds.

- name: Authenticate to AWS
  uses: aws-actions/configure-aws-credentials@v4
  with:
    role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions-ecr
    aws-region: us-east-1

The commit SHA as the image tag matters. latest tells you nothing about what's actually running. A commit SHA is immutable and traceable — you can answer "what code is in production?" with a single kubectl get deployment.

What I'd Do Differently

Separate the manifests repo. When app code and k8s manifests live together, the CI commit that updates image tags triggers another CI run on the same repo. With branch filtering, you avoid a loop, but a dedicated *-k8s repo is cleaner.

Secrets management from the start. I used hardcoded values for the demo. Retrofitting the External Secrets Operator + AWS Secrets Manager later is painful. Wire it up day one.

Distroless everywhere, not just Go. Distroless images exist for Node.js and Python, too. I used Alpine variants for easier debugging — in production, I'd push toward distroless across the board.

Takeaways

Five stacks. Five Dockerfiles. One EKS cluster. One ApplicationSet. One pipeline.

The image optimisation alone — from multi-gigabyte naive images to sub-200MB across the board — is something concrete you can demonstrate. The Go service at 12MB in a distroless container with near-zero attack surface is something worth building just to see it work.

The deeper lesson is GitOps. Self-healing deployments, Git as the source of truth, no manual kubectl apply in production — these are what make Kubernetes manageable at scale, not just powerful on a laptop.

Full repo: github.com/poppyszn/eks-monolith-migration

Questions on any specific part — the OIDC setup, the ApplicationSet pattern, the ALB Controller IAM issue, the Nginx SPA config — drop them in the comments.