Netris Controller installation on a generic Linux host

Linux Host requirements

  • RAM: 8 GB

  • CPU: 4 Cores

  • Disk: 50GB

  • OS: Linux 64-bit

Note

K3s is expected to work on most modern Linux systems.

Some OSs have specific requirements:

  • If you are using Raspbian Buster, follow these steps to switch to legacy iptables.

  • If you are using Alpine Linux, follow these steps for additional setup.

  • If you are using (Red Hat/CentOS) Enterprise Linux, follow these steps for additional setup.

Installation

The following command will install the Netris Controller on your Linux server:

curl -sfL https://get.netris.io | sh -

Once installed, you will be able to log in to Netris Controller using your host’s IP address.

Note

The installation script does the following:

Installation with the specific host name

In order to set the specific ingress host name to the Netris Controller, use the --ctl-hostname installation argument:

curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com

A self-signed SSL certificate will be generated from that host name.

Installation with the Let’s Encrypt SSL

The installation script supports Let’s Encrypt SSL generation out-of-box. To instruct the installation script to do that use --ctl-ssl-issuer argument.

Note

The argument --ctl-ssl-issuer is passing cert-manager.io/cluster-issuer value to the ingress resource of the Netris Controller. The installation script can create two types of ClusterIssuer resource: selfsigned or letsencrypt, where selfsigned is just Cert-Manager self-signed SSL and the letsencrypt is the ACME issuer with HTTP01 challenge validation.
If the --ctl-ssl-issuer argument is not set, the installation script will proceed with selfsigned ClusterIssuer type.

Run the following command to install Netris Controller and use letsencrypt ClusterIssuer for SSL generation:

curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com --ctl-ssl-issuer letsencrypt

Note

To successfully validate and complete Let’s Encrypt SSL generation, a valid A/CNAME record for the domain/subdomain name should exist prior, and that name must be accessible from the Internet.

Installation with the Custom SSL Issuer

The HTTP01 challenge validation is the simplest way of issuing the Let’s Encrypt SSL, but it does not work when the host behind the FQDN is not accessible from the public internet. The common approach of validating and completing Let’s Encrypt SSL generation for private deployments is DNS01 challenge validation. If the DNS01 does not work for you either, Cert-Manager supports a number of certificate issuers, get familiar with all types of issuers here.

In order to install Netris Controller with the custom SSL issuer, you need to run installation script with the specified host name:

curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com

Once the installation is complete, create a yaml file with the ClusterIssuer resource, suitable for your requirements, and apply it:

kubectl apply -f my-cluster-issuer.yaml

Then rerun the installation script with the --ctl-ssl-issuer argument:

curl -sfL https://get.netris.io | sh -s -- --ctl-ssl-issuer <Your ClusterIssuer resource name>

Upgrading

To upgrade the Netris Controller to the latest version simply run the script:

curl -sfL https://get.netris.io | sh -

If a newer version of Netris Controller is available, it will be updated in a few minutes.

Uninstalling

To uninstall Netris Controller and K3s from a server node, run:

/usr/local/bin/k3s-uninstall.sh

Backup and Restore

Netris Controller stores all critical data in MariaDB. It’s highly recommended to create a cronjob with mysqldump.

Backup

To take database snapshot run the following command:

kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysqldump -u $MARIADB_USER -p${MARIADB_PASSWORD} $MARIADB_DATABASE' > db-snapshot-$(date +%Y-%m-%d-%H-%M-%S).sql

After command execution, you can find db-snapshot-YYYY-MM-DD-HH-MM-SS.sql file in the current working directory.

Backup the Secret Key

Netris Controller generates a unique secret key at the first installation. If you’re moving or reinstalling your controller, it makes sense to take note of the secret key for restoring purpose in the future. Overwise, you have to reinitiate all devices connected to the controller.

kubectl -n netris-controller get secret netris-controller-grpc-secret -o jsonpath='{.data.secret-key}{"\n"}'

Restore

In order to restore DB from a database snapshot, follow these steps:

  1. Drop the current database by running the following command:

kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "DROP DATABASE $MARIADB_DATABASE"'

  1. Create a new database:

kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "CREATE DATABASE $MARIADB_DATABASE"'

  1. Copy snapshot file to the MariaDB container:

kubectl -n netris-controller cp db-snapshot.sql netris-controller-mariadb-0:/opt/db-snapshot.sql

  1. Run the restore command:

kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} $MARIADB_DATABASE < /opt/db-snapshot.sql'

Note

In this example the snapshot file name is db-snapshot.sql and it’s located in the current working directory

Restore the Secret Key

If you want to restore the controller secret key too (you might want to do that if you’re reinstalling or moving the controller to the other place), follow these steps:

  1. Set OLD_SECRET environment variable (the secret key taken from the old controller):

export OLD_SECRET=<Your old secret key>

example: export OLD_SECRET=VUdodFFSakJCU2lFVVA4T1c0cnpuUmdiMkQxem85Y2dnS3pkajlNSg==

  1. Update the secret key of the new controller:

kubectl -n netris-controller patch secret netris-controller-grpc-secret --type='json' -p='[{"op" : "replace" ,"path" : "/data/secret-key" ,"value" : "'$OLD_SECRET'"}]'

  1. Restart Netris Controller’s all microservices

kubectl -n netris-controller rollout restart deployments