Installation Guide

This guide covers installing Cyborg, the OpenStack Acceleration Service, from source or packages. The instructions are written for manual installation but are also designed to help packagers and deployment automation tools understand the component dependencies, configuration requirements, and service ordering.

Overview

Cyborg manages hardware accelerators (FPGAs, GPUs, NICs, SSDs, AI chips) in OpenStack clouds. A typical deployment includes:

cyborg-api

REST API service, normally deployed behind a WSGI server (Apache/nginx + uwsgi). Handles device profile queries, ARQ creation, and accelerator discovery.

cyborg-conductor

Central orchestration service. Manages placement inventory updates, coordinates device bindings, and interacts with Nova for instance lifecycle events.

cyborg-agent

Runs on compute nodes. Discovers local accelerators via drivers, reports inventory to the conductor, and manages device programming and attachment.

Cyborg integrates with Nova (instance lifecycle), Placement (resource inventory and scheduling), Neutron (for SmartNIC flows), and Glance (for FPGA bitstream metadata).

Prerequisites

Before installing Cyborg:

  • An operational OpenStack deployment with at least Keystone and Placement. (Neutron and Glance would be required later when creating resources that interact with those services). Cyborg is tested against the current and previous OpenStack release.

  • A database (MySQL/MariaDB).

  • A message broker (RabbitMQ recommended).

  • Python 3.11 or newer.

See the Cyborg Support Matrix for supported VM operations and driver compatibility with specific Nova versions.

Installation Methods

Both methods share common configuration steps documented in Common Configuration.

Post-Installation

After installing Cyborg services:

Configuration

See Common Configuration for database setup, service credentials, API endpoints, and cyborg.conf settings. Driver-specific configuration is covered in Configuration Guide.

Upgrades

See Upgrades for safe upgrade procedures, database migration ordering, and online data migration requirements. Always review release-specific notes before upgrading.

Security

See Security for ARQ ownership scoping, service token requirements for Nova integration, and Keystone configuration. Cyborg requires service tokens for operations on bound ARQs.

Verification

After starting services, verify Cyborg is operational:

$ openstack accelerator device list
$ cyborg-status upgrade check

The cyborg-status command performs health and upgrade readiness checks.

Next Steps