> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/plan/architecture/deploy-kubernetes/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server. # Deploy with Kubernetes > Deploy Itential Platform on Kubernetes using validated designs for Amazon EKS and Azure AKS. Itential provides Helm charts for deploying Platform on Kubernetes. This page covers prerequisites, node sizing, secrets management, Helm chart architecture, adapter delivery, and validated configurations for Amazon EKS and Azure AKS. Itential Helm charts install Platform and Gateway only — not their dependencies. You must provide MongoDB and Redis separately. Neither Memcache nor MySQL can substitute for these dependencies. ## Prerequisites ### Cluster requirements * Kubernetes 1.31 or later * A cluster on a [validated provider](#validated-providers) that meets the [sizing recommendations](#size-your-nodes-and-distribute-pods) * Administrative access to the cluster, or access to the namespace where Itential applications will run ### Required tools | Tool | Version | Notes | | ------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Helm | 3.15.0 or later | Required to use Itential Helm charts | | cert-manager | — | Manages TLS certificates; see the [cert-manager project](https://cert-manager.io/) | | ExternalDNS | — | Optional but recommended; automates DNS entry creation for exposed services; see the [ExternalDNS project](https://github.com/kubernetes-sigs/external-dns) | ## Size your nodes and distribute pods Platform requires significant resources to run production automations. Requirements vary based on automation rate, complexity, and the number of adapters. Development environments often have similar resource needs to production because engineers experiment with real automations in development. Avoid undersizing development environments. If you are starting fresh with Itential, begin with minimum specifications and scale as needed. If you are an existing Itential customer migrating to Kubernetes, match your current resource specifications. ### Minimum specifications | Resource | Specification | | ------------ | ------------------ | | CPU | 4 cores | | RAM | 16 GB | | AWS EC2 type | m5a.xlarge | | Azure type | Standard\_D4as\_v5 | ### Production specifications | Resource | Specification | | ------------ | ------------------- | | CPU | 16 cores | | RAM | 32 GB | | AWS EC2 type | c6a.4xlarge | | Azure type | Standard\_F16as\_v5 | The instance types above are starting points. As production usage reveals your automation patterns, you may shift to memory-optimized (r5a) or general-purpose (m5a) instance types on AWS. ### Pod distribution Schedule [StatefulSet](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) containers on dedicated nodes in separate availability zones, with one Platform pod per node. This provides continuity if an availability zone experiences an outage. ## Manage secrets Manage secrets outside Kubernetes and inject them at deploy time using your preferred secrets management method. Three types of secrets are required before deploying. ### Image pull secrets Create an image pull secret to authenticate with your container registry. For AWS deployments, Platform images are hosted in Amazon ECR — configure credentials for an ECR-enabled account. This secret must exist in the cluster before deploying Itential applications. ### TLS secrets If TLS is enabled, create a secret named `itential-ca` containing the TLS Certificate Authority (CA) certificate. This CA is used to generate all other TLS certificates used by Itential applications. This secret must exist in the cluster before deploying with TLS enabled. ### Application secrets Each Itential application (Platform, Gateway 4, Gateway 5) requires application-specific secrets including encryption keys, database passwords, and other sensitive configuration values. These secrets must exist in the cluster before deploying. For the required structure of each application's secrets object, refer to the Itential Helm charts documentation. ## Helm chart architecture Itential provides Helm charts for three products: * Itential Platform * Itential Gateway version 4 * Itential Gateway version 5 The following diagram shows the architecture of the Itential Kubernetes environment: ### Ingress The Ingress provides external cluster access and supports a static hostname. It contains load balancer configuration and routing rules. ExternalDNS synchronizes exposed Services and Ingresses with your DNS provider automatically. While not required, it removes the need to manage DNS records manually. ### Services Two services are created per application: * A standard service that routes traffic to all pods * A headless service that routes traffic to individual pods directly (required for certain features) ### StatefulSet Platform runs as a StatefulSet to maintain predictable pod names and persistent volume mounts across restarts. ### Certificates and issuer When TLS is enabled (`useTLS: true` in Helm values), the chart uses a CA stored in your cluster to generate certificates through a Kubernetes Issuer. The issued certificates are stored in a Secret that pods mount at runtime. Adding the CA to the cluster is outside the scope of this guide. If cert-manager is unavailable, add TLS certificates manually in a secret named `-tls-secret` with these keys: | Key | Description | | ------------------- | ----------------------------------------------- | | `tls.crt` | The TLS certificate for this server | | `tls.key` | The private key for this certificate | | `certificateca.crt` | The CA used to generate the certificate and key | ### StorageClass If you use persistent volumes for adapters, a StorageClass is required to provision storage automatically. It defines the storage type to create (such as AWS EBS or Azure Managed Disks) and creates disk volumes when pods request storage. Do not use EFS or NFS volumes. These volume types introduce application latency. Start with 10 GB of disk space and adjust based on the number of adapters deployed. ## Add adapters and customizations Adapters can be delivered to your Kubernetes deployment using two methods: persistent volumes or layered containers. ### Choose a method Use **persistent volumes** if you: * Update adapters frequently * Want to update adapters without rebuilding container images * Prefer to manage adapter lifecycle separately from container deployments Use **layered containers** if you: * Need portable, self-contained deployments * Update adapters infrequently * Want adapter versions tied to specific container builds ### Persistent volumes Store adapters on a persistent disk volume that is mounted into the container at runtime. 1. Add a persistent volume accessible at `/opt/itential/platform/services/custom`. 2. Place your adapter directories in that location. When you update files on the volume, restart the affected adapter from the Itential Platform UI or API — a full container restart is not required. Use dedicated volumes per container. Shared volumes reduce performance. ### Layered containers Build adapters directly into the container image. #### Clone and compile each adapter ```bash mkdir -p /adapters cd /adapters git clone git@gitlab.com:itentialopensource/adapters/adapter-email.git git clone git@gitlab.com:itentialopensource/adapters/adapter-servicenow.git git clone git@gitlab.com:itentialopensource/adapters/adapter-panorama.git npm install adapter-email npm install adapter-servicenow npm install adapter-panorama ``` #### Create a Dockerfile using the Itential image as the base ```dockerfile FROM USER root RUN mkdir -p /opt/itential/platform/services/custom COPY adapters/adapter-email /opt/itential/platform/services/custom/adapter-email COPY adapters/adapter-panorama /opt/itential/platform/services/custom/adapter-panorama COPY adapters/adapter-servicenow /opt/itential/platform/services/custom/adapter-servicenow RUN chown -R itential:itential /opt/itential/platform/services/custom RUN chmod -R 775 /opt/itential/platform/services/custom USER itential ``` #### Build the image Build the image using your standard Docker build process. Consider using a CI/CD pipeline (GitHub Actions, GitLab CI/CD, or Jenkins) to automate adapter retrieval, compilation, and container builds as your adapter set grows. ## Validated providers Itential has validated Kubernetes deployments on the following providers: * Amazon Elastic Kubernetes Service (EKS) * Azure Kubernetes Service (AKS) Contact Itential for information about additional providers. ### Amazon EKS Amazon EKS manages the Kubernetes control plane. You maintain only the VMs needed to run pods. #### Ingress controller Two ingress controllers are supported on EKS: * **AWS Load Balancer Controller (recommended)**: Integrates directly with AWS Application Load Balancers. Provides native AWS integration with features like AWS WAF, AWS Certificate Manager, and VPC networking. * **NGINX Ingress Controller**: Sits behind an AWS Network Load Balancer or Classic Load Balancer. #### AWS Load Balancer Controller — example annotations ```yaml annotations: alb.ingress.kubernetes.io/backend-protocol: "HTTPS" alb.ingress.kubernetes.io/healthcheck-path: "/health/status?exclude-service=true" alb.ingress.kubernetes.io/healthcheck-port: "3443" alb.ingress.kubernetes.io/healthcheck-protocol: "HTTPS" alb.ingress.kubernetes.io/healthcheck-interval-seconds: "15" alb.ingress.kubernetes.io/healthcheck-timeout-seconds: "5" alb.ingress.kubernetes.io/healthy-threshold-count: "2" # Include port 8080 if using Gateway Manager with Gateway 5, otherwise remove it alb.ingress.kubernetes.io/listen-ports: '[{"HTTPS": 443},{"HTTPS": 8080}]' alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=60 alb.ingress.kubernetes.io/load-balancer-name: "itential-iap-lb" alb.ingress.kubernetes.io/scheme: "internet-facing" alb.ingress.kubernetes.io/success-codes: "200" alb.ingress.kubernetes.io/target-type: "ip" alb.ingress.kubernetes.io/unhealthy-threshold-count: "2" alb.ingress.kubernetes.io/websocket-paths: "/ws" alb.ingress.kubernetes.io/target-group-attributes: stickiness.enabled=true,stickiness.lb_cookie.duration_seconds=3600 ``` These annotations configure the ALB to use HTTPS for backend traffic, check application health every 15 seconds, enable WebSocket support, and maintain session stickiness for one hour. Adjust timeouts, health check intervals, and other values to match your deployment. #### NGINX Ingress Controller — example annotations (EKS) ```yaml ingress: annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" nginx.ingress.kubernetes.io/health-check-path: "/health/status?exclude-service=true" nginx.ingress.kubernetes.io/websocket-services: "iap-service" nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/force-ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-connect-timeout: "60" external-dns.alpha.kubernetes.io/hostname: itential.example.com external-dns.alpha.kubernetes.io/ttl: "300" ``` #### Storage configuration If using persistent volumes for adapters, configure your StorageClass to use `ebs.csi.aws.com` as the provisioner. ### Azure AKS Azure AKS manages the Kubernetes control plane. You maintain only the pods and Kubernetes components. #### Ingress controller The validated design for AKS uses the NGINX Ingress Controller behind an Azure Load Balancer. #### NGINX Ingress Controller — example annotations (AKS) ```yaml ingress: annotations: nginx.ingress.kubernetes.io/backend-protocol: "HTTPS" nginx.ingress.kubernetes.io/health-check-path: "/health/status?exclude-service=true" nginx.ingress.kubernetes.io/websocket-services: "iap-service" nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" nginx.ingress.kubernetes.io/ssl-redirect: "true" nginx.ingress.kubernetes.io/force-ssl-redirect: "true" nginx.ingress.kubernetes.io/proxy-connect-timeout: "60" external-dns.alpha.kubernetes.io/hostname: itential.example.com external-dns.alpha.kubernetes.io/ttl: "300" # Use an internet-facing Azure Load Balancer service.beta.kubernetes.io/azure-load-balancer-internal: "false" ``` These annotations configure NGINX to use HTTPS for backend traffic, enable WebSocket support with one-hour timeouts, force SSL redirects, and attach an internet-facing Azure Load Balancer. Adjust SSL settings, timeouts, and load balancer type to match your deployment. #### Storage configuration If using persistent volumes for adapters, configure your StorageClass to use `disk.csi.azure.com` as the provisioner. ## Related reading * [Deployment overview](./overview) * [Deploy with containers](./deploy-containers) * [Platform properties reference](/itential-platform/configure/environment-variables-properties-reference) * [ExternalDNS project](https://github.com/kubernetes-sigs/external-dns) * [cert-manager project](https://cert-manager.io/) > Deploy Itential Platform on Kubernetes using validated designs for Amazon EKS and Azure AKS.