feat: initial playbook
This commit is contained in:
Doni Crosby
parent
99bfb97ee7
commit
f8e1de4f0a
30 changed files with 1097 additions and 2 deletions
232
README.md
232
README.md
|
|
@ -1,3 +1,231 @@
|
|||
# netbox-ansible
|
||||
# NetBox Ansible Deployment
|
||||
|
||||
Ansible playbook for managing the netbox server
|
||||
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, 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
|
||||
- **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
|
||||
│ └── 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
|
||||
|
||||
# Encrypt sensitive variables
|
||||
ansible-vault encrypt group_vars/netbox/vault.yml
|
||||
```
|
||||
|
||||
3. **Deploy NetBox**
|
||||
```bash
|
||||
# Run the deployment playbook
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
|
||||
```
|
||||
|
||||
## 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_allowed_hosts`: Allowed hosts for NetBox
|
||||
- `netbox_superuser_*`: Superuser configuration
|
||||
- `netbox_db_*`: Database configuration
|
||||
- `netbox_redis_*`: Redis 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
|
||||
|
||||
Customize Docker Compose configuration via `netbox_docker_compose_overrides`:
|
||||
|
||||
```yaml
|
||||
netbox_docker_compose_overrides:
|
||||
services:
|
||||
netbox:
|
||||
ports:
|
||||
- "8000:8080"
|
||||
db:
|
||||
volumes:
|
||||
- "/opt/netbox-data/postgres:/var/lib/postgresql/data"
|
||||
```
|
||||
|
||||
## Playbooks
|
||||
|
||||
### Main Deployment (`deploy-netbox.yml`)
|
||||
|
||||
Deploys NetBox from scratch:
|
||||
- Updates system packages
|
||||
- Installs Docker and Docker Compose
|
||||
- Clones NetBox Docker repository
|
||||
- Configures environment files
|
||||
- Starts NetBox services
|
||||
- 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
|
||||
|
||||
### netbox-deploy
|
||||
- Creates necessary directories
|
||||
- Clones NetBox Docker repository
|
||||
- Generates configuration files
|
||||
- Starts NetBox services
|
||||
- Creates superuser account
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Deploy NetBox
|
||||
```bash
|
||||
ansible-playbook -i inventory/hosts.yml playbooks/deploy-netbox.yml
|
||||
```
|
||||
|
||||
### 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 "docker-install"
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## 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 port 8000 is available
|
||||
4. **Database Connection**: Check database configuration and connectivity
|
||||
|
||||
### 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"
|
||||
```
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue