gosdn

README

goSDN

goSDN is a prototypical approach to build a model driven multi-vendor SDN controller.

This repository contains submodules, therefore it must be cloned with

git clone --recurse-submodules git@code.fbi.h-da.de:danet/gosdn.git

or if you have cloned the repository without --recurse-submodules simply run:

git submodule update --init --recursive

to get all submodules.

You can find a detailed manual to install all necessary tools at our Wiki.
There you can also find some tutorials to get to know the SDN controller:

• Lab00 education, which is used in education
• Lab00, which uses servers with gNMI targets instead of Arista switch images (needs less storage than Lab01)
• Lab01, which uses servers with Arista switch images (needs less storage than Lab01)

---

Table of Contents

• Overview
  • Example
  • Structure
• Concepts
• Installing
• Getting Started
  • Playground
  • Additional services
  • Configuration file
• Development-Tutorial
• Integration tests
• Contributing
• License
• CI Status

---

Overview

goSDN is also an application that will allow you to manage your multi-vendor network using one unified controller.

goSDN provides:

• Model driven device/network element representation
• Native multi vendor support
• Multi controller environments

---

Example

A simple showcase how the controller can be addressed after make containerlab-start is shown below:

Structure

• The api is a representation of the controllers Northbound-Interface and can be used to communicate with the controller.
• The cli is the CLI to manage the controller.
• csbi is the implementation of Containerised-Southbound-Interfaces (based on the idea and the proof of concept of Manuel Kieweg). Allowing to request capabilities of MNEs and generate a containerized Southbound-Interface based on them. They are currently unsupported.
• controller represents the goSDN-controller.

---

Concepts

The goSDN controllers core - also called nucleus - is a lightweight library that manages principal network domains and provides southbound interface operations for managed network elements.

In addition, we provide a simple Northbound-API for the controller right here.

Principal Networking Domain (PND)

The PND is the single source of truth within a network. Its state is held and maintained by the controller. Any configuration of an MNE has to be applied by the PND.

Managed Network Element (MNE)

Any network element directly configured by goSDN

---

Launch goSDN Controller local

In this chapter, you learn how to launch the goSDN controller.

Firstly, make sure that you're located in the root directory of goSDN. goSDN provides a Makefile for all common use cases.

# build the application files for goSDN, cSBI orchestrator, gosdnc (CLI).
make build

# build the Dockerfiles for goSDN, cSBI orchestrator, gosdnc (CLI).
make containerize-all

Depending on how you want to use the controller, you might need to edit the example config files and provide the path to this or a new config file. This can be done by providing setting the config flag when starting the controller.

--config

In case you want to use specific services with the controller without setting them up manually you can use the provided docker compose file. More information about that can be found under Additional services.

Now you can start goSDN locally by moving to the artifacts folder and running ./gosdn from the shell:

./gosdn

---

Getting Started

If you want to use the playground you have to make sure you have containerlab installed on your system.

Playground

With the help of containerlab we provide simple test environments to play around with.

The environment Lab 01 contains two Arista cEOS, a goSDN, a gNMI target, a plugin-registry, a MongoDB and a RabbitMQ.

The environment Lab 00 contains two gNMI targets used as switches, s goSDN, two Linux servers, a plugin-registry, a MongoDB and a RabbitMQ. Lab 00 is lighter than Lab 01.

If you're a member of the danet group you should have access to the containers repo. Don't forget to sudo docker login registry.code.fbi.h-da.de (sudo is necessary since containerlab has to be run with it and therefore a normal docker login wouldn't be recognized by it.)

If you're no member of the danet group you have to create an account at Arista and download the Arista cEOS image by yourself. Don't forget to change the image name (line 11 in the gosdn.clab.yml file) to the local one you've downloaded.

# starts the containerlab topology which contains two Arista cEOS, an cSBI orchestrator, a goSDN controller and gNMI target.
make containerlab-start

# stop the containerlab topology
make containerlab-stop

Additional services

There are optional and mandatory services that can be used with the controller. They can be started via the provided docker-compose.yml:

docker compose up -d

Otherwise all the necessary services are included in the provided environments like containerlab. Within other use cases, they can also be configured by providing specific parameters in the controller config files. See Configuration file for information about the parameters. The services are:

• RabbitMQ message-broker: uses AMQP to provide a pub-sub mechanism. This is part of the event system used in goSDN. This server is optional.
• Databases: The controller can be used with a file store system or by providing an external database. Currently, there is only support for MongoDB. It is not mandatory to use a database.
• Plugin-registry: The plugin-registry provides plug-ins to the controller, which are used to handle different YANG files used within the communication with MNE via gNMI.

Configuration file

goSDN can be configured by using providing a config file. Examples can be found in controller/configs. These examples contain different pre-defined configurations for different environments. There's no need to touch the config files when using provided environments like starting the containerlab via makefile. The following parameters can be set:

For goSDN:

• security: the security level of the controller.
  • 'secure' mode does use the built-in authentication and RBAC mechanisms (recommended)
  • 'insecure' does not use these (only use for testing purposes). Uses default if not set.
• socket: the desired port, where to reach the controller
• basepnduuid: an initial ID of a PND within the network, needs to be a UUID
• config: path to this configuration file, so change can be written back to the file
• gnmisubscriptionspath: path to the file providing the YANG paths the controller should subscribe to in each network element existing in its storage
• defaultjwtduration: duration of how long session tokens will be valid, provide an integer for the desired hours, example: 24 for tokens that should be valid for one day
• log-level: set to 'debug' for a better level of information
• help: print the description of all available flags
• tlscertfile: path to a signed certificate, if set goSDN will use this in combination with a key file to set up TLS connections with communication partners
• tlskeyfile: path to a private key, if set goSDN will use this in combination with a signed cert file to set up TLS connections with communication partners

For the storage system:

• databaseconnection: address of the database, only add this parameter if you want to use a database. Currently, only mongoDB is supported.
• filesystempathtostores: set this path if the controller should use only the file store system, does not support all entities currently.
  Note: if the database connection is set as well, this parameter will be ignored.
• plugin-folder: path to where the plugins are/should be stored.

For the event system (RabbitMQ broker):

• amqpprefix: the URI prefix that is needed to connect to the RabbitMQ broker.
• amqphost: IP address of the broker
• amqpport: port of the broker
• amqpuser: username of credentials to access the broker, default value is guest
• amqppassword: user password of credentials to access the broker, default is guest

For the plugin registry:

• plugin-registry: IP address and port of the plugin-registry

---

CLI

Information about how to use the CLI is provided in the cli folder, see here.

CI Status

Master

---

Development Tutorial

There are several options on how to develop. There is the classic way to install everything on your machine or the option to use dev containers (locally or remotely) with VSCode.

Dev container

For this method you only need docker and vscode with the plugin Dev Containers from Microsoft installed. After you installed the required tools, you can simply open the folder in the dev container. Either you click on Open in Container if a pop-up appears on the bottom right, or by selecting Open in Container after clicking on Remote Explorer in the left bar in VSCode. Please note: depending on your internet connection and the performance of the device, the initial creation of the container can take several minutes or longer! Furthermore, the initial git discovery of every submodule in this repo (if installed) can also take some minutes.

Keep in mind that containerlab also needs sudo in the dev container, so you need to log in via sudo docker login registry.code.fbi.h-da.de

The dev container has everything you need in it (even relevant VSCode plugins), so you should not need anything more. As per the default configuration you will get access to a zsh shell with oh-my-zsh installed. Everything happening in your user home folder /home/vscode in the dev container is persistent in a docker volume. This means, that you can customize your .zshrc or configure a different shell. Your zsh history is also saved, but not synchronized with the history on your own machine. This is by design because of the idea of separation, but can be changed by mounting your local history file into the dev container.

The volume also means, that caches for things like golang-ci lint are persistent.

Furthermore, the folder /root/docker is a persistent volume, so that docker login credentials for root (used by containerlab) are also persistent.

For some changes to the dev container setup, mainly changes where the config lays in volumes later, the changes can only be applied if all volumes get deleted beforehand. So if some things do not work in your dev container, maybe you missed an update. In that case stop the dev container, delete all volumes of this project and rebuild (not restart!) the container.

Dev container - remote

If for example your local device is not very performant, an ARM device, or you want to use a remote device for other reasons to develop, you can use the dev container setup remotely via SSH on a different device/server.

You will need the plugins Remote Development and Dev Containers for VSCode and the target host needs docker installed. Your local machine doesn't need docker! To use this setup, connect to a remote host via SSH. Afterwards, you can use the dev containers just as you would locally.

Classic

The classic installation requires go, docker, docker compose and containerlab. To help with developing there is a small script available, which helps to create the complete dev environment.

Create a dev environment

For a quick start simply use make start-dev-env to start everything. This can take a while. Afterwards, you see the output of goSDN, to stop it hit Ctrl+C. To stop everything else use make stop-dev-env.

If you want more control over your environment, you can use the manage_virt_env.sh script directly.

It works like this, if you are in the projects root folder:

./scripts/manage_virt_env.sh --mode $(start || stop) --topology $PATH_TO_TOPOLOGY --SDNCONFIG $PATH_TO_SDNCONFIG --keepdb (optional)

mode defines if it should start or stop the environment, while the two commands --topology and --sdnconfig are used to provide the desired files. The optional flag keepdb is used if you want to create the environment without reloading the SDN config file, which is handy if you just want to restart the environment. For every command there is a shortcut available (e.g. -t for --topology, etc.).

Example usages:

./scripts/manage_virt_env.sh --mode start --topology dev_env_data/clab/basic_two_aristas.yaml --sdnconfig dev_env_data/sdn/basic_two_aristas.json

./scripts/manage_virt_env.sh --mode start --topology dev_env_data/clab/basic_two_aristas.yaml --keepdb

./scripts/manage_virt_env.sh --mode stop --topology dev_env_data/clab/basic_two_aristas.yaml

Backup and restore your mongoDB

If you are using the mongoDB provided via the docker-compose.yaml, you can easily back up and restore your data via two scripts.

./scripts/backup_mongo_volume.sh $(suffix_of_backup)

./scripts/restore_mongo_volume.sh $(suffix_of_backup)

Keep in mind that a restore will restart the mongoDB container.

Developing SDN applications

To develop applications, we provide a framework that can be found here within this repository.

The framework provides some basic code to easily set up the subscription to the event system of the controller, so that your application can get notified via the events published by the RabbitMQ server about information you would like to receive. This includes functions to register and subscribe to the used server. The information you receive includes changes on network elements like if a value of a YANG path changes or other changes like additions or deletions of entities.

Examples where the application framework is used can be found here.

Integration tests

The integration tests are currently in its own folder named integration-tests, as they use a complete black box design. The idea is to test as many of our code with as little tests as possible to get a "catch all" approach where a test may fail and hint for a problem, without really telling us what the problem is. As of the nature of this project many people contribute only a small part and often don't have time to write good unit-tests. Therefore, we simply want to make sure that a change doesn't break anything important.

There exists a example_tests folder where examples of using the integrationTestUtils are shown. Each test should use the appropriate set-up and tear-down/clean-up functions, so that each test operates independent of each other.

Run the integration tests with make controller-integration-tests. If you want to debug the tests, use make controller-integration-tests-debug-up to start the environment. You can now use the debugger to debug the test (but not the goSDN side). Stop the environment when you are done with make controller-integration-tests-debug-down.