On-Prem Infrastructure Requirements

This page covers all infrastructure that must be provisioned before deploying Unstract. Complete these steps first, then proceed to the Deployment Guide.

LLMWhisperer Dependency

LLMWhisperer is a required dependency for Unstract and must be deployed before deploying Unstract. Refer to the LLMWhisperer On-Prem Deployment Guide for its deployment details.

Infrastructure Prerequisites

The following infrastructure must be provisioned by the customer team before proceeding with the Helm installation. Use whatever provisioning approach follows your internal standards (Terraform, Pulumi, CloudFormation, manual setup, etc.).

Kubernetes Cluster

Recommended version: >= 1.29 (latest tested: 1.35)
Node autoscaling should be enabled
Single AZ is sufficient for standard deployments. For production HA deployments, multi-AZ is supported — see the HA Deployment Guide
Ingress controller as a K8s cluster add-on for load balancer creation (recommended)
- Ingress requires a maximum timeout of 900 seconds to work as expected (see Appendix c)
In-house or cloud provider observability stack (recommended)

PostgreSQL Database

Supported versions: 15 or 17
Minimum specs: 1 vCPU, 8 GiB RAM, 50 GiB SSD
Autoscale enabled (recommended)
A dedicated database for Unstract should be created within the PostgreSQL instance

Object Storage

Managed blob storage: AWS S3 / Azure Blob Storage / GCP GCS
IAM / service principal with read/write access to the target bucket or container
See Remote Storage Configuration for detailed setup

Message Broker (RabbitMQ)

Unstract uses RabbitMQ as its task message broker — it is required for every deployment. RabbitMQ runs in-cluster (there is no external service to provision): the chart provisions a RabbitmqCluster custom resource, which is reconciled by the RabbitMQ Cluster Operator.

The operator is cluster-scoped and is installed once per cluster as part of the required LLMWhisperer on-prem setup (the LLMWhisperer dependency noted at the top of this page). No separate Unstract step installs it, but the operator must already be present before you deploy Unstract.

DNS & SSL

A domain for pointing to Unstract (e.g., unstract.<customer-domain>.com)
An active SSL certificate is required — HTTPS is mandatory for the authentication system to function properly

Networking

Recommend allocating a subnet of /18 CIDR size for pods
Recommended: use a CNI that enforces NetworkPolicy — for example GKE with Dataplane V2, Calico, Cilium, or OpenShift's OVN-Kubernetes. Without an enforcing CNI, NetworkPolicy objects are accepted by the Kubernetes API server but never applied, so any pod in the cluster can reach any other pod's ports — including Unstract's in-cluster Redis. See Restricting Redis Network Access.

Node Profile

Machine Type	Label	Taint (NoSchedule)	Min	Max
4 vCPU and 32 GiB	`service: unstract`	`service: unstract`	2	4

The above is a small profile suitable for initial setup. For production sizing, see Appendix b.

It is expected that the workloads are to be deployed on non-spot nodepools.

Remote Storage Configuration

AWS

For EKS deployments, IRSA (IAM Roles for Service Accounts) is the recommended authentication method. It eliminates static credentials and provides per-pod scoped permissions for S3 and Bedrock. The full setup — S3 bucket creation, IAM policies, OIDC provider association, role + trust policy, Helm wiring, and verification — is covered in a dedicated guide:

➡️ AWS IRSA Setup for EKS Deployments (available from v0.158.4)

For non-EKS deployments or environments where IRSA is not available, use static credentials:

Static Credentials

on-prem.values.yaml:

PERMANENT_REMOTE_STORAGE: &PERMANENT_REMOTE_STORAGE '{"provider": "s3", "credentials": {"key":"<s3-access-key>","secret":"<s3-access-secret>","endpoint_url":"<s3-endpoint-url>"}}'

Config placeholder	Expected credential
`s3-access-key`	AWS access key
`s3-access-secret`	AWS secret key
`s3-endpoint-url`	e.g. `https://s3.ap-south-1.amazonaws.com/`

Common Helm Values

values.yaml — replace <s3-bucket-name> with your S3 bucket name:

backend:
  configMap:
    REMOTE_SIMPLE_PROMPT_STUDIO_FILE_PATH: <s3-bucket-name>/simple-prompt-studio-data
    REMOTE_PROMPT_STUDIO_FILE_PATH: <s3-bucket-name>/prompt-studio-data

platform:
  configMap:
    MODEL_PRICES_FILE_PATH: <s3-bucket-name>/cost/model_prices.json

prompt:
  configMap:
    REMOTE_PROMPT_STUDIO_FILE_PATH: <s3-bucket-name>/prompt-studio-data

Azure

Helm Chart Values

on-prem.values.yaml:

PERMANENT_REMOTE_STORAGE: &PERMANENT_REMOTE_STORAGE '{"provider": "abfs", "credentials": {"account_name":"<azure-account-name>","access_key":"<azure-access-key>","connection_string":"<azure-connection-string>"}}'

Config placeholder	Expected credential
`azure-account-name`	Azure account name
`azure-access_key`	Azure access key
`azure-connection_string`	E.g. `DefaultEndpointsProtocol=https;AccountName=xxxxxxx;AccountKey=xxxxx;EndpointSuffix=core.windows.net`

values.yaml — replace azure-container-name with applicable Azure container name:

backend:
  configMap:
    REMOTE_SIMPLE_PROMPT_STUDIO_FILE_PATH: <azure-container-name>/simple-prompt-studio-data
    REMOTE_PROMPT_STUDIO_FILE_PATH: <azure-container-name>/prompt-studio-data

platform:
  configMap:
    MODEL_PRICES_FILE_PATH: <azure-container-name>/cost/model_prices.json

prompt:
  configMap:
    REMOTE_PROMPT_STUDIO_FILE_PATH: <azure-container-name>/prompt-studio-data

Appendix

a. Cluster Nodes Config

Minimum spec: 4 vCPU / 32 GiB
Node autoscaling should be enabled
Node Groups are optional based on the profile
Single AZ is sufficient for standard deployments
- For production HA deployments with Redis Sentinel, RabbitMQ quorum queues, and MinIO HA, multi-AZ is supported — see the HA Deployment Guide

b. Cluster Size Profiles

Small Profile (not recommended for high volume)

No autoscaling (can be enabled if required)
Only one default Node Group

Machine Type	Label	Taint (NoSchedule)	Min	Max
4 vCPU and 32 GiB	`service: unstract`	`service: unstract`	2	4

Production Profile

Different Node Groups based on workloads
Add 50 GiB SSD for application data to each machine

Machine Type	Label	Taint (NoSchedule)	Min	Max
4 vCPU and 32 GiB	`service: unstract`	`service: unstract`	5	16

It is expected that the workloads are to be deployed on non-spot nodepools.

c. Ingress Setup

All ingress types must support a 900-second timeout.

The unstract-backend service requires WebSocket connections (used for real-time log streaming and execution status updates). Most controllers proxy the WebSocket Upgrade/Connection handshake automatically, but depending on the ingress controller, additional annotations may be required to enable or preserve it. The per-controller notes below call out where this applies — verify WebSocket support for the controller installed in your cluster.

AWS ALB Ingress Controller

Ingress configuration in EKS Auto Mode

Required annotation:

# REF: https://kubernetes-sigs.github.io/aws-load-balancer-controller/latest/how-it-works/#ip-mode
alb.ingress.kubernetes.io/target-type: ip

WebSocket: the ALB handles WebSocket traffic natively, so no upgrade annotation is needed. Raise the connection idle timeout so long-lived sockets are not dropped:
```
alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=900
```
note
load-balancer-attributes is a single annotation holding a comma-separated list of key=value pairs. If you already set it for other purposes (e.g. access logging), append the idle timeout rather than adding a second entry — a duplicate annotation key silently overrides the first: idle_timeout.timeout_seconds=900,access_logs.s3.enabled=true.

Nginx Ingress Controller

Recommended ingress controller for Azure AKS
Two Nginx Ingress Controllers are commonly deployed and they use different, mutually exclusive annotation prefixes. Pick the annotation set that matches the controller installed in your cluster — do not mix the two:
- Community Ingress Controller (kubernetes/ingress-nginx) — uses the nginx.ingress.kubernetes.io/* prefix.
- NGINX Ingress Controller (maintained by F5 NGINX) — uses the nginx.org/* prefix.
In both cases, set the controller via spec.ingressClassName: nginx on the Ingress resource (preferred since Kubernetes 1.18). The legacy kubernetes.io/ingress.class: nginx annotation still works for older clusters but is deprecated.

Option A — Community Ingress Controller

# Selects the ingress controller. Deprecated since K8s 1.18 in favor of
# spec.ingressClassName, but still honored as a fallback by the controller.
kubernetes.io/ingress.class: nginx

# Must be increased from default 60 to 900.
nginx.ingress.kubernetes.io/proxy-read-timeout: "900"

# Must be increased from default 1 MB for large document uploads.
nginx.ingress.kubernetes.io/proxy-body-size: "200m"

# Forces X-Forwarded-Proto=https when AWS NLB terminates TLS upstream.
# Requires --allow-snippet-annotations=true on the controller (off by default since v1.9.0).
nginx.ingress.kubernetes.io/configuration-snippet: |
  access_by_lua_block { ngx.var.pass_access_scheme = "https" }

WebSocket: handled automatically by this controller — no extra annotation needed. The proxy-read-timeout: "900" above also keeps idle WebSocket connections alive.

Option B — NGINX Ingress Controller (F5 NGINX)

# Selects the ingress controller. Deprecated since K8s 1.18 in favor of
# spec.ingressClassName, but still honored as a fallback by the controller.
kubernetes.io/ingress.class: nginx

# Default is 60. Must be increased to 900.
nginx.org/proxy-read-timeout: "900"

# Default is 1 MB. Must be increased for large document uploads.
nginx.org/client-max-body-size: "200m"

# Required when using AWS NLB (Layer 4) with TLS termination.
# NLB does not inject X-Forwarded-Proto, causing http:// callback URLs.
nginx.org/proxy-set-headers: "X-Forwarded-Proto: https"

# WebSocket: this controller does NOT proxy WebSockets by default. The backend
# service must be listed here, or log streaming / status updates will fail.
nginx.org/websocket-services: "unstract-backend"

Configure Nginx to work with AWS EKS

warning

If you are using the Community Ingress Controller (kubernetes/ingress-nginx), avoid using the nginx.ingress.kubernetes.io/rewrite-target annotation. In Community NGINX Controller versions >= v0.22.0, the old rewrite-target: / syntax causes authentication failures (401 Unauthorized responses). If you encounter login issues, remove any rewrite-target annotations from your ingress configuration.

d. Container Images

For the full list of container images used by the Unstract Platform Helm chart, including instructions for mirroring, registry overrides, and pre-pulling, see the dedicated Container Images Reference.

Infrastructure Prerequisites​

Kubernetes Cluster​

PostgreSQL Database​

Object Storage​

Message Broker (RabbitMQ)​

DNS & SSL​

Networking​

Node Profile​

Remote Storage Configuration​

AWS​

Static Credentials​

Common Helm Values​

Azure​

Appendix​

a. Cluster Nodes Config​

b. Cluster Size Profiles​

c. Ingress Setup​

d. Container Images​