Thursday, February 11, 2016

Openstack-manuals autogenerated tables - Headers

Another category of autogenerated files 'types' are the headers files. They are located at tools/autogenerate-config-flagmappings and the filename formats are '*.headers'. These files specify the titles of the available configuration tables.

Table titles take the format "Description of ... configuration options". It is the contents of "..." that you specify in the headers file. For example, "dothill Dot Hill volume driver" in cinders.headers means that the cinder-dothill config table title will be "Description of Dot Hill volume driver configuration options"

Just like the flagmappings files, headers file contents are also in alphabetical order.

Wednesday, February 10, 2016

Openstack-manuals autogenerated tables - Flagmappings

If you have contributed to the Openstack-manuals you might have come across some files that start with "Warning: Do not edit this file. It is automatically generated ...". These files are configuration tables for the different Openstack services, located at 'doc/config-reference/source/tables'

This post documents one of the types of files that aid the autogeneration of the configuration tables. Disclaimer -> This is from my own observation of the files and from working on them and is not intended to be the final authority on what these files really are and what they really do.

As the name suggests these files map a configuration option to a configuration table. Rules

  • Each line of a flagmappings file first states the configuration option then the table file name. For example "agent_down_time common" in the neutron.flagmappings file means that the neutron_common.rst table has a configuration option known as the agent_down_time. Note that the filename part of the line is just "common" and not "neutron_common.rst", this is because it is already a fact that the configuration option is for Neutron because it is in the neutron.flagmappings file so it would be redundant to again repeat the name of the file.
  • The options are listed in alphabetical order
  • Incase an option belongs in a particular section of the configuration file, this section will precede the configuration option with the two being separated by a front-slash("/"). For example "database/connection" means that the 'connection' config option belong in the '[database]' section of the config file.

    In this scenario, the sectionless config options will go first followed by the sectioned one also in alphabetical order by the sections.

  • A config option belonging to more than one file will have the filenames added to the options. For example "AGENT/dont_fragment openvswitch_agent ml2_ofa" means the 'dont_fragment' option is under the 'AGENT' sections of two files, the "neutron_openvswitch_agent" and "neutron_ml2_ofa" configuration table files