Octavia Client for OpenStack Load Balancing

3.13.0 · active · verified Fri Apr 17

The `python-octaviaclient` library provides a client for interacting with the OpenStack Octavia Load Balancing service API (primarily v2). It allows users to programmatically manage load balancers, listeners, pools, members, and health monitors within an OpenStack environment. The current version is 3.13.0, and releases generally follow OpenStack development cycles, with patch releases occurring as needed.

Common errors

```
ImportError: cannot import name 'Client' from 'octaviaclient.client'
```
cause Attempting to import the client from an incorrect or non-existent path.

fix The `Client` class is specific to API v2. Use `from octaviaclient.v2.client import Client`.
```
HTTP 401 Unauthorized: The request you have made requires authentication.
```
cause Incorrect or missing OpenStack authentication credentials (e.g., environment variables) or an unreachable Keystone endpoint.

fix Verify that `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, `OS_USER_DOMAIN_NAME`, and `OS_PROJECT_DOMAIN_NAME` are correctly set as environment variables or passed directly to the `keystoneauth1.identity.v3.Password` constructor.
```
keystoneauth1.exceptions.catalog.EndpointNotFound: Could not find service endpoint for type 'load-balancer' in region 'RegionOne'.
```
cause The Octavia (load-balancer) service is not available in the specified region, or the service type/interface is incorrect.

fix Check your OpenStack service catalog (`openstack catalog show`) to confirm the availability of 'load-balancer' service in your target `region_name`. Ensure `service_type` is 'load-balancer' and `interface` is appropriate (e.g., 'public', 'admin', 'internal').

Warnings

gotcha Authentication requires `keystoneauth1`. Users commonly forget to install it or configure it correctly, leading to authentication errors or `ImportError`.
Fix: Ensure `pip install keystoneauth1` is run and that OpenStack environment variables (e.g., `OS_AUTH_URL`, `OS_USERNAME`, `OS_PASSWORD`, `OS_PROJECT_NAME`, etc.) are correctly set or provided programmatically.
breaking The client is designed for Octavia API v2. Direct support for any hypothetical Octavia API v1 is not present in this client. Attempting to use older API versions or endpoints will result in errors.
Fix: Ensure that the Octavia service endpoint configured in your OpenStack environment (or passed to the client) corresponds to API v2, typically `/v2.0` suffix. The client's imports explicitly use `v2`.
gotcha The client methods return dictionaries (or lists of dictionaries) representing API resources, not custom object classes. This means direct attribute access (e.g., `lb.name`) will not work; dictionary key access (e.g., `lb['name']`) is required.
Fix: Always access resource properties using dictionary syntax, e.g., `load_balancer['id']` or `load_balancer['name']`. If you prefer object-like access, consider wrapping the dictionaries in a custom class or using `openstacksdk` which provides object abstractions.

Install

pip install python-octaviaclient Install latest version

Imports

Client
wrong:
```
from octaviaclient.client import Client
```
correct:
```
from octaviaclient.v2.client import Client
```
The client class is specific to API version 2, so it's located under the `v2` module.
Session
```
from keystoneauth1.session import Session
```
Required for authentication; not directly part of octaviaclient but essential for its usage.
Adapter
```
from keystoneauth1.adapter import Adapter
```
Required for authenticating API requests with Keystone; not directly part of octaviaclient but essential for its usage.

Quickstart

This quickstart demonstrates how to initialize the Octavia client using Keystone v3 authentication, retrieve an authenticated session, and then list existing load balancers. It relies on standard OpenStack environment variables for credentials. Ensure these are set or replace `os.environ.get` calls with your specific values.

import os
from keystoneauth1.identity import v3
from keystoneauth1.session import Session
from keystoneauth1.adapter import Adapter
from octaviaclient.v2.client import Client

# Set OpenStack authentication environment variables (e.g., OS_AUTH_URL, OS_USERNAME, OS_PASSWORD, etc.)
# Or directly provide credentials

auth = v3.Password(
    auth_url=os.environ.get('OS_AUTH_URL', 'http://localhost:5000/v3'),
    username=os.environ.get('OS_USERNAME', 'admin'),
    password=os.environ.get('OS_PASSWORD', 'password'),
    project_name=os.environ.get('OS_PROJECT_NAME', 'admin'),
    user_domain_name=os.environ.get('OS_USER_DOMAIN_NAME', 'Default'),
    project_domain_name=os.environ.get('OS_PROJECT_DOMAIN_NAME', 'Default')
)
sess = Session(auth=auth)

# Create an Octavia client adapter
octavia_client = Client(
    session=sess,
    region_name=os.environ.get('OS_REGION_NAME', None),
    service_type='load-balancer',
    interface='public'
)

try:
    # Example: List all load balancers
    load_balancers = octavia_client.loadbalancer.list()
    print(f"Found {len(load_balancers)} load balancers:")
    for lb in load_balancers:
        print(f"  - ID: {lb['id']}, Name: {lb['name']}, Provisioning Status: {lb['provisioning_status']}")
except Exception as e:
    print(f"Error connecting to Octavia or listing load balancers: {e}")
    print("Please ensure your OpenStack environment variables are correctly set.")

view raw JSON →