How to launch a large deployment¶

This guide shows how to deploy a multi-application OpenSearch cluster using Juju, with dedicated node roles for scalability and fault tolerance.

For background on node roles, data tiers, and the main orchestrator pattern, see Node roles and cluster topology.

Node roles¶

Roles are assigned at the Juju application level (all units in an application share the same roles). If no roles are configured, the charm auto-assigns: data, ingest, ml, cluster_manager.

To set roles at deploy time:

juju deploy opensearch -n 3 --config roles="cluster_manager,data,ml"

To change roles after deployment (triggers a rolling restart):

juju config opensearch roles="cluster_manager,data,ml"

Note

Removal of the cluster_manager or data roles is not supported.

Deploy the cluster applications¶

A large deployment consists of multiple Juju applications integrated together, each configured with specific node roles. See Node roles and cluster topology for an explanation of the main orchestrator, failover, and data-node pattern.

Caution

The examples below use the testing profile (sets the JVM heap size to 1 GB per node) for a single-host LXD environment. For production, use the production profile (JVM heap set to 50% of RAM, capped at 31 GB). See How to optimize cluster performance with profiles for details on the available profiles.

Note

Two critical configuration rules for large deployments:

All applications must share the same cluster_name value. A mismatch prevents applications from forming a cluster.
Set init_hold=true on every application except the main orchestrator. This prevents non-orchestrator applications from starting before integration.

See Node roles and cluster topology for details on why these rules are required.

1. Deploy the main orchestrator¶

Deploy the main application:

juju deploy -n 3 \
    opensearch main \
    --config cluster_name="app" \
    --channel 2/stable

Since no roles are specified, the charm auto-assigns all default roles.

2. Deploy a failover application (recommended)¶

The failover application takes over orchestration if the main app fails or is removed:

juju deploy -n 3 \
    opensearch failover \
    --config cluster_name="app" \
    --config init_hold="true" \
    --config roles="cluster_manager" \
    --channel 2/stable

3. Deploy data nodes¶

Deploy an application with data.hot roles:

juju deploy -n 3 \
    opensearch data-hot \
    --config cluster_name="app" \
    --config roles="data.hot" \
    --config init_hold="true" \
    --channel 2/stable

4. Deploy TLS certificates¶

Deploy a TLS certificate provider:

juju deploy self-signed-certificates

Track deployment progress:

juju status --watch 1s

At this point, main will show blocked (missing TLS), while failover and data-hot will show blocked (waiting for peer cluster relation).

Configure TLS encryption¶

Charmed OpenSearch requires TLS. Integrate self-signed-certificates with all OpenSearch applications:

juju integrate self-signed-certificates main
juju integrate self-signed-certificates failover
juju integrate self-signed-certificates data-hot

The main app will become active once TLS is configured. The other apps remain blocked until the peer-cluster relations are added in the next step.

Form the OpenSearch cluster¶

Integrate the applications 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

The main application orchestrates cluster formation. Track progress with:

juju status --watch 1s

Once all applications show active, the cluster is fully formed and operational.

Caution

The cluster will not come online if no data nodes are available. Ensure data nodes are deployed and ready before forming the cluster.

Next steps¶

Manage TLS encryption — configure and rotate TLS certificates.
Enable monitoring (COS) — observe the cluster.
Scale a cluster horizontally — adjust cluster size.