k3s-taskforce

Ogólnie

• Repozytorium dla studentów SPIW. Opisy postępowania w ramach tego labu podano w instrukcjach.

• Wykorzystujemy K3s - lekką dystrybycję Kubernetesa autorstwa Rancher. Cechuje się ona małym "footprintem", jednak przy zachowaniu pełnej funkcjonalności Kubernetes. Jest to więc rodzaj dystrybucji Kubernetesa, a nie jego okrojona wersja. Preferowanym obszarem zastosowań K3s to środowiska z ograniczoną ilością zasobów obliczeniowych (np. tzw. rozwiązania brzegowe w sieci). Nasze środowisko oparte na Raspberry Pi idealnie wpisuje się w ten scenariusz. Moduły węzła controller (master) zajmują łącznie ok. 512MB RAM, a moduły węzła worker poniżej 50MB RAM. Implementacyjne odstępstwa od "vanilla Kubernetes" polegają w szczególności na tym, że funkcje Kubernetes w ramach węzła danego typu są zaimplementowane w jednym procesie (np. moduły kubelet, kube-proxy i flanneld w węźle typu worker); w K8s poszczególne funkcje zwykle są implementowane jako niezależne pody/procesy (por. https://traefik.io/glossary/k3s-explained/).

• Wszelkie sugestie są mile widziane, w szególności też propozycje zadań praktycznych do wykonania.

Zakładane do osiągnięcia cele laborki (lista "żywa")

• zapoznanie się z deklaratywną naturą Ansible (na tle wybitnie imperatywnych skryptów bash) - jako przykładu notacji deklaratywnej do automatyzacji zadań konfiguracyjnych (part 1)
• zapoznanie się z zasadami "sieciowania" (networking) w klastrach kubernetes (part 2, 3)
  • koncepcja CNI na podstawie CNI flannel
  • usługi (Service) typu ClusterIP, NodePort, LoadBalancer; ekspozycja usług HTTP poprzez mechanizm Ingress
  • koncepcja NetworkPolicy (reguły filtrowania ruchu na poziomie użytkowym)
• zapoznanie się z wybranymi aspektami zarządzania zasobami i aplikacjami w klastrach Kubernetes (part 2, 3)
  • ograniczanie swobody rozkładania podów przez Kubernetes scheduler - mechanizmy taint i tolerations
  • inne - do wymyślenia/zaproponowania w ramach task-force (przykłady pożądanych: skalowanie poziome/pionowe, własne metryki, ... - w sensownym wymiarze, ale niekoniecznie tak proste, jak zmiana 'replicas: x' w Deploymencie !)
• zapoznanie się z problematyką monitorowania usług w środowiskacch CNF (na podstawie Prometheus/Grafana) (part 3)
  • jako fragmentem szerszego obszaru "telemetry"/"observability"
  • szczegółowe działania (poza przeglądaniem w dashboardach informacji na temat stanu samego klastra) pozostają do zaproponowania/opracowania

Drogą do osiągnięcia tych celów jest instalacja klastra k3s "bare metal" na platformie Raspberry Pi, instalacja i konfiguracja wybranych modułów składowych klastra (MetalLB, Traefik) oraz aplikacji poziomu "observability" (Prometheus/Grafana) z wykorzystaniem różnych mechanizmów/funkcjonalności Kubernetes, a także uruchamianie przykładowych "aplikacji" demonstracyjnych w celu ilustracji wybranych konceptów.

Co teraz mamy w katalogach/plikach

ansible-tests/ - proste przykłady wykorzystania Ansible; obecnie: mikro-demo ilustrujące istotę działania "gather facts" na przykładzie lokalnego hosta

gettemp.sh - skrypt korzystający z playbook'a Ansible get-temp.yaml do sprawdzania temperatury procesora malinek

instrukcje/ - instrukcje laboratiryjne (podstawa do realizacji ćwiczeń)

pi-cluster-install/ - źródłowe pliki instalacyje k3s (bash, Ansible); jednym z oczekiwań (i efektów nauczania) odnośnie tej części laborki jest analiza szablonów Ansible w celu zapoznania się z ich deklaratywną naturą (na tle wybitnie ipmeratywnych skryptów bash)

manifests.db/ - manifesty Kubernetes dla instalowanych modułów, testowanych wdrożeń (deploymentów), przykłady ćwiczeń laborkowych (na razie zajawka - to co bezpośrednio wynika z obecnej wersji instrukcji i służy głównie poznaniu mechanizów "sieciowych" Kubernetes). Obecnie jest to dokładna wersja plików, które w ramach testów posłużyły do pełnego uruchmienia labu na dwa dni przed otwarciem zajęć. Zostawiono je w repozytorium do dyspozycji studentów tylko dla celów prównawczych w przypadku napotkania problemów. Zasadniczo oczekuje się jednak, że zespoły będą dążyć do wykonania wszystkich ćwiczeń samodzielnie na podstawie instrukcji, bez korzystania z tych plików metodą copy-paste.

shutubu.sh - wywołanie w trybie ad-hoc komendy Ansible wyłączającej (shutdown) węzły klastra; po jej wywołaniu nie trzeba czekać na zakończenie pracy Ansible i w razie czego można od razu zamknąć swoją maszynę management-host (w tym przypadku Ansible zamyka klaster autonomicznie, bez kontaktowania się zwrotnie z management-host). Trzeba tylko dostosować do swojego przypadku nazwy węzłów klastra w pliku pi-cluster-install/shutdown-hosts.ini. To jest zalecana forma wyłączania klastra - aby ograniczyć ryzyko wystąpienia uszkodzeń wskutek "twardego" odłączenia zasilania. Na końcu pliku w komentarzu podano też sposób odczytywania temperatury CPU malinki z wiersza poleceń będąc "na" malince.

Uwagi:

• Zamykanie klastra poprzez shutdown wyłącza jedynie płytki Raspbbery Pi - nadal pozostają zasilane i pracują TP-Link oraz nakładki PoE. Można je wyłączyć jedynie poprzez wyłączenie zasilania TP-Link. Wtedy jednak zdalne włączenie klastra poprzez restart TP-Link nie będzie już możliwe.
• W przypadku korzystania z ZeroTier i jego instalacji na wybranym RbPi klastra oraz zdalnym zamykaniu/startowaniu węzłów klastra należy pamiętać o niezamykaniu malinki hostującej ZeroTier (por. zt-manual.md). W przeciwnym razie stracimy dostęp zdalny do klastra. Natomiast w przypadku zainstalowania ZeroTier (lub podobnej aplikacji) na odrębnej maszynie, zamknąć można cały klaster. W przypadku problemów z siecią na terenie akademików PW (niestety, zdarza się z powodu stosowanych polityk bezpieczeństwa) należy interweniować u administratora sieci lokalnej.

temperature_control.md - wskazowki dotyczące sterowania temperatura Raspberry Pi (opcja)

troubleshooting.txt - napotkane problemy i sposób ich rozwiązania; tutaj opisujemy sposoby rozwiązywania problemów wszelakich, które uznajemy za warte skomentowania

workloads - podkatalog busypod: Docker file dla obrazu kontenera pozwalającego realizować testy obciążeniowe klastra (głównie na poziomie CPU) i przykładowy skrypt bash do tworzenia wielu podów obciążeniowych z wykorzytaniem komend kubectl i naszego obrazu; można wykorzystać go w celu emulacji zmiennego obciążenia klastra i monitorowania parametrów wydajnościowych klastra przy użyciu Prometheus i Grafana

zt-config.sh, zt-manual.md - skrypt i instrukcja konfiguracji sieci wirtualnej ZeroTier umożliwiającej zdalny dostęp do klastra przez wszystkich uczestników grupy studenckiej. Opisano też sposób zdalnego włączania/wyłączania klastra (włączania/wyłączania malinek).

Eksperymenty gotowe do testów w ramach rozwoju własnego [stan listy: 2024.05.25]

5G Core - uruchomienie opensource 5G Core (free5GC) + symulator RAN (osoby zainteresowane - kontakt na priv)

• instalacja i sprawdzenie działania (np. ping 8.8.8.8) otwartoźródłowej platformy 5G (free5GC) w konfiguracji: (1) 5G core control plane na klastrze K3s/RaspberryPi, (2) 5G core UPF na klastrze K3s/odrębna VM/VirtualBox, (3) emulator sieci RAN (od strony 5G core, ekwiwalent UE+gNodeB) na odrębnej VM/VirtualBox
• konkretne przykłady orkiestracyjno/management-owe na poziomie Kubernetes są do ustalenia (open-source-y nie dają się sensownie skalować horyzontalnie, najwyżej wertykalnie)

English version

General

• This repo is intended for use by the students of the SPIW course at the Warsaw University of Technology during their lab experiments. All instructions to the what and how are provided in the lab guides contained in directory instrukcje.

• We use K3s - a lightweight Kubernetes distribution by Rancher. It is characterized by a small "footprint", while maintaining the full Kubernetes functionality. So, k3s is a kind of Kubernetes distribution, not a stripped down version of it. The preferred area of application of K3s is environments with a limited amount of computing resources (e.g. so-called edge solutions in the network). Our Raspberry Pi-based environment fits perfectly into this scenario. In k3s, the controller (master) node modules occupy a total of approximately 512MB RAM, and the worker node modules require less than 50MB RAM (as of k3s v1.25.5). Implementation bias from the "vanilla Kubernetes" consists in particular in that Kubernetes functions on the node of a given type (master/worker) in a k3 cluster are implemented by a single process (e.g., kubelet, kube-proxy and flanneld modules in worker nodes are implemented in one process); while in K8s, individual functions are typically implemented as independent pods/processes (ref. https://traefik.io/glossary/k3s-explained/).

• All suggestions to improve the lab are wellcome, in particular propositions of new experiments.

Assumed goals of the laboratory to be achieved ("live" list)

• getting acquainted with the declarative nature of Ansible (in contrast to highly imperative bash scripts that also are used in the lab) - as an example of a declarative notation used for the automation of configuration tasks (part 1 of the lab)
• principles of kubernetes networking (part 2, 3 of the lab)
  • the role of CNI based on flannel CNI
  • Services: ClusterIP, NodePort, LoadBalancer; exposing HTTP services using Ingress
  • NetworkPolicy - rules for user-plane traffic filtering within the cluster
• getting acquainted with selected aspects of resource and application management in Kubernetes clusters (part 2, 3 of the lab)
  • controlling the placement of pods by Kubernetes scheduler - taint and tolerations mechanisms
  • other use cases are welcome - to be invented/proposed by the students (examples: horizontal/vertical scaling, custom metrics, etc., ideally tailored to a reasonable "size", but not as simple as changing 'replicas: x' in Deployment !)
• getting acquainted with service monitoring in CNF environments (based on Prometheus/Grafana) (part 3 of the lab)
  • as part of a wider domain referred to as "telemetry"/"observability"
  • apart form installation and very basic operations (viewing information about the state of the cluster in Grafana dashboards), more complex/interesting use cases remain to be prepared and propositions are more than welcome

The means to achieve these goals is the installation of k3s "bare metal" cluster on Raspberry Pi platform, the installation and configuration of selected cluster components (MetalLB, Traefik) and "observability" level applications (Prometheus/Grafana) using various Kubernetes mechanisms/functionalities, and also running simple demo "applications" to illustrate selected concepts.

What we have in the folders/files

ansible-tests/ - simple examples of Ansible constructs; currently: micro-demo illustrating the essence of "gather facts" based on the example of a local host

gettemp.sh - script that uses Ansible playbook get-temp.yaml for checking processor temperature of the RbPis in the cluster

instrukcje/ - lab guides (the main part of the lab)

pi-cluster-install/ - k3s installation source files (bash, Ansible); one of the goals expected from running this part of the lab is to analyze the Ansible templates in order to get acquainted with the principles of declarative approach to task automation. Note: This will be further extended based on Kubernetes manifest examples and later on (in other labs) based on OpenStack HOT).

manifests/ - Kubernetes manifests for the modules installed during the lab, tested implementations (deployments), examples of lab exercises (for now, a simple teaser that strictly corresponds to the current version of the lab guides and is mainly related to learning Kubernetes networking mechanisms)

shutubu.sh - executes Ansible ad-hoc command to shutdown the cluster nodes; after invoking shutubu.sh, you don't have to wait for Ansible to finish its work, and you can immediately shut down your management host (in this case, Ansible shuts down the cluster autonomously, without contacting back the management host). To use it one only needs to customize the cluster node names in the pi-cluster-install/shutdown-hosts.ini file. NOTE: This is the recommended (required) form of shutting down the cluster - to reduce the risk of damage caused by a "hard" disconnection of the power supply. Notice that at the end of the file (in a comment) inctructions to read the raspberry CPU temperature from the command line are also provided (say, a bonus :-) ).

Note: when using ZeroTier (see below) and installing it on a Pi in our cluster, to remotely shut down/start the cluster nodes, remember not to close the Pi that hosts ZeroTier (cf. zt-manual.md). Otherwise remote access to the cluster will be lost. (This note is very specific to the SPIW lab where the members of lab teams can set remote access to their cluster for experimenting.)

temperature_control.md - note on temperature control of Raspberry Pi board (optional)

troubleshooting.txt - descriptions of problems encountered and hints how to solve them; here we describe the ways to solve all kinds of problems that we consider worth mentioning

workloads - in subdirectory busypod: Docker file for container image that can be used in workload generation test of the cluster and example bash script allowing one to produce multiple workload pods using kubectl commands and our container image; it can be used for generating varying workloads in the cluster and monitor/visualise cluster performance metrics with Prometheus and Grafana

zt-config.sh, zt-manual.md - script and instructions for configuring the ZeroTier virtual network enabling remote access to the cluster by all members of a lab team. It also describes how to remotely enable/disable the cluster (enable/disable the Pis).

Experiments ready (or almost ready) for testing as part of self-learning [state of the list: 2024.05.25]

5G Core - deploying 5G Core (free5GC) platform + RAN network simulator (interested persons - please contact me on priv)

• installation and basic tests (e.g. ping 8.8.8.8) of the open source 5G platform (free5GC) in the following configuration: (1) 5G core control plane on the K3s/RaspberryPi cluster, (2) 5G core UPF on the K3s/separate VM/VirtualBox cluster, ( 3) RAN network emulator (equivalent of 5G-radio-network + UE + gNodeB) on a separate VM/VirtualBox
• specific orchestration/management examples applicable at the Kubernetes level are still to be determined (for example, we know that open-source 5G platforms do not scale horizontally well, and at most a form of vertical scaling of the functions can be attempted)