Add Configuration Validator

Support the ability to validate oslo.config options against an
operator configuration file, as-well-as potentially validation
of options on service start.

Change-Id: If5d3b56c71cb3b916d04d80e77781d9bdd7f3b5c
This commit is contained in:
Brian Stajkowski 2016-10-04 09:23:01 -07:00
parent 41eaa56bc3
commit 5f188151ca
1 changed files with 232 additions and 0 deletions

View File

@ -0,0 +1,232 @@
==========================
Configuration Validator
==========================
https://blueprints.launchpad.net/oslo.config/+spec/oslo-validator
Support the ability to validate oslo.config options at a basic level
against an operator configuration file, as-well-as potentially validation
of options on service start(example usage).
Problem description
===================
It is extremely easy to have invalid conf files for any project:
* Invalid Sections
* Invalid Option Name
* Deprecated Options
* Misspellings
* Usage of Advanced Options (warnings)
* Lack of Configured Required Options
* Usage of Choices Outside of Scope
* Usage of Default Values in Configuration File
Configuration validation, in its basic form, can help alleviate these basic
issues by providing a way to validate options and configured values both
manually, via cli, and on service start(example usage). Operators have been
asking for this functionality for some time now, as the deviation from version
to version, with regard to options, can be substantial.
Use Cases
---------
As an operator, being able to validate the configuration prior to deployment
is invaluable, providing a clear path for both CI/CD utilization and manual
checks.
As a developer, being able to provide an option to operators for basic
validation against project configuration files. This can be by way of shell
script traversing each namespace, as Neutron utilizes, or it could be by way of
an additional argument specific for config validation, i.e. `ironic-api
--validate-config`. Implementation is customizable per project.
Proposed change
===============
The new validator module would offer two avenues for consumption: cli
command and the ability to import the validator for use during service
start(example usage). Oslo config validator would be a basic check on
common configuration mistakes and in no way offers an opinion on a correct
configuration or a desired configuration.
For cli usage, a new entry point will be added to oslo.config,
`oslo-config-validator`. Similar to `oslo-config-generator`, operators will
be able to pass an argument, `--namespace`, to indicate what application
namespace their configuration file will validate against. Or, optionally an
operator/developer can pass `--validator-config-file`, which would contain the
application namespaces. In addition, `--config-file` will be a required
argument to indicate the location of their configuration file. Ideally, each
project would implement a shell script tool to traverse the namespaces used
by the project for validation. For example, here is the usage in Neutron:
neutron/blob/master/tools/generate_config_file_samples.sh
For module import, developers will be able to utilize `validator.validate`
and pass a required collection of configured options to check against the
registered namespaces and options in `oslo.config`. This could be
performed on service start(example usage), after configuration files are
ingested, and output to the configured log file. It could be also used
in each project as an additional argument, i.e. `ironic-api --validate-config`,
where the configuration is then validated as a separate operation, if a shell
script is not developed above. Both options would be available, how each
project implements config validation is out of the scope of this spec.
One use case for `validator.validate` would be to fail on service start, where
`validate` returns `valid_configuration(bool)`, `invalid_configuration_items(dict)`.
The return values can help determine if the service is capable of starting by
examining `invalid_configuration_items['errors'] (bool)` if `valid_configuration`
is `false`. This would allow developers to have control over warnings being
suppressed by having `invalid_configuration_items['errors'] (bool)` and
`invalid_configuration_items['warnings'] (bool)` separate with their own
respective iterable list of items considered in error::
invalid_configuration_items['config_errors'] = [
{'config_item': 'namespace', 'item_name': 'DEFULT',
'message': 'Namespace DEFULT does not exist.'},
{'config_item': 'option', 'item_name': 'auth_uri',
'message': 'Option auth_uri has no value assigned.'},
]
And for configuration warnings::
invalid_configuration_items['config_warnings'] = [
{'config_item': 'option', 'item_name': 'auth_strategy',
'message': 'Option is configured with the default value, not required.'},
{'config_item': 'option', 'item_name': 'some_advanced_option',
'message': 'Option some_advanced_option is an advanced option and may'
'effect performance.'},
]
These are just examples of data structures potentially being returned and
may change when configuration validator is implemented. In any case, a list of
errors/warnings will be returned for easy output to console or logs.
Configuration validator would report on the following discrepancies:
* Option not in namespace (error)
* Option has no value (error)
* Option has no value and is required (error)
* Option value is not in range (error)
* Option value is default, not required in config (warning)
* Option is deprecated (warning)
* Option is advanced (warning)
* Option type validation, i.e. '2' vs 2 (error)
* Invalid configuration section (error)
* Missing configuration section, i.e. [DEFAULT] (warning)
Files to add:
* oslo.config/oslo_config/validator.py
* oslo.config/doc/source/validator.rst
Files to modify:
* oslo.config/setup.cfg
Alternatives
------------
None.
Impact on Existing APIs
-----------------------
None.
Security impact
---------------
None.
Performance Impact
------------------
This could be an additional check on service start(example usage), which could
have an impact on the time it would take to become fully operational. At its
most basic form, manual checks via cli would not have a performance impact.
Configuration Impact
--------------------
None.
Developer Impact
----------------
None.
Testing Impact
--------------
Additional unit tests would be required to cover raised warnings and
errors provided by validator.
Implementation
==============
Assignee(s)
-----------
Primary assignee:
ski
Milestones
----------
Target Milestone for completion:
ocata-1
Work Items
----------
* Create new module `validator.py`.
* Create new entrypoint `oslo-config-validator`.
* Create new docs file `validator.rst`
Incubation
==========
None.
Adoption
--------
It is likely that this module will be used throughout OpenStack as it satisfies
operator need surrounding the complexity of configuration files.
Library
-------
oslo.config
Anticipated API Stabilization
-----------------------------
None.
Documentation Impact
====================
Will need to develop additional documentation in `validator.rst` to detail how
validator can be consumed both at the cli level and as a module.
Dependencies
============
This additional module will not require any dependencies.
References
==========
oslo.config: http://git.openstack.org/cgit/openstack/oslo.config/
http://docs.openstack.org/developer/oslo.config/
neutron: http://github.com/openstack/neutron
ironic: http://github.com/openstack/ironic
.. note::
This work is licensed under a Creative Commons Attribution 3.0
Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode