Open Stack

Rocky tipped me off to a request to document config drive which came up 
at the Boston Forum, and I tracked that down to Clark's wishlist 
etherpad [1] (L195) which states:

"Document the config drive. The only way I have been able to figure out 
how to make a config drive is by either reading nova's source code or by 
reading cloud-init's source code."

So naturally I have some questions, and I'm looking to flesh the idea / 
request out a bit so we can start something in the in-tree nova devref.

Question the first: is this existing document [2] helpful? At a high 
level, that's more about 'how' rather than 'what', as in what's in the 
config drive.

Question the second: are people mostly looking for documentation on the 
content of the config drive? I assume so, because without reading the 
source code you wouldn't know, which is the terrible part.

Based on this, I can think of a few things we can do:

1. Start documenting the versions which come out of the metadata API 
service, which regardless of whether or not you're using it, is used to 
build the config drive. I'm thinking we could start with something like 
the in-tree REST API version history [3]. This would basically be a 
change log of each version, e.g. in 2016-06-30 you got device tags, in 
2017-02-22 you got vlan tags, etc.

2. Start documenting the contents similar to the response tables in the 
compute API reference [4]. For example, network_data.json has an example 
response in this spec [5]. So have an example response and a table with 
an explanation of fields in the response, so describe 
ethernet_mac_address and vif_id, their type, whether or not they are 
optional or required, and in which version they were added to the 
response, similar to how we document microversions in the compute REST 
API reference.

--

Are there other thoughts here or things I'm missing? At this point I'm 
just trying to gather requirements so we can get something started. I 
don't have volunteers to work on this, but I'm thinking we can at least 
start with some basics and then people can help flesh it out over time.

[1] https://etherpad.openstack.org/p/openstack-user-api-improvements
[2] https://docs.openstack.org/user-guide/cli-config-drive.html
[3] https://docs.openstack.org/developer/nova/api_microversion_history.html
[4] https://developer.openstack.org/api-ref/compute/
[5] 
https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html#rest-api-impact

-- 

Thanks,

Matt