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.