Skip to content
Snippets Groups Projects
Commit 5a636da4 authored by Fabian Seidl's avatar Fabian Seidl
Browse files

Update readme with progress 


See merge request !474

Co-authored-by: default avatarAndre Sterba <andre.sterba@stud.h-da.de>
Co-authored-by: default avatarKatharina Renk <katharina.renk@stud.h-da.de>
Co-authored-by: default avatarEnglert, Fabian Emil <fabian.e.englert@stud.h-da.de>
parent 45a2987f
No related branches found
No related tags found
1 merge request!474Update readme with progress
Pipeline #157730 failed
Stage: tools
Stage: build
Stage: test
Stage: analyze
Stage: integration-test
Stage: deploy
Hide whitespace changes
Inline Side-by-side
.gitignore
+ 3
− 0
View file @ 5a636da4
...@@ -53,6 +53,9 @@ stores/*.json ...@@ -53,6 +53,9 @@ stores/*.json
# gosdn # gosdn
configs/gosdn.toml configs/gosdn.toml
config/.gosdnc.toml config/.gosdnc.toml
configs/development-gosdn.toml
configs/development-gosdn
configs/gNMISubscriptions.txt
gosdn.toml gosdn.toml
# venv-manager # venv-manager
......
README.md
+ 138
− 31
View file @ 5a636da4
...@@ -2,42 +2,65 @@ ...@@ -2,42 +2,65 @@
`goSDN` is a prototypical approach to build a model driven multi-vendor SDN controller. `goSDN` is a prototypical approach to build a model driven multi-vendor SDN controller.
This repository contains submodules, therefore it must be cloned with This repository contains submodules, therefore it **must** be cloned with
`git clone --recurse-submodules git@code.fbi.h-da.de:danet/gosdn.git`.
If you have cloned the repository without `--recurse-submodules` simply run `git submodule update --init --recursive` ```sh
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:
```sh
git submodule update --init --recursive
```
to get all submodules. to get all submodules.
# Table of Contents You can find a detailed manual to install all necessary tools at our [Wiki](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Prerequisites). <br>
There you can also find some tutorials to get to know the SDN controller:
- [Lab00 education](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab00-education), which is used in education
- [Lab00](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab00), which uses servers with gNMI targets instead of Arista switch images (needs less storage than Lab01)
- [Lab01](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab01), which uses servers with Arista switch images (needs less storage than Lab01)
---
## Table of Contents
- [Overview](#overview) - [Overview](#overview)
* [Example](#example) - [Example](#example)
* [Structure](#structure) - [Structure](#structure)
- [Concepts](#concepts) - [Concepts](#concepts)
- [Installing](#installing) - [Installing](#installing)
- [Getting Started](#getting-started) - [Getting Started](#getting-started)
* [Playground](#playground) - [Playground](#playground)
- [Additional services](#additional-services)
- [Configuration file](#configuration-file)
- [Contributing](CONTRIBUTING.md) - [Contributing](CONTRIBUTING.md)
- [License](LICENSE) - [License](LICENSE)
- [CI Status](#ci-status) - [CI Status](#ci-status)
- [Development Tutorial](#development-tutorial) - [Development Tutorial](#development-tutorial)
# Overview ---
## Overview
`goSDN` is also an application that will allow you to manage your multi-vendor `goSDN` is also an application that will allow you to manage your multi-vendor
network using one unified controller. network using one unified controller.
`goSDN` provides: `goSDN` provides:
* Model driven device/network element representation
* Native multi vendor support - Model driven device/network element representation
* Multi controller environments - Native multi vendor support
- Multi controller environments
---
## Example ## Example
A simple showcase how the controller can be adressed after A simple showcase how the controller can be adressed after
`make containerlab-start` is shown below: `make containerlab-start` is shown below:
![](gosdn-cli-showcase.webm) ![](gosdn-cli-showcase.webm)
## Structure ### Structure
- The `api` is a representation of the `controllers` Northbound-Interface and - The `api` is a representation of the `controllers` Northbound-Interface and
can be used to communicate with the `controller`. can be used to communicate with the `controller`.
...@@ -48,25 +71,31 @@ A simple showcase how the controller can be adressed after ...@@ -48,25 +71,31 @@ A simple showcase how the controller can be adressed after
on them. They are currently unsupported. on them. They are currently unsupported.
- `controller` represents the `goSDN-controller`. - `controller` represents the `goSDN-controller`.
# Concepts ---
## Concepts
The `goSDN` controllers core - also called `nucleus` - is a lightweight library The `goSDN` controllers core - also called `nucleus` - is a lightweight library
that manages principal network domains and provides southbound interface that manages principal network domains and provides southbound interface
operations for managed network elements. operations for managed network elements.
In addition, we provide a simple Northbound-API for the controller () In addition, we provide a simple Northbound-API for the controller [right here](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/controller/api).
## Principal Networking Domain (PND) ### Principal Networking Domain (PND)
The PND is the single source of truth within a network. Its state is held and 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 maintained by the controller. Any configuration of an MNE has to be applied by
the PND. the PND.
## Managed Network Element (MNE) ### Managed Network Element (MNE)
Any network element directly configured by `goSDN` Any network element directly configured by `goSDN`
# Installing ---
## 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. `goSDN` provides a `Makefile` for all common use cases.
```sh ```sh
...@@ -77,23 +106,37 @@ make build ...@@ -77,23 +106,37 @@ make build
make containerize-all 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.
```sh
--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](#additional-services).
Now you can start `goSDN` locally by moving to the `artifacts` folder and Now you can start `goSDN` locally by moving to the `artifacts` folder and
running `./gosdn` from the shell. running `./gosdn` from the shell:
```sh
./gosdn
```
---
# Getting Started ## Getting Started
If you want to use the the [playground](#playground) you have to make sure you If you want to use the the [playground](#playground) you have to make sure you
have [containerlab](https://containerlab.dev/install/) installed on your have [containerlab](https://containerlab.dev/install/) installed on your
system. system.
## Playground ### Playground
With the help of [containerlab](https://containerlab.dev/) we provide a simple With the help of [containerlab](https://containerlab.dev/) we provide simple test environments to play around with.
test environment to play around with.
The environment contains two [Arista The environment Lab 01 contains two [Arista
cEOS](https://www.arista.com/en/products/software-controlled-container-networking), cEOS](https://www.arista.com/en/products/software-controlled-container-networking),
a goSDN, a cSBI orchestrator and a gNMI target. 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 > If you're a member of the danet group you should have access to the
> containers repo. Don't forget to `sudo docker login > containers repo. Don't forget to `sudo docker login
...@@ -114,17 +157,72 @@ make containerlab-start ...@@ -114,17 +157,72 @@ make containerlab-start
make containerlab-stop 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](#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
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 adress of the broker
- `amqpport`: port of the broker
- `amqpuser`: user name 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 adress and port of the plugin-registry
---
## CLI ## CLI
Information about how to use the CLI is provided in the `cli` folder, see [here](cli#usage). Information about how to use the CLI is provided in the `cli` folder, see [here](cli#usage).
# CI Status ## CI Status
| Master |
| ------ |
| [![coverage report](https://code.fbi.h-da.de/danet/gosdn/badges/master/coverage.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/master) |
| [![pipeline status](https://code.fbi.h-da.de/danet/gosdn/badges/master/pipeline.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/master) |
| Master | Develop | ---
| ------ | ------ |
| [![coverage report](https://code.fbi.h-da.de/danet/gosdn/badges/master/coverage.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/master) | [![coverage report](https://code.fbi.h-da.de/danet/gosdn/badges/develop/coverage.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/develop) |
| [![pipeline status](https://code.fbi.h-da.de/danet/gosdn/badges/master/pipeline.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/master) | [![pipeline status](https://code.fbi.h-da.de/danet/gosdn/badges/develop/pipeline.svg)](https://code.fbi.h-da.de/danet/gosdn/-/commits/develop) |
# Development Tutorial ## Development Tutorial
To help with developing there is a small script available, which helps to create the complete dev environment. To help with developing there is a small script available, which helps to create the complete dev environment.
For it to work, you need `go`, `docker`, `docker compose` and `containerlab`. For it to work, you need `go`, `docker`, `docker compose` and `containerlab`.
...@@ -148,15 +246,24 @@ Example usages: ...@@ -148,15 +246,24 @@ Example usages:
`./scripts/manage_virt_env.sh --mode stop --topology dev_env_data/clab/basic_two_aristas.yaml` `./scripts/manage_virt_env.sh --mode stop --topology dev_env_data/clab/basic_two_aristas.yaml`
## Backup and restore your mongodb ### 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. If you are using the mongodb provided via the `docker-compose.yaml`, you can easily back up and restore your data via two scripts.
```bash ```bash
./scripts/backup_mongo_volume.sh $(suffix_of_backup) ./scripts/backup_mongo_volume.sh $(suffix_of_backup)
``` ```
```bash ```bash
./scripts/restore_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. 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](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/application-framework) within this repository.
The framework provides some basic code to easily setup 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](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/applications).
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment