pikram/user-microservice
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add documentation to project

Browse Source
This commit is contained in:
Marcin-Ramotowski
2026-08-11 17:03:25 +02:00
parent d3d3c98f99
commit 76f8f491a5
1 changed files with 334 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+334
View File
@@ -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/<id>` | Szczegóły użytkownika | właściciel lub `Administrator` |
| `PUT`/`PATCH` | `/users/<id>` | Edycja użytkownika (`PUT` wymaga wszystkich pól) | właściciel lub `Administrator` |
| `DELETE` | `/users/<id>` | 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 | `[email protected]` |
| `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).