From 76f8f491a557bcdaf90633b844f51debe86257d4 Mon Sep 17 00:00:00 2001 From: Marcin-Ramotowski Date: Tue, 11 Aug 2026 17:03:25 +0200 Subject: [PATCH] add documentation to project --- README.md | 334 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 334 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..273a7cd --- /dev/null +++ b/README.md @@ -0,0 +1,334 @@ +# user-microservice + +Mikroserwis REST do zarządzania kontami użytkowników, zbudowany w celu **porównania +narzędzi CI/CD do automatycznego budowania i wdrażania aplikacji skonteneryzowanych**. +Projekt powstał w ramach pracy magisterskiej. + +To repozytorium zawiera **kod aplikacji** oraz **potoki CI** (budowanie, testy, publikacja +obrazu, aktualizacja repozytorium GitOps). Manifesty Kubernetes i konfiguracje narzędzi CD +znajdują się w drugim repozytorium: **[`user-microservice-deploy`](../user-microservice-deploy)**. + +--- + +## Spis treści + +- [Cel projektu](#cel-projektu) +- [Architektura rozwiązania](#architektura-rozwiązania) +- [Porównywane narzędzia (5)](#porównywane-narzędzia-5) +- [Scenariusze pomiarowe](#scenariusze-pomiarowe) +- [Mapa branchy](#mapa-branchy) +- [Aplikacja](#aplikacja) + - [Stos technologiczny](#stos-technologiczny) + - [API](#api) + - [Model danych](#model-danych) + - [Konfiguracja (zmienne środowiskowe)](#konfiguracja-zmienne-środowiskowe) + - [Uruchomienie lokalne](#uruchomienie-lokalne) + - [Testy](#testy) +- [Potoki CI](#potoki-ci) + - [Jenkins](#jenkins) + - [Woodpecker CI](#woodpecker-ci) + - [Argo Workflows](#argo-workflows) + - [Wspólny schemat potoku CI](#wspólny-schemat-potoku-ci) +- [Infrastruktura](#infrastruktura) +- [Pomiar dostarczenia zmiany](#pomiar-dostarczenia-zmiany) +- [Struktura repozytorium](#struktura-repozytorium) + +--- + +## Cel projektu + +Zaprojektowano jednolity proces CI/CD (build → test → publikacja obrazu → wdrożenie na +Kubernetes) i zaimplementowano go w **pięciu narzędziach**, a następnie **zmierzono czas +dostarczenia zmiany** (od commita do działającej aplikacji) dla różnych kombinacji narzędzi +CI i CD. Celem była obiektywna, ilościowa i jakościowa charakterystyka tych narzędzi. + +Proces jest identyczny funkcjonalnie w każdym narzędziu: + +1. Uruchomienie po zdarzeniu `push` do repozytorium aplikacji. +2. Uruchomienie testów jednostkowych (`pytest`). +3. Zbudowanie obrazu kontenera i opublikowanie go w rejestrze (Azure Container Registry), + z tagiem równym SHA commita. +4. Zaktualizowanie manifestu wdrożenia w repozytorium GitOps (`user-microservice-deploy`) — + podmiana taga obrazu na nowy SHA. +5. Wdrożenie nowej wersji na klaster Kubernetes (Azure AKS) przez narzędzie CD. + +## Architektura rozwiązania + +``` + ┌──────────────────────────┐ push ┌───────────────────────────┐ + │ user-microservice (Git) │ ────────────────────▶ │ Potok CI │ + │ kod aplikacji + potoki │ │ Jenkins / Woodpecker / │ + └──────────────────────────┘ │ Argo Workflows │ + └────────────┬──────────────┘ + │ + ┌──────────────────────────────────┬──────────┴───────┐ + │ 1. pytest │ │ + │ 2. docker build + push ▼ ▼ + │ ┌────────────────────┐ ┌───────────────┐ + │ │ Azure Container │ │ commit taga │ + │ │ Registry (ACR) │ │ do repo │ + │ └────────────────────┘ │ GitOps │ + │ └───────┬───────┘ + ▼ │ + ▼ + ┌──────────────────────────┐ obserwuje / webhook ┌───────────────────────────┐ + │ user-microservice-deploy │ ◀──────────────────────────────▶│ Potok CD │ + │ manifesty K8s (GitOps) │ │ kubectl / ArgoCD / Flux │ + └──────────────────────────┘ └────────────┬──────────────┘ + │ apply / sync + ▼ + ┌───────────────────────────┐ + │ Azure Kubernetes (AKS) │ + │ namespace: user-... │ + └───────────────────────────┘ +``` + +## Porównywane narzędzia (5) + +| Rola | Narzędzie | Model działania | +|------|-----------|-----------------| +| **CI** (build/test/push) | **Jenkins** | Potok deklaratywny (`Jenkinsfile`), agent w Kubernetes (pod z wieloma kontenerami) | +| **CI** | **Woodpecker CI** | Potok YAML (`.woodpecker/build.yaml`), backend Kubernetes | +| **CI** | **Argo Workflows** | Sterowany zdarzeniami (Argo Events: `EventSource` + `Sensor` → `Workflow`) | +| **CD** (deploy) | **ArgoCD** | GitOps typu *pull* — synchronizuje stan klastra z repo deploymentowym | +| **CD** | **FluxCD** | GitOps typu *pull* — `GitRepository` + `Kustomization` + `Receiver` | + +Dodatkowo każde narzędzie CI potrafi też pełnić rolę CD w wariancie „to samo narzędzie": +wdrożenie realizowane jest wtedy imperatywnie przez `kubectl apply` (potok wyzwalany +commitem do repo GitOps). + +## Scenariusze pomiarowe + +Pełna macierz to **3 narzędzia CI × 3 warianty CD = 9 scenariuszy**: + +| # | CI | CD | +|---|----|----| +| Scenariusz 1 | Jenkins | Jenkins (`kubectl apply`) | +| Scenariusz 2 | Jenkins | ArgoCD | +| Scenariusz 3 | Jenkins | FluxCD | +| Scenariusz 4 | Woodpecker | Woodpecker (`kubectl apply`) | +| Scenariusz 5 | Woodpecker | ArgoCD | +| Scenariusz 6 | Woodpecker | FluxCD | +| Scenariusz 7 | Argo Workflows | Argo Workflows | +| Scenariusz 8 | Argo Workflows | ArgoCD | +| Scenariusz 9 | Argo Workflows | FluxCD | + +> Scenariusze 1–3 obejmują Jenkinsa, 4–6 Woodpeckera, a 7–9 Argo Workflows — w każdej trójce +> kolejno: to samo narzędzie do CD, ArgoCD oraz FluxCD. + +## Mapa branchy + +Każda kombinacja narzędzi ma osobny branch — w obu repozytoriach. Poniżej odwzorowanie +scenariuszy na branche. + +**Repozytorium aplikacji (`user-microservice`) — definicje CI:** + +| Branch | Zawartość | +|--------|-----------| +| `main` | Kod aplikacji (bazowy), ten README, skrypty analizy | +| `dev` | Gałąź rozwojowa aplikacji | +| `jenkins-pipeline` | CI w Jenkins (`.jenkins/Jenkinsfile`, `podTemplate.yaml`) | +| `woodpecker` | CI w Woodpecker (`.woodpecker/build.yaml`) | +| `argo-workflows` | CI w Argo Workflows / Argo Events (`argo-workflows/*`) | +| `jenkins-fluxcd`, `woodpecker-argocd`, `woodpecker-fluxcd`, `argoworkflow-argocd`, `argoworkflow-fluxcd` | Warianty CI dostrojone do konkretnego narzędzia CD (np. docelowy branch repo GitOps) | + +**Repozytorium deploymentowe (`user-microservice-deploy`) — manifesty i CD:** + +| Branch | Scenariusz | +|--------|-----------| +| `master` | Baza manifestów | +| `jenkins-kubernetes` | Sc 1 — Jenkins wdraża przez `kubectl` | +| `jenkins-argocd-deploy` | Sc 2 — ArgoCD | +| `jenkins-fluxcd-deploy` | Sc 3 — FluxCD | +| `woodpecker-deploy` | Sc 4 — Woodpecker wdraża przez `kubectl` | +| `woodpecker-argocd-deploy` | Sc 5 — ArgoCD | +| `woodpecker-fluxcd-deploy` | Sc 6 — FluxCD | +| `argo-deploy` | Sc 7 — Argo Workflows | +| `argoworkflow-argocd` | Sc 8 — ArgoCD | +| `argoworkflow-fluxcd` / `fluxcd` | Sc 9 — FluxCD | + +> Uwaga: warianty FluxCD używają układu katalogów `apps/` + `clusters/prod/` wymaganego przez +> Flux, pozostałe warianty trzymają manifesty w katalogu głównym repo GitOps. + +--- + +## Aplikacja + +Mikroserwis udostępnia API REST do zarządzania kontami użytkowników wraz z uwierzytelnianiem +JWT (tokeny w ciasteczkach), rolami oraz mechanizmem wylogowania (unieważnianie tokenów). + +### Stos technologiczny + +- **Python 3.11**, **Flask 3** +- **Flask-JWT-Extended** — uwierzytelnianie JWT +- **Flask-SQLAlchemy / SQLAlchemy 2** — ORM +- **MySQL** (produkcyjnie), **SQLite in-memory** (testy) +- **waitress** — produkcyjny serwer WSGI +- **pytest** — testy jednostkowe +- **Docker** — konteneryzacja (obraz bazowy `python:3.11.7-slim-bookworm`) + +### API + +| Metoda | Ścieżka | Opis | Autoryzacja | +|--------|---------|------|-------------| +| `POST` | `/users` | Utworzenie użytkownika | brak (konto `Administrator` wymaga tokena admina) | +| `GET` | `/users` | Lista wszystkich użytkowników | tylko `Administrator` | +| `GET` | `/users/` | Szczegóły użytkownika | właściciel lub `Administrator` | +| `PUT`/`PATCH` | `/users/` | Edycja użytkownika (`PUT` wymaga wszystkich pól) | właściciel lub `Administrator` | +| `DELETE` | `/users/` | Usunięcie użytkownika | właściciel lub `Administrator` | +| `POST` | `/login` | Logowanie, ustawia token JWT w ciasteczku | brak | +| `GET` | `/logout` | Wylogowanie (unieważnienie tokena) | zalogowany | +| `GET` | `/health` | Sprawdzenie stanu aplikacji i połączenia z bazą | brak *(dostępne na branchach z potokami CI/CD)* | + +Przy pierwszym uruchomieniu, jeśli baza jest pusta, tworzone jest domyślne konto administratora +(zob. zmienne `ADMIN_*`). + +### Model danych + +- **`User`** — `id`, `username` (unikalny), `email` (unikalny), `role` (`Administrator`/`User`), + `password` (hash). +- **`RevokedToken`** — `jti` unieważnionych tokenów JWT (blocklist przy wylogowaniu). + +### Konfiguracja (zmienne środowiskowe) + +| Zmienna | Opis | Domyślna | +|---------|------|----------| +| `SQLALCHEMY_DATABASE_URI` | Połączenie do bazy MySQL | — (wymagana poza testami) | +| `JWT_SECRET_KEY` | Klucz podpisujący tokeny JWT | `changeme` | +| `APP_PORT` | Port serwera | `80` | +| `ADMIN_USERNAME` | Login domyślnego admina | `admin` | +| `ADMIN_EMAIL` | E-mail domyślnego admina | `admin@example.pl` | +| `ADMIN_PASSWORD` | Hasło domyślnego admina | `admin` | + +Produkcyjnie sekrety (`SQLALCHEMY_DATABASE_URI`, hasła MySQL) są dostarczane z **Azure Key +Vault** przez sterownik CSI `secrets-store` — zob. repozytorium deploymentowe. + +### Uruchomienie lokalne + +Za pomocą Docker Compose (uruchamia API + MySQL): + +```bash +# przygotuj pliki api/.env oraz db/.env ze zmiennymi środowiskowymi +docker compose up --build +``` + +Bez konteneryzacji: + +```bash +cd api +python3 -m venv env && source env/bin/activate +pip install -r requirements.txt +python3 app.py +``` + +Aplikacja czeka na gotowość bazy danych przy starcie (`wait_for_db`, do 100 prób co 3 s). + +### Testy + +```bash +cd api +python3 -m venv env && source env/bin/activate +pip install -r requirements.txt pytest +python3 -m pytest +``` + +Testy używają bazy SQLite w pamięci (konfiguracja `testing`) i pokrywają operacje CRUD oraz +uwierzytelnianie. Ten sam zestaw testów jest uruchamiany w każdym potoku CI. + +> Wcześniejsze wersje potoków korzystały dodatkowo z testów kontenera **Goss** — zostały one +> ostatecznie usunięte z potoków (por. historia commitów), a walidację przejęły testy +> `pytest` oraz health check po wdrożeniu. + +--- + +## Potoki CI + +Definicje potoków znajdują się na branchach poszczególnych narzędzi. Wszystkie realizują ten +sam trzyetapowy proces: **testy → build&push → commit do GitOps**. + +### Jenkins + +Branch `jenkins-pipeline`, plik `.jenkins/Jenkinsfile`. Potok deklaratywny uruchamiany na +**agencie w Kubernetes** — pod z osobnymi kontenerami do każdego etapu (`podTemplate.yaml`): + +- `python` — uruchomienie `pytest` (wyniki jako JUnit XML), +- `docker` — `docker build` + logowanie do ACR (Azure managed identity) + `docker push`, +- `git` — sklonowanie repo GitOps, podmiana taga obrazu (`awk`) i commit na branch + `jenkins-kubernetes`. + +Build kontenera działa bez uprawnień roota dzięki **sysbox** (`runtimeClassName: sysbox-runc`). + +### Woodpecker CI + +Branch `woodpecker`, plik `.woodpecker/build.yaml`. Trzy kroki (`code-tests`, +`build-and-push`, `gitops-commit`) na backendzie Kubernetes. Docker-in-Docker uruchamiany +lokalnie (`dockerd &`) w kontenerze z sysbox. Sekrety (klucz deploy do Gitea, known hosts) +pobierane z sekretów Woodpeckera. + +### Argo Workflows + +Branch `argo-workflows`, katalog `argo-workflows/`. Podejście **sterowane zdarzeniami** przez +Argo Events: + +- `source.yaml` — `EventSource` (webhook, dwa endpointy: dla repo aplikacji i deploymentowego), +- `sensor.yaml` — `Sensor` reagujący na push i tworzący `Workflow` budujący (etapy: + `checkout` → `tests` → `build-and-push-image` → `gitops-commit`), +- `eventbus-default.yaml` — szyna zdarzeń (NATS), +- `permissions.yaml` — `ServiceAccount` + `Role`/`RoleBinding`, +- `secret-store.yaml` — dostęp do sekretów z Key Vault. + +### Wspólny schemat potoku CI + +Wszystkie trzy narzędzia wykonują tę samą logikę, różniąc się jedynie składnią i modelem +uruchamiania: + +``` +push → [pytest] → [docker build → az acr login → docker push (tag = SHA)] → [clone repo GitOps → awk: podmiana tagu → commit → push] +``` + +Aktualizacja manifestu w repo GitOps jest realizowana identycznym skryptem `awk`, który +znajduje kontener `api` i podmienia w nim tag obrazu na SHA nowego commita. + +## Infrastruktura + +| Element | Zastosowanie | +|---------|--------------| +| **Azure Kubernetes Service (AKS)** | Klaster docelowy; działają na nim także agenci CI oraz kontrolery CD | +| **Azure Container Registry** (`marcin00.azurecr.io`) | Rejestr obrazów | +| **Azure Key Vault** + CSI `secrets-store` | Dostarczanie sekretów do podów | +| **Managed Identity** | Bezhasłowe uwierzytelnianie do ACR / AKS / Key Vault | +| **Gitea** (self-hosted, `gitea.marcin00.pl`) | Repozytoria Git + webhooki wyzwalające potoki | +| **sysbox** (`sysbox-runc`) | Budowanie obrazów bez uprawnień roota (rootless DinD) | +| **NGINX Ingress** | Wystawienie aplikacji (`user-microservice.marcin00.pl`) | + +## Pomiar dostarczenia zmiany + +Metryką porównawczą jest **czas dostarczenia zmiany** (od commita do działającej aplikacji na +klastrze), rozbity na składowe: + +- **trigger_time** — czas od startu potoku CI do faktycznego rozpoczęcia budowania, +- **build_time** — czas budowania i publikacji obrazu, +- **deploy_time** — czas wdrożenia na klaster, +- **full_time** — całkowity czas dostarczenia. + +Pomiar wykonywany jest osobno dla każdego z [9 scenariuszy](#scenariusze-pomiarowe) na +podstawie znaczników czasu z potoków CI/CD, co pozwala porównać narzędzia zarówno pod kątem +całkowitego czasu, jak i wkładu poszczególnych etapów. + +## Struktura repozytorium + +``` +user-microservice/ +├── api/ +│ ├── app.py # fabryka aplikacji Flask, konfiguracja, start serwera waitress +│ ├── views.py # endpointy API (użytkownicy, login/logout) +│ ├── models.py # modele SQLAlchemy: User, RevokedToken +│ ├── utils.py # autoryzacja, oczekiwanie na bazę, inicjalizacja admina +│ ├── requirements.txt # zależności aplikacji +│ └── tests/ # testy pytest (conftest.py, test_users.py) +├── Dockerfile # obraz aplikacji +└── docker-compose.yml # lokalne uruchomienie API + MySQL +``` + +> Definicje potoków CI (`Jenkinsfile`, `.woodpecker/`, `argo-workflows/`) znajdują się na +> odpowiednich branchach — zob. [Mapa branchy](#mapa-branchy).