Skip to content

Commit a438ac2

Browse files
committed
docs: clarify broker redundancyFactor minimum of 2
The REST API schema allows a minimum value of 1 for backendChain.redundancyFactor, but the service requires at least 2 for high availability and upgrade support. Deployments with redundancyFactor=1 are rejected at admission. Add explicit minimum value callouts in: - Broker cardinality config doc (redundancy factor description) - Upgrade doc (backend replicas requirement)
1 parent 39abbe5 commit a438ac2

4 files changed

Lines changed: 8 additions & 2 deletions

File tree

articles/iot-operations/deploy-iot-ops/concept-production-guidelines.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,9 @@ In the Azure portal deployment wizard, the broker resource is set up in the **Co
7272
| **backendPartitions** | 1 | 5 |
7373
| [Memory profile](../manage-mqtt-broker/howto-configure-availability-scale.md#configure-memory-profile) | Low | High |
7474

75+
> [!NOTE]
76+
> The backend redundancy factor must be **2 or greater**. The broker requires at least two backend replicas per partition for high availability and rolling upgrade support.
77+
7578
* [Encrypt internal traffic](../manage-mqtt-broker/howto-encrypt-internal-traffic.md).
7679

7780
* Set [disk-backed message buffer](../manage-mqtt-broker/howto-disk-backed-message-buffer.md) with a max size that prevents RAM overflow.

articles/iot-operations/deploy-iot-ops/howto-deploy-iot-operations.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ The Azure portal deployment experience is a helper tool that generates a deploym
7777
| Parameter | Value |
7878
| --------- | ----- |
7979
| **Azure IoT Operations name** | *Optional*: Replace the default name for the Azure IoT Operations instance. |
80-
| **MQTT broker configuration** | *Optional*: Edit the default settings for the MQTT broker. In Azure portal it's possible to [configure cardinality and memory profile settings](../manage-mqtt-broker/howto-configure-availability-scale.md). To configure other settings including disk-backed message buffer and advanced MQTT client options, see [Azure CLI support for advanced MQTT broker configuration](https://aka.ms/aziotops-broker-config). |
80+
| **MQTT broker configuration** | *Optional*: Edit the default settings for the MQTT broker. In Azure portal it's possible to [configure cardinality and memory profile settings](../manage-mqtt-broker/howto-configure-availability-scale.md). The backend redundancy factor must be set to **2 or greater** for high availability and upgrade support. To configure other settings including disk-backed message buffer and advanced MQTT client options, see [Azure CLI support for advanced MQTT broker configuration](https://aka.ms/aziotops-broker-config). |
8181
| **Data flow profile configuration** | *Optional*: Edit the default settings for data flows. For more information, see [Configure data flow profile](../connect-to-cloud/howto-configure-dataflow-profile.md). |
8282

8383
:::image type="content" source="./media/howto-deploy-iot-operations/deploy-configuration.png" alt-text="A screenshot that shows the second tab for deploying Azure IoT Operations from the portal." lightbox="./media/howto-deploy-iot-operations/deploy-configuration.png":::

articles/iot-operations/deploy-iot-ops/howto-upgrade.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ To ensure zero data loss and high availability during deployment upgrades, the M
128128

129129
If a failure occurs during the upgrade process, the health manager pod automatically restarts the upgrade process while ensuring no loss of data or connectivity.
130130

131-
Rolling updates can only occur if the MQTT broker is deployed with two or more backend replicas. MQTT broker upgrades aren't supported for single-replica deployments. When you deploy Azure IoT Operations, you specify the number of backend replicas to create in the [az iot ops create](/cli/azure/iot/ops#az-iot-ops-create) command with the `--broker-backend-rf` parameter.
131+
Rolling updates can only occur if the MQTT broker is deployed with two or more backend replicas. MQTT broker upgrades aren't supported for single-replica deployments. When you deploy Azure IoT Operations, you specify the number of backend replicas to create in the [az iot ops create](/cli/azure/iot/ops#az-iot-ops-create) command with the `--broker-backend-rf` parameter. The minimum value for this parameter is `2`. Setting the backend redundancy factor to `1` results in a deployment error.
132132

133133
## Supported versions
134134

articles/iot-operations/manage-mqtt-broker/howto-configure-availability-scale.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,9 @@ The backend chain subfield defines the settings for the backend partitions. The
127127
- **Redundancy factor**: The number of backend replicas (pods) to deploy per partition. Increasing the redundancy factor increases the number of data copies to provide resiliency against node failures in the cluster.
128128
- **Workers**: The number of workers to deploy per backend replica. Increasing the number of workers per backend replica might increase the number of messages that the backend pod can handle. Each worker can consume up to two CPU cores at most, so be careful when you increase the number of workers per replica to not exceed the number of CPU cores in the cluster.
129129

130+
> [!IMPORTANT]
131+
> The backend redundancy factor must be set to **2 or greater**. The broker requires at least two backend replicas per partition for high availability and rolling upgrade support. Setting the redundancy factor to `1` results in a deployment validation error.
132+
130133
#### Considerations
131134

132135
When you increase the cardinality values, the broker's capacity to handle more connections and messages generally improves, and it enhances high availability if there are pod or node failures. This increased capacity also leads to higher resource consumption. So when you adjust cardinality values, consider the [memory profile settings](#configure-memory-profile) and broker's [CPU resource requests](#cardinality-and-kubernetes-resource-limits). Increasing the number of workers per frontend replica can help increase CPU core utilization if you discover that frontend CPU utilization is a bottleneck. Increasing the number of backend workers can help with the message throughput if backend CPU utilization is a bottleneck.

0 commit comments

Comments
 (0)