From 889b4ad25449aa0082e5896f02a1e6db5f1221d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vin=C3=ADcius=20Ferr=C3=A3o?= <2031761+viniciusferrao@users.noreply.github.com> Date: Thu, 23 Apr 2026 11:51:09 -0300 Subject: [PATCH] Document the DHCP backend validation matrix --- .../code/dhcp_backend_validation_matrix.rst | 141 ++++++++++++++++++ docs/source/developers/guides/code/index.rst | 1 + .../guides/code/kea_dhcp_backend_plan.rst | 4 + 3 files changed, 146 insertions(+) create mode 100644 docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst diff --git a/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst b/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst new file mode 100644 index 000000000..eb5167f7a --- /dev/null +++ b/docs/source/developers/guides/code/dhcp_backend_validation_matrix.rst @@ -0,0 +1,141 @@ +DHCP Backend Validation Matrix +============================== + +Purpose +------- + +This document defines the default validation matrix for xCAT DHCP backend +changes. + +Use this matrix for: + +* backend selection changes +* DHCP renderer changes +* reservation add, delete, or query changes +* DDNS and service-management changes +* PXE, xNBA, or boot-policy changes + +Backend Policy +-------------- + +The default backend split is: + +* EL9, Ubuntu 22.04 LTS, and older supported releases: ``ISC DHCP`` +* EL10, Ubuntu 24.04 LTS, and newer supported releases: ``Kea`` + +``site.dhcpbackend=auto`` must follow that rule. Explicit ``isc`` and ``kea`` +overrides remain available for development and troubleshooting. + +Always-Run Checks +----------------- + +Run these checks for every DHCP backend change before live validation: + +* Perl syntax checks for changed DHCP modules +* unit tests for backend selection, range handling, boot policy, and renderer + behavior +* backend-native configuration validation: + + * ``dhcpd -t -cf `` for ISC + * ``kea-dhcp4 -t `` for Kea DHCPv4 + * ``kea-dhcp6 -t `` for Kea DHCPv6 when used + * ``kea-ctrl-agent -t `` for Control Agent when used + * ``kea-dhcp-ddns -t `` for D2 when used + +Default Live Matrix +------------------- + +The following matrix is the default live validation gate for DHCP backend work. + +.. list-table:: + :header-rows: 1 + :widths: 14 10 10 18 48 + + * - Platform + - Arch + - Backend + - Boot Validation + - Minimum Required Checks + * - EL9 + - ``x86_64`` + - ``ISC`` + - ``xNBA shell`` + - ``makedhcp -n``; ``dhcpd -t``; reservation add/query/delete; DHCP/TFTP; + node-specific xNBA handoff; Genesis fetch + * - Ubuntu 22.04 LTS + - ``x86_64`` + - ``ISC`` + - ``xNBA shell`` + - ``makedhcp -n``; ``dhcpd -t``; reservation add/query/delete; DHCP/TFTP; + node-specific xNBA handoff; Genesis fetch + * - EL10 + - ``x86_64`` + - ``Kea`` + - ``xNBA shell`` and ``full netboot image`` + - ``makedhcp -n``; ``kea-dhcp4 -t``; reservation add/query/delete; + xNBA shell boot; full compute-image boot through kernel, initrd, and + root image + * - Ubuntu 24.04 LTS + - ``x86_64`` + - ``Kea`` + - ``xNBA shell`` and ``full netboot image`` + - ``makedhcp -n``; ``kea-dhcp4 -t``; reservation add/query/delete; + xNBA shell boot; full compute-image boot through kernel, initrd, and + root image + +Extended Architecture Matrix +---------------------------- + +Run the extended matrix when a change touches architecture-specific boot logic, +client classification, firmware-specific file paths, or non-``x86_64`` code +paths. + +.. list-table:: + :header-rows: 1 + :widths: 14 10 10 18 48 + + * - Platform + - Arch + - Backend + - Boot Validation + - Minimum Required Checks + * - EL10 + - ``ppc64le`` + - ``Kea`` + - ``Genesis handoff`` + - DHCP offer; boot file handoff; xCAT Genesis reachability; POWER boot-path + correctness + +Current Lab Baseline +-------------------- + +The current KVM validation hosts are: + +* ``rome01.local.versatushpc.com.br`` for ``x86_64`` +* ``power.local.versatushpc.com.br`` for ``ppc64le`` + +Known Exceptions +---------------- + +Known blockers do not remove the matrix requirement. They must be recorded +explicitly in the validation result. + +Current exceptions: + +* Ubuntu 22.04 LTS ISC OMAPI/``omshell`` host reservation updates are blocked by + issue ``#11``. The failure reproduces on upstream ``master`` and is not caused + by the Kea backend work. +* EL10 ``ppc64le`` currently reaches xCAT Genesis, but full POWER validation is + blocked by a preexisting ``genesis.kernel.ppc64`` issue unrelated to Kea. + +Reporting Rule +-------------- + +Every DHCP backend PR should summarize validation using this matrix: + +* what rows were run +* what passed +* what failed +* what was blocked by a known external issue + +If a row was skipped, the PR should state why. diff --git a/docs/source/developers/guides/code/index.rst b/docs/source/developers/guides/code/index.rst index 715e796fd..8abde363a 100644 --- a/docs/source/developers/guides/code/index.rst +++ b/docs/source/developers/guides/code/index.rst @@ -7,5 +7,6 @@ Code Development code_standard.rst builds.rst debug.rst + dhcp_backend_validation_matrix.rst kea_dhcp_backend_plan.rst tips.rst diff --git a/docs/source/developers/guides/code/kea_dhcp_backend_plan.rst b/docs/source/developers/guides/code/kea_dhcp_backend_plan.rst index 3e1b0b409..44914c918 100644 --- a/docs/source/developers/guides/code/kea_dhcp_backend_plan.rst +++ b/docs/source/developers/guides/code/kea_dhcp_backend_plan.rst @@ -259,6 +259,10 @@ Areas that currently assume ISC DHCP must become backend-aware: Testing Strategy ---------------- +The standing validation baseline for DHCP backend work is maintained in +``dhcp_backend_validation_matrix.rst``. Use that matrix as the default gate for +future DHCP backend changes. + Unit tests: * normalized DHCP intent creation