11 KiB
Expose virtual device tags in REST API
https://blueprints.launchpad.net/nova/+spec/expose-virtual-device-tags-in-rest-api
The 2.32 microversion allows creating a server with tagged block devices and virtual interfaces (ports) and the 2.49 microversion allows specifying a tag when attaching volumes and ports, but there is no way to get those tags out of the REST API. This spec proposes to expose the block device mapping and virtual interface tags in the REST API when listing volume attachments and ports for a given server.
Problem description
It is possible to attach volumes and ports to a server with tags but there is nothing in the REST API that allows a user to read those back. The virtual device tags are available within the guest VM via the config drive or metadata API service, but not the front-end compute REST API.
Furthermore, correlating volume attachments to BlockDeviceMapping
objects via tag has come up in the Remove device from volume
attach requests spec as a way to replace reliance on the otherwise
unused device
field to determine ordering of block devices
within the guest.
Using volume attachment tags was also an option discussed in the Detach and attach boot
volumes spec as a way to indicate which volume was the root volume
attached to the server without relying on the server
OS-EXT-SRV-ATTR:root_device_name
field.
Use Cases
As a user, I want to correlate information, based on tags, to the volumes and ports attached to my server.
Proposed change
In a new microversion, expose virtual device tags in the REST API response when showing volume attachments and attached ports.
See the REST API impact section for details on route and response changes.
Technical / performance considerations
When showing attached volume tags, there would really be no additional effort in exposing the tag since we already query the database for a BlockDeviceMappingList per instance.
However, the os-interface
port tags present a different
challenge. The GET /servers/{server_id}/os-interface
and
GET /servers/{server_id}/os-interface/{port_id}
APIs are
today simply proxies to the neutron networking APIs to list ports
attached to an instance and show details about a port attached to an
instance, respectively.
The device tag for a port attached to an instance is not stored in
neutron, it is stored in the nova cell database
virtual_interfaces
table. So the problem we have is one of
performance when listing ports attached to a server and we want to show
tags because we would have to query both the neutron API to list ports
and then the virtual_interfaces
table for the instance to
get the tags. We have two options:
- Accept that when listing ports for a single instance, doing one more DB query to get the tags is not that big of an issue.
- Rather than proxy the calls to neutron, we could rely on the instance network info cache to provide the details. That might be OK except we currently do not store the tags in the info cache, so for any existing instance the tags would not be shown, unless we did a DB query to look for them and heal the cache.
Given the complications with option 2, this spec will just use option 1.
Non-volume BDMs
It should be noted that swap and ephemeral block devices can also
have tags when the server is created, however there is nothing in the
API today which exposes those types of BDMs; the API only exposes volume
BDMs. As such, this spec does not intend to expose non-volume block
device mapping tags. It is possible that in the future if a kind of
GET /servers/{server_id}/disks
API were added we could
expose swap and ephemeral block devices along with their tags, but that
is out of scope for this spec.
Alternatives
In addition to showing the tags in the
os-volume_attachments
and os-interface
APIs,
we could also modify the server show/list view builder to provide tags
in the server resource os-extended-volumes:volumes_attached
and addresses
fields. This would be trivial to do for
showing attached volume tags since we already query the DB per instance
to get the BDMs, but as noted in the Proposed
change section, it would be non-trivial for port tags since those
are not currently stored in the instance network info cache which is
used to build the addresses
field response value. And it
would be odd to show the attached volume tags in the server response but
not the virtual interface tags. We could heal the network info cache
over time, but that seems unnecessarily complicated when the proposed
change already provides a way to get the tag information for all
volumes/ports attached to a given server resource.
We could also take this opportunity to expose other fields on the
BlockDeviceMapping which are inputs when creating a server, like
boot_index
, volume_type
,
source_type
, destination_type
,
guest_format
, etc. For simplicity, that is omitted from the
proposed change since it's simpler to just focus on tag exposure for
multiple types of resources.
Data model impact
None.
REST API impact
There are two API resource routes which would be changed. In all
cases, if the block device mapping or virtual interface record does not
have a tag specified, the response value for the tag
key
will be None
.
os-volume_attachments
A tag
field will be added to the response for each of
the following APIs.
GET /servers/{server_id}/os-volume_attachments (list)
{ "volumeAttachments": [{ "device": "/dev/sdd", "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803", "serverId": "4d8c3732-a248-40ed-bebc-539a6ffd25c0", "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803", "tag": "os" }] }
GET /servers/{server_id}/os-volume_attachments/{volume_id} (show)
{ "volumeAttachment": { "device": "/dev/sdd", "id": "a26887c6-c47b-4654-abb5-dfadf7d3f803", "serverId": "2390fb4d-1693-45d7-b309-e29c4af16538", "volumeId": "a26887c6-c47b-4654-abb5-dfadf7d3f803", "tag": "os" } }
POST /servers/{server_id}/os-volume_attachments (attach)
{ "volumeAttachment": { "device": "/dev/vdb", "id": "c996dd74-44a0-4fd1-a582-a14a4007cc94", "serverId": "2390fb4d-1693-45d7-b309-e29c4af16538", "volumeId": "c996dd74-44a0-4fd1-a582-a14a4007cc94", "tag": "data" } }
os-interface
A tag
field will be added to the response for each of
the following APIs.
GET /servers/{server_id}/os-interface (list)
{ "interfaceAttachments": [{ "fixed_ips": [{ "ip_address": "192.168.1.3", "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef" }], "mac_addr": "fa:16:3e:4c:2c:30", "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6", "port_id": "ce531f90-199f-48c0-816c-13e38010b442", "port_state": "ACTIVE", "tag": "public" }] }
GET /servers/{server_id}/os-interface/{port_id} (show)
{ "interfaceAttachment": { "fixed_ips": [{ "ip_address": "192.168.1.3", "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef" }], "mac_addr": "fa:16:3e:4c:2c:30", "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6", "port_id": "ce531f90-199f-48c0-816c-13e38010b442", "port_state": "ACTIVE", "tag": "public" } }
POST /servers/{server_id}/os-interface (attach)
{ "interfaceAttachment": { "fixed_ips": [{ "ip_address": "192.168.1.4", "subnet_id": "f8a6e8f8-c2ec-497c-9f23-da9616de54ef" }], "mac_addr": "fa:16:3e:4c:2c:31", "net_id": "3cb9bc59-5699-4588-a4b1-b87f96708bc6", "port_id": "ce531f90-199f-48c0-816c-13e38010b443", "port_state": "ACTIVE", "tag": "management" } }
Security impact
None.
Notifications impact
The BlockDevicePayload
object already exposes BDM tags
for versioned notifications. The IpPayload
object does not
expose tags since they are not in the instance network info cache, but
these payloads are only exposed via the InstancePayload
and
like the servers
API we will not make additional changes to
try and show the tags for the resources nested within the server
(InstancePayload) body. This could be done in the future if desired,
potentially with a configuration option like
[notifications]/bdms_in_notifications
, but it is out of
scope for this spec.
Other end user impact
python-novaclient and python-openstackclient will be updated as
necessary to support the new microversion. This likely just means adding
a new Tag
column in CLI output when listing attached
volumes and ports.
Performance Impact
There will be a new database query to the
virtual_interfaces
table when showing device tags for ports
attached to a server. This should have a minimal impact to API response
times though.
Other deployer impact
None.
Developer impact
None.
Upgrade impact
None.
Implementation
Assignee(s)
- Primary assignee:
-
Matt Riedemann <mriedem.os@gmail.com> (mriedem)
Work Items
Implement a new microversion and use that to determine if a new
tag
field should be in the
os-volume_attachments
and os-interface
API
responses when listing/showing/attaching volumes/ports to a server.
Dependencies
None.
Testing
Functional API samples tests should be sufficient coverage of this feature.
Documentation Impact
The compute API reference will be updated to note the
tag
field in the response for the
os-volume_attachments
and os-interface
APIs.
References
This was originally discussed at the Ocata summit. It came up again at the Rocky PTG.
Related specs:
- Remove
device
from volume attach API: https://review.openstack.org/452546/ - Detach/attach boot volume: https://review.openstack.org/600628/
History
Release Name | Description |
---|---|
Pike | Originally proposed but abandoned |
Stein | Re-proposed |