{"id":13836776,"url":"https://github.com/romana/core","last_synced_at":"2026-03-11T18:01:49.936Z","repository":{"id":57553055,"uuid":"43855674","full_name":"romana/core","owner":"romana","description":"Romana core components - Micro services written in Go.","archived":false,"fork":false,"pushed_at":"2018-04-16T09:45:28.000Z","size":3184,"stargazers_count":47,"open_issues_count":8,"forks_count":11,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-10-08T12:56:54.660Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/romana.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-08T01:45:35.000Z","updated_at":"2023-12-27T03:05:47.000Z","dependencies_parsed_at":"2022-09-26T16:31:10.181Z","dependency_job_id":null,"html_url":"https://github.com/romana/core","commit_stats":null,"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romana%2Fcore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romana%2Fcore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romana%2Fcore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/romana%2Fcore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/romana","download_url":"https://codeload.github.com/romana/core/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225647762,"owners_count":17502128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":"2024-08-04T15:00:54.285Z","updated_at":"2025-12-15T15:31:37.467Z","avatar_url":"https://github.com/romana.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# Romana Core Components\n\n[![License][License-Image]][License-Url] [![ReportCard][ReportCard-Image]][ReportCard-Url] [![GoDoc][GoDoc-Image]][GoDoc-Url]\n\nRomana is a new Software Defined Network (SDN) solution specifically designed\nfor the Cloud Native architectural style. The result of this focus is that\nRomana cloud networks are less expensive to build, easier to operate and\ndeliver higher performance than cloud networks built using alternative SDN\ndesigns.\n\n## What's in this repository\n\nThis repository contains the core components of the Romana system: A series of\ncooperating microservices written in Go. These services currently are:\n\n* *[Root](https://godoc.org/github.com/romana/core/root)*: Used as the starting point for services to discover each other. Also\nholds the configuration and serves relevant parts to the other services.\n* *[Tenant](https://godoc.org/github.com/romana/core/tenant)*: Manages tenants in the Romana system, interfaces with environments\nsuch as OpenStack, to map their tenants to Romana tenants.\n* *[Topology](https://godoc.org/github.com/romana/core/topology)*: Keeps track of the network topology in which we are deployed,\nknows about hosts, racks, spines, etc. This information is the used by the IPAM\nservice.\n* *[IPAM](https://godoc.org/github.com/romana/core/ipam)*: Generates and manages the IP addresses Romana assigns to network\nendpoints. Uses the topology service to be able to create topology aware\naddresses.\n* *[Agent](https://godoc.org/github.com/romana/core/agent)*: Lives on hosts and there performs actions on behalf of Romana, such\nas creating interfaces, setting routes or iptables rules.\n* *Auth*: Serves authentication tokens to tenants and services.\n* *[CLI](romana/README.md)*: Command Line Interface, which provides a reference romana API implmentation.\n\n## Getting started\n\n### Setup the Go development environment\n\nFirst, you need to setup a Go development environment. You can skip this if\nyou have a development environment already.\n\nOption A: Using binary distribution\n\n  * Download https://storage.googleapis.com/golang/go1.6.2.linux-amd64.tar.gz\n  * Unpack to /usr/local/go using following command:\n      ```\n      sudo tar -C /usr/local -xzf go1.6.2.linux-amd64.tar.gz\n      ```\n  * Update your profile to include:\n\n      ```\n      if [ -d /usr/local/go/bin ]; then\n        PATH=\"$PATH:/usr/local/go/bin\"\n        export GOPATH=\"$HOME/go\"\n      fi\n      ```\n\nOption B: Installing from source\n\n   * Follow the instructions here: https://golang.org/doc/install/source\n\n### Download, build and test the Romana core source code\n\nOnce you have your Go environment, follow these steps to download, build and\ntest the Romana core components:\n\n 1. Prepare a Go workspace.\n 2. Ensure your `PATH` is set to find your Go installation and binaries.\n 3. Ensure the `GOPATH` environment variable is set to point at the root of your\n    workspace.\n 5. Inside of the workspace directory run: `go get github.com/romana/core/...`\n    (the three dots at the end are part of the command).\n 6. You may see an error at this point, complaining about `No submodule mapping found in .gitmodules...`. This is due to a known bug in \"go get\". You can fix that by running `cd $GOPATH/src/github.com/romana/core ; git submodule update --init --recursive`.\n 7. If you wish to work with a specific branch or tag you need to run: `git checkout \u003cbranchname\u003e ; git submodule update --init --recursive`.\n 8. To run unit test for a specific Romana service run: `go test -v github.com/romana/core/\u003cname\u003e`, where `\u003cname\u003e` might be `agent`, `root`, `ipam`, `tenant`, `policy` or `topology`.\n\n### Update a running cluster with your modified code\n\nIf you use the 'romana-setup' script (provided in the https://github.com/romana/romana\nrepository), you get an OpenStack DevStack cluster running on some EC2\ninstances. It installs a standard version of the Romana core components.\n\nLet's say you have made changes to the core services and wish to test them on a running\ncluster. Here are the instructions describing how to replace the binaries on\nthe cluster and how to restart the services:\n\n 1. After successfully compiling your code locally, you will find the binaries\n    in `$GOPATH/bin` as `agent`, `root`, `ipam`, `tenant`, `policy`, `listener`, `romana` and `topology`.\n 2. Upload these binaries to every host in the cluster (every EC2 instance)\n    with this command: `rsync -e 'ssh -i \u003cabsolute path to your SSH key .ssh/ec2_id_rsa\u003e' -azu --existing \"$GOPATH/bin/\" ubuntu@\u003cec2-ip-address\u003e:~/romana/bin/`. This command needs to be executed for every EC2 instance in the cluster. Please remember to specify the correct IP address of the EC2 instance and the absolute path to your SSH key where indicated.\n 3. Log into the controller host and restart the services with these commands\n    (note that only root and agent need to be re-started manually, other\n    services will re-start on their own):\n\n    ```\n    for i in ipam tenant topology root agent policy listener; do\n        sudo service romana-$i stop\n    done\n    sudo service romana-root start\n    sudo service romana-agent start\n    ```\n\n 4. On the compute host(s), restart the services with these commands:\n\n    ```\n    sudo service romana-agent stop\n    sudo service romana-agent start\n    ```    \n\n### Previous Releases\nPrevious Releases can be found [here][github-release].\n\n[License-Url]: LICENSE\n[License-Image]: https://img.shields.io/badge/license-Apache--2-blue.svg\n[ReportCard-Url]: https://goreportcard.com/report/romana/core\n[ReportCard-Image]: https://goreportcard.com/badge/romana/core\n[github-release]: https://github.com/romana/core/releases/\n[GoDoc-Image]: https://godoc.org/github.com/romana/core?status.png\n[GoDoc-Url]: https://godoc.org/github.com/romana/core\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromana%2Fcore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fromana%2Fcore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fromana%2Fcore/lists"}