Merge branch '84-update-the-all-in-one-vm-guide' into 'master'

Resolve "Update the all-in-one VM guide"

Closes #84

See merge request !23

docs/tutorials-workshops/all-in-one-vm-image.md

+# All-in-one nmaas VM Image
+
+An all-in-one VirtualBox VM image with an installed single node K3s Kubernetes cluster and a deployment of nmaas is available for download. The goal of this image is to be able to get a local nmaas environment suitable for basic experiments as fast as possible. The installed software includes:
+
+- Single node K3s cluster
+- GitLab
+- nmaas
+- Stakater Reloader component for automatic restarting of containers that have mounted a ConfigMap that has changed
+- Ingress Nginx
+
+Most notably, the all-in-one VM image does not include a LoadBalancer implementation and it is up to the user to install and configure one. As a result, the deployment of some applications in the catalog that rely on `LoadBalancer` type Services will not work (e.g., PostgreSQL). Users are advised to install [MetalLB manually](https://metallb.universe.tf/installation/) and [configure](https://metallb.universe.tf/configuration/) it depending on their local environment and network setup. 
+
+The access details for the nmaas VM are:
+    - OS Login:
+        - Username: `nmaas`
+        - Password: `password`
+    - GitLab
+        - Username: `root`
+        - Password: `nmaasPassword123`
+    - nmaas
+        - Username: `admin`
+        - Password: `saamn`
+
+The VM image is based on the lightweight Ubuntu distribution Lubuntu and has a full user interface. By default it uses a NAT type VirtualBox adapter, so it can be deployed even in restrictive networks. Access to the GitLab instance, nmaas itself, and any applications deployed from nmaas is possible via the built-in Mozilla Firefox web browser. Upon first launching the browser, the user will see that quick access links are already available for these locations in the bookmark toolbar.

docs/tutorials-workshops/jres2022/p2_installing-nmaas.md → docs/tutorials-workshops/deploying-nmaas-test-instance.md

-# Part 2: Installing nmaas
+# Installing nmaas
 
 Once a working Kubernetes cluster has been deployed, we are ready to proceed to the next step - installing nmaas.
 
-All the necessary components will be installed in a single namespace – `nmaas-system`. If this namespace has not been created so far, execute:
-
-```bash
-kubectl create namespace nmaas-system
-```
+All the necessary components will be installed in the `nmaas-system` namespace that was created in the [previous part](./deploying-local-kubernetes-cluster.md).
 
 ## GitLab Installation
 
-The first nmaas dependency that we will set up is GitLab, a self-hosted web based Git repository hosting service. Many applications that are deployed by nmaas users store their configuration data in a Git repository, allowing easier editing, and version management.
+The first nmaas dependency that we will set up is GitLab, a self-hosted web based Git repository hosting service. Many applications that are deployed by nmaas users store their configuration data in a Git repository, allowing easier editing and version management, thus following the GitOps approach.
 
-GitLab has an official Helm chart, and we will use it to create a basic GitLab installation locally. Some parameters must be customized in the values.yaml file before deployment:
+GitLab has an official Helm chart, and we will use it to create a basic GitLab installation locally. Some parameters must be customized in the values .yaml file before deployment:
 
 - `global.hosts.domain` – should be set to the domain that will be allocated to GitLab. Note that the final hostname where GitLab will be reachable will have a `gitlab` prepended to it. If `nmaas.example.local` is set as the `global.hosts.domain` parameter, then GitLab will be available on `gitlab.nmaas.example.local`.
 - `global.hosts.ssh` – in order for users to be able to interact with their GitLab repositories via SSH, the value of `global.hosts.ssh` should be set to the MetalLB IP that will be assigned to this new service (usually the next available one) for the gitlab-shell component. If the IP is not known at the time of deployment, then after the initial deployment, once the LoadBalancer service is created and the IP is allocated, a chart upgrade can be performed, where the `global.hosts.ssh` parameter will be set to the appropriate value.
@@ -21,46 +17,54 @@ GitLab has an official Helm chart, and we will use it to create a basic GitLab i
 - optionally, if an email server is available, the `global.smtp` section can be edited with the appropriate parameters so that outbound email is enabled.
 
 ```yaml title="gitlab-values.yaml"
+gitlab:
+  gitlab-shell:
+    minReplicas: 1
+    maxReplicas: 1
+  webservice:
+    deployments:
+      default:
+        ingress:
+          path: /
+        hpa:
+          enabled: false
+          minReplicas: 1
+          maxReplicas: 1
+  sidekiq:
+    minReplicas: 1
+    maxReplicas: 1
 certmanager:
   install: false
 nginx-ingress:
   enabled: false
 prometheus:
   install: false
+gitlab-runner:
+  install: false
 redis:
   install: true
+registry:
+  enabled: false
 postgresql:
   postgresqlUsername: gitlab
   install: true
   postgresqlDatabase: gitlabhq_production
   usePasswordFile: false
   existingSecret: 'gitlab-postgresql'
-  master:
-    extraVolumeMounts:
-      - name: custom-init-scripts
-        mountPath: /docker-entrypoint-preinitdb.d/init_revision.sh
-        subPath: init_revision.sh
-    podAnnotations:
-      postgresql.gitlab/init-revision: "1"
   metrics:
     enabled: false
-gitlab-runner:
-  install: false
-gitlab-shell:
-  service:
-    type: LoadBalancer
 global:
+  kas:
+    enabled: false
   edition: ce
   hosts:
-    domain: nmaas.<INGRESS_IP>.nip.io
-    https: true
-    ssh: <LB_SSH_IP>.nip.io
+    domain: nmaas.internal
+    https: false
   ingress:
     enabled: true
     configureCertmanager: false
     tls:
-      enabled: true
-      # secretName: <EXISTING_OR_DUMMY_TLS_SECRET_NAME> # can be left empty, self-signed certificates will be generated
+      enabled: false
     path: /
     class: "nginx"
   initialRootPassword:
@@ -72,25 +76,6 @@ global:
   time_zone: Europe/Warsaw
   smtp:
     enabled: false
-    address: smtp.example.com
-    port: 587
-    user_name: ""
-    ## doc/installation/secrets.md#smtp-password
-    password:
-      secret: "my-smtp-secret"
-      key: password
-    # domain:
-    authentication: "login"
-    starttls_auto: true
-    openssl_verify_mode: "peer"
-## doc/installation/deployment.md#outgoing-email
-## Email persona used in email sent by GitLab
-  email:
-    from: 'noreply@example.com'
-    display_name: GitLab
-    reply_to: 'support@example.com'
-    smime:
-      enabled: false
 ```
 
 GitLab requires the deployment of a PostgreSQL instance. The necessary secrets containing the PostgreSQL passwords need to be created, as well as the secret containing the initial root GitLab password:
@@ -103,12 +88,12 @@ kubectl create secret generic -n $NMAAS_NAMESPACE gitlab-root-password --from-li
 
 The root GitLab password will be used for login to the GitLab web interface.
 
-We are ready to add the GitLab Helm repository and install the 8.2.x version of GitLab:
+We are ready to add the GitLab Helm repository and install the 8.5.x version of GitLab:
 
 ```bash
 helm repo add gitlab https://charts.gitlab.io
 helm repo update
-helm install -f gitlab-values.yaml --namespace nmaas-system nmaas-gitlab --version 8.2.0 gitlab/gitlab
+helm install -f gitlab-values.yaml --namespace nmaas-system nmaas-gitlab --version 8.5.0 gitlab/gitlab
 ```
 
 Once GitLab has been deployed, it should be possible to navigate to the login page using a web browser. After logging in, users are advised to configure the following settings:
@@ -117,8 +102,9 @@ Once GitLab has been deployed, it should be possible to navigate to the login pa
     - `Sign-up enabled` should be unchecked
     - `Require admin approval for new sign-ups` should be unchecked
 - enable webhooks to local addresses (`Admin Area -> Settings -> Network -> Outbound requests`)
-    - `Allow requests to the local network from web hooks and services` = checked
-    - `Allow requests to the local network from system hooks` = checked
+    - `Allow requests to the local network from web hooks and services` should be checked
+    - `Allow requests to the local network from system hooks` should be checked
+    - `Enforce DNS-rebinding attack protection` should be unchecked
 
 The final step before installing nmaas itself is to generate a GitLab personal access token which will allow nmaas to connect to the GitLab API. This can be done from the User Profile page:
 
@@ -134,10 +120,10 @@ The final step is to install nmaas. nmaas uses SSH communication to connect betw
 export NMAAS_NAMESPACE="nmaas-system"
 tmpdir=$(mktemp -d)
 ssh-keygen -f $tmpdir/key -N ""
-  
+
 # nmaas-helm-key-private should be replaced with {{ .Values.global.helmAccessKeyPrivate }}
 kubectl create secret generic nmaas-helm-key-private -n $NMAAS_NAMESPACE --from-file=id_rsa=$tmpdir/key
-  
+
 # nmaas-helm-key-private should be replaced with {{ .Values.global.helmAccessKeyPublic }}
 kubectl create secret generic nmaas-helm-key-public -n $NMAAS_NAMESPACE --from-file=helm=$tmpdir/key.pub
 ```
@@ -160,46 +146,71 @@ global:
   acmeIssuer: false
   demoDeployment: true
   ingressName: nmaas
-  nmaasDomain: nmaas.<INGRESS_IP>.nip.io
-  wildcardCertificateName: <EXISTING_OR_DUMMY_TLS_SECRET_NAME>
+  nmaasDomain: nmaas.internal
+  wildcardCertificateName: nmaas-internal-wildcard
   gitlabApiUrl: 'http://nmaas-gitlab-webservice-default:8181/api/v4'
   gitlabApiToken:
-    literal: <GITLAB_ACCESS_TOKEN>
+    literal: glpat-bSHxML48QNsZJE4CLHxc
 platform:
+  initscripts:
+    enabled: true
   ingress:
     className: nginx
   adminPassword:
     literal: saamn
   apiSecret:
     literal: saamn
-  initscripts:
-    enabled: true
   properties:
     autoNamespaceCreationForDomains: true
+    adminEmail: noreply@nmaas.internal
+    appInstanceFailureEmailList: noreply@nmaas.internal
     sso:
-      encrpytionSecret:
-        literal: saamn
-    adminEmail: noreply@nmaas.local
-    appInstanceFailureEmailList: noreply@nmaas.local
+      enabled: false
     k8s:
       ingress:
         certificate:
-          issuerOrWildcardName: <EXISTING_OR_DUMMY_TLS_SECRET_NAME>
+          issuerOrWildcardName: nmaas-internal-wildcard
         controller:
-          ingressClass: nmaas
-          publicIngresClass: nmaas
-          publicServiceDomain: nmaas.<INGRESS_IP>.nip.io
-          externalServiceDomain: nmaas.<INGRESS_IP>.nip.io
+          externalServiceDomain: nmaas.internal
+          ingressClass: nginx
+          publicIngresClass: nginx
+          publicServiceDomain: nmaas.internal
+portal:
+  ingress:
+    className: nginx
+  properties:
+    langingPageFlavor: VLAB
+
+sp:
+  enabled: false
+
+postfix:
+  image:
+    repository: artifactory.software.geant.org/nmaas-docker-local/nmaas-postfix-smtp
+    tag: 1.0.0
+  properties:
+    hostname: mailer.nmaas.internal
+    smtp:
+      fromAddress: noreply@nmaas.internal
+      host:
+        literal: localhost
+      username:
+        literal: smtpUsername
+      password:
+        literal: mysecret
+      port: '1050'
 ```
 
 Once the values.yaml file has been customized, nmaas can be deployed by executing:
 
 ```bash
 helm repo add nmaas https://artifactory.software.geant.org/artifactory/nmaas-helm
-helm install -f nmaas-values.yaml --namespace nmaas-system nmaas --version 1.2.11 nmaas/nmaas
+helm install -f nmaas-values.yaml --namespace nmaas-system nmaas --version 1.2.14 nmaas/nmaas
 ```
 
-nmaas also requires an the stakater autoreloader component, which can simply be installed using the commands below. This component takes care of restarting the affected pods whenever a configuration change is submitted via GitLab.
+The email configuration in the `postfix` section configures an invalid email server on purpose (`localhost:1050:`), as to prevent email sending. If available, users are advised to use their own SMTP credentials, so that email sending will be fully functional.
+
+nmaas also requires an the Stakater AutoReloader component, which can simply be installed using the commands below. This component takes care of restarting the affected pods whenever a configuration change is submitted via GitLab.
 
 ```bash
 helm repo add stakater https://stakater.github.io/stakater-charts

docs/tutorials-workshops/introduction.md

@@ -3,4 +3,10 @@
 This section contains the materials for tutorials and workshops where the nmaas Platform or one of its use-cases has been presented. Currently it includes the archived resources for the following events:
 
 - [JRES 2022 - GÉANT Network Management as a Service tutorial](jres2022/introduction.md)
-- [JRES 2024 - Orchestrated Deployment of Virtual Labs for Education](jres2024/introduction.md)
\ No newline at end of file
+- [JRES 2024 - Orchestrated Deployment of Virtual Labs for Education](jres2024/introduction.md)
+
+To fully leverage the content in these materials, access to an nmaas test instance is advised. This can be accomplish by:
+
+- deploying a [local Kubernetes cluster](./deploying-local-kubernetes-cluster.md) and then [deploying an nmaas test instance in it](./deploying-nmaas-test-instance.md).
+- registering for an account on the [managed vNOC Playground instance](https://nmaas.geant.org) or the [managed vLAB instance](https://vlab.dev.nmaas.eu), depending on the use-case that you are interested in.
+- downloading the ready-made all-in-one nmaas test VM image. Please note that this VM image does not have a `LoadBalancer` implementation installed and it is up to the user to install and configure one. More details about the all-in-one nmaas image are available on the [corresponding docs page](./all-in-one-vm-image.md).
\ No newline at end of file

docs/tutorials-workshops/jres2022/appendix.md

@@ -2,7 +2,7 @@
 
 !!! note Virtual Machine Download
 
-    The virtual machine image can be downloaded from [https://drive1.demo.renater.fr/index.php/s/rp2awZ6sMnNFQwK](https://drive1.demo.renater.fr/index.php/s/rp2awZ6sMnNFQwK). Users are advised to follow [part 1](p1_local-kubernetes-cluster.md) in order to set up the required VirtualBox NAT network before importing.
+    The virtual machine image can be downloaded from [https://drive1.demo.renater.fr/index.php/s/rp2awZ6sMnNFQwK](https://drive1.demo.renater.fr/index.php/s/rp2awZ6sMnNFQwK). Users are advised to follow [part 1](../deploying-local-kubernetes-cluster.md) in order to set up the required VirtualBox NAT network before importing.
 
 | Name                                       | Value                                                  |
 |--------------------------------------------|--------------------------------------------------------|
@@ -30,6 +30,6 @@
 | Oxidized Test Instance URL                 | https://oxidized-demo.nmaas.10.99.99.150.nip.io        |
 | Oxidized Test Instance HTTP Username       | nmaas_demo                                             |
 | Oxidized Test Instance HTTP Password       | nmaasdemo                                              |
-| UptimeKuma Test Instance URL              | https://uptimekuma-demo.nmaas.10.99.99.150.nip.io      |
-| UptimeKuma Test Instance Username         | nmaas_demo                                             |
-| UptimeKuma Test Instance Password         | nmaasdemo!                                             |
\ No newline at end of file
+| UptimeKuma Test Instance URL               | https://uptimekuma-demo.nmaas.10.99.99.150.nip.io      |
+| UptimeKuma Test Instance Username          | nmaas_demo                                             |
+| UptimeKuma Test Instance Password          | nmaasdemo!                                             |
\ No newline at end of file

docs/tutorials-workshops/jres2022/introduction.md

@@ -2,10 +2,6 @@
 
 Network management is an essential part of any production network, no matter its size. However, organizations often face staff shortages or lack the required resources to properly monitor their network. nmaas (Network Management as a Service) is a GÉANT production service that allows effortless deployment of many open-source network monitoring tools on demand, with minimal initial configuration by the end users. Based on the Kubernetes container orchestrator, and deployable on private infrastructure as well, a dedicated nmaas instance can be used as a central point for monitoring many distributed networks, by utilizing VPN tunnels. New applications can be added to the nmaas catalogue at any time using Helm charts, an industry standard package manager for Kubernetes. nmaas hides the operational complexity from end users who access the service through a web application from where they can manage and configure their existing application instances or deploy new ones.
 
-Users can also evaluate nmaas on their own infrastructure by either following this tutorial or by simply [downloading the already prepared virtual machine](https://drive1.demo.renater.fr/index.php/s/rp2awZ6sMnNFQwK). After downloading the virtual machine image, users are advised to follow [part 1](./p1_local-kubernetes-cluster.md) in order to set up the necessary VirtualBox NAT network which is required by the VM so that all of its components can run as expected, and the subnets described in the [Appendix](./appendix.md) remain unchanged.
-
-By the end of this 5 part tutorial, users should have an exact replica of the setup done within the virtual machine.
-
-This tutorial begins with [part 1](./p1_local-kubernetes-cluster.md) where a local Kubernetes cluster is initialized allowing users to choose between two lightweight Kubernetes distributions - MicroK8s or K3s. It then proceeds with [part 2](./p2_installing-nmaas.md) where the nmaas installation procedure is explained, along with all required dependencies. In [part 3](./p3_demo-network-environment.md), a simple method is described for setting up virtualized demo networking devices that can later be used as monitoring targets for the applications deployed by nmaas. The process of deploying such monitoring applications from the list of supported applications in the nmaas catalog is described in [part 4](./p4_monitoring-demo-network-environment.md). The tutorial is concluded with [part 5](./p5_adding_custom_app.md), allowing advanced users to add their own custom applications to the nmaas catalog, thus making it available to all potential users of their nmaas instance.
+If you want to follow this tutorial, please make sure that you have either downloaded the [pre-prepared VM](../all-in-one-vm-image.md) or have followed the necessary steps for deploying a local Kubernetes cluster and installing an nmaas test instance. After completing these prerequisites, this tutorial continues with [setting up a demo network environment](./p3_demo-network-environment.md), where virtualized demo networking devices are used that can later act as monitoring targets for the applications deployed by nmaas. The process of deploying such monitoring applications from the list of supported applications in the nmaas catalog is described in the part on [monitoring the demo network environment](./p4_monitoring-demo-network-environment.md). The tutorial is concluded with [instructions on adding a custom application](./p5_adding_custom_app.md), allowing advanced users to add their own applications to the nmaas catalog, thus making it available to all potential users of their nmaas instance.
 
 For users who choose to download the already prepared virtual machine and avoid the whole setup process, the [Appendix](./appendix.md) gives an overview of all the credentials that have been used.
\ No newline at end of file

docs/tutorials-workshops/jres2022/p3_demo-network-environment.md

@@ -4,6 +4,10 @@
 
     These instructions are heavily based on the excellent blog posts and FreeRTR Docs written by [Fréderic Loui](https://twitter.com/FredericLoui) and the RARE team.
 
+!!! note "Clarification"
+
+    This guide assumes that a local deployment of nmaas already exists and that either you are working in the provided nmaas test VM or you have followed the [instructions to deploy nmaas from scratch locally](../deploying-local-kubernetes-cluster.md).
+
 If there are existing network elements ready to be monitored by nmaas applications, then this part can be completely skipped. 
 
 ## Configuring VirtualBox
@@ -12,7 +16,7 @@ This tutorial will assume that VirtualBox is used, even though the discussion sh
 
 The virtual machine where FreeRTR will be installed requires at least two network interfaces, one primary and one additional for each FreeRTR process. 
 
-The addition of new interfaces can be easily accomplished from the VirtualBox VM settings screen, using the Network section. Each new interface is represented by a new tab, named `Adapter 1`, `Adapter 2`... For the new interface, choose `Attached to: NAT` and **make sure to select the NAT network created in [Part 1](./p1_local-kubernetes-cluster.md#creating-a-new-nat-network-in-virtualbox) and that Promiscuous Mode is set to Allow All** in the Advanced section. If Promiscuous Mode is not enabled, unfortunately pcapInt will not be able to work properly.
+The addition of new interfaces can be easily accomplished from the VirtualBox VM settings screen, using the Network section. Each new interface is represented by a new tab, named `Adapter 1`, `Adapter 2`... For the new interface, choose `Attached to: NAT` and **make sure to select a `NAT network` created and that Promiscuous Mode is set to Allow All** in the Advanced section. If Promiscuous Mode is not enabled, unfortunately pcapInt will not be able to work properly.
 
 ## Installing FreeRTR