opensearch-k8s-operator runs OpenSearch clusters as a custom resource

A cluster becomes a custom resource instead of a manifest pile

The operator's job is described in one sentence and it is a broad one: it automates the deployment, provisioning, management and orchestration of OpenSearch clusters and OpenSearch Dashboards. The unit of work is the OpenSearchCluster custom resource, and after the operator is installed you deploy your first cluster by creating one, with the details of the configuration in the User Guide. That is the whole pitch, and it is the standard operator pattern, so anyone who has deployed a database operator before will recognise the shape. The repository layout backs it up, with the operator code under an opensearch-operator directory, a charts directory for the Helm chart, a docs directory holding the user guide and separate developer documentation, and a scripts directory. The Go workspace setup with go.work and go.work.sum at the top level tells you the project is split into multiple modules rather than a single one.

Node pools, roles and per pool scaling are the unit of control

The feature list explains what the custom resource actually models, and the first three entries are the ones that matter most. You can deploy and manage OpenSearch clusters with multiple node pools, which is the difference between an operator and a stateful set with a ConfigMap. You can configure all node roles, with cluster_manager, data, ingest and coordinating named as examples, which is how OpenSearch separates duties in a way that a single uniform deployment cannot express. And you can scale cluster resources manually, per node pool. The design consequence is that the resource is not a single cluster spec but a set of pools with their own settings, so a cluster that mixes dedicated ingest nodes with data nodes is expressed directly rather than approximated. The other half of the cluster object is the dashboard, since the operator deploys and configures OpenSearch Dashboards as well, which is what makes the whole thing usable rather than just runnable.

Rolling upgrades, disk growth and TLS reload are the operational features

The middle of the feature list is where an operator earns its keep, because these are the operations that break at three in the morning. Rolling version upgrades with quorum-safe restarts means the operator restarts nodes in an order that keeps the cluster available, which is the single most requested feature in this category. Online volume expansion for disk scaling handles the case where the data outgrows the provisioned volume, and doing it online avoids the outage that a resize with a restart implies. Certificate management with TLS hot reloading means the operator issues and rotates certificates and applies them without a restart, and for a cluster that talks to a service mesh or to clients outside the cluster, certificate expiry is a routine cause of downtime. Plugin installation during the bootstrap phase covers the case where a cluster needs an analysis plugin from the start, since installing one later is a different operation with a different failure mode.

Multi-namespace support decides whether one operator can serve several teams

Multi-namespace support for managing clusters across organizational boundaries is the feature that changes the deployment topology. Without it, an operator that watches one namespace is a per-team tool, and platform teams end up running several instances. With it, one operator can serve clusters for different organizational boundaries, which is what a shared platform needs. The trade is that the custom resource is available in more than one namespace, so the permissions model, the certificate handling and the resource limits all have to be thought about as a platform concern rather than an application one. The repository also carries a MAINTAINERS.md and a RELEASING.md, and the CI configuration in the .github directory shows separate workflows for the docker build, the tests, the linting and the Helm release, which is the release plumbing a project with an image, a chart and a set of Go modules needs.

Installing the operator is two Helm commands

The install path is short, which is a deliberate choice for a project people evaluate quickly. The operator can be installed using Helm on any CNCF-certified Kubernetes cluster, starting by adding the Helm repository.

1. Add the helm repo: `helm repo add opensearch-operator https://opensearch-project.github.io/opensearch-k8s-operator/`

Then the chart itself is installed with the release name opensearch-operator.

2. Install the Operator: `helm install opensearch-operator opensearch-operator/opensearch-operator`

The chart is also published to Artifact Hub under the repository name opensearch-operator, which is where a lot of people will find it first. The documentation also points to a video tutorial series on YouTube for the install and usage path, which is a reasonable thing to have next to a user guide. The charts directory in the repository is where the chart source lives, so anyone deploying from a chart they built themselves, for instance with a pinned image or an air-gapped mirror, has the inputs to do that.

The API group migration is the thing to plan around

There is a notice at the top of the readme and it is the most operationally significant line in the document. The operator is migrating from the opensearch.opster.io API group to the opensearch.org API group, and both are currently supported, but opensearch.opster.io is deprecated, with the Migration Guide holding the details. That is a real change for anyone who has manifests in the old group, because the custom resource definition and the resource kind move with it, and a cluster that is not migrated is on a deprecated path. The deprecation also affects tooling that reads the old group, such as dashboards, policy engines and monitoring that key on the API group. Nothing in the readme gives a removal date, so the reasonable posture is to plan the migration into your own upgrade cycle rather than to assume a deadline, and to check the Migration Guide before writing new manifests.

The compatibility table lists tested versions and leaves the rest to you

The compatibility table is unusually honest and worth reading closely. The operator aims to be compatible with all supported OpenSearch versions, and the table shows the combinations that have been explicitly tested. Operator 3.0.0 supports a minimum of OpenSearch 2.19.2 and a maximum of the latest 3.x, and operator 2.8.0 has the same range. The older line of operator versions, 2.7.0 down to 2.5.0, supports a minimum of 1.3.x and a maximum of 2.19.2. The table also states what it does not mean, that it only lists versions explicitly tested with the operator and that the operator will not prevent you from using other versions. Newer minor versions in the 2.x range that are not listed generally also work, but the documentation says you should proceed with caution and test in a non-production environment first. That sentence is the difference between a compatibility table that is a contract and one that is a warning, and it is worth taking at face value before a rolling upgrade touches a production cluster.

Where the operator is the wrong choice

The first wrong case is a single cluster on a small team, because the official OpenSearch Helm chart is a smaller dependency for a deployment that does not need a control loop reconciling custom resources. The second is a cluster on a platform that is not Kubernetes, since the whole project is a Kubernetes operator and the resource model assumes the custom resource definition and the controller are there. The third is an environment where the OpenSearch version you need is not in the tested range and you cannot afford the caution the documentation asks for, because an untested combination during a rolling upgrade is where a data node goes down at the wrong moment. The fourth is a team that wants to avoid a deprecated API group in new manifests, since creating new resources against opensearch.opster.io means creating work you will have to migrate. The fifth is a deployment that needs features outside the list, such as multi-tenancy at a level finer than namespaces, or a cluster that a managed service already provides, since the operator is a management layer and not a substitute for the search engine itself.

Editorial conclusion

Platform teams who run OpenSearch on Kubernetes and want clusters declared rather than hand-assembled are the people this operator is for, and the combination of node pool management, rolling upgrades with quorum-safe restarts and multi-namespace support is what a search platform actually needs. It is the wrong tool for a single cluster on a small team that can run the official Helm chart, since the operator adds a control loop and a custom resource API you then have to maintain. Check three things before you install it: which API group your manifests use, because the operator is migrating from opensearch.opster.io to opensearch.org with both currently supported and the old one deprecated, which OpenSearch version you intend to run against the compatibility table, since only some combinations are explicitly tested, and that you are on a CNCF certified Kubernetes cluster, which is the stated requirement for the Helm install path. The licence is Apache-2.0, the newest release is v3.0.0 from 2026-09-25, and the last push was on 2026-10-20.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. opensearch-project/opensearch-k8s-operator on GitHub
4. README
5. Releases