Re: [openstack-dev] Documenting config drive - what do you want to see?
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.op
Re: [openstack-dev] Documenting config drive - what do you want to see?
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. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Documenting config drive - what do you want to see?
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. > 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". > 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. ++ > > -- > > 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. > > [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, Clark __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Documenting config drive - what do you want to see?
On Wed, May 24, 2017 at 10: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. Thanks, I didn't know about that page. I usually read sources or boot an instance and check by myself. > 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 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. > 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. +1 I'm not sure about the format as there is a lot of cases to cover. * There a multiple supported config drive versions (2012-08-10, ..., 2017-02-22) so we need to document them all. * How do we plan on making it easy for someone to understand which fields will be available in each versions? * If a field is removed, how will it be expressed in the documentation? * Could a field change type in the future? (object vs list of objects for example) * 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). * 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. > 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. +1 > [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 -- Mathieu __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] Documenting config drive - what do you want to see?
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 __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
