PCI Alias Is Not Defined: OpenStack Nova Troubleshooting
In the case of OpenStack Nova, PCI passthrough helps all instances to use various hardware devices such as GPUs directly. This feature is critical at the time of utilizing GPU servers, mainly in the case of artificial intelligence and machine learning environments or virtual desktop infrastructures. Moreover, a general configuration error occurs at the time Nova fails to launch instances just because of a missing or undefined PCI alias. This guide covers what causes the “PCI alias is not defined” issue and how to troubleshoot it.
A Few Error Message Example
At the time of attempting to boot any instance along with GPU passthrough allowed, you may easily encounter an issue like:
ERROR (BadRequest): Invalid input for field/attribute pci_alias. Value: ‘gpu’. Alias ‘gpu’ is not defined in the configuration file.
This shows that the requested alias (in this case, gpu) does not easily map to any specified PCI device as described in the OpenStack Nova setup.
Root Cause
The issue takes place just because the alias utilized in the flavor or image metadata is not known. Nova utilizes pci_alias entries described in the nova.conf file to map logical alias names (such as gpu) to physical PCI devices.
This error is common at the time of setting up GPU hosting with a GPU dedicated server, as physical GPU assets must be clearly described in the OpenStack Nova configuration.
Prerequisites
Before resolving, make sure:
- You have full root or admin access to your compute nodes and OpenStack Nova controller.
- PCI passthrough is allowed in your environment.
- You have installed GPU server and detected them at the hardware level (for example, NVIDIA A40 & NVIDIA A100).
- Nova-api and nova-compute services are constantly running.
Step-by-Step Troubleshooting Guide
1. Check GPU Presence on Compute Node
Make sure that the GPU device is completely visible on the host.
lspci | grep -i nvidia
Predicted result (example):
65:00.0 3D controller: NVIDIA Corporation A100 PCIe 80GB
2. Check Present PCI Alias Configuration
Check your nova.conf file, generally located at /etc/nova/nova.conf.
Look under the [pci] section:
[pci]
alias = {
“name”: “gpu”,
“product_id”: “20B0”,
“vendor_id”: “10DE”,
“device_type”: “type-PCI”
}
- vendor_id: Mainly 10DE for NVIDIA.
- product_id: Matches the GPU model (utilize lspci -nn to verify).
- name: Alias that will be specified in the metadata or flavor.
If no alias is described properly, then this is the main reason for the error.
3. Describe PCI Alias in nova.conf
Simply update or add the PCI alias entry in the [pci] section. The instance for NVIDIA A100 is:
[pci]
alias = {
“name”: “gpu”,
“vendor_id”: “10DE”,
“product_id”: “20B0”,
“device_type”: “type-PCI”
}
For numerous GPUs with diverse product IDs (e.g., NVIDIA A40 and NVIDIA A100), describe many aliases:
alias = {
“name”: “gpu_a100”,
“vendor_id”: “10DE”,
“product_id”: “20B0”,
“device_type”: “type-PCI”
}
alias = {
“name”: “gpu_a40”,
“vendor_id”: “10DE”,
“product_id”: “2235”,
“device_type”: “type-PCI”
}
You can easily define multiple alias entries by reiterating the alias = line.
4. Restart Nova Services
After simply updating nova.conf, just restart the appropriate services:
sudo systemctl restart nova-compute
sudo systemctl restart nova-api
5. Create or Update Flavor with Additional Specs
Once the alias is properly described, modify or create a flavor to utilize it.
Example (for NVIDIA A100 GPU):
openstack flavor set m1.gpu –property “pci_passthrough:alias”=”gpu_a100:1”
This describes Nova to allocate 1 GPU that simply matches the alias gpu_a100 to instances launched with this flavor.
- You can also utilize metadata on all images, but utilizing flavors is generally more compatible for GPU hosting environments.
6. Test Instance Boot
Try launching an instance utilizing the flavor related to the GPU alias:
openstack server create \
–flavor m1.gpu \
–image ubuntu-22.04 \
–network private-net \
–security-group default \
–key-name mykey \
gpu-instance
If configured properly, the instance will be effortlessly scheduled on a compute node with an easily available GPU coordinating with the alias.
More Tips
Verify Accessible PCI Devices With the Help of Placement
Utilize the Placement API to examine resource availability:
openstack resource provider list –os-placement-api-version 1.2
This helps guarantee the appropriate compute nodes are reporting their GPU server proficiencies to the OpenStack Nova controller.
Log File Troubleshooting
Check all logs if any issues continue:
- /var/log/nova/nova-compute.log
- /var/log/nova/nova-api.log
Opt for messages associated with PCI passthrough, scheduling failures, or device claiming.
Real-World Use Case Situations
- AI and ML-Based Tasks: Organizations utilizing a GPU dedicated server, especially for AI model training (such as TensorFlow and PyTorch), depend on the right PCI passthrough for model boost.
- AI Image Generator Deployment: Tools such as AI image generators get a good advantage from running on virtual machines along with direct GPU usage.
- GPU Hosting Platforms: Both private and public cloud service providers providing GPU hosting must describe PCI aliases for client access to GPUs such as the NVIDIA A40 and NVIDIA A100.
General Mistakes to Avoid
- Incorrect product ID: Always verify product IDs utilizing lspci -nn instead of guessing.
- Syntax issues in nova.conf: Inappropriate JSON format can quietly fail.
- Service not restarted: Modifications won’t be implemented unless OpenStack Nova services are restarted properly.
- Flavor mismatch: The alias in the case of flavor must precisely match the one that is present in nova.conf.
Quick Setup Guide
| Task | Command File |
| Verify GPU hardware | `lspci |
| Edit PCI alias | /etc/nova/nova.conf |
| Restart services | systemctl restart nova-* |
| Create flavor | openstack flavor set … |
| Launch instance | openstack server create … |
| View logs | /var/log/nova/ |
Conclusion
Describing PCI aliases appropriately in the case of OpenStack Nova is necessary when allowing GPU passthrough, especially for virtual machines, mainly in all those environments that are powered by a GPU dedicated server or a GPU server. The “PCI alias is not defined” issue specifically arises from missing or misconfigured alias entries in the case of the nova.conf file. By properly identifying GPU devices (such as NVIDIA A40 or NVIDIA A100), configuring the appropriate alias configuration, and relating all of them with flavors, admins can guarantee quick deployment of GPU-backed instances.
For long-term growth, always keep your configuration files well-documented, enable hardware mappings along with lspci, and automate testing after some changes to Nova settings.