feat(api): persist DPU IPv6 loopback reservations

[chet]

As it stood, the IPv6 underlay work had nowhere durable to keep one loopback address per DPU. #2390 needs that value before it can render the IPv6 underlay, but there was no pool-backed ManagedHostNetworkConfig.loopback_ip_v6 to provide one.

So, this adds the optional lo-ip-v6 pool and reserves one typed Ipv6Addr per DPU. New DPU rows allocate it in db::machine::create; existing rows get a bounded backfill during startup or AdminGrowResourcePool; discovery and MachineCreator fill any remaining gap; and admin_force_delete_machine returns the reservation to the pool.

Mixed-version deployments need a little extra care here: an older API pod replaces the complete network_config document without fields it doesn't know. The targeted preserve_machine_ipv6_loopback trigger restores only an omitted loopback_ip_v6, while an explicit null from a current writer can still clear it. Backfill reuses the DPU's existing reservation, retries compare-and-swap conflicts, and refuses to write once ForceDeletion wins; deletion asks the pool for the owner's current reservation instead of trusting its earlier machine snapshot.

While collecting the missing address fields into one compare-and-swap write, this also fixes an existing secondary-VTEP leak: discovery could reserve secondary_overlay_vtep_ip, make a second write with the now-stale network_config_version, ignore the false return, and commit the reservation without persisting it. A failed compare-and-swap now fails the transaction, which returns every new address to its pool.

Related issues

This supports #2389

Type of Change

• Add - New feature or capability
• Change - Changes in existing functionality
• Fix - Bug fixes
• Remove - Removed features or deprecated functionality
• Internal - Internal changes (refactoring, tests, docs, etc.)

Breaking Changes

• This PR contains breaking changes

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• No testing required (docs, internal refactor, etc.)

The new coverage walks typed serialization, IPv6 pool listing, reservation reuse and exhaustion, mixed-version writes, startup/runtime backfill, compare-and-swap retries, force-deletion races, discovery, cleanup, and multi-DPU MachineCreator creation.

cargo make format-nightly
cargo make check-format-nightly
cargo make clippy
cargo make carbide-lints
cargo test -p carbide-api-model managed_host_network_config --lib -- --nocapture
cargo test -p carbide-api-db test_ipv6_pool_define_allocate_release --lib -- --nocapture
cargo test -p carbide-api-db ipv6_loopback --lib -- --nocapture
cargo test -p carbide-api-db find_owned_allocation_returns_typed_value_and_rejects_duplicates --lib -- --nocapture
cargo test -p carbide-api-core test_grow_ipv6_loopback_pool_backfills_existing_dpus --lib -- --nocapture
cargo test -p carbide-api-core test_discover_dpu_by_source_ip --lib -- --nocapture
cargo test -p carbide-api-core test_admin_force_delete_dpu_only --lib -- --nocapture
cargo test -p carbide-site-explorer --test integration test_machine_creator_creates_multi_dpu_managed_host

Tests added!

Additional Notes

This intentionally does NOT enable IPv6 FNN rendering by itself. lo-ip-v6 is optional, so sites without it keep their IPv4-only behavior; #2390 is the step that plumbs the persisted value into the underlay.

Deploy this change before configuring lo-ip-v6 or rolling out #2390, so every API pod knows how to preserve the field before it can be written.

The grow-time backfill sees committed DPU rows. A creation transaction that crosses the first lo-ip-v6 grow can land just after that scan; replaying the additive grow or restarting the API reruns the idempotent pass.

AdminGrowResourcePool commits the additive pool change before it starts per-DPU reconciliation. If reconciliation reports exhaustion or a persistent compare-and-swap conflict, the grow itself is already durable and the request can be replayed safely after correcting the pool or contention.

Startup uses the same per-DPU pass but logs a failure and continues, so one exhausted or busy DPU does not take the API offline while completed reservations remain persisted.

Closes #2389

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0db261ca-0190-40f8-a651-a4e4a1802273

📥 Commits

Reviewing files that changed from the base of the PR and between c635e11 and 71e9b24.

📒 Files selected for processing (15)

• crates/api-core/src/handlers/dpu.rs
• crates/api-core/src/handlers/machine.rs
• crates/api-core/src/handlers/machine_discovery.rs
• crates/api-core/src/handlers/resource_pool.rs
• crates/api-core/src/setup.rs
• crates/api-core/src/tests/machine_admin_force_delete.rs
• crates/api-core/src/tests/machine_discovery.rs
• crates/api-core/src/tests/resource_pool.rs
• crates/api-db/migrations/20260722120000_preserve_machine_ipv6_loopback.sql
• crates/api-db/src/machine.rs
• crates/api-db/src/resource_pool.rs
• crates/api-model/src/machine/mod.rs
• crates/api-model/src/machine/network.rs
• crates/api-model/src/resource_pool/common.rs
• crates/api-model/src/test_support/machine_snapshot.rs

🚧 Files skipped from review as they are similar to previous changes (15)

• crates/api-db/migrations/20260722120000_preserve_machine_ipv6_loopback.sql
• crates/api-core/src/setup.rs
• crates/api-core/src/handlers/dpu.rs
• crates/api-core/src/handlers/machine.rs
• crates/api-core/src/tests/machine_discovery.rs
• crates/api-model/src/test_support/machine_snapshot.rs
• crates/api-core/src/handlers/machine_discovery.rs
• crates/api-model/src/resource_pool/common.rs
• crates/api-model/src/machine/mod.rs
• crates/api-core/src/handlers/resource_pool.rs
• crates/api-core/src/tests/resource_pool.rs
• crates/api-core/src/tests/machine_admin_force_delete.rs
• crates/api-model/src/machine/network.rs
• crates/api-db/src/resource_pool.rs
• crates/api-db/src/machine.rs

---

Summary by CodeRabbit

• New Features
  • Added IPv6 loopback address support across DPUs, managed hosts, and machine creation/discovery.
  • Introduced an IPv6 loopback resource pool (lo-ip-v6) with automatic backfill for existing DPUs when the pool is created/expanded.
• Bug Fixes
  • Improved network configuration update behavior to reduce stale/concurrent overwrites via batched updates and safer version handling.
  • Force deletion now best-effort releases IPv6 loopback allocations.
• Maintenance
  • Added a database trigger to preserve existing IPv6 loopback values when updating network_config.

Walkthrough

Adds optional IPv6 loopback configuration and resource-pool support for DPUs, including allocation, backfill, CAS-safe updates, startup and pool-growth reconciliation, stale-snapshot cleanup, persistence compatibility, and expanded integration coverage.

Changes

IPv6 DPU loopback lifecycle

Layer / File(s)	Summary
Configuration and pool contracts crates/api-model/..., crates/api-db/migrations/..., crates/test-harness/..., crates/api-db/src/resource_pool.rs	Adds the IPv6 loopback field, public accessor, resource-pool wiring, persistence trigger, fixtures, builders, snapshots, and serialization coverage.
Allocation and CAS backfill crates/api-db/src/machine.rs, crates/api-db/src/resource_pool.rs	Adds owned-allocation lookup, IPv6 allocation and reuse, force-deletion-aware updates, and retrying DPU backfill with database tests.
Lifecycle reconciliation and cleanup crates/api-core/..., crates/site-explorer/...	Integrates allocation into discovery and DPU creation, reconciles startup and pool growth, releases stale force-deletion allocations, and validates provisioning and accounting.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DPUProvisioning
  participant IPv6LoopbackPool
  participant MachineDatabase
  participant Reconciliation
  DPUProvisioning->>IPv6LoopbackPool: allocate loopback_ip_v6
  IPv6LoopbackPool-->>DPUProvisioning: reserved IPv6 address
  DPUProvisioning->>MachineDatabase: persist network configuration
  Reconciliation->>MachineDatabase: find DPUs missing IPv6 loopback
  Reconciliation->>IPv6LoopbackPool: allocate missing reservations
  Reconciliation->>MachineDatabase: CAS-update loopback_ip_v6

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly captures the main change: persisting DPU IPv6 loopback reservations.
Description check	✅ Passed	The description is detailed and directly matches the implemented IPv6 loopback persistence and backfill changes.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[chet]

@coderabbitai full_review, thanks!

[coderabbitai]

@chet: Starting a complete re-review of #3913.

✅ Action performed

Full review finished.

[coderabbitai]

🧹 Nitpick comments (1)

crates/api-core/src/setup.rs (1)

1028-1033: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider aligning the log severity with the adjacent best-effort reconciliation. This backfill is intentionally non-fatal and its most likely failure (ConcurrentModificationError) is transient and self-healing on the next startup or AdminGrowResourcePool. Emitting it at error while the immediately following update_dpu_asns best-effort step uses warn risks spurious alerts for a benign condition. A warn level would keep the two swallow-and-continue paths consistent.

♻️ Suggested alignment

     if let Err(error) = update_dpu_loopback_ips_v6(db_pool, common_pools).await {
-        tracing::error!(
+        tracing::warn!(
             error = %error,
             "Failed to update IPv6 loopback IPs for DPUs",
         );
     }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@crates/api-core/src/setup.rs` around lines 1028 - 1033, Change the tracing
severity in the update_dpu_loopback_ips_v6 error branch from error to warn,
keeping the existing error context and message unchanged so this non-fatal
reconciliation matches the adjacent update_dpu_asns best-effort path.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@crates/api-core/src/setup.rs`:
- Around line 1028-1033: Change the tracing severity in the
update_dpu_loopback_ips_v6 error branch from error to warn, keeping the existing
error context and message unchanged so this non-fatal reconciliation matches the
adjacent update_dpu_asns best-effort path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 5b963dff-dbf4-4443-a848-fbfa4f3ae8be

📥 Commits

Reviewing files that changed from the base of the PR and between 6db91ec and c635e11.

📒 Files selected for processing (18)

• crates/api-core/src/handlers/dpu.rs
• crates/api-core/src/handlers/machine.rs
• crates/api-core/src/handlers/machine_discovery.rs
• crates/api-core/src/handlers/resource_pool.rs
• crates/api-core/src/setup.rs
• crates/api-core/src/tests/machine_admin_force_delete.rs
• crates/api-core/src/tests/machine_discovery.rs
• crates/api-core/src/tests/resource_pool.rs
• crates/api-db/migrations/20260722120000_preserve_machine_ipv6_loopback.sql
• crates/api-db/src/machine.rs
• crates/api-db/src/resource_pool.rs
• crates/api-model/src/machine/mod.rs
• crates/api-model/src/machine/network.rs
• crates/api-model/src/resource_pool/common.rs
• crates/api-model/src/test_support/machine_snapshot.rs
• crates/site-explorer/src/machine_creator.rs
• crates/site-explorer/tests/integration/machine_creator.rs
• crates/test-harness/src/resource_pool.rs