Difference between revisions of "Project Proposals/vppcfg"
Pimvanpelt (Talk | contribs) |
Pimvanpelt (Talk | contribs) (→Vendor Neutral) |
||
| (14 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
== Name == | == Name == | ||
| − | VPP Configuration utility | + | VPP Configuration utility, or vppcfg for short. |
== Project Contact Name and Email == | == Project Contact Name and Email == | ||
| Line 12: | Line 12: | ||
== Description == | == Description == | ||
| − | + | ||
| + | VPP is a programmable dataplane, and by design it does not include any configuration or controlplane management stack. It’s meant to be integrated into a full stack by operators. For end-users, this unfortunately means that typing on the CLI won’t persist any configuration, and if VPP is restarted, it will not pick up where it left off. There’s one developer convenience in the form of the exec command-line (and startup.conf!) option, which will read a file and apply the contents to the CLI line by line. However, if any typo is made in the file, processing immediately stops. It’s meant as a convenience for VPP developers, and is certainly not a useful configuration method for all but the simplest topologies. | ||
| + | |||
| + | Luckily, VPP comes with an extensive set of APIs to allow it to be programmed. What is needed is a configuration utility that can take a configuration file, compare it to a running VPP instance, and step-by-step plan through the API calls needed to safely apply the configuration to the dataplane. This proposal describes an existing tool [https://github.com/pimvanpelt/vppcfg] to be adopted by fd.io community to serve that purpose. | ||
vppcfg consumes YAML files of a specific format. Their validity is asserted by two main types of validation: | vppcfg consumes YAML files of a specific format. Their validity is asserted by two main types of validation: | ||
* syntax checks are performed and this ensures that all fields in the YAML file are correctly formed, that field-names are correctly spelled, that no extra fields are given, and their values are of the correct type. | * syntax checks are performed and this ensures that all fields in the YAML file are correctly formed, that field-names are correctly spelled, that no extra fields are given, and their values are of the correct type. | ||
| − | * semantic validations are performed to ensure that configurations are safely | + | * semantic validations are performed to ensure that configurations are safely applicable to a running VPP. Note: Some semantic checks are stricter than VPP, because applying them may leave the dataplane in a non-recoverable state. |
Then, a path is planned from the current running VPP dataplane configuration to the desired target configuration. | Then, a path is planned from the current running VPP dataplane configuration to the desired target configuration. | ||
| + | It would benefit to be adopted not only by downstream VPP users, but by the VPP developer community and fd.io for its integration testing, regression testing, and developer workflow, as that process ensures vppcfg develops into and stays a first class citizen. For this reason, more committers and maintainers are sought as a part of this application. | ||
== Scope == | == Scope == | ||
The scope of vppcfg is: | The scope of vppcfg is: | ||
| − | + | * a declarative description, in YAML, of the configuration attributes of any appropriate/required VPP APIs | |
| − | + | * a set of syntax constraints that validate a YAML file is correctly formed and does not have or erroneous attributes | |
| − | + | * a set of semantic constraints that validate the config expressed in the YAML file can be correctly applied and does not have contradictory attributes | |
| − | + | * a set of temporal constraints and a DAG that create a path based on object pruning, object creation and object attribute synchronization | |
| + | |||
| + | The APIs and object types that vppcfg is targeted to handle are: | ||
| + | * Any 'core' APIs that are stable | ||
| + | * Any 'plugin' APIs that are stable. | ||
| + | * (low-pri) any 'plugin' APIs that are in development. | ||
| + | |||
| + | === Background and Previous Work === | ||
Details and two papers on the topic: | Details and two papers on the topic: | ||
| − | + | * https://ipng.ch/s/articles/2022/03/27/vppcfg-1.html | |
| − | + | * https://ipng.ch/s/articles/2022/04/02/vppcfg-2.html | |
| + | |||
| + | === Relationship to other FD.io features === | ||
| + | |||
| + | Besides the downstream VPP users, the primary fd.io project that can benefit from vppcfg is CSIT: https://wiki.fd.io/view/CSIT/Description as its remit is the development of software code for fully automated VPP code testing, functionality, performance, regression and new functions. VPP developers rationally agree that their APIs should be configurable to all reasonably expected configuration states, safely and without regressing (loss of service, crashing the dataplane). vppcfg can programmatically test any combination of APIs at runtime, which greatly simplifies catching unintended regressions. | ||
| + | |||
| + | APIs and object types that cannot be safely provisioned, or have runtime attributes that are not able to be programmatically get/set, will be flagged based on a friction report against the feature/plugin/API owner. As a by-product of this work, API and object friction reports (ie. poor error handling, bounds checking, crashes in API / CLI calls, etc) will be emitted against feature/plugin/API owners. | ||
== Initial Committers == | == Initial Committers == | ||
| − | Pim van Pelt <pim@ipng.nl> | + | |
| − | Dave Wallace <dwallacelf@gmail.com> | + | Pim van Pelt <pim@ipng.nl>, Dave Wallace <dwallacelf@gmail.com>, ... two more |
| − | ... two more | + | |
== Vendor Neutral == | == Vendor Neutral == | ||
| − | There is no desire or need for vppcfg to commit | + | There is no desire or need for vppcfg to commit or champion any given vendor. It's purpose is to configure the open source fd.io version of the VPP dataplane based a YAML configuration file. No external tools or projects/products will be in scope for vppcfg to configure. In principle, the only entity it will be talking to is the CLI and API endpoints provided by VPP itself, and in case of missing VPP functionality, the Linux Netlink API (for example, setting MAC addresses of LCP, or moving TAP interfaces in and out of Linux host bridges). |
| − | + | ||
== Meets Board Policy (including IPR, being within Board defined Scope etc) == | == Meets Board Policy (including IPR, being within Board defined Scope etc) == | ||
Meets board policy as expressed in [https://fd.io/sites/cpstandard/files/pages/files/exhibit_c_-_fd.io_technical_community_charter.pdf Technical Community Charter] and [https://fd.io/sites/cpstandard/files/pages/files/exhibit_b_-_fd.io_ip_policy.pdf IP Policy] | Meets board policy as expressed in [https://fd.io/sites/cpstandard/files/pages/files/exhibit_c_-_fd.io_technical_community_charter.pdf Technical Community Charter] and [https://fd.io/sites/cpstandard/files/pages/files/exhibit_b_-_fd.io_ip_policy.pdf IP Policy] | ||
| + | |||
| + | NOTE(pim) -- both links here are broken. | ||
== Administrata == | == Administrata == | ||
Latest revision as of 08:28, 9 April 2022
Contents
Name
VPP Configuration utility, or vppcfg for short.
Project Contact Name and Email
Pim van Pelt <pim@ipng.nl>
Repository Name
vppcfg
Description
VPP is a programmable dataplane, and by design it does not include any configuration or controlplane management stack. It’s meant to be integrated into a full stack by operators. For end-users, this unfortunately means that typing on the CLI won’t persist any configuration, and if VPP is restarted, it will not pick up where it left off. There’s one developer convenience in the form of the exec command-line (and startup.conf!) option, which will read a file and apply the contents to the CLI line by line. However, if any typo is made in the file, processing immediately stops. It’s meant as a convenience for VPP developers, and is certainly not a useful configuration method for all but the simplest topologies.
Luckily, VPP comes with an extensive set of APIs to allow it to be programmed. What is needed is a configuration utility that can take a configuration file, compare it to a running VPP instance, and step-by-step plan through the API calls needed to safely apply the configuration to the dataplane. This proposal describes an existing tool [1] to be adopted by fd.io community to serve that purpose.
vppcfg consumes YAML files of a specific format. Their validity is asserted by two main types of validation:
- syntax checks are performed and this ensures that all fields in the YAML file are correctly formed, that field-names are correctly spelled, that no extra fields are given, and their values are of the correct type.
- semantic validations are performed to ensure that configurations are safely applicable to a running VPP. Note: Some semantic checks are stricter than VPP, because applying them may leave the dataplane in a non-recoverable state.
Then, a path is planned from the current running VPP dataplane configuration to the desired target configuration.
It would benefit to be adopted not only by downstream VPP users, but by the VPP developer community and fd.io for its integration testing, regression testing, and developer workflow, as that process ensures vppcfg develops into and stays a first class citizen. For this reason, more committers and maintainers are sought as a part of this application.
Scope
The scope of vppcfg is:
- a declarative description, in YAML, of the configuration attributes of any appropriate/required VPP APIs
- a set of syntax constraints that validate a YAML file is correctly formed and does not have or erroneous attributes
- a set of semantic constraints that validate the config expressed in the YAML file can be correctly applied and does not have contradictory attributes
- a set of temporal constraints and a DAG that create a path based on object pruning, object creation and object attribute synchronization
The APIs and object types that vppcfg is targeted to handle are:
- Any 'core' APIs that are stable
- Any 'plugin' APIs that are stable.
- (low-pri) any 'plugin' APIs that are in development.
Background and Previous Work
Details and two papers on the topic:
- https://ipng.ch/s/articles/2022/03/27/vppcfg-1.html
- https://ipng.ch/s/articles/2022/04/02/vppcfg-2.html
Relationship to other FD.io features
Besides the downstream VPP users, the primary fd.io project that can benefit from vppcfg is CSIT: https://wiki.fd.io/view/CSIT/Description as its remit is the development of software code for fully automated VPP code testing, functionality, performance, regression and new functions. VPP developers rationally agree that their APIs should be configurable to all reasonably expected configuration states, safely and without regressing (loss of service, crashing the dataplane). vppcfg can programmatically test any combination of APIs at runtime, which greatly simplifies catching unintended regressions.
APIs and object types that cannot be safely provisioned, or have runtime attributes that are not able to be programmatically get/set, will be flagged based on a friction report against the feature/plugin/API owner. As a by-product of this work, API and object friction reports (ie. poor error handling, bounds checking, crashes in API / CLI calls, etc) will be emitted against feature/plugin/API owners.
Initial Committers
Pim van Pelt <pim@ipng.nl>, Dave Wallace <dwallacelf@gmail.com>, ... two more
Vendor Neutral
There is no desire or need for vppcfg to commit or champion any given vendor. It's purpose is to configure the open source fd.io version of the VPP dataplane based a YAML configuration file. No external tools or projects/products will be in scope for vppcfg to configure. In principle, the only entity it will be talking to is the CLI and API endpoints provided by VPP itself, and in case of missing VPP functionality, the Linux Netlink API (for example, setting MAC addresses of LCP, or moving TAP interfaces in and out of Linux host bridges).
Meets Board Policy (including IPR, being within Board defined Scope etc)
Meets board policy as expressed in Technical Community Charter and IP Policy
NOTE(pim) -- both links here are broken.
Administrata
- Request for Project proposal consideration
- Email: (place link to email to TSC proposing project, this can be obtained from TSC Archives
- Date: (date proposed, makes it simpler to calculate the pre-requisite 2 week time period of gestation before being permitted to be voted on)
