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

# 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