Skip to main content

Install with kolla-ansible

The service's kolla-ansible playbook uses your inventory to deploy containers, create the database and Keystone service user, register the backup endpoint, and configure HAProxy. The installer links the service's role and playbook into your kolla-ansible installation.

kolla-ansible 2025.1 (Epoxy) or newer is required. The playbook refuses older releases in its first play.

Check the cloud's storage first​

Identify where your volumes and instance disks are stored before preparing the inventory. The configuration below supports Ceph storage. Other backends may require compute agents or movers on the storage network. Check Supported storage for their requirements.

Prepare the deploy host​

From the deploy/kolla directory of the release:

./install.sh
cp inventory/ferry-groups /etc/kolla/ferry-groups
cat etc/passwords.yml >> /etc/kolla/passwords.yml
kolla-genpwd

install.sh links the role into the kolla-ansible installation it finds on PATH. Run it again after every kolla-ansible upgrade, because pip replaces the directory the links live in.

ferry-groups is a second inventory file that maps the service's groups onto yours:

[ferry-manager:children]
control

[ferry-mover:children]
control

[ferry-compute:children]
compute

[ferry-mover-fabric]

You can initially run movers on control nodes. Use dedicated hosts when backups need more bandwidth or must be isolated from API host failures. To do that, list those hosts under [ferry-mover] instead. Every hypervisor whose guests should get filesystem-consistent backups needs to be in [ferry-compute]. Leave [ferry-mover-fabric] empty unless Storage the service can read says otherwise.

Create the Ceph users​

Create separate cephx identities for the manager, backup reads and restores. The backup identity has read-only access to production pools, limiting what movers can do while backing up data.

./tools/create-cephx.sh

Run it where you have the Ceph admin keyring. It writes the keyrings and a minimal ceph.conf to /etc/kolla/config/ferry/ceph/. If that is not the deploy host, copy the directory there. Running it again is safe. It reuses existing users and leaves an existing ceph.conf unchanged.

Configure globals.yml​

Set these values in /etc/kolla/globals.yml:

enable_ferry: "yes"
ferry_tag: "0.16.1"
ferry_external_fqdn: "backup.mycompany.com"
ferry_ceph_enabled: true
ferry_kms_driver: "none"
  • ferry_tag pins the release. Pin it explicitly and change it only to upgrade.
  • ferry_external_fqdn is the public name of the API and the console, served through kolla's external HAProxy. With kolla's haproxy_single_external_frontend on, they answer on that name's HTTPS port. Otherwise they answer on port 9776 (ferry_api_port), as https://backup.mycompany.com:9776/.
  • ferry_kms_driver decides whether backups are encrypted: barbican, vault or none. It is used to protect repository credentials and keys at registration. Review Encryption before choosing.

The site name, which movers use to find work, defaults to the region name in lower case (ferry_site_name). Repositories are registered against it.

To protect object storage buckets on a cloud with kolla's RADOS Gateway, add:

ferry_objects_enabled: true

and create the gateway user once, where radosgw-admin works:

./tools/create-rgw-user.sh

It writes the user's keys to /etc/kolla/config/ferry/objects.yml. Keep that file owned by the user who runs kolla-ansible. The role reads it without privilege escalation. A root-owned copy fails the deploy with "Could not find or access".

To let projects browse files inside a backup through the API, add ferry_enable_flr: true. It switches the movers to an image that can open guest filesystems.

Deploy​

PLAYBOOK=$(dirname $(which kolla-ansible))/../share/kolla-ansible/ansible/ferry.yml
kolla-ansible prechecks -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK
kolla-ansible pull      -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK
kolla-ansible deploy    -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK

Run pull as its own step. deploy starts the containers from whatever image is present. If you change ferry_tag without a pull, the old version keeps running and nothing reports it.

The run restarts HAProxy through kolla's own handlers, standby nodes first and the node holding the virtual IP last. Like any kolla service deployment, it also re-renders kolla's HAProxy and keepalived configuration from globals.yml.

Configuration beyond the role's variables goes in /etc/kolla/config/ferry/manager.yaml, mover.yaml or compute.yaml, merged over what the role renders. If a component finds a key it does not know, it refuses to start and names the key.

Send the logs to OpenSearch​

Every component writes JSON lines to /var/log/kolla/ferry/ and rotates them itself. Point kolla's fluentd at them once:

cp etc/fluentd/input/20-ferry.conf  /etc/kolla/config/fluentd/input/
cp etc/fluentd/filter/20-ferry.conf /etc/kolla/config/fluentd/filter/
kolla-ansible reconfigure -i /etc/kolla/inventory --tags common

Send the metrics to Prometheus​

When kolla-ansible runs Prometheus, the role can add the service to it. In /etc/kolla/globals.yml:

ferry_admin_bind_internal: true
ferry_prometheus_integration: true

The first setting opens each component's admin port on the internal API network instead of loopback. The second adds scrape jobs for the managers, the movers and the compute agents, and the alert rules, to kolla's Prometheus configuration. Deploy again, then reconfigure Prometheus:

kolla-ansible deploy      -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK
kolla-ansible reconfigure -i /etc/kolla/inventory --tags prometheus

kolla-ansible loads the alert rules only when enable_prometheus_alertmanager is on.

Check the installation​

openstack endpoint list --service backup
curl -s https://backup.mycompany.com/readyz

/readyz answers with the version, the site and the cloud name. Then register a repository to provide storage for backups.

Upgrade​

Change ferry_tag, then pull and upgrade:

kolla-ansible pull    -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK
kolla-ansible upgrade -i /etc/kolla/inventory -i /etc/kolla/ferry-groups -p $PLAYBOOK

The playbook upgrades in the order the service needs. It upgrades the managers one at a time, and waits for each to answer before the next. Then it upgrades the movers one at a time, including those on manager hosts. Then it upgrades all compute agents together. See Upgrades for what to check before and after.