145 lines
5.0 KiB
Markdown
145 lines
5.0 KiB
Markdown
# OTel BI Forecast App
|
|
|
|
OpenTelemetry-instrumented BI platform with microservices, frontend OIDC login plus backend token validation, read-only MSSQL data warehouse access, and PostgreSQL persistence for writable app data.
|
|
|
|
## Architecture
|
|
|
|
- Frontend: React + TypeScript (`frontend/`)
|
|
- Backend microservices (`backend/microservices/`):
|
|
- `api_gateway`: public API, frontend JWT validation, internal token minting, routing/audit forwarding
|
|
- `bi_query`: read-only MSSQL warehouse queries
|
|
- `analytics`: forecasting, rankings, recommendations
|
|
- `persistence`: PostgreSQL writes/reads for app data
|
|
- Data sources:
|
|
- MSSQL (`WorldWideImporters`, `AdventureWorks2022DWH`) read-only only
|
|
- PostgreSQL writable app store (`audit_logs`, `forecast_runs`, `ranking_runs`, `recommendation_runs`)
|
|
- Observability: OTLP/HTTP to Grafana Alloy (`/v1/traces`, `/v1/metrics`)
|
|
|
|
## Authentication Model
|
|
|
|
- Frontend uses OIDC Authorization Code + PKCE.
|
|
- `api_gateway` validates frontend bearer JWT (`iss`, `aud`, signature, expiry, optional scopes) against configured JWKS.
|
|
- `api_gateway` mints short-lived internal service tokens (`x-internal-service-token`) for service-to-service calls.
|
|
- Internal services (`analytics`, `bi_query`, `persistence`) require valid internal token on non-health endpoints and enforce issuer/type checks.
|
|
- Combine with K8s network controls (ClusterIP, NetworkPolicy, mTLS/service mesh where available).
|
|
|
|
Frontend uses OIDC Authorization Code + PKCE with:
|
|
- `VITE_OIDC_ENABLED=true`
|
|
- `VITE_OIDC_AUTHORITY=<issuer-base-url>`
|
|
- `VITE_OIDC_CLIENT_ID=<frontend-client-id>`
|
|
- `VITE_OIDC_REDIRECT_URI=<frontend-url>`
|
|
- `VITE_OIDC_POST_LOGOUT_REDIRECT_URI=<frontend-url>`
|
|
- `VITE_OIDC_SCOPE=openid profile email`
|
|
|
|
Backend security env:
|
|
- `REQUIRE_FRONTEND_AUTH=true`
|
|
- `FRONTEND_JWT_ISSUER_URL=<oidc-issuer>`
|
|
- `FRONTEND_JWT_JWKS_URL=<issuer-jwks-url>`
|
|
- `FRONTEND_JWT_AUDIENCE=<api-audience>`
|
|
- `FRONTEND_REQUIRED_SCOPES=<space-separated>`
|
|
- `INTERNAL_SERVICE_SHARED_SECRET=<strong-random-secret-at-least-32-bytes>`
|
|
- `INTERNAL_SERVICE_ALLOWED_ISSUERS=api-gateway`
|
|
- `MSSQL_TRUST_SERVER_CERTIFICATE=false` and `POSTGRES_SSLMODE=require` for production TLS validation
|
|
|
|
## Local Run (Microservices)
|
|
|
|
```bash
|
|
cd backend
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -e .
|
|
cp .env.example .env
|
|
```
|
|
|
|
Run services in separate terminals:
|
|
|
|
```bash
|
|
uvicorn microservices.persistence.main:app --host 0.0.0.0 --port 8103 --reload
|
|
uvicorn microservices.bi_query.main:app --host 0.0.0.0 --port 8101 --reload
|
|
uvicorn microservices.analytics.main:app --host 0.0.0.0 --port 8102 --reload
|
|
uvicorn microservices.api_gateway.main:app --host 0.0.0.0 --port 8000 --reload
|
|
```
|
|
|
|
Frontend:
|
|
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
cp .env.example .env
|
|
npm run dev
|
|
```
|
|
|
|
Set:
|
|
- `VITE_API_BASE_URL=http://localhost:8000`
|
|
- `VITE_OTEL_COLLECTOR_ENDPOINT=http://alloy.monitoring.svc.cluster.local:4318`
|
|
|
|
Frontend sends `Authorization: Bearer <token>` from the active OIDC session.
|
|
|
|
## API Endpoints (via Gateway)
|
|
|
|
- `GET /api/health`
|
|
- `GET /api/telemetry/status`
|
|
- `GET /api/kpis`
|
|
- `GET /api/history?days_back=365`
|
|
- `GET /api/forecasts?days=30`
|
|
- `GET /api/rankings?top_n=10`
|
|
- `GET /api/recommendations`
|
|
- `GET /api/dashboard`
|
|
- `GET /api/storage/audit-logs?limit=50`
|
|
- `GET /api/storage/forecasts?limit=50`
|
|
- `GET /api/storage/rankings?limit=50`
|
|
- `GET /api/storage/recommendations?limit=50`
|
|
|
|
## K8s Deployment
|
|
|
|
Example manifest:
|
|
- `k8s/microservices.yaml`
|
|
|
|
It includes:
|
|
- namespace, config map, secret
|
|
- deployments/services for `api-gateway`, `bi-query`, `analytics`, `persistence`
|
|
- Alloy endpoint wiring via `OTEL_COLLECTOR_ENDPOINT`
|
|
- frontend JWT validation config and internal token secret wiring
|
|
- hardened pod security defaults (`runAsNonRoot`, dropped capabilities, `seccompProfile: RuntimeDefault`, no auto-mounted service account token)
|
|
|
|
## Read-Only Guarantee
|
|
|
|
- MSSQL connections enforce `ApplicationIntent=ReadOnly`.
|
|
- Warehouse query layer only accepts `SELECT`/`WITH`.
|
|
- Writable operations are isolated to PostgreSQL only.
|
|
- Use SQL Server account with `SELECT` grants only.
|
|
|
|
## OTel Coverage
|
|
|
|
- Frontend:
|
|
- W3C trace/baggage propagation
|
|
- document-load, user-interaction, fetch, XHR instrumentation
|
|
- manual dashboard spans
|
|
- Backend services:
|
|
- FastAPI request spans
|
|
- HTTP client spans for service-to-service calls
|
|
- SQLAlchemy spans (MSSQL and PostgreSQL)
|
|
- manual analytics + persistence spans
|
|
- audit/snapshot persistence telemetry
|
|
|
|
## Verification
|
|
|
|
1. Call `GET /api/telemetry/status` with a valid frontend bearer token.
|
|
2. Confirm response has non-null `trace_id` and `span_id`.
|
|
3. Trigger `GET /api/dashboard`; then verify records in `GET /api/storage/audit-logs`.
|
|
4. In Grafana/Tempo, confirm trace path includes:
|
|
- `api-gateway` span
|
|
- `analytics` span
|
|
- `bi-query` MSSQL spans
|
|
- `persistence` PostgreSQL spans
|
|
5. Call internal service endpoint directly without `x-internal-service-token` and verify it returns `401`.
|
|
|
|
## Optional Tests
|
|
|
|
```bash
|
|
cd backend
|
|
source .venv/bin/activate
|
|
pip install -e .[dev]
|
|
pytest
|
|
```
|