k3s-lab

Production-ready k3s cluster on VPS — automated setup with Traefik, cert-manager, Prometheus, Grafana, Loki, and Promtail.

Features

• Lightweight Kubernetes via k3s with automated control-plane and worker bootstrap
• Ingress + automatic HTTPS via Traefik and cert-manager (Let's Encrypt HTTP-01)
• Full observability stack: Prometheus, Grafana, Alertmanager, Loki, and Promtail
• Makefile-driven workflow — one target per lifecycle stage
• Static CI: ShellCheck, actionlint, kubeconform, Bats, and secret scanning (no live cluster required)
• Reusable as a git submodule with includeable Makefile fragments
• Optional: HashiCorp Vault + External Secrets Operator for centralized secret management

Prerequisites

• A VPS with SSH access
• make, kubectl, helm
• Secrets configured in .env (copy from .env.example)

Usage

cp .env.example .env          # fill in your values
make k3s-server               # bootstrap control plane
make k3s-agent                # join agent node
make kubeconfig               # fetch kubeconfig
make deploy                   # deploy Traefik + cert-manager
make deploy-monitoring        # deploy Prometheus + Grafana + Loki
make deploy-vault             # (optional) deploy HashiCorp Vault
make vault-init               # (optional) initialize + configure Vault
make deploy-eso               # (optional) deploy External Secrets Operator

→ Full guide: docs

Documentation

Full documentation is available at https://kevindebenedetti.github.io/k3s-lab/. It is generated from the docs/ directory and published automatically on push.