koris

Launch kubernetes clusters on OpenStack.

Features

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)

Quickstart

If you just want to use koris to create a cluster follow the steps below, for more details refer to :doc:`/installation` and :doc:`/usage`.

If you want to develop, please refer to :doc:`/contributing`.

The complete compiled documentation of koris can be found here.

Prerequisites

Install Python 3.6:

sudo apt install python3-pip python3.6-venv

Follow the instructions to install kubectl .

Installation

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
```
Activate the environment with:
```
$ source koris-env/bin/activate
```
You can leave your virtual environment by typing deactivate.
To install the latest realese (for installation from source see :doc:`/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.

Note

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

Usage

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>\:

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,apply,delete,destroy}
                        commands
    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
                        cluster.
    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)

To get information about each subcommand type:

$ koris destroy -h
usage: koris destroy [-h] [--force] config

positional arguments:
  config

optional arguments:
  -h, --help   show this help message and exit
  --force, -f

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>

Create a configuration file. For more information check the :download:`example-config.yml <../configs/example-config.yml>`) or refer to the section :ref:`usage_deploy_cluster`.
Run koris apply with your configuration file as the argument:
```
$ koris apply your-config.yaml
```
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
```

Credits

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