Open Stack

Matt Riedemann wrote:
> 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.

So yes and no, for example there are afaik operational differences that 
are not mentioned; for example I believe the instance metadata ie (in 
that page the "meta" field) can be changed and then a REST call to the 
metadata REST api will return that updated value; while the config-drive 
will never have that updated value, so these kinds of gotchas really 
should be mentioned somewhere. Are there other kinds of gotchas like the 
above (where the metadata REST api will return a different/changing 
value while the config-drive will stay immutable)?

Those would be really nice to know about/document and/or fix.

One that comes to mind is does the "security-groups" field change in the 
metadata REST api (while the config-drive stays the same) when a 
security group is added/removed...

>
> 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.

For better/worse idk if there are that many people trying to figure out 
the contents; cloud-init tries to hide it behind the concept of a 
datasource (see 
https://cloudinit.readthedocs.io/en/latest/topics/datasources.html#datasource-documentation 
for a bunch of them) but yes I think a better job could be done 
explaining the contents (if just to make certain cloud-init `like` 
programs easier to make).

>
> 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.
>

As one of the developers of cloud-init yes please to all the above.

Fyi,

https://cloudinit.readthedocs.io/en/latest/topics/datasources/configdrive.html 
is something cloud-init has (nothing like the detail that could be 
produced by nova itself).

`network_data.json` was one of those examples that was somewhat hard to 
figure it out, but eventually the other cloud-init folks and myself did.