Overview

This series teaches K3s — the lightweight Kubernetes distribution by Rancher — through heavily annotated, self-contained examples. Each example focuses on a single K3s or Kubernetes concept and includes inline annotations explaining what each command or manifest directive does, why it matters, and what cluster state results from it.

K3s packages a full Kubernetes control plane into a single ~70 MB binary. It uses containerd instead of Docker, embeds Traefik as an ingress controller, ships local-path-provisioner for storage, and bundles CoreDNS, Flannel CNI, and Klipper load balancer — all with zero external dependencies for a single-node install. This series covers K3s v1.36.1+k3s1 running Kubernetes v1.36.1.

Series Structure

The examples are organized into three levels based on complexity:

• Beginner — Installation, core workload types, networking basics, storage, health checks, and K3s-specific features like the auto-manifest directory and config file (Examples 1-28)
• Intermediate — High availability setup, CNI replacement, HelmChart CRD, cert-manager TLS, MetalLB, RBAC, NetworkPolicy, autoscaling, Longhorn storage, and workload placement (Examples 29-57)
• Advanced — GitOps with Flux CD, multi-cluster with Rancher, policy enforcement with OPA Gatekeeper, observability stacks, cluster backup/restore, custom operators, and production hardening (Examples 58-85)

Structure of Each Example

Every example follows a consistent five-part format:

1. Brief Explanation — what the K3s concept addresses and why it matters (2-3 sentences)
2. Mermaid Diagram — visual representation of cluster topology, traffic flow, or component relationships (when appropriate)
3. Heavily Annotated Code — shell commands or YAML manifests with # => comments documenting each step and its cluster-state effect
4. Key Takeaway — the core insight to retain from the example (1-2 sentences)
5. Why It Matters — production relevance and real-world impact (50-100 words)

Prerequisites

These examples assume you have:

• A Linux host (Ubuntu 22.04 or Debian 12 recommended) with at least 1 CPU and 512 MB RAM
• sudo access for installation commands
• Familiarity with basic shell commands and YAML syntax
• Understanding of core Kubernetes concepts (Pod, Deployment, Service) at a conceptual level

How to Use This Series

Each page presents annotated shell sessions and YAML manifests. Read the # => annotations alongside the commands to understand both the mechanics and the intent. The examples within each level build progressively, so reading sequentially within a level gives the fullest understanding.

Examples by Level

Beginner (Examples 1–28)

• Example 1: Install K3s Single-Node Server
• Example 2: Configure KUBECONFIG for Local kubectl Access
• Example 3: Verify Installation — Nodes and Component Health
• Example 4: Deploy a First Pod
• Example 5: Create a Deployment with Replicas
• Example 6: Expose a Deployment with a Service
• Example 7: View Pod Logs
• Example 8: Execute into a Running Pod
• Example 9: Create and Use a Namespace
• Example 10: ConfigMaps — Create from Literal and from File
• Example 11: Secrets — Create and Use in Pods
• Example 12: Apply a YAML Manifest
• Example 13: K3s Node Token — Find and Use It
• Example 14: Add and Verify a Worker Node Join
• Example 15: Port-Forward to a Pod or Service
• Example 16: Resource Limits — CPU and Memory
• Example 17: Basic Ingress with Traefik
• Example 18: Traefik IngressRoute CRD
• Example 19: View the Traefik Dashboard
• Example 20: local-path-provisioner — PVC and Pod Volume
• Example 21: StatefulSet with PVC Template
• Example 22: Health Checks — Liveness, Readiness, and Startup Probes
• Example 23: Rolling Update and Rollback
• Example 24: DaemonSet for Per-Node Agents
• Example 25: CronJob for Scheduled Tasks
• Example 26: K3s Auto-Manifest Deployment
• Example 27: K3s Config File
• Example 28: Uninstall K3s Cleanly

Intermediate (Examples 29–57)

• Example 29: HA K3s Cluster — Embedded etcd (3 Nodes)
• Example 30: HA K3s with External PostgreSQL Datastore
• Example 31: Disable Default K3s Components
• Example 32: Replace Flannel with Calico CNI
• Example 33: Replace Flannel with Cilium CNI
• Example 34: Custom Cluster CIDR and Service CIDR
• Example 35: HelmChart CRD — Deploy Applications via K3s Helm Controller
• Example 36: HelmChartConfig CRD — Customize Helm Release Values
• Example 37: Install cert-manager via HelmChart CRD
• Example 38: ClusterIssuer and Certificate with cert-manager
• Example 39: Traefik IngressRoute with TLS Termination
• Example 40: Traefik Middleware — Headers, Rate Limiting
• Example 41: MetalLB for LoadBalancer Services on Bare Metal
• Example 42: K3s Registries — Private Registry Mirrors
• Example 43: Airgap Installation — Offline K3s Setup
• Example 44: RBAC — ClusterRole, ClusterRoleBinding, ServiceAccount
• Example 45: NetworkPolicy — Restrict Pod-to-Pod Traffic
• Example 46: PodDisruptionBudget — Availability During Maintenance
• Example 47: HorizontalPodAutoscaler — Scale on CPU and Memory
• Example 48: metrics-server — kubectl top Nodes and Pods
• Example 49: Longhorn Distributed Block Storage — Install and StorageClass
• Example 50: Longhorn Backup to S3-Compatible Storage
• Example 51: Longhorn Volume Snapshots and Restore
• Example 52: kube-vip for HA LoadBalancer on Bare Metal
• Example 53: kube-vip LoadBalancer for Services
• Example 54: Secrets Encryption at Rest
• Example 55: Pod Security Admission — Enforce Restricted Mode
• Example 56: Node Taints and Tolerations for Workload Placement
• Example 57: Node Affinity and Pod Anti-Affinity Rules

Advanced (Examples 58–85)

• Example 58: GitOps with Flux CD v2 — Bootstrap on K3s
• Example 59: Flux Kustomization — Sync a Git Repository
• Example 60: Flux HelmRelease — Manage Helm Releases via Git
• Example 61: Flux Image Automation — Auto-Update Deployments
• Example 62: Multi-Cluster Management with Rancher v2.14.2
• Example 63: Rancher Projects and Namespaces — Tenant Isolation
• Example 64: Rancher Apps and Marketplace — Deploy Catalog Applications
• Example 65: OPA Gatekeeper for Policy Enforcement
• Example 66: Falco for Runtime Security Monitoring
• Example 67: Velero for Cluster Backup and Restore
• Example 68: Velero Scheduled Backup to S3
• Example 69: Prometheus and Grafana Stack via Helm
• Example 70: Custom Prometheus Alerting Rules and Alertmanager
• Example 71: Loki and Promtail for Log Aggregation
• Example 72: Distributed Tracing with Tempo and Grafana
• Example 73: Multi-Tenancy with vcluster
• Example 74: KEDA — Event-Driven Autoscaling
• Example 75: Vertical Pod Autoscaler — Auto-Right-Size Resource Requests
• Example 76: Spegel — Peer-to-Peer Container Image Distribution
• Example 77: K3s Upgrade via system-upgrade-controller
• Example 78: K3s Backup and Restore — etcd Snapshot
• Example 79: HA Node Replacement in K3s Cluster
• Example 80: Custom Admission Webhooks
• Example 81: Custom Resource Definitions — Write a Simple Operator
• Example 82: Kaniko — In-Cluster Container Image Builds
• Example 83: Tekton Pipelines — CI/CD Inside K3s
• Example 84: K3s Security Hardening — CIS Kubernetes Benchmark
• Example 85: Production Readiness Checklist