docs(k8s): add pktvisor sidecar deployment example (#743)

[leoparente]

Refs #743. (Does not auto-close the issue — see discussion there.)

What

Adds a runnable, documented Kubernetes example under a new top-level k8s/ directory that runs pktvisord as a sidecar observing a pod's eth0 traffic, scraped by Prometheus via pod annotations. Docs/example only — no C++, image, or CI changes.

• k8s/pktvisor-sidecar.yaml — a pktvisor-demo Deployment whose pod shares one network namespace across three containers: app (nginx placeholder workload), an optional traffic-gen (busybox wget loop, clearly fenced as removable), and the pktvisord sidecar (capture on eth0, /metrics on :10853).
• k8s/README.md — deploy / verify / generate-traffic / Prometheus scrape config / Grafana dashboard / adapt-to-your-workload / security notes.

Why a sidecar

pktvisord captures via libpcap/AF_PACKET in promiscuous mode, so it needs CAP_NET_RAW + CAP_NET_ADMIN and must run in the network namespace of the interface it monitors. Containers in a pod share one netns, so a pktvisord sidecar sees the app container's eth0. (A standalone pod would only see its own near-empty traffic; a hostNetwork DaemonSet would see node-wide traffic, not a pod's.)

Three load-bearing manifest details (each verified against the source)

• args lead with pktvisord — the image ENTRYPOINT (/entry-cp.sh) selects the binary from the first arg.
• -l 0.0.0.0 — the web/metrics server defaults to binding localhost (cmd/pktvisord/main.cpp), so without this Prometheus could not reach POD_IP:10853.
• -H $(POD_IP)/32 — -H requires a CIDR; a bare IP throws invalid CIDR (parse_host_specs in libs/visor_utils/utils.cpp) and crash-loops. $(POD_IP) is injected via the downward API (fieldRef: status.podIP) on the same container, so Kubernetes substitutes it in args. Use /128 on IPv6 clusters.

Security: the sidecar adds NET_RAW + NET_ADMIN (never privileged) — NET_RAW opens the raw/AF_PACKET socket and NET_ADMIN is needed for promiscuous capture, matching pktvisord's documented setcap cap_net_raw,cap_net_admin. Both are rejected by the PodSecurity baseline/restricted levels, so the namespace needs the privileged level or an exemption.

Validation

python3 YAML parse + kubectl apply --dry-run=client both pass:

YAML OK
deployment.apps/pktvisor-demo created (dry run)

The example is not run against a live cluster in CI; the README documents the port-forward + curl /metrics verification for users.

Reviews

Built spec → plan → adversarial review (which corrected two example-breaking bugs before they shipped: the bare-IP CIDR crash and the localhost bind). Execution was subagent-driven: per-file implementation, a 3-lens adversarial review each (k8s-schema validity with real kubectl dry-run, pktvisord runtime-correctness checked against entry-cp.sh/main.cpp/utils.cpp, spec compliance / README↔manifest consistency / Prometheus scrape-config correctness / technical accuracy), and a whole-branch final review. All passed with no blocking findings.

🤖 Generated with Claude Code

[leoparente]

@codex review

[Copilot]

Pull request overview

Adds a runnable Kubernetes example to deploy pktvisord as a sidecar within a pod so it can observe the pod’s eth0 traffic and expose Prometheus metrics for scraping via pod annotations. This extends the repo’s operational documentation/examples without changing the agent code or build pipeline.

Changes:

• Introduces a new k8s/ directory containing a sidecar-based Deployment manifest for pktvisord.
• Adds step-by-step documentation for deploying, verifying metrics, generating demo traffic, and configuring Prometheus scraping.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
k8s/README.md	Documents how to deploy/verify a pktvisord sidecar and configure Prometheus scraping via annotations.
k8s/pktvisor-sidecar.yaml	Provides a Deployment manifest with an app container, optional traffic generator, and a pktvisord sidecar exposing /metrics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 912dd42ee3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[github-actions]

LCOV of commit e873985 during Debug Builds #175

  lines......: 82.6% (14324 of 17341 lines)
  functions..: 73.2% (1451 of 1982 functions)
  branches...: no data found

Files changed coverage rate: n/a

Full coverage report

[leoparente]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9a859e3c46

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[leoparente]

@codex review

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7ac5c4df3c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[leoparente]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5d6ec1dfa2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[leoparente]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Can't wait for the next one!

Reviewed commit: e873985de3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".