On 05/24/2017 10:07 AM, Clark Boylan wrote:
On Wed, May 24, 2017, at 07:39 AM, 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.
This is helpful, but I think it is targeted to the deployer of OpenStack
and not the consumer of OpenStack.
Yup.
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.
I'm (due to being a cloud user) mostly noticing the lack of information
on why cloud users might use config drive and how to consume it.
Documentation for the content of the config drive is a major piece of
what is missing. What do the key value pairs mean and how can I use them
to configure my nova instances to operate properly.
But also general information like, config drive can be more reliable
that metadata service as its directly attached to instance. Trade off is
possibly no live migration for the instance (under what circumstances
does live migration work and as a user is that discoverable?). What
filesystems are valid and I need to handle in my instance images? Will
the device id always be config-2? and so on. The user guide doc you
linked does try to address some of this, but seems to do so from the
perspective of the person deploying a cloud, "do this if you want to
avoid dhcp in your cloud", "install these things on compute hosts".
Yah. Being able to point consumers at why they should care and what
benefits it has is useful since it's a flag in the server api to turn on
config-drive.
But also ++ to clarkb
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.
I like this as it should enable cloud users to implement tooling that
knows what it needs that can error properly if it ends up on a cloud too
old to contain the required information.
++
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.
++
+100!
--
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.
I like this, starting small to produce something useful then going from
there makes sense to me.
++
Another idea I've had is making a tool that collected (or was fed)
information that goes into config drives and produces the device to
attach to a VM would be nice. Reason for this is while config drive is
something grown out of nova/OpenStack you often want to boot images with
Nova and other tools so making it easy for those other tools to work
properly too would be nice. In the simple case I build images locally,
then boot them with kvm to test that they work before pushing things
into OpenStack and config drive makes that somewhat complicated. Ideally
this would be the same code that nova uses to generate the config drives
just with a command line front end.
That would also help with testing config-drive consuming tools potentially.
We have some fixtures in the glean source repo:
http://git.openstack.org/cgit/openstack-infra/glean/tree/glean/tests/fixtures
which we collected from clouds out in the wild so we could make sure
were were doing the right things from them. I imagine it could be neat
to be able to use a tool to generate various combos of config-drive
content on the fly so they don't have to be hard-coded- but if it's not
the actual code itself it wouldn't be as awesome.
[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
Thank you for bringing this up,
Yes - thank you! I think this can be super helpful!
Monty
__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: [email protected]?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
