Build practical Kubernetes experience
Develop skills through operating a functioning cluster rather than using isolated examples.
Container Orchestration Case Study
KubernetesHomelab Platform
A practical K3s environment with datastore encryption, two-recipient SOPS recovery, Kubernetes deployment, ingress, local load balancing and evidence-led operational documentation.
Executive Summary
Learning Kubernetes by operating a real platform.
The Kubernetes Homelab was created to develop practical experience beyond theory and temporary training clusters.
The platform runs K3s on dedicated ARM64 hardware and includes containerd, MetalLB, Traefik, namespaces, deployments, services and ingress resources.
The repository also includes architecture, deployment, operations, security, troubleshooting and decision documentation, demonstrating how the platform can be supported as well as deployed.
The Challenge
Translate container knowledge into orchestration capability.
Docker Compose provides effective container management on a single host, but it does not demonstrate Kubernetes scheduling, services, ingress, namespaces or cluster-oriented networking.
The challenge was to create a manageable Kubernetes platform that provided real orchestration experience without introducing unnecessary complexity during the first implementation stage.
Project Objectives
A platform designed for practical Kubernetes development.
Create local load balancing
Provide Kubernetes LoadBalancer services with addresses usable on the home network.
Implement ingress
Use a consistent ingress layer for routing requests to applications.
Use Git-based deployment
Store manifests, scripts and documentation in version control.
Document the platform
Maintain architecture, deployment, operations, security and troubleshooting guidance.
Support future expansion
Create a foundation for monitoring, GitOps and additional application workloads.
Delivery Approach
Building the platform in controlled stages.
Prepare the host
Validated Debian, system resources, networking, storage, sudo access and swap configuration.
Install K3s
Created a single-node control-plane environment using K3s and containerd.
Validate cluster health
Confirmed the node was Ready and core Kubernetes services were running.
Configure MetalLB
Defined a safe local address pool and assigned a stable LoadBalancer address.
Use Traefik ingress
Configured ingress routing for application access through the cluster.
Deploy the first workload
Created a namespace, deployment, service and ingress for a practical demonstration application.
Core Components
Lightweight services providing standard Kubernetes capability.
Distribution
K3s
Provides a lightweight Kubernetes distribution suitable for the ARM64 lab environment.Runtime
containerd
Runs and manages container workloads beneath Kubernetes.Ingress
Traefik
Routes HTTP requests to services using Kubernetes ingress resources.Load Balancing
MetalLB
Provides usable LoadBalancer addresses on the local Layer 2 network.Storage
NVMe Host Storage
Provides sufficient local capacity for workloads, images and future persistent data.Delivery
Git Repository
Stores scripts, manifests, architecture decisions and operational documentation.Architecture
From LAN traffic to container workloads.
↓
↓
↓
↓
Platform Environment
A dedicated Linux host for practical orchestration.
The cluster runs on dedicated ARM64 hardware with sufficient memory and NVMe storage to support the control plane, platform services and continued workload development.
Operating system
Debian 12
A stable Linux foundation running on dedicated ARM64 hardware.Kubernetes distribution
K3s
A lightweight Kubernetes distribution suitable for the available hardware.Container runtime
containerd
The runtime responsible for pulling images and running container workloads.Ingress controller
Traefik
Routes inbound HTTP traffic to Kubernetes services.Load balancer
MetalLB
Provides local Layer 2 LoadBalancer addresses for services.Storage
NVMe
Provides local capacity for container images, workloads and future persistent volumes.Namespace Design
Separating applications from platform responsibilities.
Namespaces provide logical separation between application workloads, monitoring, logging, networking and future GitOps services.
applicationsApplication workloads intended to run independently from platform services.
argocdReserved for GitOps deployment and continuous reconciliation.
monitoringMonitoring components, dashboards and metrics collection.
loggingCentral logging components and log-processing workloads.
metallb-systemMetalLB controllers, speakers and address-pool configuration.
demoSafe namespace for testing workloads and Kubernetes resources.
First Application Deployment
Whoami demonstration application
The first workload was deliberately small so the focus remained on understanding Kubernetes resources and network flow rather than application complexity.
Resources created
- A dedicated demo namespace
- A Kubernetes Deployment
- A ClusterIP Service
- A Traefik Ingress resource
- A MetalLB-backed external address
What It Demonstrated
Namespaces must exist before namespaced resources are applied.
Services provide stable access even when pods are recreated.
Ingress rules separate external routing from application configuration.
Testing with a simple workload makes networking issues easier to isolate.
Architecture Decisions
Choices balancing realism and manageable complexity.
Use K3s
Decision
Select K3s rather than a heavier multi-component Kubernetes installation.
Reason
The platform needed to run efficiently on ARM64 hardware while providing genuine Kubernetes capability.
Benefit
Lower operational overhead with access to standard Kubernetes resources and tooling.
Begin with one node
Decision
Start with a single control-plane node before expanding to multiple nodes.
Reason
This allowed focus on Kubernetes concepts, networking and deployment before adding cluster complexity.
Benefit
Created a manageable learning environment with a clear future expansion path.
Use MetalLB
Decision
Provide Layer 2 LoadBalancer addresses from a reserved section of the LAN.
Reason
Local Kubernetes environments do not receive managed cloud load balancers.
Benefit
Applications can use standard LoadBalancer services with stable network addresses.
Retain Traefik
Decision
Use the ingress controller provided and supported by K3s.
Reason
Traefik integrates naturally with K3s and avoids unnecessary replacement during the initial platform stage.
Benefit
Reduced implementation complexity while retaining standard ingress capability.
Project Delivery
Technical implementation supported by structured planning.
Requirements and readiness
Validated the operating system, hardware, storage and networking before installation.
Dependency sequencing
Delivered host preparation, K3s, networking, ingress and workloads in a controlled order.
Risk management
Checked address availability and avoided introducing conflicts into the existing LAN.
Issue resolution
Investigated namespace and networking problems using Kubernetes and Linux tooling.
Decision records
Documented why K3s, Traefik, MetalLB and a single-node starting point were selected.
Future planning
Structured the repository to support GitOps, monitoring, security and additional nodes.
Challenges
Resolving networking, sequencing and supportability issues.
LoadBalancer address conflict
Problem
The initial MetalLB address selected was already in use by another device on the network.
Response
Scanned the available address range, identified safe addresses and changed the assigned IP.
Outcome
The Kubernetes service received a stable address without disrupting another device.
Namespace deployment error
Problem
The first workload resources were applied before the expected namespace existed.
Response
Created the namespace and reapplied the deployment, service and ingress resources.
Outcome
The application deployed successfully and the importance of dependency order was reinforced.
Host resource planning
Problem
The cluster needed sufficient memory, storage and network stability for future workloads.
Response
Validated the host before installation and documented available capacity.
Outcome
The cluster runs on a suitable foundation with room for continued development.
Operational documentation
Problem
A working cluster without clear operating guidance would be difficult to maintain or demonstrate.
Response
Created architecture, deployment, operations, security, decision and troubleshooting documents.
Outcome
The project demonstrates both implementation and supportability.
Outcomes
A functioning base for continued Kubernetes development.
Control-plane node
A functioning K3s control plane running on dedicated ARM64 hardware.
LoadBalancer address
MetalLB provides a fixed address accessible from the local network.
Ingress traffic
Traefik routes requests to applications through Kubernetes ingress.
Platform definition
Scripts, manifests and documentation are maintained through Git.
Datastore Secrets
All 14 existing Kubernetes Secrets were re-encrypted with matching server hashes.
SOPS foundation
Operational, protected recovery and detached-media controls have been independently validated.
Skills Demonstrated
Container orchestration with operational documentation.
Operational Practices
Building a cluster that can be understood and supported.
The project is not considered complete when an application starts. Ongoing operation, troubleshooting and documentation are treated as part of the platform design.
Cluster health checks
Regularly verify node readiness, pod state, services, ingress resources and system namespaces.
Version-controlled manifests
Store scripts, YAML resources and documentation in Git so changes remain reviewable and repeatable.
Resource awareness
Monitor memory, storage and workload requirements before introducing additional applications.
Network planning
Reserve LoadBalancer addresses carefully to avoid conflicts with existing LAN devices.
Troubleshooting
Use kubectl, logs, events and Linux network tools to investigate failed deployments and routing problems.
Documentation
Maintain deployment, operations, security, architecture and troubleshooting guidance alongside the project.
Platform Roadmap
Expanding capability in controlled stages.
The current cluster provides a stable learning foundation. Future improvements will be introduced only when they add clear operational or learning value.
GitOps with Argo CD
Use Git as the desired-state source and automatically reconcile approved Kubernetes changes.
Platform monitoring
Add Kubernetes metrics, node monitoring, pod health and workload dashboards.
Persistent storage
Introduce a documented storage approach for applications requiring persistent data.
Additional nodes
Expand from the single-node foundation when greater resilience or workload capacity is needed.
Application secret onboarding
Use the validated SOPS and age foundation when an application-managed credential is introduced.
Application migration
Evaluate suitable Docker workloads for controlled migration into Kubernetes.
Lessons Learned
Cluster simplicity creates space to understand the fundamentals.
A smaller Kubernetes environment still provides meaningful experience with services, ingress, namespaces and orchestration.
Address planning is essential when integrating MetalLB into an existing network.
Kubernetes resources have dependencies, and applying them in a clear order makes failures easier to understand.
Documentation and decision records are as important as manifests when the objective is to demonstrate an operable platform.
Source and Related Work