Merge branch 'main' into feature/multi-cloud

docs/DEVELOPER-GUIDE.md

@@ -962,6 +962,46 @@ User sees application (authenticated)
 
 ---
 
+### Accessing Authenticated User Information
+
+The auth sidecar handles all authentication before requests reach your application. Your app never sees unauthenticated traffic — the sidecar returns 401 or redirects to the IdP first.
+
+After successful authentication, the sidecar forwards the request to your application with user identity injected as HTTP headers:
+
+| Header | Description | Available in |
+|--------|-------------|-------------|
+| `X-Auth-User` | Username or display name | Token, OIDC, MCP |
+| `X-Auth-Email` | User email address | OIDC |
+| `X-Auth-Subject` | OIDC `sub` claim (stable user ID) | OIDC, MCP |
+| `X-Auth-Groups` | Comma-separated group memberships | OIDC (if scope includes `groups`) |
+| `X-Auth-Token` | The validated access token | All modes |
+
+**Your application reads these headers — no auth library needed:**
+
+```javascript
+// Express.js example
+app.get('/profile', (req, res) => {
+  const user = req.headers['x-auth-user'];
+  const email = req.headers['x-auth-email'];
+  res.json({ user, email });
+});
+```
+
+```python
+# Flask example
+@app.route('/profile')
+def profile():
+    user = request.headers.get('X-Auth-User')
+    email = request.headers.get('X-Auth-Email')
+    return jsonify(user=user, email=email)
+```
+
+**Why this is safe**: The Kyverno-generated NetworkPolicy restricts ingress to the sidecar port only. Traffic cannot bypass the sidecar to reach the application port directly, so the `X-Auth-*` headers can be trusted unconditionally.
+
+**Key principle**: Your application is zero-trust-unaware by design. It reads headers and renders UI. All authentication complexity lives in the sidecar and Kyverno policy.
+
+---
+
 ### Authentication Configuration Reference
 
 #### Helm Values Schema

docs/REFERENCE.md

@@ -631,6 +631,15 @@ retry:
 4. 40 seconds
 5. 80 seconds (capped at 3 minutes)
 
+### Global Settings (`argocd-cm`)
+
+| Setting | Value | Purpose |
+|---------|-------|---------|
+| `application.resourceTrackingMethod` | `annotation` | Track resources via annotations |
+| `timeout.reconciliation` | `60s` | Reconciliation interval |
+| `admin.enabled` | `true` | Enable admin account |
+| `git.submodule.enabled` | `false` | Disable git submodule checkout — submodules are not needed for manifest generation |
+
 ---
 
 ## Infrastructure Components
@@ -1098,6 +1107,33 @@ kubectl get secret keycloak-client-<app> -n keycloak -o jsonpath='{.metadata.ann
 
 **See**: [Developer Guide - Adding a New Keycloak Client](DEVELOPER-GUIDE.md#adding-a-new-keycloak-client)
 
+### Karpor
+
+**Chart**: `karpor` from `https://kusionstack.github.io/charts`
+**Version**: 0.7.6 (app v0.6.4)
+**Namespace**: `karpor`
+**Sync Wave**: 1
+
+**Purpose**: Kubernetes visualization and intelligence tool. Provides cross-cluster resource search, compliance checking, and topology visualization. Gives platform engineers a unified view of all cluster resources and their relationships.
+
+**Architecture** (4 components):
+- **Server** — main Karpor API/UI (port 7443)
+- **Syncer** — syncs cluster state into the search index
+- **ElasticSearch** — search backend for resource indexing
+- **etcd** — persistent key-value store (10Gi PVC)
+
+**Configuration** (`infra/values/base/karpor-values.yaml`):
+- `namespaceEnabled: false` — ArgoCD manages namespace creation
+- Default resource limits tuned for small clusters
+- ElasticSearch: 2 CPU / 4Gi memory (the heaviest component)
+- AI features available but not enabled (requires `server.ai.authToken` + backend config)
+
+**Access**: Port-forward to reach the UI:
+```bash
+kubectl port-forward svc/karpor-release-server -n karpor 7443:7443
+# Open https://localhost:7443
+```
+
 ### Renovate
 
 **Chart**: `renovate` (OCI: `ghcr.io/renovatebot/charts`)
@@ -1545,7 +1581,23 @@ Forward to Application (localhost:3000)
 Application processes request
 ```
 
-**See**: [Developer Guide - Enabling Authentication](DEVELOPER-GUIDE.md#enabling-authentication-for-applications) for usage examples.
+#### Forwarded Headers
+
+After successful authentication, the sidecar injects user identity as HTTP headers before forwarding the request to the application container:
+
+| Header | Description | Auth Modes |
+|--------|-------------|------------|
+| `X-Auth-User` | Username or display name | Token, OIDC, MCP |
+| `X-Auth-Email` | User email address | OIDC |
+| `X-Auth-Subject` | OIDC `sub` claim (stable user ID) | OIDC, MCP |
+| `X-Auth-Groups` | Comma-separated group memberships | OIDC (if `groups` scope) |
+| `X-Auth-Token` | The validated access token | All modes |
+
+These headers are trustworthy because the auto-generated `NetworkPolicy` restricts pod ingress to the sidecar port only — external traffic cannot reach the application container directly, so headers cannot be spoofed.
+
+Applications should read these headers to obtain authenticated user information (e.g. for display, authorisation decisions, or audit logging) instead of implementing their own authentication.
+
+**See**: [Developer Guide - Accessing Authenticated User Information](DEVELOPER-GUIDE.md#accessing-authenticated-user-information) for code examples.
 
 ---