DHCPLease Resource Kind

Kind: DHCPLeaseapiVersion: pivirt.hu/v1Aliases: lease, leases, dhcplease

The DHCPLease resource represents an active dynamic IP lease or a permanent static IP reservation managed by pivirtd’s embedded DHCP server (AF_PACKET).

In traditional hypervisors, DHCP leases are buried inside opaque files (such as ipam.json or dnsmasq.leases). In PiVirt, making DHCP leases first-class declarative objects allows operators and agents to list active leases, inspect IP assignments, and declare static IP reservations using standard GitOps workflows.

---

Accepted Kind Aliases

In pivirtctl commands, any of the following aliases are recognized: DHCPLease, dhcplease, dhcpleases, lease, leases.

---

Example Manifests

Static IP Reservation

apiVersion: pivirt.hu/v1
kind: DHCPLease
metadata:
  name: web-01-reservation
  labels:
    network: virbr0
    tier: frontend
spec:
  network: virbr0
  macAddress: "52:54:00:12:34:56"
  ipAddress: "192.168.100.10"
  hostname: "web-01.local"
  type: static # 'static' for permanent reservations, 'dynamic' for auto-assigned

Dynamic Lease Query Representation

apiVersion: pivirt.hu/v1
kind: DHCPLease
metadata:
  name: lease-52-54-00-a1-b2-c3
  labels:
    network: virbr0
spec:
  network: virbr0
  macAddress: "52:54:00:a1:b2:c3"
  ipAddress: "192.168.100.145"
  hostname: "talos-worker-01"
  type: dynamic
  expiresAt: "2026-09-07T14:30:00Z"

---

Specification Reference (spec)

Field	Type	Required	Default	Description
network	string	Yes		Target Network or bridge device name (e.g. virbr0, br0)
macAddress	string	Yes		Client hardware MAC address
ipAddress	string	Yes		Assigned or reserved IPv4 address
hostname	string	No		Optional DNS hostname requested by client
type	string	No	static	Lease type: static (never expires) or dynamic
expiresAt	string	No		Expiration timestamp (RFC3339) for dynamic leases

---

Why DHCPLease is a First-Class Kind

1. Declarative IP Reservations: Setting a fixed IP for a VM is an apply (kind: DHCPLease with macAddress → ipAddress) rather than editing backend configuration files.
2. Cluster Multi-Node Visibility: When a network spans multiple hypervisor nodes, each node runs a local DHCP service serving a delegated sub-range. Making DHCPLease listable allows the Node Agent to detect IP collisions across hosts.
3. Provisioning Interlock: While a VM has an active provisioning lock (pivirtd.pilab.hu/is-provisioning=true), its DHCPLease cannot be deleted or relocated, preventing guest bootstrap failures.

---

CLI Management Examples

# List all active DHCP leases on the host
pivirtctl get leases

# List using canonical kind name
pivirtctl get dhcpleases

# Apply a static reservation
pivirtctl apply -f static-ip.yaml

# Query a specific lease
pivirtctl get lease web-01-reservation -o yaml

# Inspect lease details
pivirtctl describe lease web-01-reservation

# Release/delete a static lease reservation
pivirtctl delete lease web-01-reservation