--- title: "Deploying Document Engine on Kubernetes | Nutrient" canonical_url: "https://www.nutrient.io/guides/document-engine/deployment/kubernetes/" md_url: "https://www.nutrient.io/guides/document-engine/deployment/kubernetes.md" last_updated: "2026-06-11T00:00:00.000Z" description: "Kubernetes is an open source container orchestration engine for automating deployment, scaling, and management of containerized applications." --- # Deploying on Kubernetes [Kubernetes](https://kubernetes.io/) is an open source container orchestration system for deploying, scaling, and managing containerized applications. We recommend installing Document Engine with a [Helm](https://helm.sh/) chart. For more information: - Refer to the [Helm deployment](https://www.nutrient.io/guides/document-engine/deployment/helm.md) guide to install Document Engine. - Refer to the [ingress](https://www.nutrient.io/guides/document-engine/deployment/ingress.md) guide to expose it outside the cluster. - Refer to the [Helm deployment](https://www.nutrient.io/guides/document-engine/deployment/helm.md#migrate-from-docker-compose) guide if you’re moving from Docker Compose to Helm. We also provide public [examples](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples) 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](https://www.docker.com/products/docker-desktop/) for macOS, Windows, and Linux includes [Kubernetes](https://docs.docker.com/desktop/kubernetes/). #### OrbStack [OrbStack](https://orbstack.dev/) is an alternative to Docker Desktop for macOS and Linux. It includes built-in Kubernetes support. #### MicroK8s [MicroK8s](https://microk8s.io/) is a lightweight way to run Kubernetes on Linux, including single-node setups. We provide a [MicroK8s example](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples/de-aws-ubuntu-microk8s) 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](https://www.nutrient.io/guides/document-engine/deployment/horizontal-scaling.md#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: ` 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](https://www.nutrient.io/guides/document-engine/deployment/helm.md) guide for the `extraEnvs` example, and refer to the [horizontal scaling](https://www.nutrient.io/guides/document-engine/deployment/horizontal-scaling.md) guide for background on clustering behavior. ## Managed Kubernetes services Many cloud providers offer managed Kubernetes services: - [Elastic Kubernetes Service](https://aws.amazon.com/eks/) on AWS — refer to the [EKS deployment example](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples/de-aws-eks). - [Google Kubernetes Engine](https://cloud.google.com/kubernetes-engine) — refer to the [GKE deployment example](https://github.com/PSPDFKit/document-engine-reference-architecture/tree/master/examples/de-google-kubernetes-engine). - [Azure Kubernetes Service](https://azure.microsoft.com/en-us/products/kubernetes-service) --- ## Related pages - [Deploying to Amazon Web Services](/guides/document-engine/deployment/aws.md) - [Deploying on Kubernetes with Helm](/guides/document-engine/deployment/helm.md) - [Choose a Docker registry](/guides/document-engine/deployment/docker-registry.md) - [Backup and recovery](/guides/document-engine/deployment/backup-and-recovery.md) - [Horizontal scaling](/guides/document-engine/deployment/horizontal-scaling.md) - [Deploying to Google Cloud Platform](/guides/document-engine/deployment/google-cloud-platform.md) - [Document Engine deployment overview](/guides/document-engine/deployment.md) - [Application-specific timeouts](/guides/document-engine/deployment/ingress.md) - [Deploying to Microsoft Azure](/guides/document-engine/deployment/microsoft-azure-aks.md) - [Product activation](/guides/document-engine/deployment/product-activation.md)