Scaling in Dossier Organizer

Description

Our recommendation for production is to deploy at least two pods of organizer, viewer, and worker-topdf to ensure reliability and scalability. See Sizing article for exact recommendations.

Scaling the Dossier Organizer application for production environments requires setting up a session stickiness mechanism to ensure that all requests from the same user session are always routed to the same server instance.

Session Stickiness

Sticky sessions (also known as Session affinity), ensure that requests from the same user in a Session are always routed to the same server instance.

Session stickiness can be configured either by the used Loadbalancer or Ingress plugin inside the cluster environment. The exact configuration varies depending on the used components and has to be configured accordingly.

Viewer

The Jadice Web Toolkit is used as the main viewer in most installations. For better performance and efficiency, the viewer caches document data locally. It is essential to configure session stickiness for viewer pods so that all requests from the same user session are always routed to the same viewer pod instance. This ensures consistent access to cached data and avoids issues with session state.

To achieve this, configure your Ingress or LoadBalancer to use sticky sessions (for example, using cookie-based affinity). For NGINX Ingress, this can be done with annotations such as:

nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "route"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"

The Kubernetes service name that should be handled this way is fusion-dossier-organizer-viewer.

Organizer

Only if the organizer has no external database configured, as described in the alternatives section of the database configuration, session stickiness is required for the organizer. This ensures that all requests from a user are using the same database.

The Kubernetes service name that has to be handled this way is fusion-dossier-organizer.

Scaling instances

After all prerequisites are handled we are able to scale instances of all Organizer services. In the Dossier Organizer Helm chart all subcomponents have a field replicaCount that is used to increase the scaling as needed:

organizer:
  replicaCount:   # number of organizer pods
viewer:
  replicaCount:   # number of viewer pods
controller:
  replicaCount:   # number of controller pods
worker-topdf:
  replicaCount:   # number of export worker pods

Autoscaling

Instead of statically setting the number of pods via replicaCount, each subcomponent can be scaled automatically based on resource utilization using a Horizontal Pod Autoscaler (HPA). When autoscaling is enabled, Kubernetes adjusts the number of pods between minReplicas and maxReplicas to keep CPU and memory utilization around the configured targets.

Configure autoscaling per subcomponent in your values.yaml file:

organizer:
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPUUtilizationPercentage: 80
    targetMemoryUtilizationPercentage: 80

Property	Description
enabled	Enables the Horizontal Pod Autoscaler for the subcomponent. When true, replicaCount is ignored.
minReplicas	Minimum number of pods the autoscaler will maintain.
maxReplicas	Maximum number of pods the autoscaler may scale up to.
targetCPUUtilizationPercentage	Target average CPU utilization across pods that triggers scaling.
targetMemoryUtilizationPercentage	Target average memory utilization across pods that triggers scaling.

The same autoscaling block can be applied to the viewer, and worker-topdf subcomponents.

When using autoscaling, make sure the prerequisites described in the sections above are met — in particular, a shared database and shared storage. Also ensure session stickiness is configured where required, since the autoscaler may add or remove pods at any time.