Metadata-Version: 2.1
Name: sp-ovirt
Version: 0.2.2
Summary: StorPool integration for oVirt
Author-email: StorPool <support@storpool.com>
License-Expression: Apache-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.6
Provides-Extra: ovirt-engine
Requires-Dist: psycopg2>=2.7.5; extra == 'ovirt-engine'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2025 StorPool <support@storpool.com>
SPDX-License-Identifier: Apache-2.0
-->
# oVirt StorPool Adapter

This package provides StorPool integration for oVirt in the form of a Managed
Storage Domain adapter.

## Requirements

The StorPool adapter works through a Managed Storage Dispatch mechanism that is
proposed by these pull requests:

- https://github.com/oVirt/ovirt-engine/pull/1081
- https://github.com/oVirt/vdsm/pull/442

Additionally it requires the changes from the following pull request that add
support for the StorPool storage driver type:

- https://github.com/oVirt/vdsm/pull/449

Current production versions of oVirt and Vdsm can be patched post-installation.

### oVirt Engine

No StorPool installation is required on the Engine hosts. The StorPool adapter
works through the StorPool API entirely. Network access to the StorPool API must
be provided to the host running the Engine (be it standalone or hosted).

To configure the StorPool API host and credentials, the following fields need to
be passed along in the `driver_options` and `driver_sensitive_options`
dictionaries during managed storage domain creation:

- `adapter` must be set to `storpool`.

- `sp_api_http_host`: the floating IP address (or hostname) of the StorPool
  cluster API. Same as `SP_API_HTTP_HOST` in `storpool.conf`.

- `sp_api_http_port`: the StorPool API port (optional). Same as
  `SP_API_HTTP_PORT` in `storpool.conf`. If not set, defaults to `81`.

- `sp_auth_token`: the StorPool API authentication token. Same as
  `SP_AUTH_TOKEN` in `storpool.conf`. This must be in the
  `driver_sensitive_options` dictionary.

The adapter also requires access to the Managed Block database (CinderLib
database in older versions of oVirt), where it will create its own set of tables
to store the mapping between oVirt's disk UUIDs and StorPool's volume global
IDs. This database can be created at any point by running the oVirt
`engine-setup` utility with the `--reconfigure-optional-components` argument.

### Vdsm

Each Vdsm hypervisor node in the cluster that would be attaching StorPool
volumes needs at the least the StorPool block and client installed. Hypervisor
nodes can also be hyperconverged (have StorPool server as well).

The StorPool adapter requires access to `/etc/storpool.conf` on the Vdsm hosts
as well as network access to the StorPool API. The adapter reads the following
configuration variables from `/etc/storpool.conf`:

- `SP_API_HTTP_HOST`;
- `SP_API_HTTP_PORT` (optional, defaults to `81` if missing);
- `SP_AUTH_TOKEN`;
- `SP_OURID` under the section for the Vdsm host.

Additionally to the Managed Storage Dispatch mechanism, the StorPool adapter
requires the Vdsm hook mechanism to be available.

The adapter uses the following Vdsm hooks:

- `before_vm_start`: used to implement safer VM start. This is done to prevent
  potential data corruption by making sure all other disk attachments are
  forcefully disconnected.

## Installation

After installing the package on each Vdsm host, the following must be done (it
will become part of the package post-install script in the future):

- Add `sanlock`, `vdsm`, `qemu` and `ovirtimg` users to the `disk` group. This
  allows various non-superuser Vdsm and oVirt components to have read-write
  access to StorPool block devices.

```
for user in sanlock vdsm qemu ovirtimg; do
    usermod -a -G disk $user
done
```

- Block StorPool devices in the multipath configuration.

```
cat > /etc/multipath/conf.d/storpool_blacklist.conf <<EOF
blacklist {
    devnode "sp-[0-9]+"
}
EOF
```

To activate the integration, users need to manually link the `sp-ovirt-*`
scripts.

For oVirt engine:

```
ln -sf /usr/bin/sp-ovrit-adapter /usr/share/ovirt-engine/managedblock/storpool-adapter
```

For Vdsm:

```
ln -sf /usr/bin/sp-vdsm-adapter /usr/libexec/vdsm/managedvolume-helper-storpool
ln -sf /usr/bin/sp-vdsm-hook /usr/libexec/vdsm/hooks/before_vm_start/99_storpool_hook
```

An upcoming release with support for automatic patching of older oVirt versions
that do not include managed storage adapters will automatically set these up.

## Storage Setup

StorPool storage domains are created using the Managed Storage Domain type, by
setting the `adapter` field to `storpool` in the `driver_options` map. This can
be done through the oVirt web admin interface or automated with Ansible as
described below.

The `adapter` field is mandatory. It will instruct the `CinderlibExecutor` to
redirect all storage operations for that storage domain to our vendor helper
scripts.

Example using the `ovirt.ovirt.ovirt_storage_domain` Ansible module:

```
ovirt.ovirt.ovirt_storage_domain:
  auth: "{{ ovirt_auth }}"
  data_center: Default
  host: "{{ vdsm_host }}"
  name: storpool
  managed_block_storage:
    driver_options:
      - name: adapter
        value: storpool
      - name: sp_api_http_host
        value: 10.1.2.3
    driver_sensitive_options:
      - name: sp_auth_token
        value: "changeme"
  state: present
```

The `vdsm_host` is the name of an already registered Vdsm host in the oVirt
cluster, for example one created by using the `ovirt.ovirt.ovirt_host` or
manually through the oVirt web admin interface. The Vdsm host must also have the
StorPool integration installed beforehand.

The `ovirt_auth` fact can be obtained by running the `ovirt.ovirt.ovirt_auth`
module. For more information visit the oVirt Ansible collection documentation
at [https://galaxy.ansible.com/ui/repo/published/ovirt/ovirt/docs/].

## Storage Usage

The StorPool Managed Storage integration supports the following:

- Creating disks directly in the StorPool Storage domain;

- Copying disk from other Storage Domains (e.g. NFS) to the StorPool Storage
  Domain;

- Attaching StorPool disks to a VM (during creation, while the VM is live or
  powered down);

- Live migrating a VM from one Vdsm host to another, where both Vdsm hosts have
  the StorPool integration;

- Creating VM snapshots;

- Previewing VM snapshots;

- Reverting a VM to a snapshot preview;

- Deleting VM snapshots.

## StorPool Tags

The StorPool integration will tag each volume (oVirt disk) and snapshot with the
corresponding oVirt UUID using the `ovirt-uuid` tag.
