daniel/ansible-bind9-role
1
0
Fork 0
Code Issues 3 Pull Requests 1 Actions Releases Wiki Activity

docs: Add BIND9 grammar files for v9.18.44 and v9.20.18 #13

Merged
daniel merged 5 commits from 9.18 into main 2026-02-07 22:33:15 +00:00
Conversation 1 Commits 5 Files Changed 33 +484
2 changed files with 484 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit ef45f4ef0b - Show all commits

114
CHANGELOG.md Normal file
View File

@@ -0,0 +1,114 @@
# Changelog
All notable changes to the ansible-bind9-role will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Version support policy documentation in `docs/VERSION_SUPPORT.md`
- Branching strategy for supporting multiple BIND9 versions
- Grammar comparison tooling (`scripts/compare_bind_versions.py`)
- Grammar fetcher for upstream BIND9 sources (`scripts/fetch_bind_grammar.py`)
- Automated version difference tracking
- Operating system support matrix
### Changed
- Established formal release management process
- Defined backporting policy for security, bugs, and features
### Planned
- BIND9 9.20+ support in separate `9.20` branch
- Multi-platform molecule test matrix
- Automated BIND9 version detection in tasks
- Version-specific template conditional logic
- Enhanced CI/CD pipeline with version matrix testing
## [1.0.0] - TBD
### Initial Release
- Full support for BIND9 9.18.x (LTS)
- Configuration grammar based on BIND9 9.18.44
- Comprehensive template system for all BIND9 statement types:
- `acl`
- `controls`
- `dlz`
- `dnssec-policy`
- `dyndb`
- `http`
- `key`
- `logging`
- `options`
- `parental-agents`
- `primaries` (masters)
- `server`
- `statistics-channels`
- `tls`
- `trust-anchors`
- `view`
- `zone` (all types: primary, secondary, forward, hint, stub, static-stub, mirror, redirect, in-view, delegation-only)
- Support for Debian 11, 12, 13
- Support for Ubuntu 20.04, 22.04, 24.04
- Molecule testing framework
- Configuration validation with `named-checkconf`
- Automatic configuration backup and rollback on errors
- Detailed configuration grammar documentation
- GPL-3.0-or-later license
---
## Version History (Pre-Changelog)
Prior to this changelog, the role was developed without formal version tracking.
This changelog starts with the establishment of the version support policy.
---
## Versioning Schema
- **MAJOR**: Incompatible changes to role variables or behavior
- **MINOR**: New features in a backwards compatible manner
- **PATCH**: Backwards compatible bug fixes
### Branch-Specific Versioning
- `main` branch: `vX.Y.Z` (BIND9 9.18 LTS)
- `9.20` branch: `v9.20.X[-suffix]` (BIND9 9.20+)
- Suffixes: `-alpha`, `-beta`, `-rc` for pre-releases
## Release Types
### Security Releases
Critical security fixes are released as patch versions and backported to all supported branches.
### Feature Releases
New features are added in minor version increments. Breaking changes require major version increments.
### Bug Fix Releases
Bug fixes are released as patch versions when they accumulate or for critical issues.
## Upgrade Notes
### From Pre-Versioned to v1.0.0
The first official release establishes baseline compatibility. Users of pre-release versions should:
1. Review all role variables for any changes
2. Test in non-production environment
3. Review generated configuration with `named-checkconf`
4. Check `docs/VERSION_SUPPORT.md` for supported platforms
### Future Upgrades
Check individual version sections above for specific upgrade notes and breaking changes.
## Contributing
See `docs/VERSION_SUPPORT.md` for contribution guidelines and release processes.
## Links
- [Version Support Policy](docs/VERSION_SUPPORT.md)
- [Configuration Grammar](CONFIGURATION_GRAMMAR.md)
- [Issue Tracker](https://git.valid.dk/daniel/ansible-bind9-role/issues)
- [Repository](https://git.valid.dk/daniel/ansible-bind9-role)

370
docs/VERSION_SUPPORT.md Normal file
View File

@@ -0,0 +1,370 @@
# BIND9 Version Support Policy
**Document Version**: 1.0
**Last Updated**: 2026-02-07
**Role Version**: Current development
## Overview
This document defines the version maintenance strategy for the ansible-bind9-role, including supported BIND9 versions, OS platforms, branching strategy, and release management policies.
## Supported Versions
### BIND9 Versions
| BIND9 Version | Branch | Status | Support Level | EOL Date |
|---------------|--------|--------|---------------|----------|
| 9.18.x (LTS) | `main` | ✅ Active | Full support | TBD (following ISC LTS timeline) |
| 9.20.x+ | `9.20` | 🚧 In Development | Planned | N/A |
#### Version Selection Rationale
- **BIND9 9.18**: Long Term Support (LTS) release from ISC
- Maintained by ISC with extended support timeline
- Stable feature set suitable for production environments
- Current focus of this role
- **BIND9 9.20+**: Feature release series
- Introduces significant configuration changes
- New features and modernization
- May have shorter support windows per release
- Will be supported in separate branch to prevent breaking changes
### Operating System Support Matrix
| OS Distribution | Versions | BIND9 9.18 | BIND9 9.20+ | Notes |
|----------------|----------|------------|-------------|-------|
| Debian | 11 (Bullseye) | ✅ Supported | 🔍 Testing | Current stable |
| Debian | 12 (Bookworm) | ✅ Supported | ✅ Supported | Current testing focus |
| Debian | 13 (Trixie) | ✅ Supported | ✅ Supported | Future stable |
| Ubuntu | 20.04 LTS | ✅ Supported | 🔍 Testing | LTS until 2025 |
| Ubuntu | 22.04 LTS | ✅ Supported | ✅ Supported | LTS until 2027 |
| Ubuntu | 24.04 LTS | ✅ Supported | ✅ Supported | LTS until 2029 |
**Legend**:
- ✅ Supported: Fully tested and supported
- 🔍 Testing: In testing, use with caution
- ⚠️ Limited: Basic support only
- ❌ Unsupported: Not supported
### Minimum Requirements
- **Ansible**: 2.13 or later
- **Python**: 3.8 or later (on controller and managed nodes)
- **BIND9 Packages**: Must be available in distribution repositories or custom sources
## Branching Strategy
### Branch Structure
```
main # BIND9 9.18 LTS (stable)
├── 9.20 # BIND9 9.20+ development
├── docs # Documentation updates (merged to both)
└── feature/* # Feature branches (target appropriate base)
```
### Branch Policies
#### `main` Branch
- **Purpose**: Production-ready code for BIND9 9.18 LTS
- **Stability**: Stable, tested releases only
- **Breaking Changes**: Not allowed
- **Version Tagging**: `v1.x.x`, `v2.x.x`, etc.
#### `9.20` Branch
- **Purpose**: Development for BIND9 9.20+ support
- **Stability**: Development/testing phase
- **Breaking Changes**: Allowed (vs 9.18 configurations)
- **Version Tagging**: `v9.20.x-betaX`, `v9.20.x-rcX`, `v9.20.x`
#### Feature Branches
- **Naming**: `feature/description` or `fix/issue-number`
- **Target**: Merge to appropriate base (`main` for 9.18, `9.20` for 9.20+)
- **Lifecycle**: Delete after merge
### Backporting Policy
#### Security Fixes
- **Policy**: MUST be backported to all supported branches
- **Timeline**: Within 48 hours of fix
- **Priority**: Critical
#### Bug Fixes
- **Policy**: SHOULD be backported if:
- Affects both versions
- Low risk of introducing regressions
- Reasonable effort required
- **Timeline**: Within 1 week
- **Priority**: High
#### New Features
- **Policy**: Case-by-case evaluation
- **Criteria**:
- Feature is compatible with both BIND9 versions
- Does not introduce breaking changes
- Provides significant value
- Low implementation complexity
- **Timeline**: Best effort
- **Priority**: Medium
#### Breaking Changes
- **Policy**: NEVER backported
- **Implementation**: Only in version-specific branches
## Release Management
### Version Numbering
Following [Semantic Versioning 2.0.0](https://semver.org/):
```
MAJOR.MINOR.PATCH
MAJOR: Incompatible API changes (role variable structure changes)
MINOR: New functionality in a backwards compatible manner
PATCH: Backwards compatible bug fixes
```
#### Examples
- `v1.2.3`: Patch release for BIND9 9.18
- `v2.0.0`: Major release with breaking role variable changes
- `v9.20.0-beta1`: Beta release for BIND9 9.20 support
- `v9.20.0`: First stable release for BIND9 9.20
### Release Cadence
- **Patch Releases**: As needed for bug fixes and security updates
- **Minor Releases**: Quarterly (or when significant features accumulate)
- **Major Releases**: Annually (or when breaking changes are necessary)
### Pre-release Testing
All releases must pass:
1. **Molecule tests** across all supported platforms
2. **named-checkconf** validation for all example configurations
3. **Manual testing** on at least 2 different distributions
4. **Documentation review** and update
### Release Checklist
- [ ] Update `CHANGELOG.md` with all changes
- [ ] Update version in `meta/main.yml`
- [ ] Run full molecule test suite
- [ ] Update `README.md` if needed
- [ ] Create annotated git tag
- [ ] Push tag to trigger CI/CD
- [ ] Create GitHub/Gitea release with notes
- [ ] Announce on project channels
## Testing Strategy
### Test Matrix
#### Molecule Scenarios
| Scenario | Distribution | BIND9 Version | Purpose |
|----------|--------------|---------------|---------|
| default | Debian 13 | 9.18 | Primary development testing |
| ubuntu2204 | Ubuntu 22.04 | 9.18 | LTS testing |
| ubuntu2404 | Ubuntu 24.04 | 9.18/9.20 | Future-proofing |
| debian12 | Debian 12 | 9.18 | Stable release testing |
#### Test Coverage
- **Syntax validation**: All templates pass `named-checkconf`
- **Service management**: Start, stop, reload, restart operations
- **Configuration types**: All zone types and statement blocks
- **Edge cases**: Empty configurations, complex nested structures
- **Upgrade scenarios**: Migration from previous role versions
### Continuous Integration
```yaml
# .github/workflows/test.yml (example structure)
on: [push, pull_request]
jobs:
molecule:
strategy:
matrix:
distro: [debian12, debian13, ubuntu2204, ubuntu2404]
bind_version: ['9.18', '9.20']
exclude:
# Don't test 9.20 on older distributions
- distro: ubuntu2004
bind_version: '9.20'
```
## Grammar Tracking and Validation
### Automated Grammar Comparison
The role maintains upstream BIND9 grammar files to:
1. Detect configuration syntax changes between versions
2. Identify deprecated and removed options
3. Document breaking changes for users
#### Grammar Repository Structure
```
bind9-grammar/
├── upstream/
│ ├── v9.18.44/ # Latest 9.18 LTS grammar
│ │ ├── grammar/
│ │ │ ├── options
│ │ │ ├── *.zoneopt
│ │ │ └── parsegrammar.py
│ │ └── metadata.json
│ └── v9.20.18/ # Latest 9.20 grammar
│ ├── grammar/
│ └── metadata.json
├── 9.18/ # Current 9.18 JSON schemas
│ └── *.json
└── 9.20/ # Future 9.20 JSON schemas
└── *.json
```
### Validation Tools
#### `scripts/fetch_bind_grammar.py`
- Fetches grammar files from Gitea mirror (`Mirrors/bind9`)
- Supports version tags (e.g., `v9.18.44`, `v9.20.18`)
- Stores upstream grammar for comparison
#### `scripts/compare_bind_versions.py`
- Compares grammar files between versions
- Generates `docs/BIND_VERSION_DIFFERENCES.md`
- Identifies:
- Breaking changes (removed options)
- New features (added options)
- Modified syntax
- Deprecation notices
### Grammar Update Workflow
1. **Monitor**: Watch Gitea mirror for new BIND9 releases
2. **Fetch**: Run `fetch_bind_grammar.py` for new version
3. **Compare**: Run `compare_bind_versions.py` to identify changes
4. **Review**: Analyze breaking changes and impact
5. **Update**: Modify templates and variables as needed
6. **Test**: Run molecule tests with new version
7. **Document**: Update `BIND_VERSION_DIFFERENCES.md` and `CHANGELOG.md`
## Deprecation Policy
### Deprecation Process
1. **Announcement**: Document deprecation in `CHANGELOG.md` and `README.md`
2. **Warning Period**: Minimum 2 minor releases before removal
3. **Alternative**: Provide migration path or alternative approach
4. **Removal**: Only in major version releases
### Current Deprecations
*None at this time*
### Planned Deprecations
*To be determined based on BIND9 9.20 analysis*
## Version-Specific Features
### Version Detection
The role will detect BIND9 version at runtime:
```yaml
# tasks/main.yml (planned implementation)
- name: Detect BIND9 version
ansible.builtin.command: named -V
register: _bind9_version_output
changed_when: false
- 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 }}"
```
### Conditional Configuration
Templates will use version-aware conditionals:
```jinja2
{# templates/named.conf.options.j2 (planned) #}
{% if bind9_version_major | int >= 20 %}
{# BIND9 9.20+ specific options #}
{% else %}
{# BIND9 9.18 options #}
{% endif %}
```
## Migration Guidance
### Migrating from BIND9 9.18 to 9.20
When BIND9 9.20 support is released:
1. **Review**: Read `docs/BIND_VERSION_DIFFERENCES.md`
2. **Test**: Use `9.20` branch in test environment
3. **Update**: Modify playbook variables for deprecated/removed options
4. **Validate**: Run `named-checkconf` against generated configuration
5. **Deploy**: Upgrade BIND9 package and deploy new configuration
6. **Monitor**: Check logs for warnings or errors
### Migrating Between Role Versions
See `CHANGELOG.md` for version-specific migration notes.
## Support and Contribution
### Getting Help
- **Issues**: Report bugs and request features on Gitea
- **Documentation**: Refer to `README.md` and `CONFIGURATION_GRAMMAR.md`
- **Examples**: Check `tests/` directory for working configurations
### Contributing
- **Bug Fixes**: Target `main` branch (or `9.20` if version-specific)
- **Features**: Discuss in issue before implementation
- **Testing**: Ensure molecule tests pass
- **Documentation**: Update relevant documentation files
### Governance
- **Maintainer**: Primary maintainer approves all merges
- **Review**: All changes require review before merge
- **Testing**: CI/CD must pass before merge
## Future Considerations
### BIND9 9.21+ and Beyond
- Monitor ISC release announcements
- Evaluate need for additional branches
- Consider dropping support for EOL'd distributions
- Reassess branching strategy if maintenance burden increases
### Automation Improvements
- Automated grammar fetching in CI
- Automated breaking change detection
- Version compatibility testing matrix
- Documentation generation from grammar files
## References
- [ISC BIND9 Documentation](https://bind9.readthedocs.io/)
- [ISC BIND9 Release Schedule](https://www.isc.org/bind/)
- [Semantic Versioning](https://semver.org/)
- [Ansible Best Practices](https://docs.ansible.com/ansible/latest/tips_tricks/ansible_tips_tricks.html)
## Changelog
| Date | Version | Changes |
|------|---------|---------|
| 2026-02-07 | 1.0 | Initial version support policy |