orca/.ciagent/CLARIFY_v0.14.md

CLARIFY v0.14: Ingress Bootstrap Completeness

Autonomy: full (config autonomy.level = "full") Budget: 10 questions (used: 5 interactive, 5 auto-resolved) Result: all ambiguities resolved; 9 decisions (D-255..D-263) recorded in PROJECT.md

Interactive Questions (resolved with operator)

Q1: iptables vs nft emitter

Ambiguity: Codebase is nft-only (D-218). Operator said "iptables used for SNAT/DNAT". Resolution: D-255 (partial) — Extend the existing nft emitter (internal/emitter/nft.go) with SNAT/MASQUERADE postrouting rules. "iptables" in the operator's description is read as "kernel NAT" — nft is the modern backend. No literal iptables emitter. Confidence: 0.95

Q2: ingress LXC lifecycle

Ambiguity: Should the floating-IP LXC be registered as an orca-managed node or left as a one-shot external proxy? Resolution: D-259 — Register as a managed linux node (name=ingress, addr=<floating-ip>:8443). orca job run pushes traefik dynamic config to it like any linux node. This makes routing-to-other-hosts work. Confidence: 0.92

Q3: Floating-IP network topology

Ambiguity: Where does SNAT run and how does the LXC get the public IP? Resolution: LXC owns floating IP on eth0 (net0 bridge=vmbr0,hwaddr=<mac>,ip=<floating-ip>/<prefix>,gw=<gateway>). nft runs inside the LXC. Matches Hetzner/OVH floating-IP-with-MAC model. Confidence: 0.90

Q4: TLS cert resolver in the image

Ambiguity: The emitted static config references certResolver: orca but never declares the certificatesResolvers.orca block. v0.11 claimed P10 would wire step-ca but it was never implemented. Resolution: D-257 — Bake a certificatesResolvers.orca.tls: { } block pointing at a mounted /etc/orca/step-ca-root.crt CA file. No ACME (offline-first, R-001). If the file is absent at start, traefik logs a warning and serves plain HTTP (graceful degradation). The orca bootstrap pushes the cluster root CA into the container volume. Confidence: 0.90

Q5: Container networking

Ambiguity: nft DNAT targets 127.0.0.1:8080/8443 on the host. How does the podman container receive that traffic? Resolution: D-256 — --network host so traefik binds 127.0.0.1:8080/8443 directly on the host (or LXC) loopback. No container port publishing. Simplest, matches the hybrid R-017 model. Confidence: 0.92

Q6: Dynamic config volume strategy

Ambiguity: How does the podman traefik container consume dynamic config? Today orca job run writes /etc/traefik/dynamic/orca-<svc>.yaml on the host. Resolution: D-258 — Mount /etc/traefik/dynamic from host (-v /etc/traefik/dynamic:/etc/traefik/dynamic:Z). Zero changes to the existing deployRemote WriteFile path. The image's file provider watches /etc/traefik/dynamic as today. Confidence: 0.95

Auto-resolved questions (full autonomy, no operator interaction)

Q7: Floating-IP mode — does the PVE host also register as a node?

Ambiguity: In floating-IP mode, only the ingress LXC handles traffic. Does the PVE host also get registered? Resolution: D-259 — Yes. The PVE host registers as a proxmox node (for pct/qm workload dispatch). The ingress LXC registers as a linux node (for traefik dynamic config pushes). Both are in the registry. Confidence: 0.92

Q8: --ingress-mode persistence

Ambiguity: Should --ingress-mode be stored on the node record so doctor ingress knows which check path to run? Resolution: D-260 — Yes. Add IngressMode field to model.Node + a schema migration (0007). Values: "" (legacy/default for linux/localhost), "native", "floating-ip". Confidence: 0.90

Q9: MAC generation when --mac omitted

Ambiguity: In floating-IP mode, if --mac is not provided, should orca generate one or require it? Resolution: D-261 — Interactive mode: generate a random locally-administered MAC (02:XX:XX:XX:XX:XX) and print it for operator confirmation. --json mode: require --mac explicitly (no silent generation — non-interactive means explicit inputs). Confidence: 0.88

Q10: Proxmox native nft DNAT target

Ambiguity: In native mode, traefik runs inside an LXC. LXC has its own network namespace. nft DNAT to 127.0.0.1:8443 on the PVE host would NOT reach a container inside an LXC (different loopback). What's the DNAT target? Resolution: D-262 — The nft DNAT target is parameterized via NftClusterConfig.DNATTarget (default 127.0.0.1:8443). For proxmox native mode, the DNAT target is the LXC's bridge IP (<lxc-ip>:8443). The LXC gets a DHCP/static bridge IP; orca discovers it after pct start via pct list or pct inspect. Confidence: 0.90

Additional decisions (derived from constraints, no ambiguity)

D-263: LXC podman requirements

Ubuntu 24.04 LXC template does not have podman preinstalled. Bootstrap must:

1. pct create with --features nesting=1,keyctl=1 (required for podman in unprivileged LXC)
2. After LXC start: apt-get update && apt-get install -y podman nftables inside the LXC
3. Then podman pull orca-traefik:<tag> + podman run ...

This adds ~30-60s to the join time. Documented in docs/uat.md.

Image tag strategy

The orca-traefik image uses the same version tag as the orca release (v0.13.x line). The podman reconciler resolves the tag from internal/cli.version. In dev builds (version="dev"), it falls back to latest.

Registry auth

The orca-traefik image is in the same registry/org as orca (git.cloudinit.dev/coreci/). Pulls are anonymous (REQ-045, repo is public). No podman login needed on workers.

Requirements impact

No new requirements beyond REQ-171..REQ-179 (already in REQUIREMENTS.md). The clarify stage confirmed scope and resolved all implementation ambiguities. The 9 decisions (D-255..D-263) are recorded in PROJECT.md.