ansible-bind9-role/docs/BIND9_9.20_SUPPORT.md

# BIND9 9.20 Support Implementation Guide

## Overview

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

### Branch-Based Support Strategy

The role uses branch-only support boundaries:

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 support
│
└─ 9.20                 # BIND9 9.20+ feature-release support
   └─ feature/*          # Short-lived feature branches targeting 9.20
```

## Implementation Details

### 1. Task Flow

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.

There is no runtime `bind9_version` fact in this flow.

### 2. Meta/Argument Specs Updates

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

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 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
- `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 9.20 branch should handle this through:

1. **Documentation**: Each deprecated option is documented in BIND9_MIGRATION_GUIDE.md
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

### 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
- [ ] 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
- [ ] 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](BIND_VERSION_DIFFERENCES.md)
- [BIND9 Migration Guide](BIND9_MIGRATION_GUIDE.md)
- [VERSION_SUPPORT.md](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