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.33)
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 version: 15.0
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

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

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

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

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

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

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" }

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"

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​

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​