k8s/services: add ingress networking portainer llm and project guides

- Nginx ingress + TLS termination (homelab-ca) - Portainer container UI - CoreDNS internal DNS rewrites - DuckDNS DDNS updater - Ollama LLM inference - 8 project-usage guides (team reference)
2026-07-11 19:17:54 -07:00
parent 1c02e2b831
commit 6d5a0ba205
26 changed files with 3280 additions and 0 deletions
@@ -0,0 +1,183 @@
+# Authentik Federated OIDC & SSO
+
+**Provider:** `https://authentik.riotpiao.homelab.com`  
+**OIDC Issuer:** `https://authentik.riotpiao.homelab.com/application/o/talos-federation/`  
+**Namespace:** `iam`
+
+## When to Use
+
+- **Federated login** — Single sign-on for Grafana, MinIO, Forgejo, Argo CD
+- **User groups** — RBAC via group membership (admins, devops, read-only)
+- **JWT tokens** — Authenticate CLI tools, API clients
+- **SSO for custom apps** — OAuth2/OIDC redirect flow
+
+## Quick Start
+
+**1. Login to Authentik console:**
+```bash
+# Browser: https://authentik.riotpiao.homelab.com
+# Default user: akadmin
+# Password: AUTHENTIK_BOOTSTRAP_PASSWORD (from .env)
+
+# Or via OIDC (after initial setup)
+# Click "Sign in with talos-federation"
+```
+
+**2. Create user:**
+```
+Authentik console → Users → Create
+- Username: alice
+- Email: [email protected]
+- Group: homelab-devs (or homelab-admins)
+```
+
+**3. User logs into Grafana:**
+```
+https://grafana.riotpiao.homelab.com
+→ Sign in with Authentik (auto-redirects to OIDC provider)
+→ Approve access
+→ Logged in as alice (group determines role: Admin or Viewer)
+```
+
+## Configuration
+
+| Key | Value |
+|-----|-------|
+| OIDC provider | `talos-federation` (federated) |
+| OIDC issuer | `https://authentik.riotpiao.homelab.com/application/o/talos-federation/` |
+| JWKS endpoint | `https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration` |
+| Database | PostgreSQL (ddb namespace, authentik user) |
+| Backups | WAL archived to MinIO |
+
+## Common Patterns
+
+**Grafana OIDC login:**
+```yaml
+# k8s/logging/grafana-values.yaml
+grafana:
+  auth.generic_oauth:
+    enabled: true
+    name: Authentik
+    client_id: grafana
+    client_secret: $GRAFANA_OIDC_CLIENT_SECRET  # from Vault
+    auth_url: https://authentik.riotpiao.homelab.com/application/o/authorize/
+    token_url: https://authentik.riotpiao.homelab.com/application/o/token/
+    api_url: https://authentik.riotpiao.homelab.com/application/o/userinfo/
+    scopes: openid profile email groups
+    use_pkce: true
+```
+
+**MinIO OIDC login:**
+```yaml
+# k8s/storage/minio-values.yaml
+minio:
+  identity_oauth:
+    provider: authentik
+    client_id: minio
+    client_secret: $MINIO_OIDC_CLIENT_SECRET
+    redirect_uri: https://minio.riotpiao.homelab.com/oauth_callback
+    config_url: https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration
+    policy_mappings:
+      - group: homelab-admins → consoleAdmin
+      - group: homelab-devops → readwrite
+```
+
+**CLI device code flow (talos-cli):**
+```bash
+# Get JWT token (no kubeconfig needed)
+talos secrets login
+# → Opens browser, approve device code
+# → Token cached in ~/.talos/token
+
+# Use token to access Vault
+talos get cluster/ANTHROPIC_API_KEY --key ANTHROPIC_API_KEY
+# → Vault validates JWT from Authentik
+# → Returns secret
+```
+
+**Custom app OIDC redirect:**
+```go
+import "github.com/coreos/go-oidc/v3/oidc"
+
+provider, _ := oidc.NewProvider(ctx, "https://authentik.riotpiao.homelab.com/application/o/talos-federation/")
+
+verifier := provider.Verifier(&oidc.Config{ClientID: "my-app"})
+
+// After OAuth2 redirect & token exchange:
+idToken, _ := verifier.Verify(ctx, rawIDToken)
+
+// Extract claims
+var claims struct {
+  Email string `json:"email"`
+  Groups []string `json:"groups"`
+}
+idToken.Claims(&claims)
+```
+
+## Group-Based RBAC
+
+**Default groups:**
+- `homelab-admins` — Full cluster access (Grafana Admin, MinIO admin, Argo CD admin, Vault admin)
+- `homelab-devops` — Deploy & monitor (Grafana Editor, MinIO readwrite, Argo CD user)
+- `homelab-viewers` — Read-only (Grafana Viewer, MinIO readonly)
+
+**Assign user to group:**
+```
+Authentik console → Users → alice → Edit
+→ Groups → Add "homelab-devops"
+→ Save
+```
+
+**Custom group-to-role mapping:**
+```yaml
+# Per-service (see cicd-workflow.md, monitoring-metrics.md for examples)
+# Grafana: auth.generic_oauth.role_attribute_path = contains(groups[*], 'homelab-admins') && 'Admin' || 'Viewer'
+# MinIO: policy_mappings (see above)
+```
+
+## Monitoring
+
+**Authentik dashboard:** https://authentik.riotpiao.homelab.com/api/v3/admin/dashboards
+
+**Key metrics:**
+- Login attempts (success/failure)
+- Active sessions
+- Token issuance rate
+- Provider sync status
+
+## Troubleshooting
+
+**Users can't login (redirect loop):**
+```bash
+# Check redirect URI matches
+# Authentik console → Applications → grafana → Edit
+# Verify Redirect URI = https://grafana.riotpiao.homelab.com/login/generic_oauth
+
+# Check OIDC provider is running
+k get pods -n iam -l app=authentik
+```
+
+**JWT token expired:**
+```bash
+# CLI tokens have 24h expiry
+# Re-authenticate
+talos secrets login
+```
+
+**Groups not syncing:**
+```bash
+# Check group attribute in OIDC config
+# Authentik console → Applications → <app> → OIDC Configuration
+# groups_attribute = "groups" (or custom claim name)
+```
+
+**Vault can't validate JWT:**
+```bash
+# Verify JWKS endpoint is accessible
+curl https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration
+
+# Restart Vault to refresh JWKS cache
+k rollout restart -n iam deployment/vault
+```
+
+See `/TROUBLESHOOTING.md` for full incident guide.