Spec popisuje operativní rovinu workeru v produkci: deployment topologie, lifecycle, observabilita, secrets, resource limits, image build, runbook položky. Nepokrývá doménové business rules ani Anthropic SDK kontrakt — to je v worker-runtime.md.

1. Deployment topologie

1.1 K8s topologie (LIVE)

flowchart TB
    subgraph CP[ns 'talkide-prod' — control-plane]
        BE[talkide-be Deployment<br/>2 repliky alpha]
        FE[talkide-fe Deployment<br/>2 repliky alpha]
        GW[Gateway-proxy<br/>součást BE]
    end

    subgraph T1[ns 'mirek-dev' — tenant-env 1]
        W1[talkide-worker Deployment<br/>1 replika]
        S1[talkide-worker-token<br/>identity-token]
        N1[PVC claude-sessions<br/>NFS RWM]
    end

    subgraph T2[ns 'popelkam-dev']
        W2[talkide-worker Deployment<br/>1 replika]
        S2[secret]
        N2[PVC]
    end

    subgraph T3[ns 'h-talkide']
        W3[talkide-worker Deployment<br/>1 replika]
        S3[secret]
        N3[PVC]
    end

    BE -.->|HTTP+SSE<br/>HMAC| W1
    BE -.->|HTTP+SSE<br/>HMAC| W2
    BE -.->|HTTP+SSE<br/>HMAC| W3

Aktuální stav (2026-05-23):

Jeden worker pod = jedna replika = stateful (drží live SDK runtime). Multi-replica per ns je v současné alpha out-of-scope (viz § 4.2).

1.2 Service discovery

Control-plane BE volá worker přes K8s DNS:

talkide-worker.{tenant}-{env}.svc.cluster.local:8090

K8sWorkerProvisioner v BE drží mapping (tenantId, envId) → worker Service URL. Provisioning workeru = K8sWorkerProvisioner.buildWorkerDeployment (#275 LESSON — Recreate strategy v CREATE cestě, patch cesta strategii nepřepisuje, viz CLAUDE.md “Pozn. #275”).

1.3 Image registry

registry.digitalocean.com/talkide/talkide-worker:<git-sha>. DO Container Registry Professional plan (od #195 zrušen 5-repo limit). Image build pipeline: GitLab CI v talkide/talkide-worker (manual trigger, viz CLAUDE.md “CI/CD — manual cost gate”).

2. Lifecycle

2.1 Worker pod provisioning

Trigger: prvni Mara turn v tenant-environment, nebo explicitní EnvironmentService.ensureNamespace volání (ADR-026 lazy get-or-create).

Kroky (K8sWorkerProvisioner):

1. Ensure namespace {tenant}-{env} existuje (ADR-015 namespace provisioner).
2. Ensure K8s Secret talkide-worker-token (klíč identity-token + TALKIDE_GATEWAY_BASE_URL).
3. Ensure PVC claude-sessions (NFS RWM, sdílený přes všechny workery v ns).
4. Ensure ServiceAccount + RoleBinding (scope: batch.Job CREATE/GET/WATCH/DELETE — pro budoucí gradle Job dispatch, § 7.1 v worker-runtime).
5. Apply worker Deployment + Service (port 8090).
6. Wait for readiness probe.

Idempotence: všechny kroky jsou idempotentní — opakované volání nepoškodí existující resources.

2.2 Worker image upgrade

Helm talkide-platform chart obsahuje per-tenant-env worker manifest. Image bump = helm upgrade talkide ... → rolling restart workerů.

Důsledek pro Mara sessions: SDK resume(conversationId) z NFS state. Krátká SSE re-connection window (≈ 5–10 s) v BE → user vidí re-connect indicator. 3-week resume neprerušuje BE redeploy (viz worker-runtime § 5).

2.3 Tenant deprovision

OPEN (be#120 medium). Současné chování: namespace + NFS PVC zůstávají po smazání posledního projektu uživatele. Implementace fáze post-alpha.

3. Resource limits

3.1 Worker pod

NFS PVC claude-sessions velikost: 5 Gi v alfa (sdíleno přes všechny workery v ns). Session state ≈ 1–5 MB per konverzace × tisíce konverzací → roste s tenantem; monitoring přes du -sh v worker pod startup hook.

3.2 K8s nodes

Worker pody žijí na DO node poolu talkide-prod-pool-1 (s-4vcpu-8gb). s-2vcpu-4gb jsou nedostatečné — BE baseline 1.2 GB + worker × N + Kaniko Joby by node OOM-killed (incident ověřený u BE podu, viz CLAUDE.md “DigitalOcean infra reference”).

3.3 ResourceQuota per ns (plánováno post-alpha)

ADR-024 § Decision 5: ResourceQuota per {tenant}-{env} ns klíčované plánem uživatele. Plan tier → ResourceQuota (CPU/memory ceiling) + LimitRange (per-pod default). V alfa fázi (1–3 tenanti) ResourceQuota nenastavena — fair-use enforcement leží na FUP / UserBudget (UC-08001).

4. Observability

4.1 Health probes

Konkrétní implementace v talkide-worker/src/server/httpServer.ts.

4.2 Logging

• stdout = strukturovaný JSON log (level, timestamp, conversationId, message). Container log collector zachytává a posílá do platform log aggregátoru (DO LogStream → BetterStack nebo ekvivalent).
• stderr = uncaught exceptions, fatal startup errors.
• Žádný NDJSON kontroles protokol mimo SSE response k GET /sessions/{id}/stream.

⚠️ Dočasný debug (CLAUDE.md): BE LOGGING_LEVEL_COM_MDDSUMMER_TALKIDE=DEBUG po dokončení cutoveru C9 vrátit na INFO. Worker DEBUG flag pro Harness.ts v K8s env LOG_LEVEL=debug.

4.3 Metrics

Worker exponuje Prometheus metrics na :9091/metrics (TBD — open task; v alfa zatím neimplementováno, viz § 6.4). Minimální plán:

• worker_active_sessions{tenant_env} gauge
• worker_session_duration_seconds{outcome} histogram
• worker_tool_use_total{tool_name} counter
• worker_gateway_call_duration_seconds{result} histogram

4.4 Tracing

W3C traceparent propagace: BE generuje trace context, posílá v HTTP hlavičce na worker. Worker propaguje do gateway-proxy callu zpět na BE → koherentní trace přes celý turn. Anthropic SDK custom HTTP headers — TBD (otevřená otázka).

5. Secrets management

5.1 ANTHROPIC_API_KEY

Žije VÝHRADNĚ v control-plane BE pod, K8s Secret talkide-anthropic-creds v ns talkide-prod. Worker pod ho NIKDY nedostává — to je core invariant ADR-024 (gateway-proxy pattern).

Rotace: kvartální (90 dní). Při podezření na leak okamžitá rotace = K8s Secret update + BE rolling restart. Worker rotace netýká.

5.2 Identity token (talkide-be#245)

Per {tenant}-{env} K8s Secret talkide-worker-token:

Identity-token mechanismus:

• identity-token je long-lived HMAC token s scope = IDENTITY_SCOPE_CID (TTL 90 dní, nikoli 120 s). Namísto conversationId v cid nese speciální identity scope — tím BE pozná, že jde o identitní volání, ne o per-request gateway request.
• Worker ho drží trvale v env TALKIDE_WORKER_IDENTITY_TOKEN (načteno ze secretu při startu podu).
• Před každým Mara turn worker volá control-plane mint endpoint (/api/v1/worker-gateway/token/mint) autentizovaný pomocí identity-token → BE mintne čerstvý short-lived WorkerToken (TTL 120 s, scope = conversationId). Tento krátkodobý token se předá do LocalGatewayProxyServer, který ho připojuje k per-request gateway callu.
• Worker nikdy nevolá new Anthropic({ authToken: ... }) přímo s gateway URL — viz § 5.2 proxy architektura v worker-runtime.md.
• Token je per-pod stabilní; rotace = update secret + restart workeru (viz worker-runtime § 7.5).

5.3 K8s ServiceAccount RBAC

Worker SA v {tenant}-{env} ns má:

- apiGroups: ["batch"]
  resources: ["jobs"]
  verbs: ["create", "get", "watch", "delete", "list"]

Striktně Role + RoleBinding v ns — NIKDY ClusterRole. Verifikace v deploy review.

6. Roadmap & open items

7. Runbook

7.1 Worker pod zaseknutý / unresponsive

Příznak: BE SSE k workeru timeoutuje, žádné assistant_chunk eventy. Mara v UI “spinning”.

Diagnóza:

kubectl get pods -n {tenant}-{env}
kubectl logs -n {tenant}-{env} talkide-worker-<hash> --tail 200
kubectl exec -n {tenant}-{env} talkide-worker-<hash> -- ls /data/claude/projects

Akce:

1. Identifikuj zaseknutý SSE call: Harness.ts log → query() timeout? Anthropic 5xx?
2. Restart worker pod: kubectl delete pod -n {tenant}-{env} talkide-worker-<hash> → SDK resume() pickne session z NFS.
3. Pokud problém přetrvává: zkontroluj NFS PVC mount status, NFS server health.

Souvisí s open issue be#117 (Mara zaseknutá když Theo padne — commit 655c233 NEdeployed).

7.2 NFS volume full

Worker pod CrashLoopBackOff s ENOSPC při query() startu. NFS PVC plný.

Akce:

1. du -sh /data/claude/projects/* ve worker pod → identifikuj nejstarší / largest session directories.
2. Cleanup uzavřených konverzací: TBD admin endpoint v BE — interim manual rm -rf přes kubectl exec.
3. Resize PVC (infra#12 backup strategy je open).

7.3 Worker → gateway 401

Worker HMAC token nevalidní. Příznak: každý turn padá s 429/401 z gateway-proxy.

Akce:

1. kubectl get secret -n {tenant}-{env} talkide-worker-token -o jsonpath='{.data.identity-token}' | base64 -d
2. Ověř, že token začíná TalkideWorker cid=0;exp= a není prošlý (epoch v exp=).
3. Re-issue token přes admin endpoint nebo K8sWorkerProvisioner shell (re-mint identity token).

8. Vztah k jiným ADR a specifikacím

9. Co bylo a už není