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.

Table of Contents

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:

Infrastructure Component	Function
PostgreSQL	database service
Elasticsearch	search engine
Minio	object storage
Gogs as of 2021 Autumn: Gitea	self-hosted Git service
RabbitMQ	message broker
Keycloak	identity and access management service
Redis	in-memory data structure store

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

Read on

yuuvis® Postman Collections

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. Keep reading

Release Information

Looking for new features? Here, you will find what's new in a fresh yuuvis® version, as well as the rare cases - Breaking Changes - that might require your action when updating. Keep reading

yuuvis® Momentum Requirements

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

Browser not supported