From aa6d9ed85babd0002d570050df936b60ed77b6dc Mon Sep 17 00:00:00 2001 From: Andrey Khomyakov Date: Thu, 12 Feb 2026 14:10:49 -0800 Subject: [PATCH] Clean up controller installation docs --- controller-k3s-air-gap.rst | 89 --- controller-k3s-installation.rst | 220 -------- controller-k8s-quickstart.rst | 41 -- controller-vm-installation.rst | 191 ------- index.rst | 5 +- .../Controller-local-repository.rst | 6 +- .../controller-k3s-air-gap-ha.rst | 6 +- .../controller-k8s-installation.rst | 0 .../installation.rst | 44 +- installing-netris-controller.rst | 37 -- monitoring-observability/index.rst | 10 - tutorials/index.rst | 9 - tutorials/installing-netris-controller.rst | 85 --- tutorials/netris-controller-installation.rst | 88 --- tutorials/using-l4-load-balancer.rst | 13 - .../vpc-gateways-with-managed-fabric.rst | 2 +- ...grading-netris.rst => upgrading-netris.rst | 510 +++++++++--------- 17 files changed, 285 insertions(+), 1071 deletions(-) delete mode 100644 controller-k3s-air-gap.rst delete mode 100644 controller-k3s-installation.rst delete mode 100644 controller-k8s-quickstart.rst delete mode 100644 controller-vm-installation.rst rename Controller-local-repository.rst => installation/Controller-local-repository.rst (96%) rename controller-k3s-air-gap-ha.rst => installation/controller-k3s-air-gap-ha.rst (99%) rename controller-k8s-installation.rst => installation/controller-k8s-installation.rst (100%) rename installation.rst => installation/installation.rst (85%) delete mode 100644 installing-netris-controller.rst delete mode 100644 monitoring-observability/index.rst delete mode 100644 tutorials/index.rst delete mode 100644 tutorials/installing-netris-controller.rst delete mode 100644 tutorials/netris-controller-installation.rst delete mode 100644 tutorials/using-l4-load-balancer.rst rename tutorials/upgrading-netris.rst => upgrading-netris.rst (97%) diff --git a/controller-k3s-air-gap.rst b/controller-k3s-air-gap.rst deleted file mode 100644 index 33769557..00000000 --- a/controller-k3s-air-gap.rst +++ /dev/null @@ -1,89 +0,0 @@ -.. meta:: - :description: Installing Netris Controller in Air-Gapped Environments - -Installing Netris Controller in Air-Gapped Environments -======================================================= - -Why Air-Gapped Installation? ----------------------------- -Air-gapped environments are isolated from the public internet to ensure heightened security, compliance, or operational reliability. Many organizations operate in such environments to safeguard their infrastructure from external threats and maintain strict control over their data. - -Netris provides a way to install the Netris Controller in air-gapped environments to cater to these requirements, ensuring seamless deployment without relying on internet access. - - -How to Install the Netris Controller -------------------------------------- - -Prerequisites -^^^^^^^^^^^^^ -- A **tar.gz** installation file provided by Netris. -- An Ubuntu 24.04 server designated as the Netris Controller. -- Sufficient permissions to execute installation scripts and perform necessary configurations. - -Steps to Install -^^^^^^^^^^^^^^^^ - -1. **Obtain the Installation File** - - Contact Netris to obtain the required installation file (``netris-controller-v4.x.x.tar.gz``). - -2. **Transfer the File to the Server** - - Use a secure file transfer method (e.g., SCP or USB) to copy the tar.gz file to the target Ubuntu 24.04 server. - -3. **Extract the Tarball** - - Run the following command to extract the contents of the tarball: - - .. code-block:: shell-session - - tar -xzvf netris-controller-v4.x.x.tar.gz - -4. **Navigate to the Installation Directory** - - Move into the extracted directory: - - .. code-block:: shell-session - - cd netris-controller-v4.x.x - -5. **Run the Installation Script** - - Execute the installation script with the ``ctl-hostname`` argument, specifying the desired hostname for your controller. For example: - - .. code-block:: shell-session - - ./install.sh --ctl-hostname netris.example.com - -6. **Verify Installation** - - Once the script is complete, follow any on-screen instructions to verify the installation. The Netris Controller should now be operational in your air-gapped environment. - - -After Installation ------------------- - -The air-gapped Netris Controller will also include a local repository/registry. This repository provides all the necessary packages and images for installing various types of Netris agents. - -The script will output the local repository URL. Copy and paste this URL of the Local repository into the Netris Controller Web UI under **Settings** section (as shown in the screenshots below). - -.. image:: images/Global-settings-edit.png - :align: center - -.. image:: images/Global-settings-save.png - :align: center - - -How to consume local repository -------------------------------- - -Once the local repository function is enabled in the Netris Controller Settings, the Netris agent installation oneliner will automatically point to the local repository (as shown in the screenshots below). - - -.. image:: images/oneliner-from-local-repo.png - :align: center - - ---- - -For any issues or additional assistance, please contact Netris Support. diff --git a/controller-k3s-installation.rst b/controller-k3s-installation.rst deleted file mode 100644 index 2aec4f82..00000000 --- a/controller-k3s-installation.rst +++ /dev/null @@ -1,220 +0,0 @@ -.. meta:: - :description: Controller Generic Linux Host - -.. _ctl-k3s-def: - -###################################################### -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: - -.. code-block:: shell-session - - 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: - - * Installs `k3s `_ - * Installs the `Cert-Manager Helm chart `_ - * Installs the `Netris Controller Helm chart `_ - - - -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: - -.. code-block:: shell-session - - 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: - -.. code-block:: shell-session - - 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: - -.. code-block:: shell-session - - 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: - -.. code-block:: shell-session - - kubectl apply -f my-cluster-issuer.yaml - -Then rerun the installation script with the ``--ctl-ssl-issuer`` argument: - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh -s -- --ctl-ssl-issuer - - -Upgrading -========= - -To upgrade the Netris Controller to the latest version simply run the script: - -.. code-block:: shell-session - - 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: - -.. code-block:: shell-session - - /usr/local/bin/k3s-uninstall.sh - - -.. _ctl-backup-restore: - -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: - -.. code-block:: shell-session - - 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. - -.. _ctl-secret-key-backup: - - - -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. - -.. code-block:: shell-session - - 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: - -.. code-block:: shell-session - - kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "DROP DATABASE $MARIADB_DATABASE"' - -2. Create a new database: - -.. code-block:: shell-session - - kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "CREATE DATABASE $MARIADB_DATABASE"' - -3. Copy snapshot file to the MariaDB container: - -.. code-block:: shell-session - - kubectl -n netris-controller cp db-snapshot.sql netris-controller-mariadb-0:/opt/db-snapshot.sql - -4. Run the restore command: - -.. code-block:: shell-session - - 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 :ref:`the old controller`): - -.. code-block:: shell-session - - export OLD_SECRET= - -example: ``export OLD_SECRET=VUdodFFSakJCU2lFVVA4T1c0cnpuUmdiMkQxem85Y2dnS3pkajlNSg==`` - -2. Update the secret key of the new controller: - -.. code-block:: shell-session - - kubectl -n netris-controller patch secret netris-controller-grpc-secret --type='json' -p='[{"op" : "replace" ,"path" : "/data/secret-key" ,"value" : "'$OLD_SECRET'"}]' - -3. Restart Netris Controller's all microservices - -.. code-block:: shell-session - - kubectl -n netris-controller rollout restart deployments diff --git a/controller-k8s-quickstart.rst b/controller-k8s-quickstart.rst deleted file mode 100644 index 09c3eeea..00000000 --- a/controller-k8s-quickstart.rst +++ /dev/null @@ -1,41 +0,0 @@ -.. meta:: - :description: Controller Quickstart - -*********************** -Quickstart Installation -*********************** - -Netris offers a simplified deployment model for users who want to quickly install the Netris Controller in the shortest amount of time. - -**This installation process is streamlined for Linux servers that do not already have Kubernetes running.** The install does the following: - -* Installs `k3s `_ -* Installs the `Netris Controller Helm chart `_ - -If you wish to install the controller on an existing Kubernetes cluster, follow `these instructions `_ instead of this Quickstart. - -Quickstart Process ------------------- - -1. Install the Netris Controller w/ k3s by running the following command on your Linux server: - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh - - -2. When the installation completes, you will be provided with the login for the web UI. Login with the provided credentials. - -3. Navigate in the UI to Net→IPAM and add a new subnet that contains the desired management IP addresses you wish to use for your SoftGates and switches. - - For example, if you are planning on using 192.168.1.100 as the IP address of your Ubuntu server, then create a subnet in Netris UI for 192.168.1.0/24. - - Detailed configuration documentation is available here: `Netris IPAM `_. - -4. Navigate in the UI to **Topology** -5. Click the **Add** in the upper right -6. Fill out the fields for the SoftGate you wish to add -7. Select the proper **Management IP address** from the subnet selector -8. Once the SoftGate is created in the Topology, **right-click** on the SoftGate and select the **Install Agent** option -9. Copy the agent install command to your clipboard and run the command on the Ubuntu server you are using as your SoftGate -10. Congratulations. The SoftGate should now be connected to your controller. - diff --git a/controller-vm-installation.rst b/controller-vm-installation.rst deleted file mode 100644 index 73b989dd..00000000 --- a/controller-vm-installation.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. meta:: - :description: Controller Virtual Machine Installation - -**************************** -Virtual Machine Installation -**************************** - -Requirements -============ - -Minimal system requirements for the VM: - -* CPU - 4 Core -* RAM - 4 Gb -* Disk - 100Gb -* Network - 1 virtual NIC - -Recommended system requirements for the VM: - -* CPU - 8 Core -* RAM - 16 Gb -* Disk - 100Gb -* Network - 1 virtual NIC - -KVM Hypervisor Installation -=========================== -If KVM is not already installed, install Qemu/KVM on the host machine (example provided for Ubuntu Linux 18.04) - -.. code-block:: shell-session - - sudo apt-get install virt-manager - -VM Controller Installation -========================== - -1. Download the Netris Controller image. (contact Netris support for repository access permissions). - -.. code-block:: shell-session - - cd /var/lib/libvirt/images - - sudo wget http://img.netris.io/netris-controller3.qcow2 - -2. Download VM definition file. - -.. code-block:: shell-session - - cd /etc/libvirt/qemu - - sudo wget http://img.netris.io/netris-controller3.xml - -3. Define the KVM virtual machine - -.. code-block:: shell-session - - sudo virsh define netris-controller3.xml - -.. note:: - - Netris Controller virtual NIC will bind to the “br-mgmt” interface on the KVM host machine. See below for the network interface configuration example. - -Example: Network configuration on host (hypervisor) machine. - -.. note:: - - replace , and - with the correct NIC and IP for your host machine. - -.. code-block:: shell-session - - sudo vim /etc/network/interfaces - -.. code-block:: shell-session - - #Physical NIC connected to the management network - auto - iface inet static - address 0.0.0.0/0 - - #bridge interface - auto br-mgmt - iface br-mgmt inet static - address - gateway - bridge-ports - - source /etc/network/interfaces.d/* - -.. code-block:: shell-session - - sudo ifreload -a - -4. Set the virtual machine to autostart and start it. - -.. code-block:: shell-session - - sudo virsh autostart netris-controller - -.. code-block:: shell-session - - sudo virsh start netris-controller - -Accessing the Netris Controller -=============================== -By default, Netris Controller will obtain an IP address from a **DHCP** server. - -Below steps describe how to configure a **Static IP** address for the Netris Controller. - -1. Connecting to the VM console. - -default credentials. **login**: ``netris`` **password**: ``newNet0ps`` - -.. code-block:: shell-session - - sudo virsh console netris-controller - -.. note:: - - Do not forget to change the default password (using passwd command). - -2. Setting a static IP address. - -Edit network configuration file. - -.. code-block:: shell-session - - sudo vim /etc/network/interfaces - -Example: IP configuration file. - -.. code-block:: shell-session - - # The loopback network interface - auto lo - iface lo inet loopback - - - # The primary network interface - auto eth0 - iface eth0 inet static - address - gateway - dns-nameserver - - source /etc/network/interfaces.d/* - -Reload the network config. - -.. code-block:: shell-session - - sudo ifreload -a - -.. note:: - - Make sure Netris Controller has Internet access. - -3. Reboot the controller - -.. code-block:: shell-session - - sudo reboot - -After reboot, the Netris Controller GUI should be accessible using a browser. Use ``netris/newNet0ps`` credentials. - -.. image:: images/credentials.png - :align: center - :class: with-shadow - :alt: Netris Credentials - -.. note::Don’t forget to change the default password by clicking your login name in the top right corner and then clicking “Change Password”. - -Replacing the SSL certificate -============================= - -1. Replace the below file with your SSL certificate file. - -.. code-block:: shell-session - - /etc/nginx/ssl/controller.cert.pem; - -2. Replace the below file with your SSL private key. - -.. code-block:: shell-session - - /etc/nginx/ssl/controller.key.pem; - -3. Restart Nginx service. - -.. code-block:: shell-session - - systemctl restart nginx.service diff --git a/index.rst b/index.rst index b9774d25..8cbb7c31 100644 --- a/index.rst +++ b/index.rst @@ -30,7 +30,7 @@ You are welcome to join our community Slack channel (see button at the top) to g :maxdepth: 2 :caption: Detailed Installation - installation + installation/installation switch-agent-installation netris-softgate-HS @@ -44,7 +44,7 @@ You are welcome to join our community Slack channel (see button at the top) to g lag visibility maintenance-mode - tutorials/upgrading-netris + upgrading-netris .. toctree:: :maxdepth: 4 @@ -80,7 +80,6 @@ You are welcome to join our community Slack channel (see button at the top) to g ai-netris-host-networking vpc - tutorials/index tutorials/vpc-gateways-with-managed-fabric.rst .. toctree:: diff --git a/Controller-local-repository.rst b/installation/Controller-local-repository.rst similarity index 96% rename from Controller-local-repository.rst rename to installation/Controller-local-repository.rst index 5b5ebdd3..e2cf23e2 100644 --- a/Controller-local-repository.rst +++ b/installation/Controller-local-repository.rst @@ -48,10 +48,10 @@ The script will output the local repository URL and URL to ISOs directory. Copy Additionally, it provides the host system path, which you may want to use to host your custom ISOs for your servers, softgates, or switches. -.. image:: images/Global-settings-edit.png +.. image:: ../images/Global-settings-edit.png :align: center -.. image:: images/Global-settings-save.png +.. image:: ../images/Global-settings-save.png :align: center @@ -65,7 +65,7 @@ Once the local repository function is enabled in the Netris Controller Settings, The local repository includes all the necessary scripts and dependency packages for the Netris NVUE (Cumulus 5.9 and higher) and Netris SoftGate HS (Ubuntu 24.04) agents. -.. image:: images/oneliner-from-local-repo.png +.. image:: ../images/oneliner-from-local-repo.png :align: center diff --git a/controller-k3s-air-gap-ha.rst b/installation/controller-k3s-air-gap-ha.rst similarity index 99% rename from controller-k3s-air-gap-ha.rst rename to installation/controller-k3s-air-gap-ha.rst index 88776772..076cdd48 100644 --- a/controller-k3s-air-gap-ha.rst +++ b/installation/controller-k3s-air-gap-ha.rst @@ -587,10 +587,10 @@ The air-gapped Netris Controller also includes a local repository/registry. This Enable the Local repository in the Netris Controller Web UI under **Settings** section (as shown in the screenshots below). -.. image:: images/global-setting-local-repo.png +.. image:: ../images/global-setting-local-repo.png :align: center -.. image:: images/global-setting-local-repo-save.png +.. image:: ../images/global-setting-local-repo-save.png :align: center @@ -600,7 +600,7 @@ How to consume local repository Once the local repository function is enabled in the Netris Controller Settings, the Netris agent installation oneliner will automatically point to the local repository (as shown in the screenshots below). -.. image:: images/one-liner-with-local-repo.png +.. image:: ../images/one-liner-with-local-repo.png :align: center diff --git a/controller-k8s-installation.rst b/installation/controller-k8s-installation.rst similarity index 100% rename from controller-k8s-installation.rst rename to installation/controller-k8s-installation.rst diff --git a/installation.rst b/installation/installation.rst similarity index 85% rename from installation.rst rename to installation/installation.rst index 80102825..e960ad0e 100644 --- a/installation.rst +++ b/installation/installation.rst @@ -1,23 +1,21 @@ -.. meta:: - :description: Controller Installation - -======================= -Controller Installation -======================= - -Netris Controller can be installed as a VM or deployed as a Kubernetes application. Both options provide the same functionality. - -.. note:: - - Select ONE installation option below. - - -.. toctree:: - :maxdepth: 2 - :caption: Controller Installation - - controller-k3s-installation - controller-k8s-installation - Controller-local-repository - controller-k3s-air-gap - controller-k3s-air-gap-ha +.. meta:: + :description: Controller Installation + +======================= +Controller Installation +======================= + +Netris Controller can be installed as a VM or deployed as a Kubernetes application. Both options provide the same functionality. + +.. note:: + + Select ONE installation option below. + + +.. toctree:: + :maxdepth: 2 + :caption: Controller Installation + + controller-k3s-air-gap-ha + controller-k8s-installation + Controller-local-repository diff --git a/installing-netris-controller.rst b/installing-netris-controller.rst deleted file mode 100644 index cc7db172..00000000 --- a/installing-netris-controller.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. meta:: - :description: Installing a Netris Controller - -============================== -Installing a Netris Controller -============================== - -You can install the Netris controller almost on any 64-bit Linux host. Netris Controller may or may not be on the same network as the managed network nodes are. In fact if there are multiple Netris managed deployments there’s no need for an individual controller for each deployment. - -It doesn't matter where to host the Netris controller. What matters is that the Netris controller needs to be accessible over the Internet. So you can access the console, and nodes that are going to be managed by Netris need to have access to the Netris controller through their management network interface. - -Linux Host requirements - -* RAM: 8 GB -* CPU: 4 Cores -* Disk: 50GB -* OS: Linux 64-bit - -In this example I am running my Netris controller on an AWS hosted virtual machine (EC2) which has got a public IP address 54.219.211.71. While it is OK for users and nodes to refer to the Netris Controller through an IP address, I like using a DNS record (this way it will be easier to potentially move Netris Controller somewhere with a different IP address). - -I'm using Cloudflare to create this “example-netris-controller.netris.dev” DNS record to point to the public IP address of my EC2 : 54.219.211.71. - -.. image:: images/cloudflare-dns-record.png - :align: center - -Ensure that newly created domain name indeed resolves into the right IP address of the machine that you are going to install the Netris Controller. - -To install Netris Controller on a freshly installed Linux you only need to run below one-liner command. Netris Controller installer will stand up a K3S cluster and then will deploy Netris Controller on top of it using Helm Chart. The “--ctl-hostname ” will instruct the installer to generate a Let’s Encrypt SSL certificate for the provided domain name. That’s why it is important to create the DNS record before this step. - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com - -Once installation process is finished you will be able to access your newly installed Netris Controller web consonle using netris/newNet0ps credentials. - -Please immediately change the default password to something strong in Setting → My Account → Change Password. -You can also use Settings → Login whitelist to restrict web console access to the controller. diff --git a/monitoring-observability/index.rst b/monitoring-observability/index.rst deleted file mode 100644 index 9be81b26..00000000 --- a/monitoring-observability/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -========================== -Monitoring & Observability -========================== - -.. toctree:: - :maxdepth: 2 - - topology-validation - netq - healthchecks diff --git a/tutorials/index.rst b/tutorials/index.rst deleted file mode 100644 index d4dacb90..00000000 --- a/tutorials/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -======================== -Netris Generic Tutorials -======================== - -.. toctree:: - :maxdepth: 2 - - installing-netris-controller - upgrading-netris diff --git a/tutorials/installing-netris-controller.rst b/tutorials/installing-netris-controller.rst deleted file mode 100644 index 6cb57398..00000000 --- a/tutorials/installing-netris-controller.rst +++ /dev/null @@ -1,85 +0,0 @@ -.. meta:: - :description: Installing a Netris Controller - -============================== -Installing a Netris Controller -============================== - -You can install the Netris controller almost on any 64-bit Linux host. Netris Controller may or may not be on the same network as the managed network nodes are. In fact if there are multiple Netris managed deployments there's no need for an individual controller for each deployment. - -It doesn't matter where you host the Netris controller. What matters is that 1) the Netris controller needs to be accessible over the Internet. 2) You can access the web console. 3) Nodes that are going to be managed by Netris have access to the Netris controller through their management network interface. - -**Linux host requirements** - -* RAM: 8 GB -* CPU: 4 Cores -* Disk: 50GB -* OS: Linux 64-bit - -**DNS record** - -In the example below, the host has a public IP address 54.183.23.201. While it is OK for users and nodes to refer to the Netris Controller through an IP address, it is recommended to use a DNS record (this way it will be easier to potentially move Netris Controller somewhere with a different IP address). - -Below is an example using Cloudflare DNS service (may use any DNS service). - -.. image:: images/dns-record-netrisctl.png - :align: center - -Ensure that newly created domain name resolves to the right IP address of the machine that will host the Netris Controller. - -.. code-block:: shell-session - - host netrisctl.netris.dev - netrisctl.netris.dev has address 54.183.23.201 - -**Install Netris Controller software and dependencies** - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com --ctl-ssl-issuer letsencrypt - -.. note:: - The Netris Controller installer will create a K3s cluster and then will deploy Netris Controller on top of it using Helm Chart. The “--ctl-ssl-issuer” will instruct the installer to generate a Let's Encrypt SSL certificate and the "--ctl-hostname" will hint for what domain name the certificate must be generated. That's why it is important to create the DNS record before this step. Detailed info here: `doc `_. - -.. image:: images/netris-controller-installed.png - :align: center - - -Once the installation process is finished, you will be able to access your newly installed Netris Controller web console using netris/newNet0ps credentials. - - -Security Matters ----------------- - -**Change the default password** - -Setting → My Account → Change Password - -.. image:: images/change-password.png - :align: center - -**Add new admin user** - -Accounts → Users → +Add - -.. image:: images/create-new-admin-user.png - :align: center - -**Restrict incoming TCP requests to the list below:** - -+----------+--------------------------------+ -| TCP Port | Service | -+==========+================================+ -| 22 | SSH | -+----------+--------------------------------+ -| 80 | HTTP | -+----------+--------------------------------+ -| 443 | Netris Web Console | -+----------+--------------------------------+ -| 2003 | Streaming Telemetry (Collectd) | -+----------+--------------------------------+ -| 3033 | Netris Monitoring (Telescope) | -+----------+--------------------------------+ -| 50051 | Netris Agent (gRPC) | -+----------+--------------------------------+ - diff --git a/tutorials/netris-controller-installation.rst b/tutorials/netris-controller-installation.rst deleted file mode 100644 index 1832a62b..00000000 --- a/tutorials/netris-controller-installation.rst +++ /dev/null @@ -1,88 +0,0 @@ -########################### -Install a Netris Controller -########################### - -Requirements and Installation steps ------------------------------------ - -You can install the Netris controller on almost any 64-bit Linux host. The Netris Controller may or may not be on the same network as the managed network nodes. Multi-region, multi-site deployments can use a single Netris Controller (+backup). - -The location of the Netris controller host is not critical. However, it is important that the Netris controller is accessible over the network. This is required for two reasons: 1) So you can access the web console, and 2) Nodes that will be managed by Netris need access to the Netris controller through their management network interface. - -If you choose to set up the Netris Controller within your Netris managed network, make sure to provide access to the controller using an out-of-band network connection. - - -**Linux host requirements** - -* RAM: 8 GB -* CPU: 4 Cores -* Disk: 50GB -* OS: Linux 64-bit - -**DNS record** - -In this example, the controller host has a public IP address 54.183.23.201. While it is acceptable for users and nodes to refer to the Netris Controller through an IP address, we recommend using a DNS record. This approach will make it easier to potentially move the Netris Controller to a different IP address in the future. - -Below is an example using the Cloudflare DNS service. The same concept applies to any DNS software or service. - -.. image:: images/dns-record-netrisctl.png - :align: center - -Ensure that the newly created domain name indeed resolves to the correct IP address of the machine on which you plan to install the Netris Controller. - -.. code-block:: shell-session - - host netrisctl.netris.dev - netrisctl.netris.dev has address 54.183.23.201 - -**Install Netris Controller software and dependencies** - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh -s -- --ctl-hostname netris.example.com --ctl-ssl-issuer letsencrypt - -.. note:: - The Netris Controller installer will create a K3s cluster and then will deploy Netris Controller on top of it using Helm Chart. The “--ctl-ssl-issuer” will instruct the installer to generate a Let's Encrypt SSL certificate and the "--ctl-hostname" will hint for what domain name the certificate must be generated. That's why it is important to create the DNS record before this step. Detailed info here: `doc `_. - -.. image:: images/netris-controller-installed.png - :align: center - - -Once the installation process is finished, you will be able to access your newly installed Netris Controller web console using netris/newNet0ps credentials. - - -Security Matters ----------------- - -**Change the default password** - -Setting → My Account → Change Password - -.. image:: images/change-password.png - :align: center - -**Add new admin user** - -Accounts → Users → +Add - -.. image:: images/create-new-admin-user.png - :align: center - -**Restrict incoming TCP requests to the list below:** - -+----------+--------------------------------+ -| TCP Port | Service | -+==========+================================+ -| 22 | SSH | -+----------+--------------------------------+ -| 80 | HTTP | -+----------+--------------------------------+ -| 443 | Netris Web Console | -+----------+--------------------------------+ -| 2003 | Streaming Telemetry (Collectd) | -+----------+--------------------------------+ -| 3033 | Netris Monitoring (Telescope) | -+----------+--------------------------------+ -| 50051 | Netris Agent (gRPC) | -+----------+--------------------------------+ - diff --git a/tutorials/using-l4-load-balancer.rst b/tutorials/using-l4-load-balancer.rst deleted file mode 100644 index 40b7477c..00000000 --- a/tutorials/using-l4-load-balancer.rst +++ /dev/null @@ -1,13 +0,0 @@ -################################################## -Using on-demand (elastic) L4 Load Balancer service -################################################## - -Services --> L4 Load Balancer is an on-demand (elastic) server load balancer. You can natively use it for Kubernetes, as well as for any TCP/UDP service. - -Please check our cloud-native tools section of the documentation portal for consuming Load Balancer using Kubernetes native method, Kubernetes CRDs, or Terraform. - -Meanwhile, below is a screenshot of simply requesting a Load Balancer service through the Netris web console. - -.. image:: /tutorials/images/netris-l4-load-balancer.png - :align: center - diff --git a/tutorials/vpc-gateways-with-managed-fabric.rst b/tutorials/vpc-gateways-with-managed-fabric.rst index 4cb4c853..c2d688ad 100644 --- a/tutorials/vpc-gateways-with-managed-fabric.rst +++ b/tutorials/vpc-gateways-with-managed-fabric.rst @@ -11,7 +11,7 @@ Getting Started with Switch-Fabric Manager & VPC .. toctree:: :maxdepth: 2 - netris-controller-installation + ../installation/controller-k3s-air-gap-ha .. toctree:: :maxdepth: 2 diff --git a/tutorials/upgrading-netris.rst b/upgrading-netris.rst similarity index 97% rename from tutorials/upgrading-netris.rst rename to upgrading-netris.rst index 1810961d..9f4621c0 100644 --- a/tutorials/upgrading-netris.rst +++ b/upgrading-netris.rst @@ -1,255 +1,255 @@ -.. meta:: - :description: Upgrading Netris - -.. raw:: html - - - - -.. role:: green - -.. role:: red - -******************** -Upgrade and Rollback -******************** - -Netris upgrade Procedure -======================== - -Backup current database ------------------------ - -Always have a backup, just in case anything hypothetically goes wrong. SSH to the host running the Netris Controller and execute below command. - -.. code-block:: shell-session - - kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysqldump -u $MARIADB_USER -p${MARIADB_PASSWORD} $MARIADB_DATABASE' > db-snapshot.sql - -Ensure that SQL file ``db-snapshot.sql`` is generated and present in the current directory. - -.. note:: - - An SQL dump is enough for this basic upgrade scenario, however detailed backup & restore procedure is described in :ref:`here`. - -Stop Netris Agents ------------------- - -Stop Netris agents on switches and SoftGate nodes. - -**For Switches:** - -SSH to the switch and run the following command: - -.. code-block:: shell-session - - sudo systemctl stop netris-sw - -**For SoftGate nodes:** - -SSH to the SoftGate and run the following command: - -.. code-block:: shell-session - - sudo systemctl stop netris-sg - -Make sure that all devices in the *Network → Inventory* section are ":red:`red`" with the "**check_agent**" status being "**Agent is unavailable**". - - -.. note:: - - A stopped Netris agent has no impact on production traffic through the device. - -.. _upgrade 3: - -Check your current version --------------------------- - -Before upgrading the Netris Controller, take a note of the "*Netris Version*" by navigating to *Settings → General* in the Controller web interface. The current version number may be used in case of the hypothetical need to perform a rollback procedure. - -.. image:: /tutorials/images/netris_version_example.png - :align: center - :alt: Netris Version Example - -Upgrade the Controller ----------------------- - -SSH to the Controller host and execute the below command. - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh - - -.. note:: - - This process can take up to 5 minutes - - -Afterwards, make sure that all pods have either "*Running*" or "*Completed*" status by executing the following command: - -.. code-block:: shell-session - - kubectl -n netris-controller get pods - - -The output is similar to this: - -.. code-block:: shell-session - - NAME READY STATUS RESTARTS AGE - svclb-netris-controller-haproxy-6tkgj 4/4 Running 0 38d - netris-controller-haproxy-bcb944b7c-qcbf8 1/1 Running 0 13d - netris-controller-squid-7f6fdc6cf9-7fdx8 1/1 Running 0 38d - svclb-netris-controller-squid-58rnp 1/1 Running 0 38d - netris-controller-graphite-0 1/1 Running 0 38d - netris-controller-mongodb-0 1/1 Running 0 38d - netris-controller-redis-master-0 1/1 Running 0 38d - netris-controller-smtp-76778cf85f-lw5v5 1/1 Running 0 10d - netris-controller-mariadb-0 1/1 Running 0 10d - netris-controller-web-session-generator-8b9dbbcd8-8snhd 1/1 Running 0 10d - netris-controller-telescope-notifier-647975848f-fs5dn 1/1 Running 0 10d - netris-controller-app-b9b8d8f8d-4ssqb 1/1 Running 0 10d - netris-controller-grpc-987669fb9-jjskp 1/1 Running 0 10d - netris-controller-telescope-777c98c5d9-mqwl6 1/1 Running 0 10d - helm-install-netris-controller-lqmq7 0/1 Completed 0 20h - - -.. warning:: - - If, after 5 minutes, you see pods with a status other than "*Running*" or "*Completed*", please reach out to us via `Slack `__. - -Check the upgraded version --------------------------- - -Make sure that the "*Netris Version*" reflects the version change by navigating to *Settings → General* in the Controller web interface. - -Upgrade Switches and SoftGate nodes ------------------------------------ - -Once you have verified that the Netris controller is up-to-date, it is time to update the switch and SoftGate agents. - -Upgrade the switch & SoftGate agents by copying the one-liner from the "*Install Agent*" option of the device’s 3-dot menu found under the *Network → Inventory* section and pasting it into appropriate devices by SSHing to the corresponding device. - -.. note:: - - These one-liners include a unique identifier for binding the physical device with the virtual object in the Controller. Please make sure - to copy/paste into the right devices. - - -.. image:: /tutorials/images/install_agent.gif - :align: center - :alt: Install Agent - -After all the agents have finished the upgrade process, make sure all devices in the *Network → Inventory* section have a ":green:`green`" status and the *Netris version* for each device reflects the version change. - -In the event the "**check_agent**" status is "**Agent is unavailable**" after the agent upgrade has finished, perform agent restart on the affected device(s). - -**For Switches:** - -SSH to the switch and run the following command: - -.. code-block:: shell-session - - sudo systemctl restart netris-sw - -**For SoftGate nodes:** - -SSH to the SoftGate and run the following command: - -.. code-block:: shell-session - - sudo systemctl restart netris-sg - -Rollback Procedure -================== - -A rollback procedure can be executed in the event the upgrade introduces any adverse impact on the production traffic. - -Stop Netris Agents ------------------- - -Stop all Netris agents on the devices managed by the controller (switch & SoftGate). - -**For Switches:** - -SSH to the switch and run the following command: - -.. code-block:: shell-session - - sudo systemctl stop netris-sw - -**For SoftGate nodes:** - -SSH to the SoftGate and run the following command: - -.. code-block:: shell-session - - sudo systemctl stop netris-sg - -Restore The Database --------------------- - -Restore the database from the previously taken snapshot. - -Drop the current database and create a new one by running the following command after SSHing to the Controller: - -.. code-block:: shell-session - - kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "DROP DATABASE $MARIADB_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"' - -While still connected to the Controller, copy the backup file from the controller host system to the MariaDB container and restore the database: - -.. code-block:: shell-session - - kubectl -n netris-controller cp db-snapshot.sql netris-controller-mariadb-0:/opt/db-snapshot.sql - 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' - -Downgrade the Controller Software ---------------------------------- - -Downgrade Netris Controller application with the following command. - -.. note:: - - For the version number, use the number collected from :ref:`step #3` during the upgrade procedure. - -Example: - -.. code-block:: shell-session - - curl -sfL https://get.netris.io | sh -s -- --ctl-version 3.0.10-031 - -Afterwards, verify that the version of the "*Netris Version*" reflects the downgraded version by navigating to *Settings → General* in the Netris Controller. - -Downgrade Netris Agent Software -------------------------------- - -Once you have verified that the Netris controller has been downgraded to the correct version, it is time to downgrade the switch and SoftGate agents. - -Install the appropriate version of switch & SoftGate agents by copying the one-liner from the "*Install Agent*" option of the device’s 3-dot menu found under the *Network → Inventory* section and pasting it into appropriate devices by SSHing to the corresponding device. - -.. note:: - - One-liners include a unique identifier for binding the physical device with the virtual object in the Controller. Please make sure to copy/paste into the right devices. - - -After all the switches and SoftGates have been successfully downgraded, make sure all the devices in the *Network → Inventory* section have a ":green:`green`" status and the *Netris version* for each device reflects the version downgrade. - -In case the "**check_agent**" status is "**Agent is unavailable**" after agent downgrade, perform agent restart. - -**For Switches:** - -SSH to the switch and run the following command: - -.. code-block:: shell-session - - sudo systemctl restart netris-sw - -**For SoftGate nodes:** - -SSH to the SoftGate and run the following command: - -.. code-block:: shell-session - - sudo systemctl restart netris-sg +.. meta:: + :description: Upgrading Netris + +.. raw:: html + + + + +.. role:: green + +.. role:: red + +******************** +Upgrade and Rollback +******************** + +Netris upgrade Procedure +======================== + +Backup current database +----------------------- + +Always have a backup, just in case anything hypothetically goes wrong. SSH to the host running the Netris Controller and execute below command. + +.. code-block:: shell-session + + kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysqldump -u $MARIADB_USER -p${MARIADB_PASSWORD} $MARIADB_DATABASE' > db-snapshot.sql + +Ensure that SQL file ``db-snapshot.sql`` is generated and present in the current directory. + +.. note:: + + An SQL dump is enough for this basic upgrade scenario, however detailed backup & restore procedure is described in :ref:`here`. + +Stop Netris Agents +------------------ + +Stop Netris agents on switches and SoftGate nodes. + +**For Switches:** + +SSH to the switch and run the following command: + +.. code-block:: shell-session + + sudo systemctl stop netris-sw + +**For SoftGate nodes:** + +SSH to the SoftGate and run the following command: + +.. code-block:: shell-session + + sudo systemctl stop netris-sg + +Make sure that all devices in the *Network → Inventory* section are ":red:`red`" with the "**check_agent**" status being "**Agent is unavailable**". + + +.. note:: + + A stopped Netris agent has no impact on production traffic through the device. + +.. _upgrade 3: + +Check your current version +-------------------------- + +Before upgrading the Netris Controller, take a note of the "*Netris Version*" by navigating to *Settings → General* in the Controller web interface. The current version number may be used in case of the hypothetical need to perform a rollback procedure. + +.. image:: /tutorials/images/netris_version_example.png + :align: center + :alt: Netris Version Example + +Upgrade the Controller +---------------------- + +SSH to the Controller host and execute the below command. + +.. code-block:: shell-session + + curl -sfL https://get.netris.io | sh - + +.. note:: + + This process can take up to 5 minutes + + +Afterwards, make sure that all pods have either "*Running*" or "*Completed*" status by executing the following command: + +.. code-block:: shell-session + + kubectl -n netris-controller get pods + + +The output is similar to this: + +.. code-block:: shell-session + + NAME READY STATUS RESTARTS AGE + svclb-netris-controller-haproxy-6tkgj 4/4 Running 0 38d + netris-controller-haproxy-bcb944b7c-qcbf8 1/1 Running 0 13d + netris-controller-squid-7f6fdc6cf9-7fdx8 1/1 Running 0 38d + svclb-netris-controller-squid-58rnp 1/1 Running 0 38d + netris-controller-graphite-0 1/1 Running 0 38d + netris-controller-mongodb-0 1/1 Running 0 38d + netris-controller-redis-master-0 1/1 Running 0 38d + netris-controller-smtp-76778cf85f-lw5v5 1/1 Running 0 10d + netris-controller-mariadb-0 1/1 Running 0 10d + netris-controller-web-session-generator-8b9dbbcd8-8snhd 1/1 Running 0 10d + netris-controller-telescope-notifier-647975848f-fs5dn 1/1 Running 0 10d + netris-controller-app-b9b8d8f8d-4ssqb 1/1 Running 0 10d + netris-controller-grpc-987669fb9-jjskp 1/1 Running 0 10d + netris-controller-telescope-777c98c5d9-mqwl6 1/1 Running 0 10d + helm-install-netris-controller-lqmq7 0/1 Completed 0 20h + + +.. warning:: + + If, after 5 minutes, you see pods with a status other than "*Running*" or "*Completed*", please reach out to us via `Slack `__. + +Check the upgraded version +-------------------------- + +Make sure that the "*Netris Version*" reflects the version change by navigating to *Settings → General* in the Controller web interface. + +Upgrade Switches and SoftGate nodes +----------------------------------- + +Once you have verified that the Netris controller is up-to-date, it is time to update the switch and SoftGate agents. + +Upgrade the switch & SoftGate agents by copying the one-liner from the "*Install Agent*" option of the device’s 3-dot menu found under the *Network → Inventory* section and pasting it into appropriate devices by SSHing to the corresponding device. + +.. note:: + + These one-liners include a unique identifier for binding the physical device with the virtual object in the Controller. Please make sure + to copy/paste into the right devices. + + +.. image:: /tutorials/images/install_agent.gif + :align: center + :alt: Install Agent + +After all the agents have finished the upgrade process, make sure all devices in the *Network → Inventory* section have a ":green:`green`" status and the *Netris version* for each device reflects the version change. + +In the event the "**check_agent**" status is "**Agent is unavailable**" after the agent upgrade has finished, perform agent restart on the affected device(s). + +**For Switches:** + +SSH to the switch and run the following command: + +.. code-block:: shell-session + + sudo systemctl restart netris-sw + +**For SoftGate nodes:** + +SSH to the SoftGate and run the following command: + +.. code-block:: shell-session + + sudo systemctl restart netris-sg + +Rollback Procedure +================== + +A rollback procedure can be executed in the event the upgrade introduces any adverse impact on the production traffic. + +Stop Netris Agents +------------------ + +Stop all Netris agents on the devices managed by the controller (switch & SoftGate). + +**For Switches:** + +SSH to the switch and run the following command: + +.. code-block:: shell-session + + sudo systemctl stop netris-sw + +**For SoftGate nodes:** + +SSH to the SoftGate and run the following command: + +.. code-block:: shell-session + + sudo systemctl stop netris-sg + +Restore The Database +-------------------- + +Restore the database from the previously taken snapshot. + +Drop the current database and create a new one by running the following command after SSHing to the Controller: + +.. code-block:: shell-session + + kubectl -n netris-controller exec -it netris-controller-mariadb-0 -- bash -c 'mysql -u root -p${MARIADB_ROOT_PASSWORD} -e "DROP DATABASE $MARIADB_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"' + +While still connected to the Controller, copy the backup file from the controller host system to the MariaDB container and restore the database: + +.. code-block:: shell-session + + kubectl -n netris-controller cp db-snapshot.sql netris-controller-mariadb-0:/opt/db-snapshot.sql + 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' + +Downgrade the Controller Software +--------------------------------- + +Downgrade Netris Controller application with the following command. + +.. note:: + + For the version number, use the number collected from :ref:`step #3` during the upgrade procedure. + +Example: + +.. code-block:: shell-session + + curl -sfL https://get.netris.io | sh -s -- --ctl-version 3.0.10-031 + +Afterwards, verify that the version of the "*Netris Version*" reflects the downgraded version by navigating to *Settings → General* in the Netris Controller. + +Downgrade Netris Agent Software +------------------------------- + +Once you have verified that the Netris controller has been downgraded to the correct version, it is time to downgrade the switch and SoftGate agents. + +Install the appropriate version of switch & SoftGate agents by copying the one-liner from the "*Install Agent*" option of the device’s 3-dot menu found under the *Network → Inventory* section and pasting it into appropriate devices by SSHing to the corresponding device. + +.. note:: + + One-liners include a unique identifier for binding the physical device with the virtual object in the Controller. Please make sure to copy/paste into the right devices. + + +After all the switches and SoftGates have been successfully downgraded, make sure all the devices in the *Network → Inventory* section have a ":green:`green`" status and the *Netris version* for each device reflects the version downgrade. + +In case the "**check_agent**" status is "**Agent is unavailable**" after agent downgrade, perform agent restart. + +**For Switches:** + +SSH to the switch and run the following command: + +.. code-block:: shell-session + + sudo systemctl restart netris-sw + +**For SoftGate nodes:** + +SSH to the SoftGate and run the following command: + +.. code-block:: shell-session + + sudo systemctl restart netris-sg