docs: document how the K8s reporter handles Job and CronJob pods #387

The question

A user asked:

I was just wondering how K8s Jobs and CronJobs could be handled. Is it detected by the reporter?

Our docs don't answer this. tutorials/report_k8s_envs.md and client_reference/kosli_snapshot_k8s.md both describe snapshots at the pod level ("running pods", "pod container images digests and creation timestamps") but say nothing about what that means for workloads whose pods are short-lived by design.

Actual behavior (from the CLI source)

Verified in kosli-dev/cli at v2.39.2 — internal/kube/kube.go:

• The reporter collects pods, not workload kinds. It has no awareness of Job or CronJob objects — a Job pod is reported exactly like a Deployment pod.
• Only pods in phase Running or Failed are reported (kube.go:203). Pods in Succeeded — which is where a completed Job pod ends up — are never reported.
• A Failed pod whose containers have no image IDs is skipped with a warning (kube.go:54).
• Reported pod data includes the pod's owner references (PodData.Owners), so the Job/CronJob ownership chain does reach Kosli — but nothing in the docs says whether or how that is surfaced.

The practical consequence: a Job pod appears in a snapshot only if it happens to be running at the moment the snapshot is taken. With the Helm chart's default 5-minute cronSchedule, a job that finishes in under 5 minutes may never be captured at all, and one that is captured then disappears from the next snapshot.

What to add

A short section in tutorials/report_k8s_envs.md — something like "What gets reported" — covering:

1. Snapshots are pod-level and workload-kind agnostic.
2. Which pod phases are reported (Running, Failed) and which are not (Succeeded, Pending).
3. What this means for Job and CronJob pods: captured only while running, so short-lived jobs are sampled at best, and completed runs leave no trace in the environment.
4. Guidance for teams that need a record of job runs — environment snapshots are the wrong tool for that; point to attesting the job's artifact to a flow/trail instead.

If any of point 1–3 also belongs on the CLI reference page, it has to be fixed in the CLI's Go long description (cmd/kosli/snapshotK8S.go) — client_reference/kosli_snapshot_k8s.md is generated and hand-edits are reverted on the next CLI release.

To confirm before writing

• Do short-lived Job pods produce start/stop churn in environment snapshot diffs, and is there a recommended way to keep that noise out of an environment?
• Are pod owner references surfaced anywhere in the UI or API today?
• What is the recommended pattern for job-type workloads — a separate Kosli environment, namespace exclusion, or flow attestations?

Scope

Vanilla Kubernetes Job and CronJob only. Deliberately not covering Argo Workflows or other CRD-based workflow engines.