From 0e17b04474e8c1ec79ce8fad99506e665667fab3 Mon Sep 17 00:00:00 2001 From: bormanp <122468813+bormanp@users.noreply.github.com> Date: Mon, 20 May 2024 18:08:34 -0500 Subject: [PATCH] Add documentation on the expectations of vendor images. (#535) * Add documention on the expectations of vendor images. * Make clear that community contributions to vendor code in the kne repository are welcome and that the vendors should review and approve those PRs. * Update document to indicate these are guidelines (should vs must). --- docs/README.md | 7 ++++ docs/vendor.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 docs/vendor.md diff --git a/docs/README.md b/docs/README.md index 60d2d777..91fbe973 100644 --- a/docs/README.md +++ b/docs/README.md @@ -29,6 +29,13 @@ KNE can easily be scaled to run large topologies utilizing its Kubernetes backbone. This guide describes how to set up a k8s multi worker node cluster and get a 150 node KNE topology up and running. +## Vendor Image Requirements + +[Vendor Image Requirements](vendor.md) + +KNE uses vendor supplied images. This document describes the expectations +for those images. + ## Kubernetes Reference [Kubernetes Reference](kubernetes_reference.md) diff --git a/docs/vendor.md b/docs/vendor.md new file mode 100644 index 00000000..d6ead95e --- /dev/null +++ b/docs/vendor.md @@ -0,0 +1,100 @@ +# Vendor Image Requirements + +A Vendor Image is a docker container that can be used with KNE to emulate a +vendor's devices. A Vendor Image might also be a fully virtual device with +no physical version, such as openconfig/lemming. + +Without vendor images KNE is just an empty virtual machine rack that does +nothing. Vendor supplied images are what the user of KNE sees and is interested +in. This document describes the requirements and expectations of vendor images +and the associated code that is included in the KNE repository + +A vendor image requires a corresponding node implementation in topo/node/vendor +and should have working examples in examples/vendor. A single node +implementation may support multiple vendor images (e.g., cisco-xrd and cisco-8000e). A maintainer is the person or organization that maintains the vendor +specific node implementation and examples. + +In this document a vendor is considered the person or organization that makes +image containers available for use by others. + +## KNE Uses + +KNE was built to enable testing the functionality of networks without physical +hardware. Due to the obvious limitations of emulation, KNE is not designed to +test bandwidth and latency of connections. KNE is designed to enable testing of +the control protocols and interaction between devices. There are several +different types of testing. + +### Testing new Topologies + +KNE is used to test changes in network topology. Changes in network topology +can impact various protocols use in the network (e.g. BGP). + +### Testing Changes in Protocol or Configuration + +KNE is used to test protocol changes or other configuration changes. + +### Testing Device Functionality + +KNE is used to test changes to a device's Network Operating System (NOS). This +is a crucial step in validating a devices usability for a particular purpose +when a new NOS is released. + +## Fidelity + +A network device in KNE can be viewed as two main components, the control plane +and the data plane (the ASIC). + +KNE is used to test the control plane of the NOS. This requires the control +software in the virtual device behave the same as in the hardware. It is +expected that the control software used in an image is the same as the +software used on the physical device and that it is configured and reacts in the +same way as the hardware. + +KNE is not designed to test the data plane or ASIC. The emulated data plane +must support routing and packet forwarding. ASIC specific commands and features +do not need to be supported as long as the data plane provides basic +functionality. + +All of these use cases require that the vendor images to behave functionally as +if it were the hardware. The image is expected to be built from the same source +code base as the NOS used in the hardware. Faithful emulation of the ASIC is +not a requirement. The emulated ASIC (data plane) must correctly handle routing +changes and packet forwarding. + +### Deviations + +The vendor should supply a document that describes what series of devices the +image emulates as well as known limits and deviations. These include + +* Protocols not supported +* Protocols that deviate from the hardware (and how) +* OpenConfig paths only supported by hardware +* OpenConfig paths that report different results compared to the hardware. +* Known limitations of the emulated device +* Supported port configurations (e.g, number of ports, line cards, etc). + +The listed OpenConfig paths need not be leaf nodes. Wildcards may be used in +the path where applicable. + +## Testing + +Vendor images must be tested prior to publication. A standard set of tests is +found at . At a minimum, a KNE node using that image should +start and not cause the KNE emulation to hang. It should work in both a single +Kubernetes Worker Node environment as well as a multi-worker node environment. + +It is expected that released images undergo repeated testing to identify +non-deterministic errors. + +## Support + +Vendors are responsible for support of their images. The maintainer (typically +the person or organization that provides the associated container images) is +responsible for the support of the vendor image specific node implementation in +[kne/topo/node](https://github.com/openconfig/kne/tree/main/topo/node) +as well as the vendor specific examples in +[kne/examples](https://github.com/openconfig/kne/tree/main/examples). The +maintainer should be responsive to community contributions. In the event the +maintainer of a particular node implementation is unresponsive a new maintainer +may take over that implementation.