> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/solution-architecture/deployment/kubernetes-topologies.md). # Kubernetes topologies The two shipped Kubernetes shapes — a single-worker non-production cluster and a three-worker production cluster — what each assumes, what OpenShift adds, and what Kubernetes does not buy you. ## What this is, and when you need it Two of the nine shipped topologies deploy OpenIAM as container workloads on Kubernetes. This page sets out what each assumes, what the container substrate genuinely buys, and — the part that decides most arguments — what it does not. It is the right page when the organization already runs clusters and somebody has asked whether OpenIAM should be one more tenant of that capability. The decision is whether to deploy on Kubernetes at all, and if so which of the two shapes. It belongs to the platform team as much as to the identity team, because on Kubernetes the operational load moves to whoever runs the cluster. ## The decision | Topology | Cluster | What it assumes | What it is for | | --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **8. Non-production** | One cluster, one worker node | A managed cache and a managed database; everything else in-cluster | Exercising the production manifests end to end on a single worker. Development, demonstration, upgrade rehearsal | | **9. Production** | One cluster, three worker nodes | A managed graph store, a managed cache and a highly available managed database; the broker, the secrets store and the search tier in-cluster | Production. Three replicas of every workload, rolling upgrades, and a declarative deployment path | The distinction between them is a single number. The shipped cluster modules provision **one node pool whose size is the replica count**, and the same replica count sets the number of replicas of every OpenIAM workload. A one-worker cluster therefore runs one of everything; a three-worker cluster runs three of everything. There is no autoscaling in the shipped modules and no second node pool. ## What the container deployment consists of Each OpenIAM service, each console and each connector is its own workload with its own Helm chart. The backend services, the consoles and the identity provider, the reverse proxy, the message broker, the cache, the search tier, the graph, Cassandra, the secrets store and its Consul backend, and the database migration job all deploy this way. Roughly two dozen Java connectors ship as charts of their own, each attaching to the broker. Two things follow that are worth stating in a design review. **The shipped values set three replicas for every service and every console.** That is the production default the material is written around, and it is why the production shape is three workers: with one worker, three replicas of a workload would all be on the same machine, which buys nothing. **A declarative deployment path ships.** There is a set of Argo CD application manifests, one per service, each configured to sync automatically with pruning and self-healing, together with a chart that creates the namespaces for an environment and a cluster add-on for pulling secrets from an external store. If your organization already runs GitOps, OpenIAM fits that model without adaptation. If it does not, this material is not a reason to adopt it. ## What Kubernetes does not buy you here Three assumptions are common and all three are wrong. **Kubernetes is not an availability strategy on its own.** Availability still comes from the node count, because a workload's replicas can only be spread across the workers that exist. A single-worker cluster is exactly as available as a single virtual machine, and it fails the same way. The Kubernetes shapes map onto the same three-node threshold as every other topology in the catalogue. **There is no separate infrastructure node pool.** The topology 3 and topology 4 separations — moving the broker, cache and search tier off the service nodes, and later moving the consoles off as well — have no direct equivalent in the shipped Kubernetes modules, which provision one uniform pool. You can of course achieve the same isolation with node pools, taints and affinity rules of your own, but that is your design rather than shipped material, and you should say so when you present it. **The stateful tier does not become stateless because it is in a container.** The broker, the secrets store, the search tier and — where the graph is not managed — JanusGraph and Cassandra all run in the cluster with persistent volumes. Running a database or a search cluster on Kubernetes is a skill; if the platform team does not have it, moving OpenIAM to Kubernetes moves the difficulty rather than removing it. This is the strongest argument for pairing topology 9 with managed platform services wherever they exist. ## What the cluster has to provide The shipped modules provision the cluster on all three major clouds, and each has requirements worth knowing before the platform team sizes anything. **A worker size floor.** The shipped module documentation states a minimum worker machine type on AWS and on Google Cloud, and both floors are around four virtual CPUs and sixteen gigabytes of memory. The reference production figure quoted in OpenIAM's deployment material is larger than that, which is consistent: the floor is what the deployment will start on, not what a production estate should run on. [Sizing](/solution-architecture/deployment/sizing.md) covers the difference and where each number comes from. **A tested Kubernetes version.** The shipped material names the Kubernetes version the Terraform and Helm charts are tested against; deploying onto a materially older or newer cluster is a support conversation. Check the version before the platform team schedules its own upgrade. **Persistent storage with a default class.** Every stateful component in the cluster claims volumes. The shipped material handles the common case and includes handling for clusters where a non-default storage class needs to be made default. **A private cluster, on at least one platform.** The Azure module provisions a private cluster and expects a separate deployment host in a peered network that can reach it and the private database endpoint. That is a network design item, not an installation step, and it needs agreeing early. ## OpenShift OpenShift is supported and ships its own material: Helm setup for both Linux and Windows workstations, its own custom values for the database, cache, broker, search tier, Cassandra, the graph, the secrets store and the reverse proxy, its own storage class and the role and role-binding definitions that storage class needs, and a set of OpenShift templates for the application and its configuration. The practical consequence for a design is that OpenShift is a first-class target rather than "generic Kubernetes, which should work". The differences that the extra material exists to handle are the ones you would expect — security context constraints, storage class ownership, and the platform's own template mechanism — and they are handled rather than left to you. **Tanzu is not present in the shipped material.** Do not commit to it in a design or a bid. ## Where the images come from One decision that only exists on the container substrate: which registry the images are pulled from. The default is OpenIAM's own registry. For estates that cannot pull from the internet, or that require images to be scanned and admitted through their own supply chain, the shipped material includes setup for a self-hosted registry and a utility for copying the release's images into a registry of your own. That is a genuine architectural choice with consequences for upgrades — every version bump becomes a copy operation into your registry first — and it should be made at design time rather than discovered when the first air-gapped environment is built. [Environments and tenancy](/solution-architecture/deployment/environments-and-tenancy.md) covers how this interacts with promotion between environments. ## What we recommend **Deploy OpenIAM on Kubernetes if the organization already runs Kubernetes well, and not otherwise.** Where a platform team already operates clusters, a registry and a deployment pipeline, topology 9 adds less operational load than any virtual-machine shape, because most of the load is already being carried. Where it does not, adopting Kubernetes for OpenIAM means learning two things at once and is usually the more expensive path. **Pair topology 9 with managed platform services.** The combination that works best is a cluster running the stateless services with the database, cache and — where available — the graph store outside it. That leaves the broker, the secrets store and the search tier in-cluster, which is a manageable amount of stateful workload. **Use topology 8 for what it is for.** A single-worker cluster is the right place to rehearse an upgrade against the real manifests. It is not a small production deployment. **If you run OpenShift, say so early.** The material exists, but the storage class and security context work is different enough that a design assuming generic Kubernetes will need revisiting. The circumstance that changes this advice is an organization whose only deployment path is containerised — where virtual machines are not offered as a service. There, topology 9 is the answer regardless of the team's Kubernetes maturity, and the mitigation is to take every managed platform service available so that as little stateful workload as possible runs in the cluster. ## What OpenIAM does not do here * **Tanzu is not shipped.** OpenShift is. * **The shipped cluster modules provision one node pool and do not autoscale.** Node count equals replica count, set at deployment time. * **There is no shipped Kubernetes equivalent of the separated infrastructure or console tiers.** Achieving that isolation is your own scheduling design. * **The container deployment offers no search-engine choice.** OpenSearch is the only search chart that ships; the Elasticsearch alternative exists only on the packaged Linux path. * **Neither Kubernetes shape removes the message broker or the secrets store from the cluster.** There is no managed option for either on any platform. ## Related * [Choosing a topology](/solution-architecture/deployment/choosing-a-topology.md) — where these two sit among the nine. * [Platform support matrix](/solution-architecture/deployment/platform-support-matrix.md) — what each cloud will run for you outside the cluster. * [Environments and tenancy](/solution-architecture/deployment/environments-and-tenancy.md) — namespaces, registries and what moves between environments. * [Sizing](/solution-architecture/deployment/sizing.md) — worker sizing, and where the reference figures come from. * *Where settings live* in the Administration Guide — the configuration layers a container deployment still has to carry. * The [Installation Guide](/installation/installation.md) — building the cluster and deploying the charts. *Applies to OpenIAM 2026.8.1. Last reviewed 7 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/solution-architecture/deployment/kubernetes-topologies.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.