> 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-cluster-secret.md).

# Configuring the Broker Cluster Secret

The broker cluster secret is a shared credential that broker nodes use to authenticate with each other when forming a cluster and when new nodes join an existing cluster. By default, the `connectware` Helm chart generates a random secret at install time and reuses it for the lifetime of the installation. You can override this default with a value of your choice or with a Kubernetes Secret you manage yourself.

{% hint style="warning" %}

## You cannot change the cluster secret while the broker is running

Changing the broker cluster secret requires a full broker shutdown. You cannot rotate the secret on a running cluster.

Before changing the secret, scale the broker to zero replicas. For more information, see [Scaling the Broker Down to Zero](/2-4-1/cybus-helm-charts/connectware-helm-chart/scaling-connectware-components-horizontally.md#scaling-the-broker-down-to-zero).
{% endhint %}

## Choosing a Configuration Method

You have the following options for configuring the broker cluster secret. Choose the method that best fits your security and operational requirements:

* **Method 1 — Auto-generated secret (recommended for most installations)**: Helm generates a cryptographically secure random value at install time. No configuration is required.
* **Method 2 — Custom value in `values.yaml`**: You provide the secret as plain text in your Helm values. Suitable for development and test environments.
* **Method 3 — Existing Kubernetes Secret**: You create a Kubernetes Secret yourself and reference it from your Helm values. Suitable for production environments that use external secret management or GitOps workflows.

If you set both `broker.clusterSecret` and `broker.existingClusterSecret`, `broker.existingClusterSecret` takes priority. The secret value must be at least 5 characters long.

{% tabs %}
{% tab title="Method 1 — Auto-Generated" %}

## Auto-Generated Secret

Leave both `broker.clusterSecret` and `broker.existingClusterSecret` unset in your `values.yaml` file. Helm generates a random secret during installation and stores it in a Kubernetes Secret that persists across upgrades.

{% hint style="warning" %}

## Requires live cluster access

The auto-generated secret relies on Helm reading the existing Kubernetes Secret from the cluster on each upgrade. This only works when Helm operations run with access to the target cluster.

Workflows that render manifests offline, such as CI pipelines that use `helm template`, generate a new random secret on every run and break the broker cluster. Use **Method 2 — Custom Value** or **Method 3 — Existing Secret** instead.
{% endhint %}

To retrieve the auto-generated secret later, run:

{% code lineNumbers="true" %}

```bash
kubectl get secret \
  --namespace ${NAMESPACE} \
  --selector app.kubernetes.io/name=broker-cluster-secret \
  --output yaml
```

{% endcode %}

Replace `${NAMESPACE}` with the namespace of your Connectware installation.
{% endtab %}

{% tab title="Method 2 — Custom Value" %}

## Custom Value in `values.yaml`

Set `broker.clusterSecret` to provide a plain text secret value directly in your `values.yaml` file:

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

```yaml
broker:
  clusterSecret: '${CLUSTER_SECRET}'
```

{% endcode %}

Replace `${CLUSTER_SECRET}` with a strong, randomly generated string.

{% hint style="warning" %}
This method stores the secret in plain text in your `values.yaml` file. Use it only in non-production environments, or make sure your values file is stored securely.
{% endhint %}
{% endtab %}

{% tab title="Method 3 — Existing Secret" %}

## Existing Kubernetes Secret

Reference a Kubernetes Secret you create and manage yourself. This approach keeps the secret out of your `values.yaml` file and is the recommended method for production deployments.

The Kubernetes Secret must:

* Live in the same namespace as the Connectware installation.
* Contain a key named `clusterSecret` whose value is the plain text cluster secret. The `kubectl create secret` command in step 1 handles base64 encoding automatically. If you write the Secret manifest by hand, base64-encode the plain text value once, as you would for any other Kubernetes Secret.

1. Create the Kubernetes Secret:

{% code lineNumbers="true" %}

```bash
kubectl create secret generic ${SECRET_NAME} \
  --from-literal=clusterSecret="${CLUSTER_SECRET}" \
  --namespace ${NAMESPACE}
```

{% endcode %}

* Replace `${SECRET_NAME}` with the name you want to give the Kubernetes Secret.
* Replace `${CLUSTER_SECRET}` with a strong, randomly generated string.
* Replace `${NAMESPACE}` with the namespace of your Connectware installation.

2. Reference the Secret in your `values.yaml` file:

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

```yaml
broker:
  existingClusterSecret: ${SECRET_NAME}
```

{% endcode %}

Replace `${SECRET_NAME}` with the name of the Kubernetes Secret you created in step 1.

3. Optional: Mark the Secret as immutable to prevent accidental edits that could cause broker nodes to use different secrets:

{% code lineNumbers="true" %}

```bash
kubectl patch secret ${SECRET_NAME} \
  --namespace ${NAMESPACE} \
  --patch '{"immutable": true}'
```

{% endcode %}

{% hint style="info" %}

## Managing the cluster secret with an existing Kubernetes Secret

When you use an existing Kubernetes Secret, Helm does not create or manage the cluster secret. You are responsible for ensuring the Secret exists before installation and for managing it throughout the lifecycle of the installation.
{% endhint %}
{% endtab %}
{% endtabs %}


---

# 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-cluster-secret.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.