Table of Contents

Helm configuration

Annotations

Kubernetes annotations can be added to generated deployments by setting values in the annotations array property of the main configuration.

Note

Annotations keys will be prefixed by neos/, ex: my-key will be set to neos/my-key

Each value has the following properties :

Property Description Type mandatory default
key Annotation key string true
value Annotation value string true

Gateway

The gateway handles authentication and redirects traffic to the right services

The following properties can be set on the gateway property of the main configuration.

Property Description Type mandatory default
envSecret Secret name for gateway env variables (eg: Authentication tokens) string false
logLevel Gateway log level Log level false Information
replicas Desired number of instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 128Mi
maxBodySize Maximum body size (see Custom max body size) Body size false 5m

Report

The report server handles report generation.

The following properties can be set on the report property of the main configuration.

Property Description Type mandatory default
enabled Deploy the report server boolean false true
envSecret Secret name for report server env variables (eg: Stimulsoft licence Reporting__StimulsoftLicenceKey) string false
replicas Desired number of instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 1024Mi

Tenant management

Tenant manager cluster allows to administer multiple tenants in Neos clusters.

Note

Tenant management configuration is only mandatory if your clusters run in multi tenancy mode.

Common

The following properties can be set on the tenantManagement property of the main configuration.

Property Description Type mandatory default
databaseType Database persistence type (Oracle, PostgreSQL or SqlServer) string true
host Domain for tenant management access (from outside the Kubernetes cluster) string false
tlsSecret Name of the secret containing the TLS certificate string false
envSecret Secret name for backend tenantManagement container env variables (at least PersistenceSettings__ConnectionString) string false
jsonConfigurationSecret Secret name for tenantManagement frontend container additional configuration (like ApplicationInsights) string false
defaultUserAccountLogin The identifier of the user to create when starting the tenant management cluster on an empty database. The user account should already exist in authentication provider. string false
logLevel Log level for tenant management containers Log level false Information
clusterResiliencyPolicies Cluster resiliency policies Cluster resiliency policies false

Backend

The following properties can be set on the backend property of the tenant management configuration.

Property Description Type mandatory default
replicas Desired number of backend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 256Mi

Frontend

The following properties can be set on the frontend property of the tenant management configuration.

Property Description Type mandatory default
replicas Desired number of frontend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 5m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 64Mi

API Documentation (Swagger)

By default, the API documentation UI (Swagger) is not exposed.

You can configure it by setting the following properties on the apiDocumentation property of the tenant management configuration.

Property Description Type mandatory default
enabled Enable API documentation interface boolean false false
prefix Prefix for API documentation access (eg: https://<host>/<prefix>/) string false api-documentation

License management

License manager cluster allows to administer licenses in Neos clusters.

Note

License management configuration is only mandatory if you need to manage licenses.

Common

The following properties can be set on the licenseManagement property of the main configuration.

Property Description Type mandatory default
databaseType Database persistence type (Oracle, PostgreSQL or SqlServer) string true
host Domain for license management access (from outside the Kubernetes cluster) string false
tlsSecret Name of the secret containing the TLS certificate string false
envSecret Secret name for backend licenseManagement container env variables (at least PersistenceSettings__ConnectionString) string false
jsonConfigurationSecret Secret name for licenseManagement frontend container additional configuration (like ApplicationInsights) string false
defaultUserAccountLogin The identifier of the user to create when starting the license management cluster on an empty database. The user account should already exist in authentication provider. string false
logLevel Log level for license management containers Log level false Information
clusterResiliencyPolicies Cluster resiliency policies Cluster resiliency policies false

Backend

The following properties can be set on the backend property of the license management configuration.

Property Description Type mandatory default
replicas Desired number of backend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 256Mi

Frontend

The following properties can be set on the frontend property of the license management configuration.

Property Description Type mandatory default
replicas Desired number of frontend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 5m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 64Mi

API Documentation (Swagger)

By default, the API documentation UI (Swagger) is not exposed.

You can configure it by setting the following properties on the apiDocumentation property of the license management configuration.

Property Description Type mandatory default
enabled Enable API documentation interface boolean false false
prefix Prefix for API documentation access (eg: https://<host>/<prefix>/) string false api-documentation

Notifications hub (SignalR)

Notifications are handled by SignalR notification hub instances. SignalR hubs are also dependents on Redis instances.

Note

Notifications hub configuration is not mandatory since at least one replica of the hub and Redis will be created when deploying (See preset configuration).

Common

The following properties can be set on the notificationsHub property of the main configuration :

Property Description Type mandatory default
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 5m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 128Mi

Redis

Redis is used for distributed cache (and possibly as message broker).

It is deployed as a dependency for the Neos Helm chart. It uses the Bitnami Redis chart associated to a Redis stack image.

Thus, the configuration can be set using the redis property of the main configuration.

High availability in production (with Sentinel)

By default, the Neos chart will deploy a Redis instance in standalone mode (only one pod).

This is sufficient in a development environment but since this is a single point of failure, you should activate multiple replication in production.

To do so, you can enable high availability using Redis Sentinel by configuration your helm values file as following :

redis:
  architecture: replication # default standalone
  sentinel:
    enabled: true # enable Redis Sentinel

Redis state store indexes

If you need to use Redis state store indexes in your cluster, you can configure them by setting the redisQueryIndexes property of the main configuration.

The syntax is similar to the one used in cluster configuration files. Please see this article for more information on how to create indexes.

For the following cluster configuration :

# State store Redis indexes
RedisQueryIndexes:
  - Name: europeanUnionIdx
    Indexes:
      - Key: europeanUnion
        type: NUMERIC

In your Helm file, you should have :

redisQueryIndexes:
  - name: europeanUnionIdx
    indexes:
      - key: europeanUnion
        type: NUMERIC

Example

In this example, we expose one cluster (Northwind) and the tenant management :

tenantManagement:
  databaseType: "PostgreSQL"
  host: tenants.example.local
  tlsSecret: tenants-tls-secret
  envSecret: neos-tenants-env
  jsonConfigurationSecret: neos-tenants-frontend-conf
  defaultUserAccountLogin: "tenantadmin@example.com" # (optional)

gateway:
  envSecret: neos-gateway-auth

report:
  envSecret: neos-report-licence

clusters:
  - name: Northwind
    version: "1.2.3" # (default "latest")
    databaseType: "PostgreSQL"
    logLevel: "Information" # (default)
    tlsSecret: "northwind-secret-name"
    backend:
      image: "harbor.hexanet.fr:8443/neos/northwind-backend"
      envSecret: northwind-env-secret
      imagePullSecret: northwind-pull-secret # (optional)
      tag: nightly # (default "latest")
      replicas: 3 # (default 1)
      appDirectory: /app # (default)
      port: 7000 # (default)
      volume:
        storageClassName: example-nfs-server-storage-class
        mountPath: /mnt/documents
        size: 512Mi # (default)
        accessMode: ReadWriteMany # (default)
    frontend:
      image: "harbor.hexanet.fr:8443/neos/northwind-frontend"
      jsonConfigurationSecret: northwind-frontend-conf
      imagePullSecret: northwind-pull-secret # (optional)
      port: 80 # (default)
      replicas: 2 # (default 1)
      tag: nightly # (default "latest")
    host: "northwind.example.local"
    interClusterCommunication:
      pubSubMessageBroker: Redis # (default RabbitMQ)

# Redis state store indexes
redisQueryIndexes:
  - name: europeanUnionIdx
    indexes:
      - key: europeanUnion
        type: NUMERIC

# Redis High availability
redis:
  architecture: replication # (default standalone)
  sentinel:
    enabled: true # enable Redis Sentinel (default false)

Inter cluster communication (Dapr)

Inter cluster communication is handled by Dapr. The following configurations can be set on the interClusterCommunication property of the main configuration.

Publication / Subscription (RabbitMQ or Redis)

Publication / subscription communication is handled by Dapr.

By default, the Helm chart will deploy a RabbitMQ instance as a message broker for publication / subscription communication.

It is also possible to use the deployed Redis instance instead of RabbitMQ by setting the pubSubMessageBroker value to Redis.

RabbitMQ

If Publication / Subscription is handled by RabbitMQ. You can set the following properties on the rabbitmq property of the inter cluster communication configuration.

Property Description Type mandatory default
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 20m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 256Mi

Resiliency

Dapr can be configured with resiliency policies.

Global resiliency policy

By default, the global retry policy on a Neos environment is the following :

policies:
  retries:
    # Neos pubsub retry policy (5 retries with 10s delay between each retry)
    neosPubsubRetries:
      policy: constant
      duration: 10s
      maxRetries: 5
targets: # https://docs.dapr.io/developing-applications/building-blocks/pubsub/pubsub-deadletter/#retries-and-dead-letter-topics
  components:
    neos-pubsub:
      inbound:
        retry: neosPubsubRetries
      outbound:
        retry: neosPubsubRetries

If you want to override this policy, you can set the globalResiliencySpec property of the inter cluster communication configuration (see this article for details).

Example :

globalResiliencySpec:
  policies:
    retries:
      DaprBuiltInServiceRetries: # Overrides default retry behavior for service-to-service calls
        policy: exponential
        maxInterval: 5s
        maxRetries: -1 # Retries indefinitely

Cluster resiliency policies

If you want to apply cluster specific resiliency policies, you set the clusterResiliencyPolicies property of the inter cluster communication configuration (see this article for details).

Example :

clusterResiliencyPolicies:
  circuitBreakers:
    pubsubCB:
      maxRequests: 1
      interval: 8s
      timeout: 45s
      trip: consecutiveFailures > 8
  retries:
    retryForever:
      policy: exponential
      maxInterval: 15s
      maxRetries: -1 # Retry indefinitely
  timeouts:
    general: 5s

Monitoring

Inter communication traces can be sent to the following tools.

Zipkin

You can set up a Zipkin deployment (optional) to monitor inter cluster communication by setting the following properties on the zipkin property of the inter cluster communication configuration.

Property Description Type mandatory default
enable Create a Zipkin instance boolean false false
host Domain for Zipkin access (from outside the Kubernetes cluster) string false
tlsSecret Name of the secret containing the TLS certificate string false
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 5m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 256Mi

Application Insights

You can send Dapr inter cluster communication traces to Application Insights by setting the following properties on the appInsights property of the inter cluster communication configuration.

Note

To create the secret containing the AppInsights instrumentation key, you can use the following command :

kubectl create secret generic <secret-name> --from-literal=APPINSIGHTS_INSTRUMENTATIONKEY="xxx-xxx-xxx-xxx"
Property Description Type mandatory default
enable Enable sending Dapr traces to application insights boolean false false
instrumentationKeySecret Name of the secret containing the APPINSIGHTS_INSTRUMENTATIONKEY environnement variable. string false
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 400Mi

Clusters

clusters is an array of business clusters and you can use the following configuration for each one of them :

Common

Property Description Type mandatory default
name Cluster name string true
databaseType Database persistence type (Oracle, PostgreSQL or SqlServer) string false
host Domain for cluster access (from outside the Kubernetes cluster) string false
tlsSecret Name of the secret containing the TLS certificate string false
logLevel Log level for business cluster Log level false Information
clusterResiliencyPolicies Cluster resiliency policies Cluster resiliency policies false

Backend

Note

Backend configuration is not mandatory.

The following properties can be set on the backend property of the cluster configuration :

Property Description Type mandatory default
image Name of the backend image to pull string true
envSecret Secret name for backend container env variables (at least PersistenceSettings__ConnectionString) string true
useSecretAsEnv Use secret as environnement variables instead of using Dapr secret store (see this article) boolean false true
imagePullSecret Secret name for docker registry authentication string false
tag Tag of the backend image to pull string false latest
appDirectory Cluster directory path in the backend container pull string false /app
port Backend exposed port number false 7000
replicas Desired number of backend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 512Mi

Warning

If you want to deploy a cluster backend image based on a Neos version prior to 1.20, you need to set useSecretAsEnv property to true.

For security reason, since version 1.20, cluster configuration is mounted using Dapr secret stores instead of environment variables.

This prevents an attacker who has compromised the backend container from retrieving confidential information simply by accessing the process's environment variables.

Indeed, the secret store allows the values to be retrieved from the store and stored in memory at the start of the application. Only the application knows how to retrieve them.

Persistent storage (Volume)

This configuration enables a Kubernetes storage class to be used to mount a volume in the backend pod.

Note

Volume configuration is not mandatory.

The following properties can be set on the volume property of the cluster backend configuration.

Property Description Type mandatory default
storageClassName Name of the Kubernetes storage class to use string true
mountPath Volume mount path inside the backend pod string true
size Volume size Memory resource units false 512Mi
accessMode Volume access mode Volume access modes false ReadWriteMany

API Documentation (Swagger)

By default, the API documentation UI (Swagger) is not exposed.

You can configure it by setting the following properties on the apiDocumentation property of the cluster backend configuration.

Property Description Type mandatory default
enabled Enable API documentation interface boolean false false
prefix Prefix for API documentation access (eg: https://<host>/<prefix>/) string false api-documentation
multitenant Expose API documentation only for multitenant endpoints (eg: https://<host>/<tenantId>/<prefix>/) boolean false api-documentation

Host aliases

Note

Host aliases configuration is not mandatory.

You can add additional host entries to your backend containers by configuring the hostAliases property of the cluster backend configuration.

Please see this article on Kubernetes documentation for more info.

Example : add a third party service IP to be resolved as a specific host

cluster:
- name: TechnicalDemos
  # ... main cluster config ...
  backend:
    # ... cluster backend config ...
    hostAliases:
    - ip: "10.1.2.3"
      hostnames:
      - "my-service.local"

In this example, if the backend create an http request on my-service.local, it will be send to the IP 10.1.2.3.

Task runner (TaskRunner)

Note

TaskRunner configuration is not mandatory.

You can configure it by setting the following properties on the taskRunner property of the cluster backend configuration.

Property Description Type mandatory default
image Name of the task runner image to pull string true
imagePullSecret Secret name for docker registry authentication string false
tag Tag of the task runner image to pull string false latest
port Task runner exposed port number false 7000
replicas Desired number of task runner instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 10m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 512Mi

Frontend

Note

Frontend configuration is not mandatory.

The following properties can be set on the frontend property of the cluster configuration :

Property Description Type mandatory default
image Name of the frontend image to pull string true
imagePullSecret Secret name for docker registry authentication string false
tag Tag of the frontend image to pull string false latest
port Frontend exposed port number false 80
replicas Desired number of frontend instances number false 1
cpuRequest CPU request (see Resource Management for Pods and Containers) CPU resource units false 5m
memory Memory request and limit (see Resource Management for Pods and Containers) Memory resource units false 64Mi
jsonConfigurationSecret Secret name for cluster frontend container additional configuration (like ApplicationInsights) string false

Nested clusters

If you want to access a cluster using another cluster url with a prefix, you can configure this "nested" cluster using the nestedClusters array property.

For example, you have a cluster TechnicalDemos and a cluster TrackingDemo. You want to display a TrackingDemo page directly in a UI of TechnicalDemos.

To do so in production, you can set the following configuration to the helm chart configuration file :

clusters:
  - name: TechnicalDemos
    host: technical-demos.example.com
    nestedClusters:
      - name: TrackingDemo
        pathPrefix: tracking
  - name: TrackingDemo
    host: tracking-demo.example.com

In this example, you should be able to access TrackingDemo cluster with the url https://technical-demos.example.com/tracking/.

Note

For development environment, please see this article.

Please see this article for an example of how to display a UI view of a nested cluster inside a main cluster UI view.

Preset

Resources (cpu / memory) and replicas can be initialized with the preset value.

Valid values : Development or Production

Note

Preset configuration is not mandatory, by default it is set to Development.

Note

Preset configuration can be overridden by setting specific replicas, cpuRequests and memory.

(replicas / cpu / memory) Development (replicas / cpu / memory) Production
Gateway 1 / 10m / 256Mi 3 / 25m / 256Mi
Report 1 / 10m / 1024Mi 3 / 25m / 2048Mi
Tenant management backend 1 / 10m / 512Mi 3 / 20m / 512Mi
Tenant management frontend 1 / 5m / 64Mi 3 / 5m / 64Mi
Notifications hub (SignalR) 1 / 5m / 128Mi 1 / 5m / 128Mi
RabbitMQ 1 / 20m / 256Mi 1 / 40m / 512Mi
Zipkin 1 / 5m / 256Mi 1 / 5m / 256Mi
Open telemetry collector (AppInsights) 1 / 10m / 400Mi 3 / 10m / 400Mi
Cluster backend 1 / 10m / 512Mi 3 / 20m / 512Mi
Cluster frontend 1 / 5m / 64Mi 3 / 5m / 64Mi
Note

Redis deployment should be handled separately according to the Bitnami chart. See this link for activating high availability in production.