feat: live NetBox IP conflict check on reservation add form

[marcinpsk]

Summary

When creating a new reservation via the UI, check whether the IP address the user is typing already exists in NetBox IPAM. Surface the result as an inline advisory on the form — no blocking, just visibility.

Motivation

Currently the form gives no feedback about the NetBox state of an IP until after the reservation is saved and optionally synced. If the IP already exists in NetBox and was not created by Kea sync (e.g. it is a manually maintained entry assigned to a device interface), the user has no way to know this until sync silently overwrites it.

Proposed behaviour

On blur of the IP address field (DHCPv4: ip_address, DHCPv6: ip_addresses), fire a lightweight AJAX call to a new server-scoped endpoint. The endpoint queries NetBox and returns a small HTML fragment injected below the field:

NetBox state	Fragment
IP not in NetBox	(empty — no output)
IP exists, description starts with "Synced from Kea DHCP" or is blank	Blue info: "Already in NetBox IPAM (status: reserved). Saving will update it."
IP exists, foreign description or assigned to an interface	Yellow warning: "This IP exists in NetBox and was not created by Kea sync (status: active, description: 'Router loopback', assigned to: Router-1/eth0). Syncing will overwrite this entry."

The check is advisory only — the reservation can still be saved regardless. It only runs in Add mode; in Edit mode the IP field is already disabled and cannot change.

Implementation plan

1. New view — ReservationCheckNetboxIPView (sync_views.py)

• GET /plugins/netbox-kea/servers/<pk>/reservation/check-ip/?ip=<addr>
• Server-scoped via pk so existing Server permission checking applies.
• Validates ip param with netaddr.IPAddress; returns HttpResponse("") on invalid/missing.
• Calls sync.get_netbox_ip(ip_str) to look up the NetBox entry.
• Determines ownership: description.startswith("Synced from Kea DHCP") or blank description → Kea-managed; anything else → foreign.
• Returns rendered netbox_kea/inc/reservation_ip_check.html fragment.

2. New fragment template — netbox_kea/inc/reservation_ip_check.html

Three states described in the table above. Shows IP address as a link, status badge, description, and assigned object when present.

3. URL registration — urls.py

path(
    "servers/<int:pk>/reservation/check-ip/",
    views.ReservationCheckNetboxIPView.as_view(),
    name="reservation_check_ip",
),

4. Template change — server_reservation_form.html

Add a target div after {% render_form form %}:

<div id="netbox-ip-check"></div>

Add an inline <script> block (plain fetch, no HTMX dependency) that:

• Skips attachment when action != "Add".
• Selects #id_ip_address (v4) or #id_ip_addresses (v6) based on dhcp_version.
• On blur, takes the first comma-separated IP (v6 may have multiple), fetches the endpoint, swaps the fragment into #netbox-ip-check.
• Clears the div when the field is empty.

What does NOT change

• sync.py — no changes to sync functions or ownership logic.
• Form fields — no new form fields, no widget attribute changes.
• POST behaviour — saving the reservation and syncing to NetBox work exactly as today; this is purely a pre-submission hint.

[coderabbitai]

🔗 Related PRs

#29 - Feat/boot [merged]
#59 - fix: per protocol credentials [merged]
#62 - feat: sync Kea subnets to NetBox Prefixes and pools to IPRanges [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Leverage existing get_netbox_ip() function from sync module for IP lookups
• Follow the established fragment-returning view pattern from _BaseSyncView but as a GET endpoint
• Use standard Bootstrap alert components for consistent UI styling
• Keep JavaScript minimal with plain fetch API as specified (no HTMX dependency)

Implementation Steps

Phase 1: Backend Endpoint

Create a new server-scoped GET endpoint that checks whether an IP exists in NetBox and returns an HTML fragment indicating its status and ownership.

Task 1: Create ReservationCheckNetboxIPView

Add a new view class to handle IP lookups against NetBox IPAM and return appropriate HTML fragments.

• Add ReservationCheckNetboxIPView class to netbox_kea/views/sync_views.py following the existing _BaseSyncView pattern
• Use ConditionalLoginRequiredMixin for authentication and fetch server with Server.objects.restrict(request.user, "view") for authorization
• Implement GET handler that extracts ip query parameter and validates with netaddr.IPAddress; return empty HttpResponse("") on invalid/missing
• Call sync.get_netbox_ip(ip_str) to look up the IP; return empty response if not found
• Determine ownership by checking if description starts with "Synced from Kea DHCP" or is blank (Kea-managed) vs any other value (foreign)
• Build context dict with nb_ip, ownership flag, and render the fragment template

Task 2: Register URL Pattern

Add the URL pattern to make the endpoint accessible.

• Add path entry to netbox_kea/urls.py in the server-scoped section (before the include(get_model_urls(...)) line)
• Pattern: servers/<int:pk>/reservation/check-ip/ with name reservation_check_ip
• Point to views.ReservationCheckNetboxIPView.as_view()
• Export the view symbol from netbox_kea/views/__init__.py

🤖 Prompt for AI agents

Implement a new server-scoped GET endpoint for checking NetBox IP conflicts. The
goal is to look up an IP in NetBox IPAM and return an HTML fragment indicating
its existence and ownership.

**1. Add `ReservationCheckNetboxIPView` to `netbox_kea/views/sync_views.py`:**
- Follow the existing `_BaseSyncView` pattern
- Use `ConditionalLoginRequiredMixin` for authentication
- Fetch the server using `Server.objects.restrict(request.user, "view")` for
authorization
- In the GET handler:
- Extract the `ip` query parameter and validate it with `netaddr.IPAddress`;
return an empty `HttpResponse("")` on invalid or missing input
- Call `sync.get_netbox_ip(ip_str)` to look up the IP; return empty
`HttpResponse("")` if not found
- Determine ownership: if `description` starts with `"Synced from Kea DHCP"` or
is blank → Kea-managed; any other value → foreign
- Build a context dict with `nb_ip` and an ownership flag, then render and
return the fragment template

**2. Register the URL pattern in `netbox_kea/urls.py`:**
- Add the path in the server-scoped section, before the
`include(get_model_urls(...))` line
- Pattern: `servers/<int:pk>/reservation/check-ip/`
- Name: `reservation_check_ip`
- View: `views.ReservationCheckNetboxIPView.as_view()`

**3. Export the view from `netbox_kea/views/__init__.py`:**
- Add `ReservationCheckNetboxIPView` to the exports

Phase 2: Frontend Integration

Create the fragment template and add JavaScript to the reservation form to trigger the check on blur.

Task 1: Create Fragment Template

Add the HTML fragment template that displays the IP check result with appropriate styling.

• Create netbox_kea/templates/netbox_kea/inc/reservation_ip_check.html
• Handle Kea-managed state: Bootstrap alert alert-info with text "Already in NetBox IPAM (status: X). Saving will update it." and link to IP
• Handle foreign state: Bootstrap alert alert-warning with text indicating the IP exists and was not created by Kea sync, showing status, description (if present), and assigned object (if present, formatted as "Device/Interface")
• Use nb_ip.get_absolute_url, nb_ip.get_status_display, nb_ip.description, and nb_ip.assigned_object for display values
• Keep styling consistent with existing sync_badge.html patterns (MDI icons, Bootstrap classes)

Task 2: Add JavaScript to Reservation Form

Update the form template to include the target element and blur event handler.

• Add <div id="netbox-ip-check"></div> to netbox_kea/templates/netbox_kea/server_reservation_form.html after the {% render_form form %} block
• Add inline <script> block at the end of the template (before closing content block)
• Script should check if action context variable equals "Add" and skip setup otherwise (Edit mode has disabled IP field)
• Select the appropriate input field based on dhcp_version: #id_ip_address for v4, #id_ip_addresses for v6
• Attach blur event listener that extracts the IP value (for v6, take first comma-separated value after trimming)
• If value is empty, clear the target div and return
• Use fetch() to call the endpoint URL (construct using Django template tag for the URL with server pk), passing IP as query param
• On success, replace #netbox-ip-check innerHTML with response text

🤖 Prompt for AI agents

Create the HTML fragment template and wire up the reservation form with a plain
JavaScript blur-triggered fetch call. The goal is to display an advisory message
in the reservation add form when the entered IP already exists in NetBox IPAM.

**1. Create `netbox_kea/templates/netbox_kea/inc/reservation_ip_check.html`:**
- For the **Kea-managed** state: render a Bootstrap `alert alert-info` with the
message "Already in NetBox IPAM (status: X). Saving will update it." and a link
to the IP using `nb_ip.get_absolute_url`
- For the **foreign** state: render a Bootstrap `alert alert-warning` indicating
the IP exists but was not created by Kea sync; show `nb_ip.get_status_display`,
`nb_ip.description` (if present), and `nb_ip.assigned_object` formatted as
"Device/Interface" (if present)
- Use `nb_ip.get_absolute_url`, `nb_ip.get_status_display`, `nb_ip.description`,
and `nb_ip.assigned_object` for all display values
- Keep styling consistent with existing `sync_badge.html` patterns (MDI icons,
Bootstrap classes)

**2. Update `netbox_kea/templates/netbox_kea/server_reservation_form.html`:**
- Add `<div id="netbox-ip-check"></div>` after the `{% render_form form %}`
block
- Add an inline `<script>` block before the closing content block:
- Guard: only run setup if the `action` context variable equals `"Add"` (skip
for Edit mode where the IP field is disabled)
- Select the correct input based on `dhcp_version`: `#id_ip_address` for v4,
`#id_ip_addresses` for v6
- On blur: extract the IP value; for v6, take the first comma-separated value
after trimming
  - If the value is empty, clear `#netbox-ip-check` and return
- Use `fetch()` to call the endpoint (construct the URL using Django's template
tag with the server pk, passing IP as a query param)
  - On success, set `#netbox-ip-check` innerHTML to the response text

Research

The netbox_kea plugin follows NetBox's standard patterns with server-scoped views using <int:pk> URL parameters and object-level permissions via .restrict(). The sync_views.py file contains similar HTMX fragment-returning views like _BaseSyncView. Fragment templates live in templates/netbox_kea/inc/ and follow Bootstrap styling patterns (badges, alerts). The sync.get_netbox_ip() function already exists to look up IPs in NetBox IPAM by their host portion. The reservation form template extends generic/object.html and receives context variables including action ("Add" or "Edit") and dhcp_version (4 or 6).

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement a new server-scoped GET endpoint for checking NetBox IP conflicts. The
goal is to look up an IP in NetBox IPAM and return an HTML fragment indicating
its existence and ownership.

**1. Add `ReservationCheckNetboxIPView` to `netbox_kea/views/sync_views.py`:**
- Follow the existing `_BaseSyncView` pattern
- Use `ConditionalLoginRequiredMixin` for authentication
- Fetch the server using `Server.objects.restrict(request.user, "view")` for
authorization
- In the GET handler:
- Extract the `ip` query parameter and validate it with `netaddr.IPAddress`;
return an empty `HttpResponse("")` on invalid or missing input
- Call `sync.get_netbox_ip(ip_str)` to look up the IP; return empty
`HttpResponse("")` if not found
- Determine ownership: if `description` starts with `"Synced from Kea DHCP"` or
is blank → Kea-managed; any other value → foreign
- Build a context dict with `nb_ip` and an ownership flag, then render and
return the fragment template

**2. Register the URL pattern in `netbox_kea/urls.py`:**
- Add the path in the server-scoped section, before the
`include(get_model_urls(...))` line
- Pattern: `servers/<int:pk>/reservation/check-ip/`
- Name: `reservation_check_ip`
- View: `views.ReservationCheckNetboxIPView.as_view()`

**3. Export the view from `netbox_kea/views/__init__.py`:**
- Add `ReservationCheckNetboxIPView` to the exports
===============================================================================

Task: 2

Create the HTML fragment template and wire up the reservation form with a plain
JavaScript blur-triggered fetch call. The goal is to display an advisory message
in the reservation add form when the entered IP already exists in NetBox IPAM.

**1. Create `netbox_kea/templates/netbox_kea/inc/reservation_ip_check.html`:**
- For the **Kea-managed** state: render a Bootstrap `alert alert-info` with the
message "Already in NetBox IPAM (status: X). Saving will update it." and a link
to the IP using `nb_ip.get_absolute_url`
- For the **foreign** state: render a Bootstrap `alert alert-warning` indicating
the IP exists but was not created by Kea sync; show `nb_ip.get_status_display`,
`nb_ip.description` (if present), and `nb_ip.assigned_object` formatted as
"Device/Interface" (if present)
- Use `nb_ip.get_absolute_url`, `nb_ip.get_status_display`, `nb_ip.description`,
and `nb_ip.assigned_object` for all display values
- Keep styling consistent with existing `sync_badge.html` patterns (MDI icons,
Bootstrap classes)

**2. Update `netbox_kea/templates/netbox_kea/server_reservation_form.html`:**
- Add `<div id="netbox-ip-check"></div>` after the `{% render_form form %}`
block
- Add an inline `<script>` block before the closing content block:
- Guard: only run setup if the `action` context variable equals `"Add"` (skip
for Edit mode where the IP field is disabled)
- Select the correct input based on `dhcp_version`: `#id_ip_address` for v4,
`#id_ip_addresses` for v6
- On blur: extract the IP value; for v6, take the first comma-separated value
after trimming
  - If the value is empty, clear `#netbox-ip-check` and return
- Use `fetch()` to call the endpoint (construct the URL using Django's template
tag with the server pk, passing IP as a query param)
  - On success, set `#netbox-ip-check` innerHTML to the response text

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[marcinpsk]

Also: bulk sync conflict protection (Option A)

The background sync job (and bulk reservation sync) should also be protected against overwriting foreign NetBox IPs.

Rule

An IP is Kea-managed (safe to overwrite) when its description starts with "Synced from Kea DHCP" or is blank. Any other description → foreign, skip.

Changes

sync.py — add a helper and a force flag:

def is_kea_managed_ip(ip_obj) -> bool:
    desc = ip_obj.description or ""
    return not desc or desc.startswith("Synced from Kea DHCP")

Add force: bool = False to sync_lease_to_netbox and sync_reservation_to_netbox. When force=False and the existing IP is foreign, skip all field updates and return (ip_obj, False, False) unchanged. Log a warning at DEBUG level with the IP and its description.

Bulk sync views (_BaseBulkReservationSyncView in sync_views.py) — track skipped conflicts and include them in the summary message:

Bulk sync complete: 12 created, 5 updated, 3 conflicts skipped.

Background sync job (jobs.py) — same: count conflicts and include in the job result/log output.

What stays as-is

• The per-row Sync button on the reservations list calls sync_reservation_to_netbox directly and acts as the manual override — no conflict check there (user intent is explicit).
• No new form fields, no UI confirmation step for bulk.

Acceptance criteria

• A NetBox IP with description = "Router loopback" is never overwritten by a bulk sync run.
• A NetBox IP with blank description is claimed normally.
• A NetBox IP with description = "Synced from Kea DHCP lease" is updated normally.
• Conflict count is visible in the bulk sync result message and job log.