feat: deployable playbook
This commit is contained in:
Doni Crosby
parent
f8e1de4f0a
commit
7ab2b719dc
23 changed files with 754 additions and 176 deletions
162
README.md
162
README.md
|
|
@ -4,10 +4,12 @@ This Ansible project deploys NetBox using Docker Compose on Ubuntu servers. It f
|
|||
|
||||
## Features
|
||||
|
||||
- **Modular Design**: Separate roles for system updates, Docker installation, and NetBox deployment
|
||||
- **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
|
||||
|
|
@ -30,6 +32,7 @@ netbox-ansible/
|
|||
├── 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
|
||||
```
|
||||
|
|
@ -59,16 +62,23 @@ netbox-ansible/
|
|||
# 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**
|
||||
3. **Deploy NetBox with Traefik**
|
||||
```bash
|
||||
# Run the deployment playbook
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
|
||||
# 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`)
|
||||
|
|
@ -78,10 +88,12 @@ 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`)
|
||||
|
||||
|
|
@ -97,29 +109,33 @@ ansible-vault edit group_vars/netbox/vault.yml
|
|||
|
||||
### Docker Compose Overrides
|
||||
|
||||
Customize Docker Compose configuration via `netbox_docker_compose_overrides`:
|
||||
NetBox is now configured to work with Traefik labels instead of port forwarding:
|
||||
|
||||
```yaml
|
||||
netbox_docker_compose_overrides:
|
||||
services:
|
||||
netbox:
|
||||
ports:
|
||||
- "8000:8080"
|
||||
db:
|
||||
volumes:
|
||||
- "/opt/netbox-data/postgres:/var/lib/postgresql/data"
|
||||
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 from scratch:
|
||||
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
|
||||
- Starts NetBox services behind Traefik
|
||||
- Creates superuser account
|
||||
|
||||
### Update NetBox (`update-netbox.yml`)
|
||||
|
|
@ -150,18 +166,25 @@ Creates comprehensive backup:
|
|||
- 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
|
||||
- Starts NetBox services with Traefik labels
|
||||
- Creates superuser account
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Deploy NetBox
|
||||
### Deploy NetBox with Traefik
|
||||
```bash
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-pass
|
||||
```
|
||||
|
||||
### Update NetBox
|
||||
|
|
@ -181,16 +204,38 @@ ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --ask-vault-
|
|||
|
||||
### Run Specific Tags
|
||||
```bash
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --tags "docker-install"
|
||||
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
|
||||
4. **Regular Updates**: Keep NetBox and dependencies updated
|
||||
5. **Backup Strategy**: Implement regular backup procedures
|
||||
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
|
||||
|
||||
|
|
@ -198,8 +243,10 @@ ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml --tags "dock
|
|||
|
||||
1. **Permission Denied**: Ensure user has sudo privileges
|
||||
2. **Docker Not Found**: Check Docker installation and user group membership
|
||||
3. **Port Conflicts**: Verify port 8000 is available
|
||||
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
|
||||
|
||||
|
|
@ -209,8 +256,83 @@ 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue