Allow local scaphandre directory to be mapped to an instance using virtiofs

Scaphandre is a tool that can be used to measure compute and VM power consumption down to processes. (

If you want to know more, the BBC folks proposed an interesting use case to create environmental dashboards:

Problem description

Currently, this is not possible to get consumption per VM as scaphandre requires a directory on the compute node accessible into running VMs. This directory contains data required by the scaphandre instance (guest agent) running on the VM to correctly reports VM and VM associated processes consumption.

Scaphandre proposed solution to get these data is to mount the directory using virtiofs in the VM. However, the user can not do that, as it requires the VM XML definition file to be modified. Nova fully manages this file, and as a result, only nova can change it.

Use Cases

  • As a user, I want to know the consumption of my compute node and drill down to VM and VM processes individual consumption.

  • As an administrator, I want to allow this usage but make sure the user can mount only the configured required directory. I also want not to leak cloud design insights.

Proposed change

To simplify specifications, the feature will be named virtiofs-scaphandre.

Although this feature is implemented to support scaphandre, other tools could require this need. So the implementation will try to be as generic as possible.

This change relies partially on specification to build the VM XML file including virtiofs settings (mostly driver part).

This implies the same requirements and limitation.

  • QEMU >=5.0 and libvirt >= 6.2

  • Associated instances use file backed memory or huge pages

  • Live migrate an instance will not be supported as life attach and detach has landed only “recently” in libvirt.

Change description:

  • Add a compute configuration option share_local_fs that specify mappings between compute source directory and VMs destination mount_tags.

share_local_fs = { "/var/lib/libvirt/scaphandre": "scaphandre" }
  • If the above configuration option is present starting the compute node, add a compute trait COMPUTE_SHARE_LOCAL_FS specifying the virtiofs-scaphandre feature is available on this compute.

  • Users can add hw:power_metrics as extra specs or hw_power_metrics image properties, and thus 2 things will happen:

    1. Nova will schedule the instance to a host that has share_local_fs.

    2. Nova will add the virtiofs settings in the instance XML file as specified by the following example.

<filesystem type='mount' accessmode='passthrough'>
    <driver type='virtiofs'/>
    <source dir='/var/lib/libvirt/scaphandre/<DOMAIN_NAME>'/>
    <target dir='mount_tag'/>
    <readonly />


The <DOMAIN_NAME> is the name reported by virsh list or OS-EXT-SRV-ATTR:instance_name. This is the common name between qemu process that scaphandre use to get the vm name and openstack.

The instance name can be defined using the instance_name_template.


  • “OS-EXT-SRV-ATTR:instance_name”: “instance-00000034

  • /usr/bin/qemu-system-x86_64 -name guest=instance-00000034

  • As a result, user will be able to mount the compute source directory on his VM using the following command line.

user@instance $ mount -t virtiofs mount_tag /var/scaphandre


The user can see the mount_tag in the instance metadata. Mount automation can be build based on this mechanism.



REST API impact


Data model impact

Introduce hw_powermetrics image property as a new property object.

Extend the flavor extra spec validation to check hw:power_metrics.

Security impact

The compute node filesystem will be shared read-only. This is to prevent any modification on the host by VM users.

Notifications impact


Other end user impact

The scaphandre installation and configuration on compute nodes is left to the openstack administrator.

Performance Impact


Other deployer impact


Developer impact


Upgrade impact




Primary assignee:

uggla (rene.ribaud)

Feature Liaison

Feature liaison:


Work Items

  • New configuration option.

  • Add new trait.

  • Changes to share the compute node filesystem if requested by an image property or a flavor extra spec.




  • Functional API tests

  • Integration Tempest tests

Documentation Impact

Extensive admin and user documentation will be provided.




Release Name