Categorized Configuration

Cross Project Spec - https://review.openstack.org/#/c/295543 (WIP)

User Story Tracker - None

Problem description

Problem Definition

Operators currently have to grapple with hundreds of configuration options across tens of OpenStack services across multiple projects. In many cases they also need to be aware of the relationships between the options. In particular, this makes the initial deployment a very daunting task.

Opportunity/Justification

One of the largest barriers to adoption of OpenStack is perceived complexity. This surfaces in attempting to understand and properly set configurations on initial deployment, and again after upgrading.

Requirements Specification

Use Cases

This section utilizes the OpenStack UX Personas.

  • As Rey the Cloud Operator, I should be able to understand how to use a configuration option by reading the documentation. There should be no need to read the code to understand what value to choose.
  • As Rey doing an initial deployment, I want most options to have a useful default value, so they do not need to be considered or specified during the initial configuration of the system.
  • As Rey doing an initial deployment, I should be able to quickly identify what configurations I must consider, and how I should determine their value for my deployment to be successful.
  • As a Packager, I should be able to quickly identify what configuration options the packaging must set, and what options the operator needs to specify.
  • As Rey scaling out a deployment, there should be minimal configuration changes required. For the small number of options that must be changed, it should be clear what values require tuning, what symptoms are caused by incorrect values and how to determine correct values.
  • As Rey, the documentation should be clear on the relationship between configuration options. For example, if you select driver A by setting configuration option X, it should be clear what values should be set for any dependent configuration options within the same project.
  • There may be some options that are very unlikely to be used, except by the most advanced users. By default, these advanced options should be marked as such and presented in such a way as to make the documentation less daunting. While remaining discoverable it’s possible such options may require Rey to review additional documentation to fully understand their impact.
  • As Rey doing an initial configuration, it should be easy to check that you have a valid configuration file. Checking for any unrecognized configuration options and any invalid values can help find typos.
  • As Rey that has just completed an upgrade, it should be easy to check if you are making use of any deprecated configuration options, and determine what changes must be made before doing your next upgrade.

Usage Scenario Examples

  1. Initial Configuration and Deployment
  1. Deployer reviews centralized config documentation for services selected for deployment
  2. Deployer quickly finds the configurations that need setting prior to deployment
  3. Deployer makes adjustments to configs and deploys, leaving most configs unset, for example, using their default values
  4. Deployment is performed successfully
  1. Scaling Re-Configuration
  1. Deployer reviews centralized configuration documentation for services selected for scaling
  2. Deployer uses documentation to determine new configuration settings required for optimal performance at their future scale
  3. Deployer makes appropriate adjustments to configuration
  4. Deployer scales deployment successfully
  1. Scaling Troubleshooting
  1. Deployer scales deployment and begins experiencing performance degradation with a specific service
  2. Deployer consults configuration documentation to determine if symptoms are caused by mis-configuration
  3. Deployer identifies configuration adjustment required
  4. Deployer makes required configuration adjustments
  5. Deployer successfully returns deployment to optimal performance

Requirements

None.

Rejected User Stories / Usage Scenarios

None.

Glossary

None.