> 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/broker-storage.md).

# MQTT Broker Storage Volumes in Kubernetes

The broker uses two persistent volumes: one for queue data and cluster metadata, and one for log files. The disk space required depends on your use case, particularly the use of QoS levels greater than zero, retained messages, and message sizes. Since storage requirements cannot be perfectly predicted, you can configure initial volume sizes at install time and resize volumes in a running deployment when needed.

## Configuring Initial Storage Volume Sizes

When deploying Connectware, you can configure the storage volume sizes and StorageClass for the Broker through Helm values:

| Helm Value                                 | Description                                                         | Default                |
| ------------------------------------------ | ------------------------------------------------------------------- | ---------------------- |
| `broker.persistence.data.size`             | Storage for retained messages, offline queues, and cluster metadata | `1Gi`                  |
| `broker.persistence.data.storageClassName` | StorageClass for the data volume                                    | `""` (cluster default) |
| `broker.persistence.log.size`              | Storage for broker log files                                        | `200Mi`                |
| `broker.persistence.log.storageClassName`  | StorageClass for the log volume                                     | `""` (cluster default) |

Configure the storage volume sizes by adding the appropriate Helm values to your `values.yaml` file:

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

```yaml
broker:
  persistence:
    data:
      size: 5Gi
    log:
      size: 500Mi
```

{% endcode %}

{% hint style="info" %}
Because this example does not specify `storageClassName`, Kubernetes uses the cluster default StorageClass for both volumes.
{% endhint %}

## Resizing Existing Broker Storage Volumes

Use this procedure to increase the available disk space for existing broker volumes (PersistentVolumeClaims). This process requires pod restarts, which means clients must reconnect.

{% hint style="warning" %}

## Resizing volumes requires pod restarts and involves risks

Resizing broker volumes requires deleting and recreating broker pods. Clients are disconnected during the process and must reconnect once the pods are back. The procedure also involves removing the StatefulSet, which leaves the broker cluster vulnerable to failures caused by cluster events or human error. Execute this procedure with great care and only in a stable cluster environment.
{% endhint %}

### Prerequisites

* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) is installed on your system.
* You know the namespace and name of your Connectware installation, referred to as `${NAMESPACE}` and `${INSTALLATION_NAME}` throughout this guide.
* The used `StorageClass` supports volume expansion. Run `kubectl get sc` and confirm that `ALLOWVOLUMEEXPANSION` is `true` for that StorageClass.

### Preparing the Broker Cluster

1. Ensure you have a healthy broker cluster of at least two pods. Run `kubectl get sts broker -n ${NAMESPACE}` and verify it shows `READY 2/2` or higher with matching numbers on both sides of the slash.
2. If you only have a single broker, scale the StatefulSet to two replicas:

{% code lineNumbers="true" %}

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

{% endcode %}

3. Export the StatefulSet definition to a local file:

{% code lineNumbers="true" %}

```bash
kubectl get sts broker -n ${NAMESPACE} -o yaml > broker.yaml
```

{% endcode %}

### Resizing Volumes

Repeat this procedure for each broker pod in your cluster.

1. Delete the broker StatefulSet while leaving the pods as orphans:

{% code lineNumbers="true" %}

```bash
kubectl delete sts broker -n ${NAMESPACE} --cascade=orphan
```

{% endcode %}

2. Set the `$broker` variable to the pod name of the broker you want to resize (for example, `broker-0`):

{% code lineNumbers="true" %}

```bash
broker=broker-0
```

{% endcode %}

3. Delete the broker pod:

{% code lineNumbers="true" %}

```bash
kubectl delete pod $broker -n ${NAMESPACE}
```

{% endcode %}

4. Increase the PersistentVolumeClaims size. Replace `${SIZE}` with the desired Kubernetes quantity for the volume (for example, `5Gi`):

To resize the data volume:

{% code lineNumbers="true" %}

```bash
kubectl patch pvc brokerdata-$broker -n ${NAMESPACE} --patch '{"spec": { "resources": {"requests": {"storage": "${SIZE}"}}}}'
```

{% endcode %}

To resize the log volume:

{% code lineNumbers="true" %}

```bash
kubectl patch pvc brokerlog-$broker -n ${NAMESPACE} --patch '{"spec": { "resources": {"requests": {"storage": "${SIZE}"}}}}'
```

{% endcode %}

5. Wait until the PersistentVolumeClaims show the correct capacity:

{% code lineNumbers="true" %}

```bash
kubectl get pvc brokerdata-$broker -n ${NAMESPACE}
```

{% endcode %}

6. Recreate the StatefulSet:

{% code lineNumbers="true" %}

```bash
kubectl apply -f broker.yaml -n ${NAMESPACE}
```

{% endcode %}

7. Wait for the StatefulSet to recreate the missing pod. Monitor the status by running `kubectl get sts broker -n ${NAMESPACE}` until it shows `READY 2/2` or higher with matching numbers on both sides of the slash.
8. Verify that all cluster members show consistent cluster information:

{% code lineNumbers="true" %}

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

{% endcode %}

The output should list all broker nodes as `Running: true` on each pod where you run the command.

{% code lineNumbers="true" %}

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

{% endcode %}

9. Repeat this procedure for each additional broker pod until all volumes are resized.

### Persisting Volume Changes for Future Deployments

After resizing volumes, update your Helm values to reflect the new sizes for future deployments and upgrades. This prevents future Helm upgrades from reverting the volume size.

1. Update the following fields in your `values.yaml` file based on the volumes you resized:

| PersistentVolumeClaims Name | Helm Value                     |
| --------------------------- | ------------------------------ |
| brokerdata-broker-\*        | `broker.persistence.data.size` |
| brokerlog-broker-\*         | `broker.persistence.log.size`  |

2. Delete the StatefulSet while leaving the pods as orphans. This allows Helm to take ownership of the StatefulSet on the next upgrade without conflicting with the manually recreated resource:

{% code lineNumbers="true" %}

```bash
kubectl delete sts broker -n ${NAMESPACE} --cascade=orphan
```

{% endcode %}

3. Apply the configuration changes by running the `helm upgrade` command:

{% code lineNumbers="true" %}

```bash
helm upgrade -n ${NAMESPACE} ${INSTALLATION_NAME} oci://repo.cybus.io/charts/connectware -f values.yaml
```

{% endcode %}

For details, see [Applying Helm Configuration Changes](/2-4-1/cybus-helm-charts/working-with-cybus-helm-charts.md#applying-helm-configuration-changes).

## Deleting Broker Data Volumes

To permanently delete broker data volumes, see [Deleting Broker Data Volumes](/2-4-1/broker/cybusmq/operations/deleting-broker-data-volumes.md).


---

# 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/broker-storage.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.