Skip to content

Stork Doc Improvements wishlist

This is a meta-issue to capture a list of proposed improvements to the documentation.

Style

  • use the terminology glossary to standardize spelling and capitalization of terms, in the ARM and in the UI and help.
  • Use the same conventions already in place in the BIND and Kea ARMs wherever possible, including text and link styles

Overview & architecture

  • Correct the first paragraphs of the ARM which say "This is the developer’s guide... For the user’s guide, see the Stork Administrator Reference Manual" @piotrek (!885 (merged))

  • Add information how to build and access Stork Developer's Guide @piotrek (!885 (merged))

  • Add some terminology (what is an "app" what is a "server", what is a "subnetID" and why is that important, etc.). This could be an appendix, but linked in the Overview section (!859 (merged))

  • Add a list of major features and when they were introduced, perhaps with a matrix of Kea versions and Stork versions and Xs for the combinations that support that feature !878 (merged) @slawek

  • Indicate for the major features which hooks are required. This could go in the Installation section, but it should be prominent because for some people this is a key decision factor on whether or not to use Stork and what to expect when using Stork. !878 (merged) @slawek

  • Describe what Stork is and what it is not - it should be clear to the reader what kinds of tasks they will be able to complete with Stork.

  • Security. Much of the ARM deals with securing interfaces to Stork, but it would be good to explain the overall security design in the Overview as this is a critical feature. A diagram showing the interfaces and how each are secured might help, or a table. This section should include some specific suggestions about how to deploy Stork most securely, and should include any assumptions we make about the environment. Besides helping the user, this is helpful for our vulnerability handling policy, as scoring could take into consideration the explicit security advice in the ARM. It might also help to add a list of links to the security-critical sections in the ARM (TLS set up, user permissions, user authentication...) !879 (merged) @slawek

  • Architecture section should explain where is the configuration source of truth, in the Kea server or in Stork, and how is information updated, push or pull (!859 (merged))

  • Relationship of Stork to Kea databases, such as host backend, lease backend, lease file, configuration backend (!859 (merged))

Configuring Stork

  • This statement in one of the manpages "Stork does not use an explicit configuration file. Instead, its behavior can be controlled with command-line switches and/or variables." This is contradicted in section 3.3, "Configuration settings," or at least taken together it is confusing. (!865 (merged))
  • Manpages, aka the command reference, could use explicit examples for each command. @slawek
  • The section on integrating with Prometheus and Grafana could be included in the Stork configuration section

Managing applications

  • The section on Using Stork includes both configuring Stork and using it to manage applications. These might be better split into separate top level sections. (!865 (merged))
  • Add an explicit section on configuring Kea or managing Kea configurations with Stork. This could be organized as Host Reservations (monitoring, managing) and Subnets (monitoring, managing) but currently, the instructions for e.g. creating and modifying host reservations are in the section called monitoring, which is confusing. (!865 (merged))

Appendices

  • not sure why the API is labelled "Backend API", I would just call it API, but as mentioned in another ticket, it would be good to actually include the api documentation here.
  • this might be a good place for the glossary? (!859 (merged))
Edited by Slawek Figiel