{"id":40342977,"url":"https://github.com/telstra/open-kilda","last_synced_at":"2026-01-20T09:05:03.741Z","repository":{"id":37413078,"uuid":"104974693","full_name":"telstra/open-kilda","owner":"telstra","description":"OpenKilda is an open-source OpenFlow controller initially designed for use in a global network with high control-plane latency and a heavy emphasis on latency-centric data path optimisation.","archived":false,"fork":false,"pushed_at":"2025-07-10T06:38:51.000Z","size":307377,"stargazers_count":83,"open_issues_count":408,"forks_count":56,"subscribers_count":26,"default_branch":"develop","last_synced_at":"2025-10-05T12:30:54.415Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/telstra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-09-27T05:13:18.000Z","updated_at":"2025-08-13T11:17:36.000Z","dependencies_parsed_at":"2024-04-17T12:49:44.152Z","dependency_job_id":"6157646b-aa58-4956-a099-e0add74f1a4c","html_url":"https://github.com/telstra/open-kilda","commit_stats":null,"previous_names":[],"tags_count":313,"template":false,"template_full_name":null,"purl":"pkg:github/telstra/open-kilda","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telstra%2Fopen-kilda","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telstra%2Fopen-kilda/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telstra%2Fopen-kilda/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telstra%2Fopen-kilda/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/telstra","download_url":"https://codeload.github.com/telstra/open-kilda/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/telstra%2Fopen-kilda/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28599858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T08:51:33.170Z","status":"ssl_error","status_checked_at":"2026-01-20T08:51:10.855Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-20T09:05:02.500Z","updated_at":"2026-01-20T09:05:03.726Z","avatar_url":"https://github.com/telstra.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\nOPEN KILDA SDN CONTROLLER\n---\n[![Build Status](https://github.com/telstra/open-kilda/actions/workflows/unittest.yml/badge.svg)](https://github.com/telstra/open-kilda/actions/workflows/unittest.yml)[![Quality Gate](https://sonarcloud.io/api/project_badges/measure?project=org.openkilda%3Akilda-parent\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=org.openkilda%3Akilda-parent)\n\n## Introduction\n\nOpenKilda is a Web-Scale Software-Defined Networking controller. OpenKilda is capable of manage traffic on tens of thousands of switches simultaneously,\ncontrol millions of flows, and provide sub-second network telemetry. OpenKilda provides a variety of features, such as:\n- manual and automatic management of L2 services: point-to-point flows, Y-flows, etc.;\n- advanced features for some types of services: mirroring, data gathering, path pinning, etc.;\n- path computation engine: calculating paths based on different cost functions;\n- resilient mechanisms: quick reaction on changes on hardware level, paths recalculations, diverse flow groups to ensure back-up routes;\n- parallelism: flexible distributed computation, easy-to-change configuration;\n- visualized telemetry and reporting;\n- REST API and GUI to configure and manage OpenKilda capabilities;\n- and more!\n\nYou can find OpenKIlda high level design [here](docs/design/kilda-high-level-design/design.md).\n\n## Important notes\n\n### Deprecation\n\nSince the release 1.126.2 (December 2022), single-table mode for switches became deprecated. New features will be designed\nonly for multi-table mode. Current features will support single table mode till July 1, 2023. After that, single table\nmode support might be removed from any feature.\n\n## How to contribute to OpenKilda\nOpenKilda is an open source project that welcomes contributions from developers.\nTo contribute, it is mandatory to follow our contribution [workflow](docs/contrib/workflow.md).\n\n## How to build and deploy OpenKilda\n\nThe build process described below requires to install a number of packages. It is recommended that you build OpenKilda on a virtual machine.\n\n### Prerequisites\n\nThe following packages are required for building OpenKilda controller:\n - Gradle 7.0+\n - Maven 3.3.9+\n - JDK 8+\n - Python 3.8+\n - Docker 19.03.3+\n - Docker Compose 1.20.0+\n - GNU Make 4.1+\n - Open vSwitch 2.9+\n\n#### Python dependency notice\n\nWe do not recommend upgrading pip using the method described below, bypassing the packer managers. Instead, please read the documentation for installing the [pip](https://pip.pypa.io/en/stable/installation/#upgrading-pip).\n\n\n#### Dependency installation on Ubuntu 18.04\n\nFor running a virtual environment (that is a Docker instance with the Open vSwitch service) it is required to have Linux kernel 4.18+ for OVS meters support.\nThe following commands will install necessary dependencies on Ubuntu 18.04:\nAdd Python's PPA repository\n```shell\nsudo add-apt-repository -y ppa:deadsnakes/ppa\n```\n\nInstall required packages:\n```shell\nsudo apt update \u0026\u0026 sudo apt-get install -y \\\n  maven \\\n  openjdk-8-jdk \\\n  python \\\n  python3.8 \\\n  python3-pip \\\n  virtualenv \\\n  make \\\n  tox \\\n  rsync \\\n  openvswitch-switch \\\n  linux-generic-hwe-18.04\n```\n\nInstall required components for Python 3.6:\n```shell\nsudo pip3 install setuptools-rust==1.1.2 setuptools==46.4.0 --upgrade\n```\n\nUpgrade pip3:\n```shell\nsudo pip3 install pip --upgrade\n```\n\n(Optional) To avoid version conflict install python3-pip with the official script. To do it, you need to download script \u0026 run script:\n```shell\nwget -P /tmp/ https://bootstrap.pypa.io/get-pip.py \\\n  \u0026\u0026 sudo python3.8 /tmp/get-pip.py\n```\n\n#### Dependency installation on Ubuntu 20.04\n\nThe following commands will install necessary dependencies on Ubuntu 20.04:\n```shell\nsudo apt update \u0026\u0026 sudo apt install -y \\\n  maven \\\n  make \\\n  openjdk-8-jdk \\\n  openvswitch-switch \\\n  python3-pip \\\n  tox \\\n  rsync\n```\n\nUpgrade pip3:\n```shell\nsudo pip3 install pip --upgrade\n```\n\n(Optional) To avoid version conflict install python3-pip with the official script. To do it, you need to download script \u0026 run script:\n```shell\nwget -P /tmp/ https://bootstrap.pypa.io/get-pip.py \\\n  \u0026\u0026 sudo python3.8 /tmp/get-pip.py\n```\n\n#### Gradle\n\nYou can either install Gradle, or use Gradle wrapper:\n - Option 1: Use Gradle wrapper. The OpenKilda repository contains an instance of Gradle Wrapper\n which can be used straight from here without further installation.\n - Option 2: Install Gradle 7.0 or later versions - https://gradle.org/install/\n\n\n#### Docker\n\nNote that your build user needs to be a member of the docker group for the build to work.\nDo that by adding the user to /etc/groups, logging out, and logging in back again.\n\n##### Basic installation instruction from Docker site\n```shell\nsudo apt-get install -y ca-certificates curl gnupg lsb-release \\\n\u0026\u0026 sudo mkdir -p /etc/apt/keyrings \\\n\u0026\u0026 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg \\\n\u0026\u0026 echo \"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable\" \\\n | sudo tee /etc/apt/sources.list.d/docker.list \u003e /dev/null \\\n\u0026\u0026 sudo apt-get update \u0026\u0026 sudo apt-get install -y \\\n  docker-ce \\\n  docker-ce-cli \\\n  containerd.io \\\n  docker-compose-plugin \\\n\u0026\u0026 sudo usermod -aG docker $USER\n# re-login or reboot to apply the usermod command\n```\n\n#### Maven\nYou also need to increase the maven RAM limit at least up to 1G.\n\n```shell\nexport MAVEN_OPTS=\"-Xmx1g -XX:MaxPermSize=128m\"\n```\n\n### How to build OpenKilda Controller\n\nFrom the base directory, execute the following command:\n\n```shell\nmake build-stable\n```\n\nNote that additional Ubuntu packages will be installed as a part of the build process.\n\n### How to clean OpenKilda Controller\n\nFrom the base directory, execute the following command:\n\n```shell\nmake clean\n```\n\n### How to run OpenKilda Controller\n\n__NB: To run OpenKilda, you should have built it already (see the previous section).__\nThis is particularly important because docker compose will expect that some specific containers already exist.\n\nFrom the base directory, execute the following command:\n\n```shell\nmake up-stable\n```\n\n### How to create a virtual topology for test\n\n```shell\nmake test-topology\n```\n\n### How to run OpenKilda Controller in blue-green mode\n\nBlue-green mode is an implementation of zero downtime feature. In this mode, you have\ntwo versions of OpenKilda running: the old one (blue) and the new one (green).\nThen, at some point in time switch blue to green.\n\n__First of all you need to build two sets of images.__\n\nTo build blue version of OpenKilda you need to run:\n```shell\nmake build-stable\n```\n\nTo build a green version of OpenKilda you need to run:\n```shell\nmake build-latest\n```\n\nThese two commands build images with tags `stable` and `latest`.\nThese tags will be used to run OpenKilda in blue mode (from stable images)\nor in green mode (for latest images).\n\n__There are 3 new commands to run OpenKilda in blue-green mode:__\n\nThe following command runs OpenKilda in blue mode from stable images.\nIt starts all common components like Zookeeper, database, Kafka, etc.\n```shell\nmake up-stable\n```\n\nThe next command starts the green version of OpenKilda from the latest images.\nCommon components wouldn't be restarted (we started them using the previous command).\nFloodlight 1 wouldn't be restarted; Floodlight 1 will stay on blue mode.\nOnly Floodlight 2 will be restarted.\n```shell\nmake up-green\n```\n\nThe next command is used to test rollbacks. It runs stable components in blue mode.\nThe difference with `make up-stable` is that this command wouldn't start common components\n(like Zookeeper, Kafka, etc) and Floodlight 2 (it stays in green mode).\n\n```shell\nmake up-blue\n```\n\n### How to debug OpenKilda Controller components\n\nAn important aspect of troubleshooting errors and problems in your code is to avoid them in the first place. It's not\nalways that easy, so we should have reliable tools that help in resolving problems. Adding any diagnostic code may be helpful, but there are more\nconvenient ways. Just a few configuration changes will allow us to use a debugging toolkit.\nAs an example, let's take the northbound component. This is a simple REST application providing the interface for interaction\nwith switches, links, flows, features, health-check controllers, and so on. The first thing that we need to do is to add\n\n```\n\"-agentlib:jdwp=transport=dt_socket,address=50505,suspend=n,server=y\"\n```\n\nto the ```CMD``` block in ```docker/northbound/Dockerfile```, where ```50505``` is any arbitrary port we’ll be using to connect a debugger.\nThe final file will be similar to the following:\n\n```dockerfile\nARG base_image=kilda/base-ubuntu\nFROM ${base_image}\n\nADD BUILD/northbound/libs/northbound.jar /app/\nWORKDIR /app\nCMD [\"java\", \"-XX:+PrintFlagsFinal\", \"-XX:+UnlockExperimentalVMOptions\", \"-XX:+UseCGroupMemoryLimitForHeap\", \"-agentlib:jdwp=transport=dt_socket,address=50505,suspend=n,server=y\", \"-jar\", \"northbound.jar\"]\n```\n\nSince debugging is done over the network, that also means we need to expose that port in Docker. For that purpose we need\nto add  ```\"50505:50505\"``` to the northbound the ```ports``` block in ```docker-compose.yml```:\n\n```\nnorthbound:\n  container_name: openkilda-northbound\n  build:\n    context: docker\n    dockerfile: northbound/Dockerfile\n  ports:\n    - '8088:8080'\n    - '50505:50505'\n  ...\n```\n\nAfter making these changes, we need to configure a remote debugging in a debugger. For example, in IntelliJ IDEA: navigate to ```Edit Configurations -\u003e Remote```\nand set up the debug port as ```50505```. For more details, please see the documentation of a particular debugger application.\n\nNext, we just run ```docker compose up```. If everything above was done correctly you must see:\n\n```\n\"java -agentlib:jdwp=transport=dt_socket,address=50505,suspend=n,server=y -jar northbound.jar\"\n```\n\nin the command column for the open-kilda_northbound. To see the status of the northbound container, we can use the command ```docker ps -a --no-trunc | grep northbound```.\nAlso, we can check the log record in open-kilda_northbound logs. If the debugger in this container is ready, the following entry will be present in the log:\n```\nListening for transport dt_socket at address: 50505\n```\n\nNow we can run the debugger. The console log in the debugger should contain the following message:\n\n```\nConnected to the target VM, address: 'localhost:50505', transport: 'socket'\n```\n\nTo check how debugging works we need to:\n- set up a breakpoint,\n- make a call to execute some functionality.\n\nIn some cases, we must have an approach for debugging a deploy process for a couple (or more) components that interact with each other. Let's\nsuppose both of them work under docker and some component doesn't belong to us and provided as a library. The typical case:\nWorkflowManager (further WFM) and Storm. The approach that is going to be used is almost the same as for northbound but there are\nnuances.\nFirst of all, we need to check which version of Storm is used in Open Kilda Controller. For that open ```docker/storm/Dockerfile```\nand find the version of Storm. In our case, the Storm version is ```1.1.0```. To be able to debug Storm we have to clone\nthe sources from the GitHub repo ```https://github.com/apache/storm.git``` and switch to the release ```1.1.0```.\n```git checkout -b 1.1.0 e40d213```. Information about releases can be found here ```https://github.com/apache/storm/releases/```\n\nThen, go to ```docker/wfm/Dockerfile``` and add ```ENV STORM_JAR_JVM_OPTS \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50506\"```\nThe final file will look similar to the following:\n\n```dockerfile\nARG base_image=kilda/storm:latest\nFROM ${base_image}\n\nENV STORM_JAR_JVM_OPTS \"-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=50506\"\n...\n```\n\nNext, it only remains to add the port ```50506``` in the WFM container section in the dockerfile as in the example below:\n\n```\nwfm:\n  container_name: wfm\n  build:\n    context: docker\n    dockerfile: wfm/Dockerfile\n  ...\n  ports:\n    - \"50506:50506\"\n```\n\nAfter executing ```docker compose up``` you should see the following log record ```Listening for transport dt_socket at address: 50506```\nin the WFM logs.\n\nNow, after we configure the remote debugger to connect to the port ```50506```, we'll be able to debug both components: WFM and Storm.\nFor example, in IntelliJ IDEA: navigate to ```Edit Configurations -\u003e Remote``` and set up the debug port as ```50506```.\nFor more details, please see the documentation of a particular debugger application.\n\nIn order to debug a topology, for example, ```NetworkTopology```:\ncreate (or open if already exists) ```NetworkTopology.main``` application debug configuration and add ```--local``` to Program arguments,\nexecute ```docker compose up``` and run in the debug mode ```NetworkTopology.main```.\n\n### How to run tests\n\nPlease refer to the [Testing](https://github.com/telstra/open-kilda/wiki/Testing) section on our Wiki.\n\n### How to build / test locally without containers\n\nStart with the following:\n\n```shell\nmake unit\n```\n\nFrom there, you can go to specific projects to build / develop / unit test.\nJust follow the _make unit_ trail.  Most projects have a gradle ```build``` or maven ```target```.\n\n### How to build / test key use cases\n\nLook in the `docker/hacks/usecase` directory. You'll find several makefiles that will assist\nwith the development and testing of that use case.\n\nAs an example, you can execute the following command for more information on the __network\ndiscovery__ use case:\n\n```shell\nmake -f docker/hacks/usecase/network.disco.make help\n```\nor\n```shell\ncd docker/hacks/usecase\nmake -f network.disco.make help\n```\n\n\n### How to use a VM to do development\n\nVirtualBox and Vagrant are popular options for creating VMs.\nA VM may be your best bet for doing development with OpenKilda.\nThere are a set of files in the source tree that will facilitate this.\n\n* __NB1: Ensure you have VirtualBox and Vagrant installed and on the path__\n* __NB2: It is recommended to clone OpenKilda again, to ensure there are no any write permission issues\n    between the guest VM and the host.__\n\nSteps:\n\n1. From the root directory, look at the Vagrantfile; feel free to change its parameters.\n2. `vagrant up`: create the VM; it'll be running after this step.\n3. `vagrant ssh`: this will log you into the vm.\n4. `ssh-keygen -t rsa -C \"your_email@example.com\"`: you'll use this for GitHub.\n5. Add the ~/.ssh/id-rsa.pub key to your GitHub account so that you can clone OpenKilda.\n6. Clone and Build\n```\n# NB: Instead of putting it in vm-dev, you can use /vagrant/vm-dev\n#     This has the added benefit that the code will appear outside of the VM\n#     because /vagrant is a shared directory with the same directory on the host where the Vagrantfile is located.\ngit clone git@github.com:\u003cyour_github_account\u003e/open-kilda.git vm-dev\ncd vm-dev\ngit checkout mvp1rc\nmake build-base\ndocker compose build\nmake unit\nmake up-test-mode\n```\n\n### How to use confd for config/properties templating\n\nWe have confd for managing config/properties files from templates. Confd configs, templates and variable file stored in confd/ folder.\n`confd/conf.d/*.toml`: files with the description on how to process templates (src. path, dst.path.... etc).\n`confd/templates/*/*.tmpl`: templates in the go-template format.\n`confd/vars/main.yaml`: a file with all variables to be substituted in templates.\n\n#### How can I add a new template\n\n1. Create and place the template file to `confd/templates/` directory.\n2. Create and place the template description in `confd/conf.d/` directory.\n3. Change vars in `confd/main.yaml` if needed.\n4. Execute: `make update-props-dryrun` for verifying that the templates can be processed.\n5. Execute: `make update-props` for applying the templates.\n\n#### How to use a stand-alone OrientDB server?\n\nLet's suppose, you have an OrientDB server, and you want to use it instead of the dockerized OrientDB.\nYou can add OrientDB endpoints to `confd/vars/main.yaml` and create properties template for services which use OrientDB:\n\n`confd/conf.d/base-storm-topology.topologies.toml`:\n```toml\n[template]\nsrc = \"base-storm-topology/topology.properties.tmpl\"\ndest = \"src-java/base-topology/base-storm-topology/src/release/resources/topology.properties\"\nkeys = [ \"/\" ]\nmode = \"0644\"\n```\n\n`confd/vars/main.yaml`:\n```yaml\nkilda_orientdb_hosts: \"odb1.pendev,odb2.pendev,odb3.pendev\"\nkilda_orientdb_hosts_single: \"odb1.pendev\"\nkilda_orientdb_user: \"kilda\"\nkilda_orientdb_password: \"kilda\"\n```\n\n`confd/templates/base-storm-topology/topology.properties.tmpl`\n```\n...\n{{if not (exists \"/single_orientdb\")}}\norientdb.url=remote:{{ getv \"/kilda_orientdb_hosts\" }}/{{ getv \"/kilda_orientdb_database\" }}\n{{else}}\norientdb.url=remote:{{ getv \"/kilda_orientdb_hosts_single\" }}/{{ getv \"/kilda_orientdb_database\" }}\n{{end}}\norientdb.user = {{ getv \"/kilda_orientdb_user\" }}\norientdb.password = {{ getv \"/kilda_orientdb_password\" }}\n...\n```\n\nIn this example, we will generate the file ```src-java/base-topology/base-storm-topology/src/release/resources/topology.properties```\nfrom the template ```confd/templates/base-storm-topology/topology.properties.tmpl```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelstra%2Fopen-kilda","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftelstra%2Fopen-kilda","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftelstra%2Fopen-kilda/lists"}