octavia-loxilb-driver 1.0.3
LoxiLB provider driver for OpenStack Octavia Load Balancer as a Service
Requires Python: >=3.8
Keywords: openstack, octavia, loadbalancer, loxilb

# LoxiLB Octavia Driver

[![PyPI version](https://badge.fury.io/py/octavia-loxilb-driver.svg)](https://badge.fury.io/py/octavia-loxilb-driver)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![OpenStack Zed+](https://img.shields.io/badge/openstack-zed+-orange.svg)](https://docs.openstack.org/octavia/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Software Load Balancer (SLB) OpenStack Octavia provider driver for [LoxiLB](https://github.com/loxilb-io/loxilb) - bringing eBPF/XDP-powered load balancing to your OpenStack cloud through dynamic VM provisioning.

## ✨ Features

- 🚀 **High Performance**: eBPF/XDP-based load balancing with minimal CPU overhead
- ☁️ **Cloud Native**: Seamless integration with OpenStack and Kubernetes environments  
- 🔄 **High Availability**: Support for ACTIVE_STANDBY and ACTIVE_ACTIVE topologies
- 🔧 **Full Integration**: Complete OpenStack Octavia provider driver implementation
- ✅ **Production Ready**: 121/121 tests passing with 100% test coverage
- 📦 **Easy Installation**: Automated setup with deployment profiles

## 🚀 Quick Start

Choose your deployment scenario:

### 📋 Common Steps (All Deployments)

#### Step 1: Setup OpenStack Resources
```bash
pip install octavia-loxilb-driver
# Run automated setup to create networks, flavors, and security groups
octavia-loxilb-setup
```

#### Step 2: Download and Upload LoxiLB VM Image
```bash
# Download LoxiLB VM image from releases
wget https://github.com/NLX-SeokHwanKong/octavia-loxilb-driver/releases/download/vm-v1.0.0/loxilb-vm-standard-v1.0.0.qcow2.gz

# Extract and upload to OpenStack with loxilb tag and performance properties
gunzip loxilb-vm-standard-v1.0.0.qcow2.gz
openstack image create --disk-format qcow2 --container-format bare \
    --public --tag loxilb \
    --property hw_vif_multiqueue_enabled=True \
    --property hw_vif_model=virtio \
    --property hw_disk_bus=virtio \
    --property hw_video_model=virtio \
    --property os_distro=ubuntu \
    --property os_type=linux \
    --file loxilb-vm-standard-v1.0.0.qcow2 loxilb-vm-standard

# Note: hw_vif_multiqueue_enabled=True is critical for LoxiLB performance
# It enables multiple queue networking for high-throughput packet processing
```

---

### 🖥️ Traditional OpenStack (systemd services)

#### Step 3: Install Driver on Controller Node
```bash
# Install on the controller node where Octavia services run
pip install octavia-loxilb-driver
```

#### Step 4: Configure Octavia
```bash
# Edit /etc/octavia/octavia.conf and add the generated configuration
sudo vim /etc/octavia/octavia.conf
```

#### Step 5: Restart Services
```bash
sudo systemctl restart octavia-api octavia-worker octavia-controller
```

---

### 🐳 Containerized Deployments

#### For Kolla-Ansible:
```bash
# Step 3: Install in Octavia containers
sudo docker exec octavia_api pip install octavia-loxilb-driver
sudo docker exec octavia_worker pip install octavia-loxilb-driver
sudo docker exec octavia_controller pip install octavia-loxilb-driver

# Step 4: Update kolla configuration
# Add to /etc/kolla/octavia-api/octavia.conf
# Add to /etc/kolla/octavia-worker/octavia.conf  
# Add to /etc/kolla/octavia-controller/octavia.conf

# Step 5: Restart containers
sudo docker restart octavia_api octavia_worker octavia_controller
```

#### For OpenStack-Helm (Kubernetes):
```bash
# Step 3: Update helm values to include the driver
# Add to values.yaml:
# conf:
#   octavia:
#     api_settings:
#       enabled_provider_drivers: amphora:amphora,loxilb:loxilb

# Step 4: Upgrade helm release
helm upgrade octavia ./octavia --values=values.yaml
```

#### For TripleO:
```bash
# Step 3: Add to container customization
# Create custom container image with the driver pre-installed
# Or use ExtraConfig to install during deployment
```

---

### 🔧 DevStack Environment

#### Step 3: Install in DevStack
```bash
# Install in devstack environment
source ~/devstack/openrc admin admin
pip install octavia-loxilb-driver

# Configure in local.conf for persistent setup
echo "pip install octavia-loxilb-driver" >> ~/devstack/local.sh
```

---

### ✅ Verification (All Deployments)
```bash
# Verify provider is available
openstack loadbalancer provider list

# Create your first LoxiLB load balancer
openstack loadbalancer create --provider loxilb --subnet-id <SUBNET_ID> my-lb
```

**Note**: For containerized deployments, you may need to rebuild container images or use persistent volume mounts to ensure the driver survives container restarts.

## 📋 Prerequisites

- **OpenStack**: Zed or later with Octavia service
- **Python**: 3.8+ with pip
- **Access**: OpenStack admin credentials and sudo access
- **Resources**: Available compute and network quotas
- **LoxiLB VM Image**: Downloaded from GitHub releases
- **Manual Configuration**: Octavia configuration file editing required

## 🏗️ Architecture

The LoxiLB Octavia Driver is a Software Load Balancer (SLB) that dynamically provisions LoxiLB VMs for each load balancer:

```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Octavia API   │───▶│  LoxiLB Driver   │───▶│ Dynamic LoxiLB VMs 
│ (Per Load Balancer)  │                  |    |                 |
└─────────────────┘    └──────────────────┘    └─────────────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │  OpenStack VMs   │
                    │ (LoxiLB Instance)│
                    └──────────────────┘
```

**Key Components:**
- **Provider Driver**: Main integration with Octavia API
- **LoxiLB API Client**: High-performance API communication with retry logic
- **Resource Mapping**: ID translation between Octavia and LoxiLB
- **Health Monitoring**: Coordinated health checking
- **State Reconciliation**: Ensures data consistency

## ⚡ Deployment Profiles

Choose the right profile for your environment:

| Profile | Use Case | Resources | Command |
|---------|----------|-----------|---------|
| **DevStack** | Development & Testing | 1 vCPU, 4GB RAM | `octavia-loxilb-setup --deployment-type devstack` |
| **Standard** | Standard Production | 2 vCPU, 8GB RAM | `octavia-loxilb-setup` (default) |
| **Production** | High Performance | 4 vCPU, 16GB RAM | `octavia-loxilb-setup --deployment-type production` |

## 🔧 Custom Configuration

For advanced deployments, create a JSON configuration file:

```json
{
  "flavor": {
    "name": "custom-loxilb-flavor",
    "vcpus": 2,
    "ram": 4096,
    "disk": 30
  },
  "network": {
    "name": "custom-mgmt-network",
    "cidr": "172.16.100.0/24"
  }
}
```

Use with: `octavia-loxilb-setup --custom-config config.json`

## 📊 Performance Benefits

Compared to traditional software load balancers:

- **10x Lower Latency**: eBPF/XDP processing in kernel space
- **50% Less CPU Usage**: Efficient packet processing without userspace overhead
- **Higher Throughput**: Multi-million packets per second capability
- **Better Scaling**: Linear performance scaling with additional cores

## 🌐 Network Architecture

### Management Network
- **Purpose**: Octavia controller ↔ LoxiLB VM communication
- **Default**: `octavia-mgmt-net` (192.168.1.0/24)
- **Ports**: 8091 (API), 9443 (BGP), 11111/22222 (HA)

### Data Networks
- **Purpose**: User traffic load balancing
- **Integration**: Works with existing tenant networks
- **Protocols**: TCP, UDP, HTTP, HTTPS with L4/L7 load balancing

## 🛠️ Deployment-Specific Installation

### 🖥️ Traditional OpenStack (Bare Metal/VMs)
```bash
# On controller node(s)
sudo pip install octavia-loxilb-driver
octavia-loxilb-setup --deployment-type production

# Configure /etc/octavia/octavia.conf
# Restart systemd services
sudo systemctl restart octavia-api octavia-worker octavia-controller
```

### 🐳 Kolla-Ansible Deployment
```bash
# Method 1: Install in existing containers (temporary)
for container in octavia_api octavia_worker octavia_controller; do
    sudo docker exec $container pip install octavia-loxilb-driver
done

# Method 2: Persistent installation via kolla customization
# Add to /etc/kolla/kolla-build.conf:
# [octavia-base]
# pip_packages = octavia-loxilb-driver

# Rebuild containers:
# kolla-build octavia
```

### ☸️ OpenStack-Helm (Kubernetes)
```yaml
# Add to helm values.yaml
images:
  tags:
    octavia_api: custom-octavia:latest  # with driver pre-installed

conf:
  octavia:
    api_settings:
      enabled_provider_drivers: amphora:amphora,loxilb:loxilb
    loxilb:
      # Generated configuration here
```

### 🎯 DevStack Development
```bash
# Install directly
pip install octavia-loxilb-driver
octavia-loxilb-setup --deployment-type devstack

# Or add to local.conf for automated setup
echo "pip_install octavia-loxilb-driver" >> local.conf
```

### 🔧 Manual/Custom Deployment
```bash
# Generate configuration only
pip install octavia-loxilb-driver
octavia-loxilb-setup --output-config /tmp/loxilb-config.conf

# Review and manually integrate configuration
# Restart services based on your deployment method
```

## 🔍 Verification

### Check Provider Availability
```bash
openstack loadbalancer provider list
# Should show 'loxilb' in the list
```

### Health Check
```bash
octavia-loxilb-health-check --detailed
```

### Create Test Load Balancer
```bash
openstack loadbalancer create --provider loxilb --subnet-id <SUBNET_ID> test-lb
openstack loadbalancer show test-lb
```

## 📚 Documentation

| Document | Description |
|----------|-------------|
| **[Quick Start Guide](docs/QUICKSTART.md)** | Get running in 10 minutes |
| **[Installation Guide](docs/INSTALLATION.md)** | Comprehensive setup instructions |
| **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** | Common issues and solutions |
| **[VM Images Guide](docs/LOXILB-VM-IMAGES.md)** | LoxiLB VM distribution and setup |
| **[Architecture Docs](docs/architecture/)** | Technical deep-dive documentation |

## 🔧 Configuration Reference

Key configuration sections in `/etc/octavia/octavia.conf`:

```ini
[api_settings]
enabled_provider_drivers = amphora:amphora,loxilb:loxilb

[driver_loxilb]
# LoxiLB VM Configuration
api_timeout = 30
api_retries = 3
debug_api_calls = true

# OpenStack Authentication (REQUIRED for VM provisioning)
auth_url = YOUR_KEYSTONE_AUTH_URL
auth_type = password
username = octavia
password = YOUR_OCTAVIA_PASSWORD
user_domain_name = Default
project_name = service
project_domain_name = Default

# OpenStack resource IDs (populated by setup script)
lb_mgmt_net_id = abc123-def456-ghi789
lb_security_group_id = def456-ghi789-jkl012
lb_flavor_id = ghi789-jkl012-mno345
lb_image_id = jkl012-mno345-pqr678
```

## 🔒 Security Features

- **Secure API Communication**: HTTPS with authentication
- **Network Isolation**: Separate management and data networks
- **Resource Isolation**: Dedicated security groups and networks
- **Access Control**: SSH key-based access to LoxiLB VMs
- **Audit Trail**: Comprehensive logging and monitoring

## 🐛 Troubleshooting

### Common Issues

**Provider not available:**
```bash
# Check configuration
sudo grep -A 10 "enabled_provider_drivers" /etc/octavia/octavia.conf

# Restart services
sudo systemctl restart octavia-api octavia-worker
```

**LoxiLB VM issues:**
```bash
# Check LoxiLB VM status
openstack server list --name loxilb-vm

# Check VM console logs
openstack console log show <LOXILB_VM_ID>

# Check security groups
openstack security group show loxilb-mgmt-sec-grp
```

For detailed troubleshooting, see the [Troubleshooting Guide](docs/TROUBLESHOOTING.md).

## 🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Ensure all tests pass: `python -m pytest`
5. Submit a pull request

### Development Setup
```bash
git clone https://github.com/NLX-SeokHwanKong/octavia-loxilb-driver.git
cd octavia-loxilb-driver
pip install -e .
python -m pytest octavia_loxilb_driver/tests/unit/ -v
```

## 🆘 Support

- **GitHub Issues**: [Report bugs and request features](https://github.com/NLX-SeokHwanKong/octavia-loxilb-driver/issues)
- **LoxiLB Community**: [LoxiLB project](https://github.com/loxilb-io/loxilb)
- **Documentation**: [Complete documentation suite](docs/)
- **Health Check**: Built-in diagnostic tool: `octavia-loxilb-health-check`

## 📈 Roadmap

- [x] **v1.0.0**: Production-ready driver with automated setup
- [ ] **v1.1.0**: Enhanced monitoring and metrics
- [ ] **v1.2.0**: Advanced traffic policies and SSL termination
- [ ] **v2.0.0**: Multi-cloud integration and service mesh support

## 🏢 Production Usage

The LoxiLB Octavia Driver is designed for production use with:

- **Enterprise Grade**: Comprehensive testing and validation
- **High Availability**: Multi-instance deployment support
- **Monitoring Integration**: Extensive logging and health checks
- **Performance Optimization**: Tuned for high-throughput scenarios
- **Security Hardening**: Following OpenStack security best practices

## 🌟 Why Choose LoxiLB?

- **Modern Architecture**: eBPF/XDP for ultimate performance
- **Cloud Native**: Built for containerized and virtualized environments
- **OpenStack Integration**: Native Octavia provider driver
- **Active Development**: Continuous improvements and feature additions
- **Community Support**: Growing ecosystem and user community

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **LoxiLB Team**: For the amazing eBPF/XDP load balancer
- **OpenStack Octavia Team**: For the extensible load balancing framework
- **OpenStack Community**: For the robust cloud platform
- **Contributors**: Everyone who has contributed to this project

---

## 🚀 Get Started Today!

```bash
# Install the driver
pip install octavia-loxilb-driver

# Setup OpenStack resources
octavia-loxilb-setup

# Download VM image and configure Octavia (see Quick Start above)
```

Transform your OpenStack load balancing with the power of eBPF/XDP!

**Questions?** Check out our [documentation](docs/) or [open an issue](https://github.com/NLX-SeokHwanKong/octavia-loxilb-driver/issues).

---

*Made with ❤️ by the LoxiLB and OpenStack communities*