api-ref: os-pci API is not documented at all

[Matt Riedemann]

This API is not in the compute API reference at all:

https://github.com/openstack/nova/blob/master/nova/api/openstack/compute/pci.py

https://developer.openstack.org/api-ref/compute/

There are really three parts there:

1. PciServerController shows PCI information for a given server, so that's an extension of the /servers API. That puts the os-pci:pci_devices key in the server response body.

2. PciHypervisorController shows PCI devices on a given compute node, so that's an extension of the /os-hypervisors API. That puts the os-pci:pci_stats key in the os-hypervisors response body.

3. PciController is for listing all PCI devices and showing details about a specific PCI device. When listing PCI devices in this API, we query all compute nodes, and then for each compute node we get the PCI devices and dump those into a list of dicts where the keys are whitelisted and based on whether or not we're listing PCI devices with details or not.

[Matt Riedemann (mriedem)]

It was pointed out that the os-pci extension is not even enabled:

https://github.com/openstack/nova/blob/master/setup.cfg#L130

# NOTE(cyeoh): this is intentionally disabled until microversions is active.
# See https://bugs.launchpad.net/nova/+bug/1426241
# pci = nova.api.openstack.compute.pci:Pci

So this documentation bug is actually probably invalid until we expose the API (if we ever do that).

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/457854

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/457854
Committed: https://git.openstack.org/cgit/openstack/nova/commit/?id=75a7e6fc7d02608bf128ad72b2b8945515b12c21
Submitter: Jenkins
Branch: master

commit 75a7e6fc7d02608bf128ad72b2b8945515b12c21
Author: Matt Riedemann <email address hidden>
Date: Tue Apr 18 21:14:43 2017 -0400

    Remove unused os-pci API

    The os-pci API was never part of the v2.0 API and was added
    to the v3 API, but when the v3 API turned into the v2.1 API
    which is backward compatible with the v2.0 API, the os-pci
    API was removed from v2.1. The original intent was to enable
    it in a microversion but that never happened.

    We should just delete this API since it has a number of issues
    anyway:

    1. It's not documented (which makes sense since it's not enabled).
    2. The PciHypervisorController just takes the compute_nodes.pci_stats
       dict and dumps it to json out of the REST API with no control over
       the keys in the response. That means if we ever change the fields
       in the PciDevicePool object, we implicitly introduce a backward
       incompatible change in the REST API.
    3. We don't want to be reporting host stats out of the API [1].
    4. To make the os-hypervisors extension work in a multi-cell environment
       we'd have to add uuids to the PciDevices model and change the API to
       return and take in uuids to identify the devices for GET requests.
    5. And last but not least, no one has asked for this in over two years.

    As a result of removing this API we can also remove the join on the
    pci_devices table when showing details about an instance or listing
    instances, which were added years ago because of the PciServerController:

    Id3c8a0b187e399ce2acecd4aaa37ac95e731d46c

    Id3e60c3c56c2eb4209e8aca8a2c26881ca86b435

    [1] https://docs.openstack.org/developer/nova/policies.html?#metrics-gathering

    Closes-Bug: #1426241
    Closes-Bug: #1673869

    Change-Id: I9099744264eeec175672d10d04da69648dec1a9d

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/nova 16.0.0.0b2 development milestone.