#  Kubernetes Install

This guide walks you through detailed set up of FlowFuse Platform on a container envoronment managed by Kubernetes. Typically suited for large on premise deployments or deployment in Cloud infrastructure. By the end, you will have a fully functioning FlowFuse instance running on a Kubernetes cluster.

#  Checklist

#  Prerequisites

Before you begin, ensure you have the following:

1. Domain Name & DNS: A domain name that you own and can configure DNS settings for (explained in DNS)
2. 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
3. Helm: FlowFuse provides the Helm chart to manage platform deployment. Installation can be done through the instructions on their website
4. Kubernetes Cluster: The deployment has currently been tested on the following environments:
   • AWS EKS
   • Digital Ocean
   • MicroK8s
5. Ingress Controller: An Ingress controller installed on the kubernetes cluster. FlowFuse Helm chart uses the Ingress NGINX Controller by default.

For a production-ready environment, we also recommend:

• Database: Prepare dedicated database on a external database server (see FAQ for more details)
• TLS Certificate: Prepare TLS certificate for your domain and configure FlowFuse platform to use it (see Enable HTTPS)

#  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 kubernetes Ingress controller.

For example if you want projects to be accessible as [instance-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 FlowFuse 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.

#  Installing FlowFuse

#  Add FlowFuse Helm Repository

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

#  Customize Helm Chart

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

To create customization.yml file with a minimal required configuration (replace example.com with your domain):

cat <<EOF > customization.yml
forge:
  entryPoint: forge.example.com
  domain: example.com
  https: false
  localPostgresql: true
EOF

A full list of all the configuration options can be found in the Helm Chart README.

#  Label Nodes

By default FlowFuse platform expects that Kubernetes nodes have specific labels applied. The main reason behind this approach is to separate core application components from Node-RED instances.

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

List all nodes in the cluster:

kubectl get nodes

Label management nodes:

kubectl label node <management-node-name> role=management

Label project nodes:

kubectl label node <projects-node-name> role=projects

To override this behavior, you can remove the node selectors with the following entry in the customization.yml file which will mean that all pods can run on any nodes.

forge:
  projectSelector:
  managementSelector:

#  Start FlowFuse Platform

Once you have the customization.yml file created, you can install FlowFuse using our Helm chart. This will automatically create all required objects and start services:

helm upgrade --atomic --install --timeout 10m flowfuse flowfuse/flowforge -f customization.yml

#  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.

#  Upgrade

All technical aspects of the upgrade process of Flowfuse application running on Kubernetes and managed by Helm chart are maintained in our repository. Please refer to the Flowfuse Helm Chart documentation for more details about the upgrade process.

#  Common Questions

#  I would like to secure the platform with HTTPS, how can I do that?

In cloud environments, it is recommended to use a Load Balancer to terminate SSL traffic.

However, if you want to use SSL termination on the Kubernetes Ingress Controller, this is possible by utilizing Cert-Manager tool (not part of the FlowFuse Helm chart).

Once you have Cert-Manager installed, you can enable TLS support in the customization.yml file by specifying the ClusterIssuer name:

ingress:
  clusterIssuer: <your-cluster-issuer>

Apply changes with platform startup command.

#  How to use external database server?

FlowFuse platform uses PostgreSQL database to store its data. By default, the internal database instance is created and managed by the Helm chart.

If you want to use an external database server, you need to edit customization.yml file and provide the database connection details:

forge:
  localPostgresql: false # Disable internal database
postgresql:
  host: <database-host>
  port: <database-port>
  auth:
    username: <database-username>
    password: <database-password>
    database: <database-name>

Apply changes with platform startup command.

Check the FlowFuse Helm chart documentation for more details about the parameters that can be configured for the PostgreSQL database.

#  How to backup embedded database?

If you are using the internal database (value forge.localPostgresql set to true), you can use Kubernetes CronJobs to backup the database.

Apply below CronJob and PersistentVolumeClaim definitions to create a backup job which will be executed every day at 23:05 and store the backup in a PVC named db-backup-pvc:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: db-backup-pvc
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 5Gi
---
apiVersion: batch/v1
kind: CronJob
metadata:
  name: postgres-backup
spec:
  schedule: "5 23 * * *"
  jobTemplate:
    spec:
      ttlSecondsAfterFinished: 60
      template:
        metadata:
          labels:
            app: flowforge
        spec:
          containers:
          - name: backup
            image: postgres
            env:
            - name: PGPASSWORD
              valueFrom:
                secretKeyRef:
                  name: flowfuse-postgresql
                  key: postgres-password
            command:
            - /bin/sh
            - -c
            - |
              pg_dump -h flowfuse-postgresql -U postgres -d flowforge -F c -b -v -f /backup/db_backup.dump
            volumeMounts:
            - name: backup-volume
              mountPath: /backup
          restartPolicy: OnFailure
          volumes:
          - name: backup-volume
            persistentVolumeClaim:
              claimName: db-backup-pvc

#  I would like to invite my team members to the platform with e-mail, how can I do that?

FlowFuse platform allows you to invite team members to the platform using their e-mail addresses. To enable this feature, you need to configure the e-mail settings in the customization.yml file.

Check this page for more details about the parameters. Check FlowFuseHelm chart documentation for information where configuration values should be placed in customization.yml file.

If you use AWS EKS (Elastic Kubernetes Service) and want to use AWS SES (Simple Email Service) for sending e-mails, you need to provide the IAM role with the required permissions to use SES.

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

Apply changes with platform startup command.

#  I would like to use embeded MQTT broker, how can I do that?

forge:
  broker:
    enabled: true

#  I would like to use Kubernetes Persistent storage to store data, how can I do that?

Starting with the 2.6.0 release the Pods running the Node-RED Instances have a Persistent Volume mounted on /data/storage in which files can be written. These files will persist for the lifetime of the Instance including across Susspend/Resume and Stack upgrades.

To enable this feature the following configuration needs to be added to the customization.yml file (replace '' with the name of the StorageClass you have in the cluster):

forge:
  persistentStorage:
    enabled: true
    size: 5Gi
    storageClass: <storage-class-name>

Apply changes with platform startup command.

#  I would like to use FlowFuse File Storage to store context data, how can I do that?

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

forge:
  fileStore:
    enabled: true

Apply changes with platform startup command.

Check the FlowFuse Helm chart documentation for more details about the parameters that can be configured for the File Storage.

#  I would like to run FlowFuse on AWS EKS. Do you have any guidance?

Yes, we have a dedicated guide on how to deploy FlowFuse on AWS EKS. You can find it here. Furthermore, we also provide terraform scripts to automate the deployment process of all required AWS service. You can find the guide here.