# Kubernetes Install

This version of the FlowForge platform is intended for running in the Kubernetes (sometimes referred to as K8s) Container management system. Typically suited for large on premise deployments or deployment in Cloud infrastructure.

# Prerequisites

# Kubectl

To manage a Kubernetes cluster you will need a copy of the kubectl utility. Instructions on how to install it can be found here.

# Helm

FlowForge uses a Helm Chart to manage deployment. Installation can be done through the instructions on their website.

# Kubernetes

You will need a Kubernetes environment. The deployment has currently been tested on the following environments:

It should run on any Kubernetes platform, but may require some changes for vendor specific Ingress setup.

By default the Helm chart assumes that the Kubernetes cluster has at least 2 nodes:

One used to run the FlowForge management infrastructure
One or more used to run the Node-RED Project instances

You can run a small scale Proof-of-Concept on a single node cluster, details of how to do this can be found in the Configure FlowForge section below.

# PostgreSQL Database

The Helm chart can either install a dedicated PostgreSQL database into the same K8s cluster or can configure the install to use an external instance.

# DNS

A wildcard DNS entry will be needed to point to the domain that is used for the project instances. This will need to point to the K8s Ingress controller.

For example if you want projects to be access able as [project-name].example.com you will need to ensure that *.example.com is mapped to the IP address used by your Kubernetes clusters's Ingress controller.

By default the FlowForge application will be mapped to forge.example.com assuming that you set the domain to example.com.

Notes on how to setup DNS can be found here.

# Email

Some features require the ability to send email to users. This can be currently be provided by:

SMTP server
AWS SES

# Installing FlowForge

# Download

helm repo add flowforge https://flowforge.github.io/helm
helm repo update

# Configure FlowForge

All the initial configuration is handled by the Helm chart. This is done by creating a customization.yml file in the helm directory that will be passed to the helm along with the chart.

This is the minimal configuration

forge:
  entryPoint: forge.example.com
  domain: example.com
  https: false
  localPostgresql: true

When running on AWS EKS and using AWS SES for email (The IAMRole needs to have the required permissions to use SES) it would look something like:

forge:
  entryPoint: forge.example.com
  domain: example.com
  cloudProvider: aws
  aws:
    IAMRole: arn:aws:iam::<aws-account-id>:role/flowforge_service_account_role
  email:
    ses:
      region: eu-west-1

A more detailed example for running on AWS can be found here

As mentioned earlier the Helm chart defaults to expecting at least 2 nodes in the Kubernetes cluster.

You will need to label at least one node to run the management application and one to run the Node-RED Projects.

You can do this with the kubectl utility. The following command lists all the nodes in the cluster

kubectl get nodes

You can then use kubectl label node to add the required labels:

FlowForge management node(s)

kubectl label node <management node name> role=management

Node-RED projects node(s)

kubectl label node <projects node name> role=projects

To override this you can remove the node selectors with the following which will mean that all pods can run on any nodes.

forge:
  projectSelector:
  managementSelector:

A full list of all the configurable values can be found in the Helm Chart README.

The install can then be started with the following command:

helm upgrade --atomic --install flowforge flowforge/flowforge -f customization.yml

# Enabling the MQTT broker

To enable the MQTT broker with Kubernetes install you need to add the following to the customization.yml file

forge:
  broker:
    enabled: true
    url: mqtt://forge:1883

The forge.broker.public_url value will be generated by prepending ws://mqtt to the supplied forge.domain value.

# First Run Setup

The first time you access the platform in your browser, it will take you through creating an administrator for the platform and other configuration options.

For more information, follow this guide.

Once you have finished setting up the admin user there are some Kubernetes specific items to consider.

# Using FlowForge File Storage

FlowForge projects running in Kubernetes do not have direct access to a persistent file system to store files or use for storing context data.

FlowForge includes a File Storage service that can be enabled to provide persistent storage.

# Disabling the default File nodes

To remove the default Node-RED file nodes from the palette:

Edit the Project Template to add 10-file.js,23-watch.js to the "Exclude nodes by filename" section

# Configuring the File Storage service

Full details on configuring the file storage service are available here.

# Enabling the File Storage service

To enable the FlowForge File Storage component add the following to the customization.yml file:

forge:
  fileStore:
    enabled: true

# Upgrade

Run helm repo update flowforge to pull the latest version
Check the README.md for any new options to configure in customization.yml
Run the helm upgrade --install flowforge flowforge -f customization.yml