Skip to content
This repository has been archived by the owner on Jun 28, 2022. It is now read-only.

noris-network/koris

Repository files navigation

koris

WARNING: This code is no longer actively maintained!

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

  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 :doc:`/installation`), grab it with the following command (replace <LATEST_TAG> with the latest version tag, for example 1.2.0).

    $ pip install -e [email protected]: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

  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,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)
  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
  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 :download:`example-config.yml <../configs/example-config.yml>`) or refer to the section :ref:`usage_deploy_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

Credits

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