docs: clarify BIND9 9.20 branch strategy

Reviewed-on: #18

.github/skills/molecule-role-testing/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: molecule-role-testing
+description: Run Molecule scenarios to test the bind9 role using the repository's Molecule configuration.
+---
+
+Use this skill when asked to test or validate the role with Molecule.
+
+## Scope
+- Repository root: /home/alive/Code/ansible-bind9-role
+- Scenarios: molecule/default and molecule/bind9-20
+- Driver: podman
+
+## Prerequisites
+1. Ensure Podman is available and the current user can run it.
+2. Ensure Molecule and Ansible are installed in the active Python environment.
+
+## Default scenario (BIND 9.18 LTS)
+1. From the repository root, run:
+   - molecule test
+2. If a faster check is requested, run:
+   - molecule converge
+
+## BIND 9.20+ scenario
+1. From the repository root, run:
+   - molecule test -s bind9-20
+2. If a faster check is requested, run:
+   - molecule converge -s bind9-20
+
+## Notes
+- The scenarios use systemd-enabled containers and require privileged Podman.
+- If a scenario fails, capture the error summary and relevant logs before making changes.

docs/BIND9_9.20_SUPPORT.md

@@ -2,53 +2,53 @@
 
 ## Overview
 
-This document describes the ansible-bind9-role implementation for BIND9 9.20+ support through the `feature/bind9-20-support` branch.
+This document describes the ansible-bind9-role strategy for BIND9 9.20+ support through a dedicated version branch.
+
+The current implementation uses branch-level compatibility boundaries instead of runtime version detection. The main branch targets BIND9 9.18.x LTS, while the 9.20 branch targets BIND9 9.20+ feature releases.
 
 ## Architecture
 
-### Multi-Version Support Strategy
+### Branch-Based Support Strategy
 
-The role supports multiple BIND9 versions using:
+The role uses branch-only support boundaries:
 
-1. **Runtime Version Detection**: BIND9 version is detected at runtime and stored in the `bind9_version` fact
-2. **Template Conditionals**: Jinja2 conditionals in templates apply version-specific configurations
-3. **Separate Branches**: Different BIND9 feature release series are maintained on separate branches
-   - `main`: BIND9 9.18.x (LTS) - Production stable
-   - `9.20`: BIND9 9.20+ (feature releases) - New features and modern approach
+1. `main` branch: BIND9 9.18.x LTS support for production-stable deployments.
+2. `9.20` branch: BIND9 9.20+ feature-release support with version-specific templates, grammar data, tests, and documentation.
+
+The role does not currently detect BIND9 versions at runtime and does not use runtime version conditionals in templates. Each branch is expected to be tested against the BIND9 series it supports.
+
+This approach is preferred because:
+
+- compatibility boundaries are clear for users and maintainers;
+- templates avoid cross-version conditional complexity;
+- each branch can evolve with the grammar and package behavior of its target BIND9 series;
+- generated configuration does not silently change based on the installed package version.
 
 ### Branch Structure
 
 ```
-main                          # BIND9 9.18.x LTS (stable)
+main                    # BIND9 9.18.x LTS support
 │
-└─ 9.20                       # BIND9 9.20+ feature releases
-   ├─ feature/bind9-20-support  # Current development branch
-   └─ (will merge to 9.20 after testing)
+└─ 9.20                 # BIND9 9.20+ feature-release support
+   └─ feature/*          # Short-lived feature branches targeting 9.20
 ```
 
 ## Implementation Details
 
-### 1. Version Detection (tasks/main.yml)
+### 1. Task Flow
 
-```yaml
-- name: Detect BIND9 version at runtime
-  ansible.builtin.command:
-    cmd: named -v
-  register: _bind9_version_output
-  changed_when: false
+1. Install the configured BIND9 packages from `bind9_packages`.
+2. Ensure backup and logging directories exist when enabled or configured.
+3. Render configured BIND9 files through `named.conf.generator.j2`.
+4. Validate the generated configuration with `named-checkconf -z`.
+5. Restore backed-up configuration files if validation fails.
+6. Start and enable the `named` service.
 
-- name: Set bind9_version fact
-  ansible.builtin.set_fact:
-    bind9_version: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}"
-```
+There is no runtime `bind9_version` fact in this flow.
 
 ### 2. Meta/Argument Specs Updates
 
-The `meta/argument_specs.yml` has been updated to:
-
-- Document BIND9 9.20+ support alongside 9.18.x
-- Add `bind9_version` variable documentation (read-only, auto-detected)
-- Clarify version-specific behavior
+The `meta/argument_specs.yml` file documents the public role inputs for the current branch. It must not document runtime-only variables that the role does not set or consume.
 
 ### 3. Molecule Testing
 
@@ -67,7 +67,7 @@ Two molecule scenarios are now available:
 
 ### 4. Template Version Compatibility
 
-Templates have been audited for BIND9 9.20 compatibility. The primary template files include:
+Templates in each version branch should be audited for the BIND9 series targeted by that branch. The primary template files include:
 
 - `named.conf.options.j2` - Global options block
 - `named.conf.zone.j2` - Zone definitions
@@ -77,10 +77,10 @@ Templates have been audited for BIND9 9.20 compatibility. The primary template f
 
 ### 5. Deprecated Options Handling
 
-BIND9 9.20 removes 44 options from 9.18. The role handles this through:
+BIND9 9.20 removes 44 options from 9.18. The 9.20 branch should handle this through:
 
 1. **Documentation**: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
-2. **Conditional Removal**: Templates check version and exclude removed options
+2. **Branch-specific templates**: Templates on the 9.20 branch omit removed options
 3. **Migration Path**: BIND9_MIGRATION_GUIDE.md provides alternatives for each removed option
 
 ## Critical BIND9 9.20 Changes
@@ -204,6 +204,8 @@ Users upgrading from 9.18 to 9.20 should:
 
 - [ ] Automated configuration migration tool
 - [ ] Deprecation warnings in role output
+- [ ] Runtime version detection if branch-per-version maintenance becomes insufficient
+- [ ] Template conditionals only if a future design intentionally supports multiple BIND9 series from one branch
 - [ ] 9.21+ preparation when available
 - [ ] Performance tuning for 9.20 features
 - [ ] DNS-over-HTTPS (DoH) support
@@ -214,9 +216,9 @@ Users upgrading from 9.18 to 9.20 should:
 - [ISC BIND9 Website](https://www.isc.org/bind/)
 - [BIND9 9.20 Release Notes](https://www.isc.org/download/news/)
 - [BIND9 Documentation](https://bind9.readthedocs.io/)
-- [BIND9 Version Differences](../../docs/BIND_VERSION_DIFFERENCES.md)
-- [BIND9 Migration Guide](../../docs/BIND9_MIGRATION_GUIDE.md)
-- [VERSION_SUPPORT.md](../../docs/VERSION_SUPPORT.md)
+- [BIND9 Version Differences](BIND_VERSION_DIFFERENCES.md)
+- [BIND9 Migration Guide](BIND9_MIGRATION_GUIDE.md)
+- [VERSION_SUPPORT.md](VERSION_SUPPORT.md)
 
 ## Support
 

docs/BIND9_MIGRATION_GUIDE.md

@@ -347,9 +347,8 @@ Create a test playbook to validate migration:
 
 ```yaml
 ---
+# Test playbook for BIND9 9.20 migration
 - hosts: test_servers
-  vars:
-    bind9_version: "9.20"  # Document version being tested
   
   tasks:
     - name: Apply BIND9 9.20 configuration

docs/VERSION_SUPPORT.md

@@ -270,36 +270,20 @@ bind9-grammar/
 
 ## Version-Specific Features
 
-### Version Detection
+### Branch-Level Version Targeting
 
-The role will detect BIND9 version at runtime:
+The role currently uses branch-level version targeting instead of runtime version detection:
 
-```yaml
-# tasks/main.yml (planned implementation)
-- name: Detect BIND9 version
-  ansible.builtin.command: named -V
-  register: _bind9_version_output
-  changed_when: false
+- `main` targets BIND9 9.18.x LTS.
+- `9.20` targets BIND9 9.20+ feature releases.
 
-- name: Set BIND9 version facts
-  ansible.builtin.set_fact:
-    bind9_version_full: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}"
-    bind9_version_major: "{{ _bind9_version_output.stdout | regex_search('BIND (\\d+)\\.(\\d+)', '\\1') | first }}"
-    bind9_version_minor: "{{ _bind9_version_output.stdout | regex_search('BIND (\\d+)\\.(\\d+)', '\\2') | first }}"
-```
+Each branch carries the templates, grammar data, documentation, and tests appropriate for its supported BIND9 series. This keeps generated configuration predictable and avoids mixing incompatible BIND9 grammar rules in one template path.
 
-### Conditional Configuration
+### Runtime Detection
 
-Templates will use version-aware conditionals:
+Runtime version detection is not part of the current implementation. The role does not set `bind9_version_full`, `bind9_version_major`, `bind9_version_minor`, or `bind9_version`, and templates do not branch on those values.
 
-```jinja2
-{# templates/named.conf.options.j2 (planned) #}
-{% if bind9_version_major | int >= 20 %}
-    {# BIND9 9.20+ specific options #}
-{% else %}
-    {# BIND9 9.18 options #}
-{% endif %}
-```
+Runtime detection may be reconsidered in the future if maintaining separate version branches becomes more expensive than supporting multiple BIND9 series from one branch. That future design would require dedicated tasks, public metadata, template changes, and Molecule coverage before being documented as supported behavior.
 
 ## Migration Guidance
 
@@ -367,4 +351,3 @@ See `CHANGELOG.md` for version-specific migration notes.
 | Date | Version | Changes |
 |------|---------|---------|
 | 2026-02-07 | 1.0 | Initial version support policy |
-

meta/argument_specs.yml

@@ -4,8 +4,7 @@ argument_specs:
     short_description: The main entry point for the bind9 role.
     description:
       - Configures BIND9 DNS server on Debian-based systems.
-      - "Supported BIND9 versions: 9.18.x (LTS), 9.20+ (feature releases)"
-      - Version detection is automatic at runtime.
+      - "Supported BIND9 versions are branch-specific: main targets 9.18.x (LTS), and the 9.20 branch targets 9.20+ feature releases."
     options:
       bind9_config:
         type: list
@@ -57,10 +56,3 @@ argument_specs:
       bind9_backup_dir:
         type: str
         description: Directory for backups.
-      bind9_version:
-        type: str
-        description:
-          - BIND9 version detected at runtime (read-only, set automatically).
-          - "Format: X.Y.Z (e.g., 9.18.44, 9.20.18)"
-          - Used by templates to apply version-specific configurations.
-          - Users should not set this variable directly.

molecule/default/converge.yml

@@ -1,19 +1,10 @@
 ---
 - name: Converge
   hosts: all
-  tasks:
-    - name: Create log directory for BIND
-      ansible.builtin.file:
-        path: /var/log/named
-        state: directory
-        mode: '0755'
-        owner: bind
-        group: bind
-
-    - name: Include bind9 role
-      ansible.builtin.include_role:
-        name: ../../../ansible-bind9-role  # noqa: role-name[path]
+  roles:
+    - ansible-bind9-role
   vars:
+    bind9_log_dir: /var/log/named
     bind9_backup_config: false
     bind9_host_config:
       - name: named.conf.options
@@ -113,3 +104,14 @@
             forwarders:
               - 10.0.0.53
               - 10.0.0.54
+
+- name: Post-converge
+  hosts: all
+  tasks:
+    - name: Create log directory for BIND
+      ansible.builtin.file:
+        path: /var/log/named
+        state: directory
+        mode: '0750'
+        owner: bind
+        group: bind

molecule/default/molecule.yml

@@ -11,6 +11,8 @@ platforms:
     cgroupns_mode: host
 provisioner:
   name: ansible
+  env:
+    ANSIBLE_ROLES_PATH: ${MOLECULE_PROJECT_DIRECTORY}/..
   config_options:
     defaults:
       ALLOW_BROKEN_CONDITIONALS: true

molecule/default/verify.yml

@@ -41,7 +41,8 @@
       ansible.builtin.assert:
         that:
           - "'forwarders' in __options_decoded"
-          - "'8.8.8.8' in __options_decoded"
+          - "'91.239.100.100' in __options_decoded"
+          - "'89.233.43.71' in __options_decoded"
           - "'forward first' in __options_decoded"
         fail_msg: Forwarders not properly configured in named.conf.options
       vars:

tasks/main.yml

@@ -18,6 +18,17 @@
     mode: "0750"
   when: bind9_backup_config is defined and bind9_backup_config | bool
 
+- name: Ensure logging directory exists if defined
+  ansible.builtin.file:
+    path: "{{ bind9_log_dir }}"
+    state: directory
+    owner: bind
+    group: bind
+    mode: "0750"
+  when:
+    - bind9_log_dir is defined
+    - bind9_log_dir is not none
+
 - name: Deploy and Validate Configuration
   tags:
     - bind9
@@ -34,6 +45,7 @@
         owner: root
         group: bind
         mode: "0640"
+      when: bind9_backup_config | bool
       changed_when: false
       failed_when: false # It's okay if the file doesn't exist yet
       loop: "{{ bind9_config }}"
@@ -85,6 +97,7 @@
       loop: "{{ bind9_config }}"
       loop_control:
         label: "{{ item.name }}"
+      changed_when: false
       when: bind9_backup_config | bool is false
 
 - name: Ensure the named service is started