This is an outline of how the Canvas design is documented, and a pointer to the different design artefacts:
- The highest level documentation describing the services a canvas should provide to an ODA Component is in the Canvas use case library. The use case library outlines the assumptions for each use case and sequence diagrams for the interactions between an example ODA Component and the ODA Canvas.
- The next level of details of the features required to be a fully compliant ODA Canvas is in the Compliance Test Kit. These are documented as business-friendly pseudo-code in the form of BDD (Behaviour-Driven Development) features and scenarios. BDD Features should refer to use cases in the Canvas use case library (creating or amending them as required). There is a style guide for creating BDDs at TAC-353 BDD Style Guide.
- The use cases and features are Level 2 standards and should be implementation agnostic. For the Level 3 Reference Implementation, to turn the BDD features into executable compliance tests, there are a set of TDD (Test-Driven Development) tests that define tests for each BDD scenario (embedded within each BDD). These are in the Compliance Test Kit.
- Specific design decisions where we assess options and make a decision are documented in the Architecture Decision Log.
- To organise the backlog of work for the team, we use GitHub issues. Issues may describe new features, bugs or refactoring of work. Contributors self-assign to issues to indicate who is working on what.
- Finally, the source code contains the source code, helm charts and configuration files that form the reference implementation for the Canvas. Source code should embed docstrings so that it becomes part of the documentation of the system. The source code comprises of:
- Software operators - this is the key part of the canvas. Operators manage ODA components by reading the component's requirements as meta-data in the component spec and then executing whatever lifecycle process is required to meet those requirements. Operators execute the initial deployment of a component, as well as ongoing maintenance and upgrade processes. Operators are responsible for monitoring the health of the component and taking remedial action if required. The Reference Implementation implements operators following the Kubernetes Operator Pattern. Operators could be described as management-plane functions, and are the cloud-native equivalent of Network Element Managers.
- Webhooks - The Reference implementation Canvas utilizes webhooks to integrate with the Kubernetes Control Plane. The initial use of this is for the Canvas to support multiple versions of the ODA Component Standard, allowing seamless upgrades of components and appropriate deprecation warnings.
- Utilities - The reference implementation includes some simple utilities to help with the development of the Canvas. These are not part of the Canvas itself, but are useful for development and troubleshooting. We may in the future support a command-line interface to the Canvas, similar to kubectl (for Kubernetes) or istioctl (for Istio).
The canvas reads the component requirements as meta-data in the component spec. We may need to propose changes to the component standard to meet the canvas requirements. The canvas should be able to support any component that meets the component standard, but every component may not use all the features of the canvas. The component design guidelines are documented at ODA Component Design Guidelines.
The documentation approach for the Canvas is summarised in the diagram below:
The Canvas design is split into the following epics: