> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/2-4-1/cybus-helm-charts/connectware-helm-chart/scaling-connectware-components-horizontally.md).

# Scaling Connectware Components Horizontally

Horizontal scaling runs multiple replicas of a Connectware component in parallel to share load and provide redundancy if a single replica fails. Scale a component when you need to handle higher throughput or improve availability beyond what the default deployment provides.

The default replica counts cover most production deployments. The sections below describe which components support scaling and how to change their replica counts.

## Scalable Components

The following Connectware components support horizontal scaling:

| Component                | `values.yaml` key                 | Default replicas |
| ------------------------ | --------------------------------- | :--------------: |
| auth-server              | `authServer.replicas`             |         2        |
| resource-status-tracking | `resourceStatusTracking.replicas` |         2        |
| topic-explorer           | `topicExplorer.replicas`          |         2        |
| broker                   | `broker.replicas`                 |         3        |
| NATS                     | `nats.replicas`                   |         3        |

{% hint style="warning" %}
NATS has strict scaling constraints. Review [Scaling the NATS Cluster](#scaling-the-nats-cluster) before changing `nats.replicas`.
{% endhint %}

## Scaling auth-server, resource-status-tracking, and topic-explorer

The auth-server, resource-status-tracking, and topic-explorer components are stateless and can be scaled independently. Set the `replicas` value for each component in your `values.yaml`:

{% code title="values.yaml" lineNumbers="true" %}

```yaml
authServer:
  replicas: ${REPLICAS}
resourceStatusTracking:
  replicas: ${REPLICAS}
topicExplorer:
  replicas: ${REPLICAS}
```

{% endcode %}

Replace `${REPLICAS}` with the desired number of replicas. You do not need to set all three at once — components can be scaled independently.

After editing your `values.yaml`, apply the changes by running the `helm upgrade` command. For details, see [Applying Helm Configuration Changes](/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts.md#applying-helm-configuration-changes).

## Scaling the NATS Cluster

{% hint style="danger" %}

## NATS replica count is fixed after installation

The number of NATS replicas is set at initial installation and cannot be changed afterward. Scaling NATS to a different replica count after the cluster is formed and running corrupts the NATS cluster.

The only permitted operations after installation are scaling to zero (stop all pods) and scaling back to the **exact original replica count** (restart). Use `kubectl scale` for these operations. Do not change `nats.replicas` in your `values.yaml` and run `helm upgrade` to scale at runtime.
{% endhint %}

NATS requires an odd number of replicas. The recommended values are:

* `1` — no redundancy. Suitable for test setups only.
* `3` — n+1 redundancy. The default and recommended for most production deployments.
* `5` — n+2 redundancy. Use when you need the cluster to remain operational with two nodes unavailable at the same time.

Going beyond `5` rarely improves performance. If you need more capacity, allocate larger pods rather than more replicas.

If you need a different replica count, set `nats.replicas` in your `values.yaml` **before the initial installation**:

{% code title="values.yaml" lineNumbers="true" %}

```yaml
nats:
  replicas: 5
```

{% endcode %}

### Stopping and Restarting the NATS Cluster

1. Check how many replicas are currently running:

{% code lineNumbers="true" %}

```bash
kubectl get sts nats -n ${NAMESPACE}
```

{% endcode %}

**Example output**

```
NAME     READY   AGE
nats     3/3     6m52s
```

2. To temporarily stop all NATS pods, scale the StatefulSet to zero:

{% code lineNumbers="true" %}

```bash
kubectl scale sts nats -n ${NAMESPACE} --replicas 0
```

{% endcode %}

3. To restart NATS, scale back to the **exact original replica count**:

{% code lineNumbers="true" %}

```bash
kubectl scale sts nats -n ${NAMESPACE} --replicas ${ORIGINAL_REPLICA_COUNT}
```

{% endcode %}

Replace `${NAMESPACE}` with your Connectware namespace and `${ORIGINAL_REPLICA_COUNT}` with the replica count set during installation. Using a different value corrupts the cluster.

4. Verify that all NATS pods are running and ready before resuming normal operations:

{% code lineNumbers="true" %}

```bash
kubectl get pods -n ${NAMESPACE} -l app.kubernetes.io/name=nats
```

{% endcode %}

## Scaling the Broker Cluster

Scale the broker cluster up or down to change the number of broker replicas in your Kubernetes deployment. Scaling up adds more broker nodes to the cluster. Scaling down reduces the number of broker nodes.

### Scaling the Broker Up or Down

1. Check how many replicas are currently set for the broker StatefulSet:

{% code lineNumbers="true" %}

```bash
kubectl get sts broker -n ${NAMESPACE}
```

{% endcode %}

**Example output**

```
NAME     READY   AGE
broker   3/3     6m52s
```

2. Scale the StatefulSet to the desired number of replicas.

* To scale up, increase the replica count. For example, to scale up from 3 to 4 replicas:

{% code lineNumbers="true" %}

```bash
kubectl scale sts broker -n ${NAMESPACE} --replicas 4
```

{% endcode %}

* To scale down, decrease the replica count. For example, to scale down from 3 to 2 replicas:

{% code lineNumbers="true" %}

```bash
kubectl scale sts broker -n ${NAMESPACE} --replicas 2
```

{% endcode %}

3. Verify that all broker nodes have formed a healthy cluster:

{% code lineNumbers="true" %}

```bash
kubectl get pods -l app.kubernetes.io/name=broker -n ${NAMESPACE} -o name | xargs -I % kubectl exec -n ${NAMESPACE} % -- vmq-admin cluster show
```

{% endcode %}

**Example output**

```
+--------------------------------------------------------------------+---------+
| Node                                                               | Running |
+--------------------------------------------------------------------+---------+
| VerneMQ@broker-0.broker-headless-discovery.cybus.svc.cluster.local | true    |
+--------------------------------------------------------------------+---------+
| VerneMQ@broker-1.broker-headless-discovery.cybus.svc.cluster.local | true    |
+--------------------------------------------------------------------+---------+
| VerneMQ@broker-2.broker-headless-discovery.cybus.svc.cluster.local | true    |
+--------------------------------------------------------------------+---------+
```

### Scaling the Broker Down to Zero

1. Check how many replicas are currently set for the broker StatefulSet:

{% code lineNumbers="true" %}

```bash
kubectl get sts broker -n ${NAMESPACE}
```

{% endcode %}

**Example output**

```
NAME     READY   AGE
broker   3/3     6m52s
```

2. Scale the StatefulSet to zero to remove all broker pods:

{% code lineNumbers="true" %}

```bash
kubectl scale sts broker -n ${NAMESPACE} --replicas 0
```

{% endcode %}

3. Verify that all broker pods have been terminated:

{% code lineNumbers="true" %}

```bash
kubectl get pods -n ${NAMESPACE} -l app.kubernetes.io/name=broker
```

{% endcode %}

4. Optional: To bring the broker back up, follow [Scaling the Broker Up or Down](#scaling-the-broker-up-or-down) and scale to your desired replica count.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.cybus.io/2-4-1/cybus-helm-charts/connectware-helm-chart/scaling-connectware-components-horizontally.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.