Node roles and cluster topology¶

OpenSearch clusters are made up of nodes, each assigned one or more roles that determine what work the node performs. In Charmed OpenSearch, roles are assigned at the Juju application level — all units within an application share the same set of roles. This page explains the available roles, how they interact, and how multiple applications combine to form a large deployment.

Available node roles¶

Charmed OpenSearch accepts the following comma-separated values in the roles configuration option:

Role	Description
`cluster_manager`	Handles cluster-wide operations: creating and deleting indices, managing shard allocation, and rebalancing data. One node is elected cluster manager among all `cluster_manager`-eligible nodes.
`data`	Stores indexed data and performs search and indexing operations. Data nodes hold the shards that contain the indexed documents.
`data.<temperature>`	The `data` role, with a data tier assigned. The temperature is one of `hot` (most recent, most frequently queried data), `warm` (queried less frequently but still searchable), `cold` (infrequently accessed), `frozen`, or `content`.
`ingest`	Pre-processes documents before they are indexed (pipelines, transformations).
`coordinating`	Routes requests to the appropriate data nodes and aggregates results. Does not hold data.
`voting_only`	Participates in cluster manager election but is never eligible to become the cluster manager node itself.
`ml`	Runs machine learning tasks such as model training and inference.

Note

The data.<temperature> values are a Charmed OpenSearch convenience, not OpenSearch roles. Upstream, the role is data and the tier is a separate node attribute. When you set data.hot, the charm assigns the data role and sets node.attr.temp to hot. Only one temperature may be set per application.

Classifying data nodes into tiers supports index lifecycle management policies that move data between tiers as it ages. Note that the charm only tags nodes with their temperature — it does not place data on them. To route indices to the appropriate tier, you need to configure the index lifecycle management policies yourself.

Auto-generated roles¶

When the roles configuration option is left empty, the charm automatically assigns the following roles to all nodes in the application:

["data", "ingest", "ml", "cluster_manager"]

This means a single-application deployment can handle all functions — cluster management, data storage, ingestion, and machine learning — without any additional configuration.

Setting roles¶

Roles can be set at deployment time or changed later via configuration:

# At deployment time
juju deploy opensearch -n 3 --config roles="cluster_manager,data,ml"

# After deployment (triggers a rolling restart)
juju config opensearch roles="cluster_manager,data,ml"

Note

Removal of the cluster_manager role is never supported: the charm rejects the change and the application becomes blocked.

Removal of the data role is rejected in a simple (single-application) deployment, because the data on disk could no longer be served. In a large deployment, it is allowed only if another application in the cluster still holds the data role, so that shards can be reallocated.

Large deployments¶

For production workloads, a single application is often insufficient. Charmed OpenSearch supports large deployments — a single OpenSearch cluster composed of multiple Juju applications, each configured with specific node roles. This topology allows you to scale different node types independently and provides fault tolerance.

The main orchestrator pattern¶

A large deployment consists of three types of applications:

Main orchestrator — the primary application that bootstraps the cluster. It has init_hold=false (the default) and is responsible for generating the cluster UUID, initialising the security index, and sharing admin certificates with other applications. When no roles are explicitly set, it receives all auto-generated roles.
Failover orchestrator (recommended) — a dedicated cluster_manager application that takes over orchestration if the main orchestrator fails or is removed. It must have init_hold=true to prevent it from starting before being integrated with the main orchestrator.
Data applications — applications with data-tier roles (e.g. data.hot, data.warm) that store and process data. They also require init_hold=true.

Critical configuration rules¶

Two configuration options are essential for large deployments:

cluster_name: All applications must share the same cluster_name value. A mismatch prevents applications from forming a cluster. If left unset on the main orchestrator, a name is auto-generated and inherited by other applications via the peer-cluster relation.
init_hold: Must be set to true on every application except the main orchestrator. This prevents non-orchestrator applications from starting before they are integrated with the main orchestrator, which would cause them to fail (they cannot reach the cluster to obtain admin certificates and cluster metadata).

Cluster formation¶

The applications are connected via the peer-cluster relations:

juju integrate main:peer-cluster-orchestrator failover:peer-cluster
juju integrate main:peer-cluster-orchestrator data-hot:peer-cluster
juju integrate failover:peer-cluster-orchestrator data-hot:peer-cluster

Once these relations are established, the main orchestrator shares the cluster UUID, admin certificates, and security configuration with the other applications. The other applications then start and join the cluster.

Integrations and the main orchestrator¶

In a large deployment, integrations with external charms (e.g. SMTP, JWT, OAuth) must target the main orchestrator application, not the data or failover applications. The main orchestrator is responsible for distributing configuration to the rest of the cluster. If integrated with the wrong application, the charm will enter a blocked state.

You can identify the main orchestrator by inspecting the integrations section of juju status --relations — look for the application providing the peer-cluster-orchestrator endpoint.