Configuring the Broker Cluster Secret

Configure a broker cluster secret for the connectware Helm chart to control how broker nodes authenticate when forming a cluster.

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.

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.

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.

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.

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.

To retrieve the auto-generated secret later, run:

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

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

Custom Value in `values.yaml`

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

values.yaml

broker:
  clusterSecret: '${CLUSTER_SECRET}'

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

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.

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.

Create the Kubernetes Secret:

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

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.

Reference the Secret in your values.yaml file:

values.yaml

broker:
  existingClusterSecret: ${SECRET_NAME}

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

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

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

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.

PreviousBroker Storage Volumes NextConnectware Agent Helm Chart

Last updated 4 days ago

Was this helpful?