What is this project about?

Scope

The scope of this project is to create a kubernetes cluster at home using Raspberry Pis and to automate its deployment and configuration applying IaC (infrastructure as a code) and GitOps methodologies with tools like Ansible, cloud-init and Argo CD.

As part of the project, the goal is to use a lightweight Kubernetes flavor based on K3S and deploy cluster basic services such as: 1) distributed block storage for POD’s persistent volumes, LongHorn, 2) backup/restore solution for the cluster, Velero and Restic, 3) service mesh architecture, Linkerd, and 4) observability platform based on metrics monitoring solution, Prometheus, logging and analytics solution, EFḰ+LG stack (Elasticsearch-Fluentd/Fluentbit-Kibana + Loki-Grafana), and distributed tracing solution, Tempo.

Design Principles

• Use ARM 64 bits operating system enabling the possibility of using Raspberry PI B nodes with 8GB RAM. Currently only Ubuntu supports 64 bits ARM distribution for Raspberry Pi.
• Use ligthweigh Kubernetes distribution (K3S). Kuberentes distribution with a smaller memory footprint which is ideal for running on Raspberry PIs
• Use of distributed storage block technology, instead of centralized NFS system, for pod persistent storage. Kubernetes block distributed storage solutions, like Rook/Ceph or Longhorn, in their latest versions have included ARM 64 bits support.
• Use of opensource projects under the CNCF: Cloud Native Computing Foundation umbrella
• Use latest versions of each opensource project to be able to test the latest Kubernetes capabilities.
• Use of cloud-init to automate the initial OS installation.
• Use of Ansible for automating the configuration of the cluster nodes, installation of kubernetes and external services, and triggering cluster bootstrap (ArgoCD bootstrap).
• Use of Argo CD to automatically provision Kubernetes applications from git repository.

Technology Stack

The following picture shows the set of opensource solutions used for building this cluster:

	Name	Description
	Ansible	Automate OS configuration, external services installation and k3s installation and bootstrapping
	ArgoCD	GitOps tool for deploying applications to Kubernetes
	Cloud-init	Automate OS initial installation
	Ubuntu	Cluster nodes OS
	K3S	Lightweight distribution of Kubernetes
	containerd	Container runtime integrated with K3S
	Flannel	Kubernetes Networking (CNI) integrated with K3S
	CoreDNS	Kubernetes DNS
	Metal LB	Load-balancer implementation for bare metal Kubernetes clusters
	Traefik	Kubernetes Ingress Controller
	Linkerd	Kubernetes Service Mesh
	Longhorn	Kubernetes distributed block storage
	Minio	S3 Object Storage solution
	Cert-manager	TLS Certificates management
	Hashicorp Vault	Secrets Management solution
	External Secrets Operator	Sync Kubernetes Secrets from Hashicorp Vault
	Velero	Kubernetes Backup and Restore solution
	Restic	OS Backup and Restore solution
	Prometheus	Metrics monitoring and alerting
	Fluentd	Logs forwarding and distribution
	Fluentbit	Logs collection
	Loki	Logs aggregation
	Elasticsearch	Logs analytics
	Kibana	Logs analytics Dashboards
	Tempo	Distributed tracing monitoring
	Grafana	Monitoring Dashboards

External Resources and Services

Even whe the premise is to deploy all services in the kubernetes cluster, there is still a need for a few external services/resources. Below is a list of external resources/services and why we need them.

Cloud external services

	Provider	Resource	Purpose
	Letsencrypt	TLS CA Authority	Signed valid TLS certificates
	IONOS	DNS	DNS and DNS-01 challenge for certificates

Alternatives:

1. Use a private PKI (custom CA to sign certificates).

   Currently supported. Only minor changes are required. See details in Doc: Quick Start instructions.

2. Use other DNS provider.

   Cert-manager / Certbot used to automatically obtain certificates from Let’s Encrypt can be used with other DNS providers. This will need further modifications in the way cert-manager application is deployed (new providers and/or webhooks/plugins might be required).

   Currently only acme issuer (letsencytp) using IONOS as dns-01 challenge provider is configured. Check list of supported dns01 providers.

Self-hosted external services

There is another list of services that I have decided to run outside the kuberentes cluster selfhosting them.

	External Service	Resource	Purpose
	Minio	S3 Object Store	Cluster Backup
	Hashicorp Vault	Secrets Management	Cluster secrets management

Minio backup servive is hosted in a VM running in Public Cloud, using Oracle Cloud Infrastructure (OCI) free tier.

Vault service is running in gateway node, since Vault kubernetes authentication method need access to Kuberentes API, I won’t host Vault service in Public Cloud.

What I have built so far

From hardware perspective I built two different versions of the cluster

• Release 1.0: Basic version using dedicated USB flash drive for each node and centrazalized SAN as additional storage

• Release 2.0: Adding dedicated SSD disk to each node of the cluster and improving a lot the overall cluster performance

What I have developed so far

From software perspective, I have developed the following:

1. Cloud-init template files for initial OS installation in Raspberry PI nodes

   Source code can be found in Pi Cluster Git repository under metal/rpi/cloud-init directory.

2. Ansible playbook and roles for configuring cluster nodes and installating and bootstraping K3S cluster

   Source code can be found in Pi Cluster Git repository under /ansible directory.

   Aditionally several ansible roles have been developed to automate different configuration tasks on Ubuntu-based servers that can be reused in other projects. These roles are used by Pi-Cluster Ansible Playbooks

   Each ansible role source code can be found in its dedicated Github repository and is published in Ansible-Galaxy to facilitate its installation with ansible-galaxy command.

   Ansible role	Description	Github
   ricsanfre.security	Automate SSH hardening configuration tasks
   ricsanfre.ntp	Chrony NTP service configuration
   ricsanfre.firewall	NFtables firewall configuration
   ricsanfre.dnsmasq	Dnsmasq configuration
   ricsanfre.storage	Configure LVM
   ricsanfre.iscsi_target	Configure iSCSI Target
   ricsanfre.iscsi_initiator	Configure iSCSI Initiator
   ricsanfre.k8s_cli	Install kubectl and Helm utilities
   ricsanfre.fluentbit	Configure fluentbit
   ricsanfre.minio	Configure Minio S3 server
   ricsanfre.backup	Configure Restic
   ricsanfre.vault	Configure Hashicorp Vault

3. Packaged Kuberentes applications (Helm, Kustomize, manifest files) to be deployed using ArgoCD

   Source code can be found in Pi Cluster Git repository under /argocd directory.

4. This documentation website picluster.ricsanfre.com, hosted in Github pages.

   Static website generated with Jekyll.

   Source code can be found in the Pi-cluster repository under /docs directory.

Software used and latest version tested

The software used and the latest version tested of each component