https://gitlab.com/noris-network/koris/badges/dev/pipeline.svg https://gitlab.com/noris-network/koris/badges/dev/coverage.svg https://img.shields.io/badge/docs-passed-green.svg

Launch kubernetes clusters on OpenStack.


  • Get your kubernetes cluster on noris.cloud in about 5 minutes.
  • Complete provisioning of openstack infrastructure via the installer.
  • Kubernetes 1.14.X supported
  • You can use a pre-built binary installer or the Python sources
  • Resize your cluster as needed (add or remove masters and worker nodes)
  • Multiple plugins already installed (you can add more easily by deploying operators):
    • nginx-ingress controller
    • audit logging
    • cloud provider integration (create volumes and loadbalancers from within kubernetes)
    • metrics API enabled
  • Support for two CNI plugins out of the box
    • Calico (default)
    • Flannel
  • (Experimental) Single-Sign-On with:
    • LDAP
    • Gitlab
    • SAML (beta feature)


If you just want to use koris to create a cluster follow the steps below, for more details refer to Installation and Usage.

If you want to develop, please refer to Contributing.

The complete compiled documentation of koris can be found here.


Install Python 3.6:

sudo apt install python3-pip python3.6-venv

Follow the instructions to install kubectl .


  1. Create a local virtual environment for koris (using your favorite tool). For example the standard Python has a simple virtual environment tool:

    $ mkdir koris
    $ cd koris && python3 -m venv koris-env
  2. Activate the environment with:

    $ source koris-env/bin/activate

    You can leave your virtual environment by typing deactivate.

  3. To install the latest realese (for installation from source see Installation), grab it with the following command (replace <LATEST_TAG> with the latest version tag, for example 1.2.0).

    $ pip install -e git+git@gitlab.com:noris-network/koris.git@v<LATEST_TAG>#egg=koris
Koris is now installed in ./koris-env/bin and usable with an activated virtual environment.


If the machine you would like to install koris on does not have access to ``gitlab.com`noris-network download the source distribution on a machine that has, and copy it over to your desired machine:

curl https://gitlab.com/noris-network/koris/-/archive/v<LATEST_TAG>/koris-v<LATEST_TAG>.zip
scp koris-v<LATEST_TAG>.zip remotehost:~/

Repeat the steps to create and activate a virtual environment, then install the package via pip:

$ pip install koris-v<LATEST_TAG>.zip


  1. Source your OpenStack RC file and enter your password:

    $ source ~/path/to/your/openstack-openrc.sh
    Please enter your OpenStack Password for project <PROJECT> as user <USER>\:
  2. Koris is executed with koris <subcommand>. You can get a list of subcommands with -h or --help.

    $ koris -h
    usage: koris [-h] [--version]
                [--verbosity {0,1,2,3,4,quiet,error,warning,info,debug}]
                {add,apply,delete,destroy} ...
    Before any koris command can be run, an OpenStack RC file has to be sourced in
    the shell. See online documentation for more information.
    positional arguments:
        add                 Add a worker node or master node to the cluster. Add a
                            node or a master to the current active context in your
                            KUBECONFIG. You can specify any other configuration
                            file by overriding the KUBECONFIG environment
                            variable. If you specify a name and IP address the
                            program will only try to join it to the cluster
                            without trying to create the host in the cloud first.
        apply               Bootstrap a Kubernetes cluster
        delete              Delete a node from the cluster, or the complete
        destroy             Delete the complete cluster stack
    optional arguments:
      -h, --help            show this help message and exit
      --version             show version and exit
      --verbosity {0,1,2,3,4,quiet,error,warning,info,debug}, -v {0,1,2,3,4,quiet,error,warning,info,debug}
                            set the verbosity level (0 = quiet, 1 = error, 2 =
                            warning, 3 = info, 4 = debug) (default: 3)
  3. To get information about each subcommand type:

    $ koris destroy -h
    usage: koris destroy [-h] [--force] config
    positional arguments:
    optional arguments:
      -h, --help   show this help message and exit
      --force, -f
  4. Koris creates the proper security groups needed for a working cluster. However, if you are a building a cluster for a customer which has cloud-connect and needs BGP communication, add correct security rules in OpenStack:

    neutron security-group-rule-create --protocol tcp --port-range-min 179 --port-range-max 179 --remote-ip-prefix <CUSTOMER_CIDR> --direction egress <CLUSTER-SEC-GROUP>
    neutron security-group-rule-create --protocol tcp --port-range-min 179 --port-range-max 179 --direction ingress --remote-ip-prefix <CUSTOMER_CIDR> <CLUSTER-SEC-GROUP>
  5. Create a configuration file. For more information check the example-config.yml) or refer to the section Deploy your cluster.

  6. Run koris apply with your configuration file as the argument:

    $ koris apply your-config.yaml
  7. A kubectl configuration file will be created into your project root with the name of <clustername>-admin.conf. You can either pass that with each execution via kubectl --kubeconfig=/path/to/koris/your-admin.conf or by exporting it as an environment variable:

    $ export KUBECONFIG=/path/to/koris/your-admin.conf
    $ kubectl get nodes


This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.