Skip to content

README.md

Latest commit

 

History

History
176 lines (146 loc) · 6.69 KB

README.md

File metadata and controls

176 lines (146 loc) · 6.69 KB
Raw

Ansible License Arch Kubernetes

Raspberry Pi Kubernetes Automation Lab

This repository contains an Ansible-based setup for provisioning a fully functional Kubernetes cluster using Raspberry Pi and virtual machines. It is designed as a personal lab to explore infrastructure automation, container orchestration, and service deployment — all using modular and reusable code.

Project Overview

The lab automates the setup of a multi-node K3s cluster using Ansible. It includes:

  • System configuration and hostname setup
  • K3s installation and cluster bootstrapping
  • Workload deployment using templated manifests
  • Complete monitoring and observability stack (Prometheus, Node Exporter, Alertmanager, Grafana)
  • Role-based structure for easy expansion

The cluster consists of a Raspberry Pi 4 (ARM64) as the master node and a virtual machine (x86_64) as the worker node, demonstrating a mixed-architecture setup supported by K3s.

Prerequisites

  • Ansible >= 2.16 (check with ansible --version)
  • SSH access configured for all nodes in hosts.ini
  • Python 3.x installed on controller host

Directory Structure

iac-ansible-k3s-rpi-lab/
├── LICENSE
├── README.md
├── ansible.cfg
├── ca.crt
├── group_vars/              # Group-specific variables (all, master, worker, kubernetes)
│   ├── all.yml
│   ├── kubernetes.yml
│   ├── master.yml
│   └── worker.yml
├── hosts.ini                # Ansible inventory file
├── roles/
│   ├── common/              # Base system setup (packages, hostname, user, etc.)
│   │   ├── README.md
│   │   ├── handlers/        # Ansible handlers for common role
│   │   │   └── main.yml
│   │   └── tasks/           # Ansible tasks for common role
│   │       └── main.yml
│   ├── kubernetes/          # K3s cluster installation and configuration
│   │   ├── README.md
│   │   ├── defaults/        # Default variables for Kubernetes role
│   │   │   └── main.yml
│   │   ├── files/           # Static files (e.g. kube-state-metrics manifest)
│   │   │   └── kube-state-metrics.yaml
│   │   ├── images/          # Reference screenshots
│   │   │   ├── kubectl-get-nodes.png
│   │   │   ├── kubectl-get-pods.png
│   │   │   └── kubectl-get-services.png
│   │   ├── tasks/           # Playbook tasks for Kubernetes role
│   │   │   ├── main.yml
│   │   │   ├── master.yml
│   │   │   ├── worker.yml
│   │   │   └── workloads.yml
│   │   └── templates/       # Jinja2 templates for Kubernetes manifests
│   │       ├── deployment.yml.j2
│   │       └── service.yml.j2
│   └── monitoring/          # Monitoring and observability stack
│       ├── README.md
│       ├── defaults/        # Default variables for monitoring role
│       │   └── main.yml
│       ├── files/           # Static files for monitoring
│       │   └── dashboards/  # Grafana dashboards in JSON format
│       │       ├── k8s-cluster-monitoring.json
│       │       └── node-exporter-full.json
│       ├── handlers/        # Handlers for monitoring role
│       │   └── main.yml
│       ├── images/          # Monitoring screenshots
│       │   ├── alertmanager.png
│       │   ├── grafana-k8s-cluster.png
│       │   ├── node-exporter.png
│       │   └── prometheus-targets.png
│       ├── tasks/           # Playbook tasks for monitoring role
│       │   ├── alertmanager.yml
│       │   ├── grafana.yml
│       │   ├── main.yml
│       │   ├── node_exporter.yml
│       │   └── prometheus.yml
│       ├── templates/       # Jinja2 templates for monitoring configs
│       │   ├── alertmanager.yml.j2
│       │   ├── grafana-datasource.yml.j2
│       │   ├── k8s-prometheus-scrape-rbac.yml.j2
│       │   ├── prometheus.yml.j2
│       │   └── rules/       # Prometheus rule files (templates)
│       │       └── teste.yml.j2
│       └── vars/            # Variable files for monitoring role
│           ├── main.yml
│           └── vault.yml
└── setup.yml                # Main playbook entrypoint

Roadmap

✅ Phase 1: Basic Raspberry Pi Setup

  • Update and upgrade system packages
  • Install essential tools (htop, curl, vim)
  • Create a user with sudo privileges
  • Set custom hostname and update /etc/hosts
  • Refactor playbook into roles and variables

✅ Phase 2: Kubernetes Cluster

  • Install K3s on master and worker nodes
  • Configure cluster join and token exchange
  • Deploy sample workloads and services

✅ Phase 3: Monitoring & Observability

  • Install Prometheus and Node Exporter
  • Install Grafana with custom dashboards
  • Configure alerting with Alertmanager

🔜 Phase 4: Application Deployment

  • Deploy custom apps (Flask, PostgreSQL, MQTT, etc.)
  • Use Helm charts or raw manifests
  • Setup CI/CD pipeline (GitHub Actions, Drone, etc.)

🔜 Phase 5: Documentation & Automation

  • Add architecture diagrams and flowcharts
  • Create bootstrap scripts for quick setup
  • Add Makefile or CLI wrapper for common tasks

Getting Started

To run full setup:

ansible-playbook -i hosts.ini setup.yml

To run specific parts::

ansible-playbook -i hosts.ini setup.yml --tags workloads

Available tags:

  • k3s - installs K3s on master and workers
  • workloads - deploys sample pods and services
  • master - tasks specific to the master node
  • workers - tasks specific to worker nodes

Notes

  • This lab uses a mixed-architecture cluster:
    • Master node: Raspberry Pi 4 (ARM64)
    • Worker node: Virtual Machine (x86_64)
  • Ensure container images used in workloads are multi-arch compatible (e.g. nginx, busybox, etc.)
  • SSH keys and Python interpreters must be correctly set in hosts.ini.
  • The K3s token is defined in group_vars/kubernetes.yml — consider externalizing it for security.

ℹ️ Tip: Each role/module has its own README.md with specific instructions and variables.

Author

Daniel Gil

License

This project is licensed under the MIT License.