<div dir="ltr">On Wed, May 24, 2017 at 10:39 AM, Matt Riedemann <<a href="mailto:mriedemos@gmail.com">mriedemos@gmail.com</a>> wrote:<br>><br>> 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:<br>><br>> "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."<br>><br>> 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.<br>><br>> 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.<br><br>Thanks, I didn't know about that page. I usually read sources or boot an instance and check by myself.<br><br>> 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.<br><br>I usually boot an instance and inspect the config drive. Usually it's for network_data.json since (in our case) we support various network models (flat, nic teaming, tagged vlan, etc.) and need a concrete example of each.<br><br>> Based on this, I can think of a few things we can do:<br>><br>> 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.<br><br>+1<br><br>I'm not sure about the format as there is a lot of cases to cover.<br><br>* There a multiple supported config drive versions (2012-08-10, ..., 2017-02-22) so we need to document them all.<br>* How do we plan on making it easy for someone to understand which fields will be available in each versions?<br>* If a field is removed, how will it be expressed in the documentation?<br>* Could a field change type in the future? (object vs list of objects for example)<br>* The idea of a documentation similar to the REST API version history is good. I however wouldn't have the patience to mentally "compute" the resulting config drive. So I think we need both (history + schema/examples).<br>* We should document the purpose of each field and how a user can populate or use that field. For example, I have no idea what's the purpose of the "launch_index" field but I suspect it's related to the --max-count parameter with nova boot command.<br><br>> 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.<br><br>+1<br><br>> [1] <a href="https://etherpad.openstack.org/p/openstack-user-api-improvements">https://etherpad.openstack.org/p/openstack-user-api-improvements</a><br>> [2] <a href="https://docs.openstack.org/user-guide/cli-config-drive.html">https://docs.openstack.org/user-guide/cli-config-drive.html</a><br>> [3] <a href="https://docs.openstack.org/developer/nova/api_microversion_history.html">https://docs.openstack.org/developer/nova/api_microversion_history.html</a><br>> [4] <a href="https://developer.openstack.org/api-ref/compute/">https://developer.openstack.org/api-ref/compute/</a><br>> [5] <a href="https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html#rest-api-impact">https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html#rest-api-impact</a><br><br>--<br>Mathieu</div>