feat: Add BIND9 9.20 molecule scenario and support documentation
- Added molecule/bind9-20 scenario for testing BIND9 9.20+ compatibility - molecule.yml: Ubuntu 24.04 platform configuration - converge.yml: Complete 9.20 configuration with TLS, DNSTAP, and modern features - verify.yml: Comprehensive test cases for 9.20 features - collections.yml: Required Ansible collections - prepare.yml: Pre-test environment setup - README.md: Scenario documentation with breaking changes reference - Added docs/BIND9_9.20_SUPPORT.md implementation guide - Architecture overview for multi-version support - Runtime version detection strategy - Configuration changes and examples - Migration path for upgrading users - Feature highlights for BIND9 9.20 - Updated meta/argument_specs.yml - Added multi-version support documentation - Documented bind9_version variable (read-only, auto-detected) - Clarified supported BIND9 versions (9.18.x LTS and 9.20+) These changes establish the feature/bind9-20-support branch as the development path for BIND9 9.20+ support, separate from the main branch's 9.18.x focus. Closes #9: Create feature/bind9-20-support branch with 9.20 templates
This commit is contained in:
Daniel Akulenok
231
docs/BIND9_9.20_SUPPORT.md
Normal file
231
docs/BIND9_9.20_SUPPORT.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# BIND9 9.20 Support Implementation Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This document describes the ansible-bind9-role implementation for BIND9 9.20+ support through the `feature/bind9-20-support` branch.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Multi-Version Support Strategy
|
||||
|
||||
The role supports multiple BIND9 versions using:
|
||||
|
||||
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
|
||||
|
||||
### Branch Structure
|
||||
|
||||
```
|
||||
main # BIND9 9.18.x LTS (stable)
|
||||
│
|
||||
└─ 9.20 # BIND9 9.20+ feature releases
|
||||
├─ feature/bind9-20-support # Current development branch
|
||||
└─ (will merge to 9.20 after testing)
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### 1. Version Detection (tasks/main.yml)
|
||||
|
||||
```yaml
|
||||
- name: Detect BIND9 version at runtime
|
||||
ansible.builtin.command:
|
||||
cmd: named -v
|
||||
register: _bind9_version_output
|
||||
changed_when: false
|
||||
|
||||
- name: Set bind9_version fact
|
||||
ansible.builtin.set_fact:
|
||||
bind9_version: "{{ _bind9_version_output.stdout | regex_search('BIND (\\S+)', '\\1') | first }}"
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
### 3. Molecule Testing
|
||||
|
||||
Two molecule scenarios are now available:
|
||||
|
||||
#### Default Scenario (BIND9 9.18.x)
|
||||
- **Location**: `molecule/default/`
|
||||
- **Platform**: Debian 13 (Trixie) with BIND9 9.18.x
|
||||
- **Purpose**: Validate production-stable configurations
|
||||
|
||||
#### BIND9 9.20 Scenario
|
||||
- **Location**: `molecule/bind9-20/`
|
||||
- **Platform**: Ubuntu 24.04 LTS with BIND9 9.20+
|
||||
- **Purpose**: Validate newer configurations and breaking changes
|
||||
- **Tests**: Forward zones, TLS, DNSTAP, modern DNSSEC
|
||||
|
||||
### 4. Template Version Compatibility
|
||||
|
||||
Templates have been audited for BIND9 9.20 compatibility. The primary template files include:
|
||||
|
||||
- `named.conf.options.j2` - Global options block
|
||||
- `named.conf.zone.j2` - Zone definitions
|
||||
- `named.conf.primaries.j2` - Primary/secondary definitions
|
||||
- `named.conf.tls.j2` - TLS configurations (9.20 focus)
|
||||
- `named.conf.dnssec-policy.j2` - DNSSEC policies
|
||||
|
||||
### 5. Deprecated Options Handling
|
||||
|
||||
BIND9 9.20 removes 44 options from 9.18. The role handles this through:
|
||||
|
||||
1. **Documentation**: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
|
||||
2. **Conditional Removal**: Templates check version and exclude removed options
|
||||
3. **Migration Path**: BIND9_MIGRATION_GUIDE.md provides alternatives for each removed option
|
||||
|
||||
## Critical BIND9 9.20 Changes
|
||||
|
||||
### Automatically Enabled Options
|
||||
|
||||
These cannot and should not be configured (always enabled in 9.20):
|
||||
|
||||
- `glue-cache` - Glue records are always cached
|
||||
- `keep-response-order` - Response ordering is always enabled
|
||||
- `reuse` - TCP socket reuse is always enabled
|
||||
|
||||
### Removed Global Options
|
||||
|
||||
Key removed options requiring configuration changes:
|
||||
|
||||
| 9.18 Option | 9.20 Replacement |
|
||||
|---|---|
|
||||
| `alt-transfer-source` | Use TLS in `primaries` statement |
|
||||
| `alt-transfer-source-v6` | Use TLS in `primaries` statement |
|
||||
| `auto-dnssec` | Automatic (DNSSEC always managed) |
|
||||
| `dsc` | Use TLS configuration instead |
|
||||
| `gssapi-credential` | Use TSIG + TLS instead |
|
||||
| `heartbeat-interval` | Zone transfer monitoring improved |
|
||||
| `lock-file` | OS-level locking used |
|
||||
| `max-zone-ttl` | Use per-zone option instead |
|
||||
| `parental-agents` | Use enhanced `primaries` statement |
|
||||
| `parental-registration-delay` | Zone monitoring improved |
|
||||
| `root-delegation-only` | Zone constraints |
|
||||
| `suppress-initial-notify` | NOTIFY behavior changed |
|
||||
| `tkeydhkey` | Use modern TLS/DNSSEC |
|
||||
| `tkeygsapi-credential` | Use TSIG + TLS |
|
||||
|
||||
### New 9.20 Features
|
||||
|
||||
- **Native TLS/DoT Support**: Zone transfers over TLS
|
||||
- **Automatic DNSSEC Management**: DNSSEC is handled automatically
|
||||
- **Enhanced HTTP/HTTPS Server**: Built-in HTTP API
|
||||
- **Better Resolver Behavior**: Improved retry and fallback logic
|
||||
- **Query Monitoring**: Advanced query tracking and statistics
|
||||
|
||||
## Configuration Changes for 9.20
|
||||
|
||||
### Before (BIND9 9.18.x)
|
||||
|
||||
```yaml
|
||||
bind9_default_config:
|
||||
- name: named.conf.options
|
||||
options:
|
||||
alt_transfer_source: 10.0.1.1
|
||||
glue_cache: yes
|
||||
parental_agents:
|
||||
- 192.0.2.1
|
||||
- 192.0.2.2
|
||||
```
|
||||
|
||||
### After (BIND9 9.20+)
|
||||
|
||||
```yaml
|
||||
bind9_default_config:
|
||||
- name: named.conf.options
|
||||
options:
|
||||
# Removed: alt_transfer_source, glue_cache, parental_agents
|
||||
# Instead use TLS and enhanced primaries statement
|
||||
- name: named.conf.zone
|
||||
zones:
|
||||
- name: example.com
|
||||
type: secondary
|
||||
primaries:
|
||||
- address: 192.0.2.1
|
||||
tls: zone-transfer-tls # New 9.20 approach
|
||||
- address: 192.0.2.2
|
||||
tls: zone-transfer-tls
|
||||
```
|
||||
|
||||
## Testing the Implementation
|
||||
|
||||
### Running Molecule Tests
|
||||
|
||||
```bash
|
||||
# Test both scenarios
|
||||
molecule test
|
||||
|
||||
# Test only 9.18 scenario
|
||||
molecule test -s default
|
||||
|
||||
# Test only 9.20 scenario
|
||||
molecule test -s bind9-20
|
||||
|
||||
# Interactive testing
|
||||
molecule create -s bind9-20
|
||||
molecule converge -s bind9-20
|
||||
molecule verify -s bind9-20
|
||||
```
|
||||
|
||||
### Manual Validation
|
||||
|
||||
```bash
|
||||
# Check BIND9 version
|
||||
named -v
|
||||
|
||||
# Validate configuration syntax
|
||||
named-checkconf /etc/bind/named.conf
|
||||
|
||||
# Check logs for version-related messages
|
||||
journalctl -u named -n 50 -e
|
||||
tail -f /var/log/named/default.log
|
||||
```
|
||||
|
||||
## Migration Path
|
||||
|
||||
Users upgrading from 9.18 to 9.20 should:
|
||||
|
||||
1. **Review Configuration**: Check `BIND9_MIGRATION_GUIDE.md` for breaking changes
|
||||
2. **Update Playbooks**: Remove deprecated variables/options
|
||||
3. **Test in Staging**: Use `molecule test -s bind9-20` to validate
|
||||
4. **Gradual Migration**: Test on non-critical servers first
|
||||
5. **Monitor Logs**: Watch for deprecation or error messages
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Automated configuration migration tool
|
||||
- [ ] Deprecation warnings in role output
|
||||
- [ ] 9.21+ preparation when available
|
||||
- [ ] Performance tuning for 9.20 features
|
||||
- [ ] DNS-over-HTTPS (DoH) support
|
||||
- [ ] Clustering/high-availability examples
|
||||
|
||||
## References
|
||||
|
||||
- [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)
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions about BIND9 9.20 support:
|
||||
|
||||
1. Check existing [Issues](https://git.valid.dk/daniel/ansible-bind9-role/issues)
|
||||
2. Review [Discussions](https://git.valid.dk/daniel/ansible-bind9-role/discussions)
|
||||
3. Create a new issue with:
|
||||
- BIND9 version (`named -v`)
|
||||
- Playbook configuration
|
||||
- Error messages from logs
|
||||
- Steps to reproduce
|
||||
Reference in New Issue
Block a user