This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/document-engine/deployment/kubernetes.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Deploying Document Engine on Kubernetes | Nutrient

Deploying on Kubernetes

Markdown version of this page, suitable for AI agents and automation

Kubernetes(opens in a new tab) is an open source container orchestration system for deploying, scaling, and managing containerized applications.

We recommend installing Document Engine with a Helm(opens in a new tab) chart.

For more information:

  • Refer to the Helm deployment guide to install Document Engine.
  • Refer to the ingress guide to expose it outside the cluster.
  • Refer to the Helm deployment guide if you’re moving from Docker Compose to Helm.

We also provide public examples(opens in a new tab) for setting up a Kubernetes cluster and installing Document Engine.

Get Kubernetes

Run Kubernetes locally or use a managed service in the cloud.

Local Kubernetes

For development and testing, run Kubernetes locally with one of these tools.

Docker Desktop

Docker Desktop(opens in a new tab) for macOS, Windows, and Linux includes Kubernetes(opens in a new tab).

OrbStack

OrbStack(opens in a new tab) is an alternative to Docker Desktop for macOS and Linux. It includes built-in Kubernetes support.

MicroK8s

MicroK8s(opens in a new tab) is a lightweight way to run Kubernetes on Linux, including single-node setups.

We provide a MicroK8s example(opens in a new tab) that shows how to deploy an Ubuntu virtual machine on AWS, set up MicroK8s, and install Document Engine.

Clustering on Kubernetes

If you run multiple replicas, enable clustering so document-scoped requests go to one owner node per document.

On Kubernetes:

  • Set CLUSTERING_ENABLED=true on every replica.
  • Set CLUSTERING_METHOD=kubernetes_dns.
  • Make sure a headless Service exists whose name matches CLUSTERING_SERVICE_NAME — the default is document-engine, and the Helm chart creates this Service by default.
  • Keep readiness probes enabled, because a node owns documents only after its endpoint is ready.

Short periods without ownership during rollouts are expected and safe. During healthy joins, expect Local endpoint is ready. Broadcasting readiness to cluster peers followed by Cluster handshake completed (with peer: <node> metadata) before a node starts owning documents. During rolling restarts, Removing it from the ring messages are normal when an old pod exits, as long as replacement pods are discovered and complete the cluster handshake.

Refer to the Helm deployment guide for the extraEnvs example, and refer to the horizontal scaling guide for background on clustering behavior.

Managed Kubernetes services

Many cloud providers offer managed Kubernetes services: