netbox-ansible/README.md

# NetBox Ansible Deployment

This Ansible project deploys NetBox using Docker Compose on Ubuntu servers. It follows Ansible best practices with modular roles, idempotent operations, and comprehensive configuration management.

## Features

- **Modular Design**: Separate roles for system updates, Docker installation, Traefik reverse proxy, and NetBox deployment
- **Idempotent**: Safe to run multiple times without side effects
- **Ubuntu Only**: Specifically designed for Ubuntu distributions (Focal, Jammy, Noble)
- **Docker Compose**: Uses the official NetBox Docker repository
- **Traefik Integration**: Automatic reverse proxy with ACME TLS certificate management
- **HTTPS by Default**: Automatic HTTP to HTTPS redirection with Let's Encrypt certificates
- **Configuration Management**: Templated environment files with Ansible variables
- **Security**: Support for Ansible Vault for sensitive data
- **Backup Support**: Built-in backup playbook for data protection

## Project Structure

```
netbox-ansible/
├── ansible.cfg                 # Ansible configuration
├── inventory/
│   └── hosts.yml              # Inventory file
├── group_vars/
│   ├── netbox.yml             # Group variables
│   └── netbox/
│       └── vault.yml          # Encrypted sensitive variables
├── playbooks/
│   ├── deploy-netbox.yml      # Main deployment playbook
│   ├── update-netbox.yml      # Update NetBox playbook
│   └── backup-netbox.yml      # Backup NetBox playbook
├── roles/
│   ├── system-update/         # System package updates
│   ├── docker-install/        # Docker and Docker Compose installation
│   ├── traefik/              # Traefik reverse proxy with ACME TLS
│   └── netbox-deploy/        # NetBox deployment and configuration
└── templates/                 # Additional templates if needed
```

## Prerequisites

- Ansible 2.9 or later
- Target servers running Ubuntu (Focal, Jammy, or Noble)
- SSH access to target servers with sudo privileges
- Python 3 on target servers

## Quick Start

1. **Configure Inventory**
   ```bash
   # Edit inventory/hosts.yml
   vim inventory/hosts.yml
   ```
   Add your server(s):
   ```yaml
   [netbox]
   netbox-server ansible_host=192.168.1.100 ansible_user=ubuntu
   ```

2. **Configure Variables**
   ```bash
   # Edit group variables
   vim group_vars/netbox.yml
   
   # Edit vault variables (domains, ACME email, etc.)
   vim group_vars/netbox/vault.yml
   
   # Encrypt sensitive variables
   ansible-vault encrypt group_vars/netbox/vault.yml
   ```

3. **Deploy NetBox with Traefik**
   ```bash
   # Run the deployment playbook (includes Traefik)
   ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass
   ```

4. **Access Your Services**
   - NetBox: `https://your-domain.com`
   - Traefik Dashboard: `https://traefik.your-domain.com:8080`

## Configuration

### Group Variables (`group_vars/netbox.yml`)

Key configuration options:

- `netbox_install_dir`: Directory for NetBox installation (default: `/opt/netbox-docker`)
- `netbox_data_dir`: Directory for persistent data (default: `/opt/netbox-data`)
- `netbox_backup_dir`: Directory for backups (default: `/opt/netbox-backups`)
- `netbox_domain`: Domain name for NetBox (configured in vault)
- `netbox_allowed_hosts`: Allowed hosts for NetBox
- `netbox_superuser_*`: Superuser configuration
- `netbox_db_*`: Database configuration
- `netbox_redis_*`: Redis configuration
- `traefik_*`: Traefik reverse proxy configuration

### Vault Variables (`group_vars/netbox/vault.yml`)

Sensitive data should be encrypted:

```bash
# Encrypt vault file
ansible-vault encrypt group_vars/netbox/vault.yml

# Edit encrypted vault file
ansible-vault edit group_vars/netbox/vault.yml
```

### Docker Compose Overrides

NetBox is now configured to work with Traefik labels instead of port forwarding:

```yaml
netbox_docker_compose_overrides:
  services:
    netbox:
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.netbox.rule=Host(`{{ netbox_domain }}`)"
        - "traefik.http.routers.netbox.entrypoints=websecure"
        - "traefik.http.routers.netbox.tls.certresolver=letsencrypt"
        - "traefik.http.services.netbox.loadbalancer.server.port=8080"
      networks:
        - "traefik"
```

## Playbooks

### Main Deployment (`deploy-netbox.yml`)

Deploys NetBox with Traefik reverse proxy:
- Updates system packages
- Installs Docker and Docker Compose
- Deploys Traefik reverse proxy with ACME TLS
- Clones NetBox Docker repository
- Configures environment files
- Starts NetBox services behind Traefik
- Creates superuser account

### Update NetBox (`update-netbox.yml`)

Updates existing NetBox installation:
- Updates repository
- Pulls latest Docker images
- Restarts services

### Backup NetBox (`backup-netbox.yml`)

Creates comprehensive backup:
- Database dump
- Media files
- Configuration files

## Roles

### system-update
- Updates apt package cache
- Upgrades all packages
- Installs required packages
- Optional reboot if needed

### docker-install
- Adds Docker GPG key and repository
- Installs Docker CE and Docker Compose
- Configures Docker daemon
- Adds users to docker group

### traefik
- Creates Traefik directories and configuration
- Sets up ACME certificate resolver for Let's Encrypt
- Configures Docker provider for automatic service discovery
- Deploys Traefik reverse proxy with HTTPS redirection
- Creates external network for service communication

### netbox-deploy
- Creates necessary directories
- Clones NetBox Docker repository
- Generates configuration files
- Starts NetBox services with Traefik labels
- Creates superuser account

## Usage Examples

### Deploy NetBox with Traefik
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass
```

### Update NetBox
```bash
ansible-playbook -i inventory/hosts.yml playbooks/update-netbox.yml
```

### Backup NetBox
```bash
ansible-playbook -i inventory/hosts.yml playbooks/backup-netbox.yml
```

### Run with Vault
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass
```

### Run Specific Tags
```bash
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --tags "traefik"
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --tags "netbox-deploy"
```

### Traefik Management
```bash
# Check Traefik status
make traefik-status

# View Traefik logs
make traefik-logs

# View access logs (JSON format for auditing)
make traefik-access-logs

# Restart Traefik
make traefik-restart

# Update custom root CA certificate
make traefik-update-ca
```

## Security Considerations

1. **Encrypt Sensitive Data**: Use `ansible-vault` for passwords and secrets
2. **SSH Key Authentication**: Use SSH keys instead of passwords
3. **Firewall Rules**: Configure appropriate firewall rules (ports 80, 443)
4. **TLS Certificates**: ACME certificates are automatically managed by Traefik
5. **Custom Root CA**: Support for custom certificate authorities alongside system CAs
6. **Access Logging**: Comprehensive JSON-formatted access logs for auditing
7. **Regular Updates**: Keep NetBox and dependencies updated
8. **Backup Strategy**: Implement regular backup procedures

## Troubleshooting

### Common Issues

1. **Permission Denied**: Ensure user has sudo privileges
2. **Docker Not Found**: Check Docker installation and user group membership
3. **Port Conflicts**: Verify ports 80 and 443 are available
4. **Database Connection**: Check database configuration and connectivity
5. **TLS Certificate Issues**: Check ACME configuration and domain DNS
6. **Traefik Not Starting**: Check Docker network and configuration

### Logs and Debugging

```bash
# Enable verbose output
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml -vvv

# Check Docker Compose logs
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/netbox-docker && docker compose logs"

# Check Traefik logs
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/traefik && docker compose logs traefik"
```

## Logging and Auditing

### Access Logs
Traefik is configured with comprehensive access logging in JSON format for easy parsing and auditing:

- **Format**: JSON structured logs
- **Fields**: Includes request details, response codes, timing, and headers
- **Security**: Authorization headers are automatically dropped from logs
- **Headers Tracked**: User-Agent, Content-Type, X-Forwarded-For, X-Real-IP, etc.

### Log Management Commands
```bash
# View recent access logs
make traefik-access-logs

# View all Traefik logs
make traefik-logs

# Follow logs in real-time
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/traefik && docker compose logs -f traefik"
```

### Log Analysis Examples
```bash
# Count requests by status code
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/traefik && docker compose logs traefik | grep access | jq '.DownstreamStatus' | sort | uniq -c"

# Find failed requests
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/traefik && docker compose logs traefik | grep access | jq 'select(.DownstreamStatus >= 400)'"

# Analyze by IP address
ansible netbox -i inventory/hosts.yml -m shell -a "cd /opt/traefik && docker compose logs traefik | grep access | jq '.ClientHost' | sort | uniq -c"
```

## Custom Root CA Configuration

Traefik can be configured to trust custom root certificate authorities while maintaining trust for system root CAs. This is useful for internal PKI environments or corporate certificate authorities.

### Configuration

Set the custom CA URL in your vault file:

```yaml
# Custom Root CA Configuration
vault_traefik_custom_ca_url: "https://your-ca-server.com/root-ca.pem"
```

### Features

- **Dual Trust**: Trusts both custom CA and system root CAs
- **Automatic Download**: Downloads CA certificate from web server during deployment
- **Certificate Validation**: Verifies certificate format using OpenSSL
- **Secure Storage**: CA certificate stored with appropriate permissions
- **Easy Updates**: Update CA certificate without full redeployment

### Management Commands

```bash
# Update custom root CA certificate
make traefik-update-ca

# Verify CA certificate manually
ansible netbox -i inventory/hosts.yml -m shell -a "openssl x509 -in /etc/traefik/custom-ca.pem -text -noout"
```

### Requirements

- Custom CA certificate must be accessible via HTTP/HTTPS GET request
- Certificate must be in PEM format
- Web server must be accessible from the deployment server
- Certificate validation can be disabled if needed (`traefik_custom_ca_verify_ssl: false`)

## Contributing

1. Follow Ansible best practices
2. Ensure idempotency
3. Add appropriate tags
4. Update documentation
5. Test on multiple Ubuntu versions

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Check NetBox documentation: https://docs.netbox.dev/
- NetBox Community: https://github.com/netbox-community/netbox
- NetBox Docker: https://github.com/netbox-community/netbox-docker