335 lines
16 KiB
Markdown
335 lines
16 KiB
Markdown
# 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).
|