Instructions for the installation of a yuuvis® Momentum system operating in a Kubernetes cluster via Helm Charts. Start with Helm charts for testing purposes and replace default third-party software according to your preferences.

Introduction

This installation guide will help you to install yuuvis® Momentum via Helm Charts in order to operate it in a Kubernetes cluster. We assume readers are familiar with Kubernetes and Helm commands.
>> Kubernetes
>> Helm

Each yuuvis® Momentum installation contains the core services provided in the yuuvis Helm chart. Most of our optional additional services are available via separate Helm charts as well.

Requirements

Check the requirements and recommendations of third-party software in order to set up a productive yuuvis® Momentum system.
>> yuuvis® Momentum Requirements

Installation

Clone the yuuvis-api-helm-charts repository as working directory (see Version Tags Services).

Add your credentials for the docker.yuuvis.org registry in the values.yaml files of the Helm Charts. Replace all changeme default passwords in the values.yaml of the charts you plan to use.

All yuuvis® Momentum services reach out to the CONFIGSERVICE on startup to retrieve their configuration files, which results in a short delay before that services are fully operable. The yuuvis chart configures the AUTHENTICATION and ORGANIZATION services for OAuth2 with the tenants yuuvistest and testyuuvis.

For any questions about credentials please contact support@yuuvis.com.

'infrastructure' Helm Chart

The infrastructure Helm Chart provides third-party software that can be combined with yuuvis® Momentum in order to build a test system. You should replace those components according to your preferences and needs in your productive system:

In order to install and use the set of third-party software provided in the infrastructure Helm Chart, follow these steps:

• Add the required Helm repositories:

  helm repo add minio https://helm.min.io/
  helm repo add bitnami https://charts.bitnami.com/bitnami
  helm repo add gitea-charts https://dl.gitea.io/charts/

• Update the Infrastructure dependencies:

  cd infrastructure
  helm dep up
  helm repo add stable https://charts.helm.sh/stable
  cd ..

• Adjust the values.yaml file:

  • Adjust docker registry credentials.
  • Specify the address of your yuuvis® Momentum cluster by setting your CLUSTER_IP or your AUTHENTICATION service's LOAD_BALANCER_IP for the parameter yuuvis.authentication.ip.
  • Optionally change passwords.
  • Optionally change the used storage classes.

• Install the infrastructure services. Naming the chart during installation is necessary as each service would otherwise receive a default prefix from Kubernetes, making it difficult for the yuuvis® Momentum services to interact with them later. This also enables us to rollback our installation.

  kubectl create namespace infrastructure
  helm install infrastructure ./infrastructure --namespace infrastructure

• Wait until the jobs are done.

  kubectl get jobs -n infrastructure

  There are two jobs preparing the git server and the Keycloak environment that need to be completed.

  NAME                              COMPLETIONS   DURATION   AGE
  gogsrepo-init                     1/1           83s        8m4s
  keycloak-create-selfsigned-cert   1/1           8m4s       8m4s

• Run the following command to see if the infrastructure chart was deployed (STATUS DEPLOYED).

   helm list --namespace infrastructure

'yuuvis' Helm Chart

• Adjust the values.yaml file:

  • Adjust docker registry credentials.
  • If you are using Keycloak as identity provider, specify its address by setting your CLUSTER_IP or your Keycloak's LOAD_BALANCER_IP for the parameter yuuvis.keycloak.ip.
• Navigate to the root Helm Chart directory within the cloned repository.

• Install the Helm Chart. Again, naming our chart prevents randomization of service identifiers and gives us the ability to rollback all associated services.

  kubectl create namespace yuuvis
  helm install yuuvis ./yuuvis --namespace yuuvis

• Wait for the pods to be ready:

  kubectl get po -n yuuvis

'client' Helm Chart

• Adjust the docker registry credentials.

• Install the Helm Chart:

  helm install client ./client --namespace yuuvis

• Wait for the pods to be ready:

  kubectl get po -n yuuvis

• The installation of the client Helm Chart will change the app-specific systemHookConfiguration.json for the clientsystem app. Services referring to this configuration will only read it once at startup. Thus, the corresponding services must be restarted to apply the new configuration. E.g., restart the API Gateway via:

  kubectl rollout restart deployment api -n yuuvis

• To enable users to create objects, define a suitable role and assign it to them.

'bpm' Helm Chart

• Adjust the docker registry credentials.

• Install the Helm Chart:

  kubectl get po -n yuuvis
  helm install bpm ./bpm --namespace yuuvis

'rendition' Helm Chart

• Install the Helm Chart:

  kubectl get po -n yuuvis
  helm install rendition ./rendition --namespace yuuvis

'monitoring' Helm Chart

• Install the prometheus monitoring operator.

  helm install prometheus-operator stable/prometheus-operator --namespace infrastructure --values ./monitoring/values.yaml

• Verify that the prometheus operator chart has been deployed.

  helm list --namespace infrastructure
  

• Get the monitoring operator pod status.

  kubectl --namespace infrastructure get pods -l "release=prometheus-operator"

• Finally, setup the alerting rules and service monitor by running these two commands: 

  kubectl apply -f ./monitoring/templates/prometheus-alerting-rule.yaml -n infrastructure
  kubectl apply -f ./monitoring/templates/servicemonitor

• Install the monitoring Helm Chart:

  helm dep up monitoring
  helm install monitoring ./monitoring -n monitoring --create-namespace --debug

• Before deploying the monitoring Helm Chart, adjust the parameters in its values.yaml configuration file.
  >> Monitoring via Prometheus and Graphana
  
  

'repositorymanager' Helm Chart

• Adjust the docker registry credentials and the chart's values.yaml configuration file.

• Install the Helm Chart:

  # Check if yuuvis core services are running
  kubectl get po -n yuuvis
  
  # Create a new namespace for every instance, e.g. xxxxx
  kubectl create namespace xxxxx
  
  # Ensure that the correct values are set in values.yml (credentials, ports, profile, tenant...)
  helm install repositorymanager ./repositorymanager --namespace xxxxx 

Testing with Postman

Postman is a free API development tool with a multitude of useful functions for automated testing, documentation, and more. Our yuuvis® Postman Collections kick-start you right into the yuuvis® API world.
>> yuuvis® Postman Collections

Version Updates

• Update resource files in Git (in case according to the Update Instructions 2022 Winter LTS or Update Instructions 2021 - 2022 Winter LTS).

• All Helm Charts except the infrastructure chart can be updated to a new version via:

  helm upgrade -n <namespace> <chart name> <chart location>

  For the concrete individual charts this means:

  helm upgrade -n yuuvis yuuvis yuuvis
  helm upgrade -n yuuvis bpm bpm
  helm upgrade -n yuuvis client client 
  helm upgrade -n yuuvis rendition rendition

• The third-party infrastructure components have to be updated via individual docker images:
  • Use our current Docker image for Elasticsearch as it includes the required plug-ins.
  • Optionally, use our Keycloak Docker image.
  • Updates for all further third-party components are within the customer's responsibility.

Deinstallation

Note: Helm does not delete persistent volumes. Those data have to be deleted manually.

'infrastructure' Helm Chart

This chart deletes components required for the monitoring Helm Chart.

• The rollback of the installation is possible via:
  

  helm uninstall infrastructure --namespace infrastructure

• After uninstalling, run the following two commands:

  kubectl delete clusterrole create-selfsigned-cert 
  kubectl delete clusterrolebinding create-selfsigned-cert

'monitoring' Helm Chart

• The rollback of the installation is possible via:

  helm uninstall monitoring --namespace monitoring
  helm uninstall prometheus-operator --namespace infrastructure

• Delete the final setup for monitoring via:

  kubectl delete servicemonitor --all -n infrastructure and kubectl delete prometheusrule --all -n infrastructure

'yuuvis' Helm Chart

The rollback of all associated services is possible via:

helm uninstall yuuvis --namespace yuuvis