From 211de1c4c2b4fa58b9c64e92a02b317ead14c57c Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Mon, 28 Jul 2025 16:18:01 +0200 Subject: [PATCH 1/6] update RabbitMQ scaler docs with additional DeliverGetRate and PublishedToDeliveredRatio modes Signed-off-by: Wojciech Moczulski --- content/docs/2.17/scalers/rabbitmq-queue.md | 149 +++++++++++++++++++- content/docs/2.18/scalers/rabbitmq-queue.md | 149 +++++++++++++++++++- 2 files changed, 292 insertions(+), 6 deletions(-) diff --git a/content/docs/2.17/scalers/rabbitmq-queue.md b/content/docs/2.17/scalers/rabbitmq-queue.md index 5e13fc0b9..1f59ec6a1 100644 --- a/content/docs/2.17/scalers/rabbitmq-queue.md +++ b/content/docs/2.17/scalers/rabbitmq-queue.md @@ -17,7 +17,7 @@ triggers: metadata: host: amqp://localhost:5672/vhost # Optional. If not specified, it must be done by using TriggerAuthentication. protocol: auto # Optional. Specifies protocol to use, either amqp or http, or auto to autodetect based on the `host` value. Default value is auto. - mode: QueueLength # QueueLength or MessageRate + mode: QueueLength # QueueLength, MessageRate, DeliverGetRate or PublishedToDeliveredRatio value: "100.50" # message backlog or publish/sec. target per instance activationValue: "10.5" # Optional. Activation threshold queueName: testqueue @@ -35,7 +35,11 @@ triggers: - `host` - Host of RabbitMQ with format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain vhost than the trailing slash is required in this case like `http://guest:password@localhost:5672/`. When using a username/password consider using `hostFromEnv` or a TriggerAuthentication. - `queueName` - Name of the queue to read message from. -- `mode` - QueueLength to trigger on number of messages in the queue. MessageRate to trigger on the published rate into the queue. (Values: `QueueLength`, `MessageRate`) +- `mode` - Trigger mode. Can be one of following: + - `QueueLength` - trigger on number of messages in the queue + - `MessageRate` - trigger on the published rate into the queue + - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) + - `PublishedToDeliveredRatio` - trigger on the ratio of `MessageRate` to `DeliverGetRate` (see exmaple below) - `value` - Message backlog or Publish/sec. rate to trigger on. (This value can be a float when `mode: MessageRate`) - `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds).(Default: `0`, Optional, This value can be a float) - `protocol` - Protocol to be used for communication. (Values: `auto`, `http`, `amqp`, Default: `auto`, Optional) @@ -64,7 +68,7 @@ Some parameters could be provided using environmental variables, instead of sett > ⚠ **Important:** if you have unacknowledged messages and want to have these counted for the scaling to happen, make sure to utilize the `http` REST API interface which allows for these to be counted. -> ⚠ **Important:** If scaling against both is desired then the `ScaledObject` should have two triggers, one for `mode: QueueLength` and the other for `mode: MessageRate`. HPA will scale based on the largest result considering each of the two triggers independently. +> ⚠ **Important:** If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. ### Authentication Parameters @@ -424,3 +428,142 @@ spec: authenticationRef: name: keda-trigger-auth-rabbitmq-conn ``` + +#### HTTP protocol (`DeliverGetRate`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metadata: + protocol: http + queueName: testqueue + mode: DeliverGetRate + value: "30" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (`PublishedToDeliveredRatio`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1.1" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (`PublishedToDeliveredRatio` with `scalingModifiers`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + name: p2d_ratio + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1" + authenticationRef: + name: rabbitmq-trigger-auth + - type: rabbitmq + name: qlen + metadata: + protocol: http + queueName: testqueue + mode: QueueLength + value: "100" + authenticationRef: + name: rabbitmq-trigger-auth + advanced: + # Bind QueueLength and PublishedToDeliveredRatio together to control trigger value + scalingModifiers: + metricType: "Value" + # Trigger if either one of conditions is met: + # - publishing to delivery rate exceeds factor of 1.2 + # - queue lenght contains more than 1.2K messages + formula: "max(p2d_ratio, qlen/1000)" + target: 1.2 +``` diff --git a/content/docs/2.18/scalers/rabbitmq-queue.md b/content/docs/2.18/scalers/rabbitmq-queue.md index 5e13fc0b9..1f59ec6a1 100644 --- a/content/docs/2.18/scalers/rabbitmq-queue.md +++ b/content/docs/2.18/scalers/rabbitmq-queue.md @@ -17,7 +17,7 @@ triggers: metadata: host: amqp://localhost:5672/vhost # Optional. If not specified, it must be done by using TriggerAuthentication. protocol: auto # Optional. Specifies protocol to use, either amqp or http, or auto to autodetect based on the `host` value. Default value is auto. - mode: QueueLength # QueueLength or MessageRate + mode: QueueLength # QueueLength, MessageRate, DeliverGetRate or PublishedToDeliveredRatio value: "100.50" # message backlog or publish/sec. target per instance activationValue: "10.5" # Optional. Activation threshold queueName: testqueue @@ -35,7 +35,11 @@ triggers: - `host` - Host of RabbitMQ with format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain vhost than the trailing slash is required in this case like `http://guest:password@localhost:5672/`. When using a username/password consider using `hostFromEnv` or a TriggerAuthentication. - `queueName` - Name of the queue to read message from. -- `mode` - QueueLength to trigger on number of messages in the queue. MessageRate to trigger on the published rate into the queue. (Values: `QueueLength`, `MessageRate`) +- `mode` - Trigger mode. Can be one of following: + - `QueueLength` - trigger on number of messages in the queue + - `MessageRate` - trigger on the published rate into the queue + - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) + - `PublishedToDeliveredRatio` - trigger on the ratio of `MessageRate` to `DeliverGetRate` (see exmaple below) - `value` - Message backlog or Publish/sec. rate to trigger on. (This value can be a float when `mode: MessageRate`) - `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds).(Default: `0`, Optional, This value can be a float) - `protocol` - Protocol to be used for communication. (Values: `auto`, `http`, `amqp`, Default: `auto`, Optional) @@ -64,7 +68,7 @@ Some parameters could be provided using environmental variables, instead of sett > ⚠ **Important:** if you have unacknowledged messages and want to have these counted for the scaling to happen, make sure to utilize the `http` REST API interface which allows for these to be counted. -> ⚠ **Important:** If scaling against both is desired then the `ScaledObject` should have two triggers, one for `mode: QueueLength` and the other for `mode: MessageRate`. HPA will scale based on the largest result considering each of the two triggers independently. +> ⚠ **Important:** If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. ### Authentication Parameters @@ -424,3 +428,142 @@ spec: authenticationRef: name: keda-trigger-auth-rabbitmq-conn ``` + +#### HTTP protocol (`DeliverGetRate`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metadata: + protocol: http + queueName: testqueue + mode: DeliverGetRate + value: "30" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (`PublishedToDeliveredRatio`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1.1" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (`PublishedToDeliveredRatio` with `scalingModifiers`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + name: p2d_ratio + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1" + authenticationRef: + name: rabbitmq-trigger-auth + - type: rabbitmq + name: qlen + metadata: + protocol: http + queueName: testqueue + mode: QueueLength + value: "100" + authenticationRef: + name: rabbitmq-trigger-auth + advanced: + # Bind QueueLength and PublishedToDeliveredRatio together to control trigger value + scalingModifiers: + metricType: "Value" + # Trigger if either one of conditions is met: + # - publishing to delivery rate exceeds factor of 1.2 + # - queue lenght contains more than 1.2K messages + formula: "max(p2d_ratio, qlen/1000)" + target: 1.2 +``` From 37bf240a3b4b63ea107bfcb173efe9bd58084166 Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Tue, 9 Sep 2025 20:19:35 +0200 Subject: [PATCH 2/6] publish information about new RabbitMQ scaler's trigger modes in 2.18 version Signed-off-by: Wojciech Moczulski --- content/docs/2.17/scalers/rabbitmq-queue.md | 149 +------------- content/docs/2.18/scalers/rabbitmq-queue.md | 217 ++++++++++++-------- 2 files changed, 140 insertions(+), 226 deletions(-) diff --git a/content/docs/2.17/scalers/rabbitmq-queue.md b/content/docs/2.17/scalers/rabbitmq-queue.md index 1f59ec6a1..5e13fc0b9 100644 --- a/content/docs/2.17/scalers/rabbitmq-queue.md +++ b/content/docs/2.17/scalers/rabbitmq-queue.md @@ -17,7 +17,7 @@ triggers: metadata: host: amqp://localhost:5672/vhost # Optional. If not specified, it must be done by using TriggerAuthentication. protocol: auto # Optional. Specifies protocol to use, either amqp or http, or auto to autodetect based on the `host` value. Default value is auto. - mode: QueueLength # QueueLength, MessageRate, DeliverGetRate or PublishedToDeliveredRatio + mode: QueueLength # QueueLength or MessageRate value: "100.50" # message backlog or publish/sec. target per instance activationValue: "10.5" # Optional. Activation threshold queueName: testqueue @@ -35,11 +35,7 @@ triggers: - `host` - Host of RabbitMQ with format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain vhost than the trailing slash is required in this case like `http://guest:password@localhost:5672/`. When using a username/password consider using `hostFromEnv` or a TriggerAuthentication. - `queueName` - Name of the queue to read message from. -- `mode` - Trigger mode. Can be one of following: - - `QueueLength` - trigger on number of messages in the queue - - `MessageRate` - trigger on the published rate into the queue - - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) - - `PublishedToDeliveredRatio` - trigger on the ratio of `MessageRate` to `DeliverGetRate` (see exmaple below) +- `mode` - QueueLength to trigger on number of messages in the queue. MessageRate to trigger on the published rate into the queue. (Values: `QueueLength`, `MessageRate`) - `value` - Message backlog or Publish/sec. rate to trigger on. (This value can be a float when `mode: MessageRate`) - `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds).(Default: `0`, Optional, This value can be a float) - `protocol` - Protocol to be used for communication. (Values: `auto`, `http`, `amqp`, Default: `auto`, Optional) @@ -68,7 +64,7 @@ Some parameters could be provided using environmental variables, instead of sett > ⚠ **Important:** if you have unacknowledged messages and want to have these counted for the scaling to happen, make sure to utilize the `http` REST API interface which allows for these to be counted. -> ⚠ **Important:** If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. +> ⚠ **Important:** If scaling against both is desired then the `ScaledObject` should have two triggers, one for `mode: QueueLength` and the other for `mode: MessageRate`. HPA will scale based on the largest result considering each of the two triggers independently. ### Authentication Parameters @@ -428,142 +424,3 @@ spec: authenticationRef: name: keda-trigger-auth-rabbitmq-conn ``` - -#### HTTP protocol (`DeliverGetRate`) - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: keda-rabbitmq-secret -data: - host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost ---- -apiVersion: keda.sh/v1alpha1 -kind: TriggerAuthentication -metadata: - name: keda-trigger-auth-rabbitmq-conn - namespace: default -spec: - secretTargetRef: - - parameter: host - name: keda-rabbitmq-secret - key: host ---- -apiVersion: keda.sh/v1alpha1 -kind: ScaledObject -metadata: - name: rabbitmq-scaledobject - namespace: default -spec: - scaleTargetRef: - name: rabbitmq-deployment - triggers: - - type: rabbitmq - metadata: - protocol: http - queueName: testqueue - mode: DeliverGetRate - value: "30" - authenticationRef: - name: rabbitmq-trigger-auth -``` - -#### HTTP protocol (`PublishedToDeliveredRatio`) - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: keda-rabbitmq-secret -data: - host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost ---- -apiVersion: keda.sh/v1alpha1 -kind: TriggerAuthentication -metadata: - name: keda-trigger-auth-rabbitmq-conn - namespace: default -spec: - secretTargetRef: - - parameter: host - name: keda-rabbitmq-secret - key: host ---- -apiVersion: keda.sh/v1alpha1 -kind: ScaledObject -metadata: - name: rabbitmq-scaledobject - namespace: default -spec: - scaleTargetRef: - name: rabbitmq-deployment - triggers: - - type: rabbitmq - metadata: - protocol: http - queueName: testqueue - mode: PublishedToDeliveredRatio - value: "1.1" - authenticationRef: - name: rabbitmq-trigger-auth -``` - -#### HTTP protocol (`PublishedToDeliveredRatio` with `scalingModifiers`) - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: keda-rabbitmq-secret -data: - host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost ---- -apiVersion: keda.sh/v1alpha1 -kind: TriggerAuthentication -metadata: - name: keda-trigger-auth-rabbitmq-conn - namespace: default -spec: - secretTargetRef: - - parameter: host - name: keda-rabbitmq-secret - key: host ---- -apiVersion: keda.sh/v1alpha1 -kind: ScaledObject -metadata: - name: rabbitmq-scaledobject - namespace: default -spec: - scaleTargetRef: - name: rabbitmq-deployment - triggers: - - type: rabbitmq - name: p2d_ratio - metadata: - protocol: http - queueName: testqueue - mode: PublishedToDeliveredRatio - value: "1" - authenticationRef: - name: rabbitmq-trigger-auth - - type: rabbitmq - name: qlen - metadata: - protocol: http - queueName: testqueue - mode: QueueLength - value: "100" - authenticationRef: - name: rabbitmq-trigger-auth - advanced: - # Bind QueueLength and PublishedToDeliveredRatio together to control trigger value - scalingModifiers: - metricType: "Value" - # Trigger if either one of conditions is met: - # - publishing to delivery rate exceeds factor of 1.2 - # - queue lenght contains more than 1.2K messages - formula: "max(p2d_ratio, qlen/1000)" - target: 1.2 -``` diff --git a/content/docs/2.18/scalers/rabbitmq-queue.md b/content/docs/2.18/scalers/rabbitmq-queue.md index 1f59ec6a1..b4a1abeac 100644 --- a/content/docs/2.18/scalers/rabbitmq-queue.md +++ b/content/docs/2.18/scalers/rabbitmq-queue.md @@ -9,100 +9,111 @@ go_file = "rabbitmq_scaler" ### Trigger Specification -This specification describes the `rabbitmq` trigger for RabbitMQ Queue. +This specification describes the `rabbitmq` trigger for RabbitMQ queue. ```yaml triggers: - type: rabbitmq metadata: - host: amqp://localhost:5672/vhost # Optional. If not specified, it must be done by using TriggerAuthentication. - protocol: auto # Optional. Specifies protocol to use, either amqp or http, or auto to autodetect based on the `host` value. Default value is auto. - mode: QueueLength # QueueLength, MessageRate, DeliverGetRate or PublishedToDeliveredRatio - value: "100.50" # message backlog or publish/sec. target per instance - activationValue: "10.5" # Optional. Activation threshold - queueName: testqueue - vhostName: / # Optional. If not specified, use the vhost in the `host` connection string. Required for Azure AD Workload Identity authorization (see bellow) - # Alternatively, you can use existing environment variables to read configuration from: - # See details in "Parameter list" section - hostFromEnv: RABBITMQ_HOST # Optional. You can use this instead of `host` parameter - usernameFromEnv: RABBITMQ_USERNAME # Optional. You can use this instead of TriggerAuthentication - passwordFromEnv: RABBITMQ_PASSWORD # Optional. You can use this instead of TriggerAuthentication - unsafeSsl: true - timeout: 1000 # Optional. Custom timeout for the HTTP client used in this scaler + host: amqp://:/ # Optional. If not specified, it must be done by using TriggerAuthentication. + protocol: auto # Optional. Specifies protocol to use, either `amqp`, `http`, or `auto` for auto-detection based on the `host` value. Default value is `auto`. + mode: QueueLength # Supported modes are `QueueLength`, `MessageRate`, `DeliverGetRate`, `PublishedToDeliveredRatio` or `ExpectedQueueConsumptionTime` + value: "100.50" # A value defining the threshold (per instance) that, when exceeded, triggers the scaling. + activationValue: "10.5" # Optional. Activation threshold, which by default is 0. + queueName: testqueue # Name of the queue. + vhostName: / # Optional. If not specified, use the VHost in the `host` connection string. Required for Azure AD Workload Identity authorization (see below). + # You can use existing environment variables to read configuration from. For details see "Parameters list" section. + hostFromEnv: RABBITMQ_HOST # Optional. You can use this instead of `host` parameter. + usernameFromEnv: RABBITMQ_USERNAME # Optional. You can use this instead of `TriggerAuthentication`. + passwordFromEnv: RABBITMQ_PASSWORD # Optional. You can use this instead of `TriggerAuthentication`. + unsafeSsl: true # Optional. Whether to allow unsafe SSL connections. + timeout: 1000 # Optional. Custom timeout for the HTTP client used in this scaler. ``` -**Parameter list:** +**Parameters list:** -- `host` - Host of RabbitMQ with format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain vhost than the trailing slash is required in this case like `http://guest:password@localhost:5672/`. When using a username/password consider using `hostFromEnv` or a TriggerAuthentication. -- `queueName` - Name of the queue to read message from. -- `mode` - Trigger mode. Can be one of following: +- `host` - RabbitMQ host address in the format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example, the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain `vhost`, then the trailing slash is required, e.g. `http://guest:password@localhost:5672/`. When using a username with password consider using `hostFromEnv` or a `TriggerAuthentication`. +- `queueName` - Name of the queue to read required information and stats from. +- `mode` - Trigger mode. See [Choosing the right trigger mode](#choosing-the-right-trigger-mode) for additional details. Can be one of: - `QueueLength` - trigger on number of messages in the queue - - `MessageRate` - trigger on the published rate into the queue - - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) - - `PublishedToDeliveredRatio` - trigger on the ratio of `MessageRate` to `DeliverGetRate` (see exmaple below) -- `value` - Message backlog or Publish/sec. rate to trigger on. (This value can be a float when `mode: MessageRate`) -- `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds).(Default: `0`, Optional, This value can be a float) -- `protocol` - Protocol to be used for communication. (Values: `auto`, `http`, `amqp`, Default: `auto`, Optional) -- `vhostName` - Vhost to use for the connection, overrides any vhost set in the connection string from `host`/`hostFromEnv`. (Optional / Required if Azure AD Workload Identity authorization is used) -- `queueLength` - DEPRECATED! Use `mode: QueueLength` and `value: ##` instead. Target value for queue length passed to the scaler. Example: if one pod can handle 10 messages, set the queue length target to 10. If the actual number of messages in the queue is 30, the scaler scales to 3 pods. Default is 20 unless `publishRate` is specified, in which case `queueLength` is disabled for this trigger. -- `useRegex` - This parameter allows to use regex (in `queueName` parameter) to select queue instead of full name. (Values: `true`, `false`, Default: `false`, Optional, Only applies to hosts that use the `http` protocol) -- `pageSize` - This parameter allows setting page size. (Default: `100`, Optional, Only applies when `useRegex` is `true`) -- `operation` - Operation that will be applied to compute the number of messages in case of `useRegex` enabled. Either `sum` (default),`max`, or `avg`. (Optional) -- `timeout` - Timeout in milliseconds **for this specific trigger**. This value will override the value defined in `KEDA_HTTP_DEFAULT_TIMEOUT`. (Optional, Only applies to hosts that use the `http` protocol) -- `excludeUnacknowledged` - Set to `true` to specify that the `QueueLength` value should exclude unacknowledged messages (Ready messages only). (Values: `true`, `false`, Default: `false`, Optional, Only applies to hosts that use the `http` protocol) -- `unsafeSsl` - Whether to allow unsafe SSL (Values: `true`, `false`, Default: `false` ) - -Some parameters could be provided using environmental variables, instead of setting them directly in metadata. Here is a list of parameters you can use to retrieve values from environment variables: - -- `hostFromEnv` - The host and port of the RabbitMQ server, similar to `host`, but reads it from an environment variable on the scale target. -- `usernameFromEnv` - The username to use to connect to the broker's management endpoint. -- `passwordFromEnv` - The password to use to connect to the broker's management endpoint. - -> 💡 **Note:** `host`/`hostFromEnv` has an optional vhost name after the host slash which will be used to scope API request. - -> 💡 **Note:** When using `host`/`hostFromEnv` or TriggerAuthentication, the supplied password cannot contain special characters. - -> 💡 **Note:** `mode: MessageRate` requires protocol `http`. - -> 💡 **Note:** `useRegex: "true"` requires protocol `http`. - -> ⚠ **Important:** if you have unacknowledged messages and want to have these counted for the scaling to happen, make sure to utilize the `http` REST API interface which allows for these to be counted. - -> ⚠ **Important:** If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. + - `MessageRate` - trigger on the publishing rate reported by the queue + - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) reported by the queue + - `PublishedToDeliveredRatio` - trigger on the value of ratio of `MessageRate` to `DeliverGetRate` + - `ExpectedQueueConsumptionTime` - trigger on the value of expected time (in seconds) of consumption of all messages currently available in the queue (utilizes `QueueLength`, `MessageRate` and `DeliverGetRate` metrics). +- `value` - A value defining the threshold (per instance) that, when exceeded, triggers the scaling (can be a floating-point number depending on the trigger mode). +- `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds) (default: `0`; optional; can be a floating-point number). +- `protocol` - Protocol to be used for communication (values: `auto`, `http`, `amqp`; default: `auto`; optional). +- `vhostName` - VHost to use for the connection, overrides any VHost set in the connection string from `host`/`hostFromEnv` (it's optional by default but **it is required** if Azure AD Workload Identity authorization is used). +- `queueLength` - **DEPRECATED: please use `mode: QueueLength` and `value: ##` instead**. Defines a threshold value for the queue length passed to the scaler. For example: if one pod can handle 10 messages, set the queue length target to `10`. If the actual number of messages in the queue is 30, the scaler will scale up to 3 pods. Default is set to `20` unless `publishRate` is specified, in which case `queueLength` is disabled for this trigger. +- `useRegex` - This parameter allows to use regex (in `queueName` parameter) to select queue instead of using full name (values: `true`, `false`; default: `false`; optional; only applies to hosts that use the `http` protocol). +- `pageSize` - This parameter allows setting the page size (default: `100`; optional; only applies when `useRegex` is set to `true`). +- `operation` - Operation that will be applied to compute the number of messages in case when `useRegex` is enabled (values: `sum`, `max`, `avg`; defaults: `sum`; optional). +- `timeout` - Timeout in milliseconds **for this specific trigger**. This value will override the value defined in `KEDA_HTTP_DEFAULT_TIMEOUT` (optional; only applies to hosts that use the `http` protocol). +- `excludeUnacknowledged` - Set to `true` to specify that the `QueueLength` value should exclude unacknowledged messages (ready messages only; values:`true`, `false`; default: `false`; optional; only applies to hosts that use the `http` protocol). +- `unsafeSsl` - Whether to allow unsafe SSL connections (values: `true`, `false`, default: `false`). + +Some parameters can be provided using environment variables instead of setting them directly in metadata: +- `hostFromEnv` - reads the host and port of the RabbitMQ server from selected environment variable (in similar format as `host` parameter) +- `usernameFromEnv` - reads the username from selected environment variable, which is used to connect to the broker’s management endpoint +- `passwordFromEnv` - reads the password from selected environment variable, which is used to connect to the broker’s management endpoint. + +> 💡 **Notes:** +> - `host`/`hostFromEnv` has an optional VHost name after the host slash which will be used to scope API request +> - when using `host`/`hostFromEnv` or `TriggerAuthentication`, the supplied password cannot contain special characters +> - trigger modes `MessageRate`, `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` require `http` protocol. +> - setting `useRegex` to `true` also requires `protocol` to be set to `http`. + +> ⚠ **Important:** +> - If you have unacknowledged messages and you want to have these counted for the scaling to happen, make sure to utilize the `http` protocol (only REST API interface allows for these to be counted). +> - If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. + +### Choosing the right trigger mode + +Below you can find available trigger modes with most common usage scenarios: +- `QueueLength` - Mainly used to scale messages consuming services, where it is desired to keep number of messages in the queue at selected, nominal level. +- `MessageRate` - Mainly used to scale messages consuming services, where it is desired to keep the consumption rate up to messages publication rate (or higher). +- `DeliverGetRate` - This specific trigger is actually a byproduct of the resulting implementation of `PublishedToDeliveredRatio` trigger (it was implemented to be used within `scalingModifiers` as a part of composite metric), yet it still has its use in some scenarios. E.g. assuming there's a well known consumer service performance ballpark, `DeliverGetRate` trigger can be utilized to scale out messages publishing service in order to increase publication rate. In this particular example however, upper publication rate limit must be properly guarded by another trigger or by [`maxReplicaCount`](./../reference/scaledobject-spec/#maxreplicacount) so as not to scale infinitely (which could result in overloading the broker, or consumers, or both). +- `PublishedToDeliveredRatio` - This trigger is used mainly to control consumer pods scaling to keep publishing and consuming rates at stable level. Assuming that this is the case, the principle of operation is this: + - if publishing rate is greater than `value` (usually it is a value slightly above `1`), trigger will initiate scale-out process to launch more consumer pods + - if publishing rate is equal to consumption rate (value `1`) then it is the indicator that capacity of consumers is sufficient for handling ongoing messages processing and no additional pods need to be added to the pool + - if ratio is below `1`, HPA can gracefully take down some consumers but keep messages processing rate at stable level. +- `ExpectedQueueConsumptionTime` - A trigger primarily used to scale consumer pods, which uses estimate value of pending time to deliver all available messages in the queue to the consumers. If it becomes active in this particular scenario, returned metric indicates growing number of messages due either increased publishing rate or degraded performance of currently active number of consumers. It relies on proper setting of `pollingInterval` (see below for details). + +> ⚠ **Important:** +> - With `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` it is advised to set `metricType: Value` in the trigger configuration to rely on absolute metric value and not the average value across all scaled pods. For reference see [`triggers.metricType`](./../reference/scaledobject-spec/#triggers) and [`scalingModifiers.metricType`](./../reference/scaledobject-spec/#scalingmodifiersmetrictype). +> - When using `PublishedToDeliveredRatio`, having stable publication to consumption rate may not indicate that consumers pool is of the right size to do the job, since the messages consuming capabilities can change over time, which may result in much higher number of consumers than actually needed. It is then recommended to periodically re-evaluate consumers pool size using different, probably external metric (e.g. consumers count number, size of prefetch buffer, consumer performance, etc.). +> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it is best served with `pollingInterval` set to 1 second. However, since frequent polling may be expensive, it is then recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` formula multiplied by value of `pollingInterval`. ### Authentication Parameters -TriggerAuthentication CRD is used to connect and authenticate to RabbitMQ: - +`TriggerAuthentication` CRD is used to connect and authenticate to RabbitMQ: - For AMQP, the URI should look similar to `amqp://guest:password@localhost:5672/vhost`. - For HTTP, the URI should look similar to `http://guest:password@localhost:15672/path/vhost`. + > See the [RabbitMQ Ports](https://www.rabbitmq.com/networking.html#ports) section for more details on how to configure the ports. +- `vhostName` - VHost to use for the connection, overrides any VHost set in the connection string from `host`/`hostFromEnv` (optional, but **required** if Azure AD Workload Identity authorization is used). -> See the [RabbitMQ Ports](https://www.rabbitmq.com/networking.html#ports) section for more details on how to configure the ports. - -- `vhostName` - Vhost to use for the connection, overrides any vhost set in the connection string from `host`/`hostFromEnv`. (Optional / Required if Azure AD Workload Identity authorization is used) -**Username and Password based authentication:** - -This allows sensitive credentials to be stored and managed separately from the connection string. +#### Username and Password based authentication +This allows sensitive credentials to be stored and managed separately from the connection string: - `username` - The username to use to connect to the broker's management endpoint. - `password` - The password to use to connect to the broker's management endpoint. -> 💡 **Note:** If username or password are set in TriggerAuthentication or environment variables, they will override any credentials provided in the host. +> 💡 **Note:** If username or password are set in `TriggerAuthentication` or environment variables, they will override any credentials provided in the `host` parameter. -**TLS authentication:** +#### TLS authentication -- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ is not used. (Values: `enable`, `disable`, Default: `disable`, Optional) -- `ca` - Certificate authority file for TLS client authentication. (Optional) -- `cert` - Certificate for client authentication. (Optional) -- `key` - Key for client authentication. (Optional) +- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ will not be used. Valid values are `enable` ir `disable` (optional; the default is `disable`). +- `ca` - Certificate authority file for TLS client authentication (optional). +- `cert` - Certificate for client authentication (optional). +- `key` - Certificate Key for client authentication (optional). -> Using RabbitMQ host with amqps will require enabling the tls settings and passing the required parameters. +> 💡 **Note:** Using RabbitMQ host with AMQPS protocol will require enabling the TLS settings and passing the required parameters. -**Azure Workload Identity authentication:** +#### Azure Workload Identity authentication -For RabbitMQ with OIDC support (>= 3.11) you can use TriggerAuthentication CRD with `podIdentity.provider = azure-workload` and with parameter `workloadIdentityResource` which would hold application identifier of App Registration in Azure AD. In this case `username:password` part in host URI should be omitted and `vHostName` has to be set explicitly in `ScaledObject`. Only HTTP protocol is supported for AKS Workload Identity currently. +For RabbitMQ with OIDC support (>= 3.11) you can use `TriggerAuthentication` CRD with `podIdentity.provider = azure-workload` and with `workloadIdentityResource` parameter, which will hold application identifier of App Registration in Azure AD. In this case `username:password` part in host URI should be omitted and `vHostName` has to be set explicitly in `ScaledObject`. Currently, only HTTP protocol is supported for AKS Workload Identity. -### Example +### Configuration examples #### AMQP protocol: @@ -148,7 +159,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### AMQP protocol with user/password auth: +#### AMQP protocol with username and password authorization: ```yaml apiVersion: v1 @@ -196,7 +207,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### AMQPS protocol with TLS auth: +#### AMQPS protocol with TLS authorization: ```yaml apiVersion: v1 @@ -252,7 +263,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`): +#### HTTP protocol (with `QueueLength` trigger): ```yaml apiVersion: v1 @@ -292,7 +303,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`MessageRate` and `QueueLength`): +#### HTTP protocol (with `MessageRate` and `QueueLength` triggers): ```yaml apiVersion: v1 @@ -340,7 +351,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`) and using regex (`useRegex`): +#### HTTP protocol (with `QueueLength` trigger) and enabled `useRegex`: ```yaml apiVersion: v1 @@ -382,7 +393,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`) with Azure Workload Identity: +#### HTTP protocol (with `QueueLength` trigger) with Azure Workload Identity: ```yaml apiVersion: v1 @@ -429,7 +440,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`DeliverGetRate`) +#### HTTP protocol (with `DeliverGetRate` trigger) ```yaml apiVersion: v1 @@ -460,6 +471,7 @@ spec: name: rabbitmq-deployment triggers: - type: rabbitmq + metricType: Value metadata: protocol: http queueName: testqueue @@ -469,7 +481,7 @@ spec: name: rabbitmq-trigger-auth ``` -#### HTTP protocol (`PublishedToDeliveredRatio`) +#### HTTP protocol (with `PublishedToDeliveredRatio` trigger) ```yaml apiVersion: v1 @@ -500,6 +512,7 @@ spec: name: rabbitmq-deployment triggers: - type: rabbitmq + metricType: Value metadata: protocol: http queueName: testqueue @@ -509,7 +522,7 @@ spec: name: rabbitmq-trigger-auth ``` -#### HTTP protocol (`PublishedToDeliveredRatio` with `scalingModifiers`) +#### HTTP protocol (with `PublishedToDeliveredRatio` trigger used together with `scalingModifiers`) ```yaml apiVersion: v1 @@ -540,6 +553,7 @@ spec: name: rabbitmq-deployment triggers: - type: rabbitmq + metricType: Value name: p2d_ratio metadata: protocol: http @@ -560,10 +574,53 @@ spec: advanced: # Bind QueueLength and PublishedToDeliveredRatio together to control trigger value scalingModifiers: - metricType: "Value" + metricType: Value # Trigger if either one of conditions is met: # - publishing to delivery rate exceeds factor of 1.2 - # - queue lenght contains more than 1.2K messages + # - queue length contains more than 1.2K messages formula: "max(p2d_ratio, qlen/1000)" target: 1.2 ``` + +#### HTTP protocol (with `ExpectedQueueConsumptionTime` trigger) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + pollingInterval: 1 + triggers: + - type: rabbitmq + metricType: Value + name: eqct + metadata: + protocol: http + queueName: testqueue + mode: ExpectedQueueConsumptionTime + value: "20" + authenticationRef: + name: rabbitmq-trigger-auth +``` From 07735888d9d0d44667d83c289ee59049aee14aff Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Tue, 9 Sep 2025 23:10:40 +0200 Subject: [PATCH 3/6] typo Signed-off-by: Wojciech Moczulski --- content/docs/2.18/scalers/rabbitmq-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/2.18/scalers/rabbitmq-queue.md b/content/docs/2.18/scalers/rabbitmq-queue.md index b4a1abeac..e7a36029f 100644 --- a/content/docs/2.18/scalers/rabbitmq-queue.md +++ b/content/docs/2.18/scalers/rabbitmq-queue.md @@ -102,7 +102,7 @@ This allows sensitive credentials to be stored and managed separately from the c #### TLS authentication -- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ will not be used. Valid values are `enable` ir `disable` (optional; the default is `disable`). +- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ will not be used. Valid values are `enable` or `disable` (optional; the default is `disable`). - `ca` - Certificate authority file for TLS client authentication (optional). - `cert` - Certificate for client authentication (optional). - `key` - Certificate Key for client authentication (optional). From 0352aa6d2baa97057b6ff6218faec52d33cd9411 Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Mon, 13 Oct 2025 11:56:36 +0200 Subject: [PATCH 4/6] update ExpectedQueueConsumptionTime notice on using longer pollingInterval Signed-off-by: Wojciech Moczulski --- content/docs/2.18/scalers/rabbitmq-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/2.18/scalers/rabbitmq-queue.md b/content/docs/2.18/scalers/rabbitmq-queue.md index e7a36029f..1edcac964 100644 --- a/content/docs/2.18/scalers/rabbitmq-queue.md +++ b/content/docs/2.18/scalers/rabbitmq-queue.md @@ -82,7 +82,7 @@ Below you can find available trigger modes with most common usage scenarios: > ⚠ **Important:** > - With `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` it is advised to set `metricType: Value` in the trigger configuration to rely on absolute metric value and not the average value across all scaled pods. For reference see [`triggers.metricType`](./../reference/scaledobject-spec/#triggers) and [`scalingModifiers.metricType`](./../reference/scaledobject-spec/#scalingmodifiersmetrictype). > - When using `PublishedToDeliveredRatio`, having stable publication to consumption rate may not indicate that consumers pool is of the right size to do the job, since the messages consuming capabilities can change over time, which may result in much higher number of consumers than actually needed. It is then recommended to periodically re-evaluate consumers pool size using different, probably external metric (e.g. consumers count number, size of prefetch buffer, consumer performance, etc.). -> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it is best served with `pollingInterval` set to 1 second. However, since frequent polling may be expensive, it is then recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` formula multiplied by value of `pollingInterval`. +> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it is best served with `pollingInterval` set to 1 second. However, in case where such frequent polling may be expensive, it is recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` using additional triggers values in formula like so: `(ExpectedQueueConsumptionTime - (QueueLength / DeliverGetRate)) * pollingInterval + (QueueLength / DeliverGetRate)`. ### Authentication Parameters From 0e8a75841ffecfbb4cde030eaccd27c70361af29 Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Mon, 13 Oct 2025 12:08:52 +0200 Subject: [PATCH 5/6] actually, while using ExpectedQueueConsumptionTime pollingInterval *must* be set to 1 second Signed-off-by: Wojciech Moczulski --- content/docs/2.18/scalers/rabbitmq-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/2.18/scalers/rabbitmq-queue.md b/content/docs/2.18/scalers/rabbitmq-queue.md index 1edcac964..8b3e1f649 100644 --- a/content/docs/2.18/scalers/rabbitmq-queue.md +++ b/content/docs/2.18/scalers/rabbitmq-queue.md @@ -82,7 +82,7 @@ Below you can find available trigger modes with most common usage scenarios: > ⚠ **Important:** > - With `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` it is advised to set `metricType: Value` in the trigger configuration to rely on absolute metric value and not the average value across all scaled pods. For reference see [`triggers.metricType`](./../reference/scaledobject-spec/#triggers) and [`scalingModifiers.metricType`](./../reference/scaledobject-spec/#scalingmodifiersmetrictype). > - When using `PublishedToDeliveredRatio`, having stable publication to consumption rate may not indicate that consumers pool is of the right size to do the job, since the messages consuming capabilities can change over time, which may result in much higher number of consumers than actually needed. It is then recommended to periodically re-evaluate consumers pool size using different, probably external metric (e.g. consumers count number, size of prefetch buffer, consumer performance, etc.). -> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it is best served with `pollingInterval` set to 1 second. However, in case where such frequent polling may be expensive, it is recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` using additional triggers values in formula like so: `(ExpectedQueueConsumptionTime - (QueueLength / DeliverGetRate)) * pollingInterval + (QueueLength / DeliverGetRate)`. +> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it must be served with `pollingInterval` set to 1 second. However, in case where such frequent polling may be expensive, it is recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` using additional triggers values in formula like so: `(ExpectedQueueConsumptionTime - (QueueLength / DeliverGetRate)) * pollingInterval + (QueueLength / DeliverGetRate)`. ### Authentication Parameters From 9bfeab2c41768f80e62fc62f241d9feee610a3b0 Mon Sep 17 00:00:00 2001 From: Wojciech Moczulski Date: Mon, 27 Oct 2025 13:16:59 +0100 Subject: [PATCH 6/6] publish information about new RabbitMQ scaler's trigger modes in 2.19 version Signed-off-by: Wojciech Moczulski --- content/docs/2.19/scalers/rabbitmq-queue.md | 346 +++++++++++++++----- 1 file changed, 273 insertions(+), 73 deletions(-) diff --git a/content/docs/2.19/scalers/rabbitmq-queue.md b/content/docs/2.19/scalers/rabbitmq-queue.md index 0cfc9b219..8b3e1f649 100644 --- a/content/docs/2.19/scalers/rabbitmq-queue.md +++ b/content/docs/2.19/scalers/rabbitmq-queue.md @@ -9,96 +9,111 @@ go_file = "rabbitmq_scaler" ### Trigger Specification -This specification describes the `rabbitmq` trigger for RabbitMQ Queue. +This specification describes the `rabbitmq` trigger for RabbitMQ queue. ```yaml triggers: - type: rabbitmq metadata: - host: amqp://localhost:5672/vhost # Optional. If not specified, it must be done by using TriggerAuthentication. - protocol: auto # Optional. Specifies protocol to use, either amqp or http, or auto to autodetect based on the `host` value. Default value is auto. - mode: QueueLength # QueueLength or MessageRate - value: "100.50" # message backlog or publish/sec. target per instance - activationValue: "10.5" # Optional. Activation threshold - queueName: testqueue - vhostName: / # Optional. If not specified, use the vhost in the `host` connection string. Required for Azure AD Workload Identity authorization (see bellow) - # Alternatively, you can use existing environment variables to read configuration from: - # See details in "Parameter list" section - hostFromEnv: RABBITMQ_HOST # Optional. You can use this instead of `host` parameter - usernameFromEnv: RABBITMQ_USERNAME # Optional. You can use this instead of TriggerAuthentication - passwordFromEnv: RABBITMQ_PASSWORD # Optional. You can use this instead of TriggerAuthentication - unsafeSsl: true - timeout: "1000" # Optional. Custom timeout for the HTTP client used in this scaler + host: amqp://:/ # Optional. If not specified, it must be done by using TriggerAuthentication. + protocol: auto # Optional. Specifies protocol to use, either `amqp`, `http`, or `auto` for auto-detection based on the `host` value. Default value is `auto`. + mode: QueueLength # Supported modes are `QueueLength`, `MessageRate`, `DeliverGetRate`, `PublishedToDeliveredRatio` or `ExpectedQueueConsumptionTime` + value: "100.50" # A value defining the threshold (per instance) that, when exceeded, triggers the scaling. + activationValue: "10.5" # Optional. Activation threshold, which by default is 0. + queueName: testqueue # Name of the queue. + vhostName: / # Optional. If not specified, use the VHost in the `host` connection string. Required for Azure AD Workload Identity authorization (see below). + # You can use existing environment variables to read configuration from. For details see "Parameters list" section. + hostFromEnv: RABBITMQ_HOST # Optional. You can use this instead of `host` parameter. + usernameFromEnv: RABBITMQ_USERNAME # Optional. You can use this instead of `TriggerAuthentication`. + passwordFromEnv: RABBITMQ_PASSWORD # Optional. You can use this instead of `TriggerAuthentication`. + unsafeSsl: true # Optional. Whether to allow unsafe SSL connections. + timeout: 1000 # Optional. Custom timeout for the HTTP client used in this scaler. ``` -**Parameter list:** - -- `host` - Host of RabbitMQ with format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain vhost than the trailing slash is required in this case like `http://guest:password@localhost:5672/`. When using a username/password consider using `hostFromEnv` or a TriggerAuthentication. -- `queueName` - Name of the queue to read message from. -- `mode` - QueueLength to trigger on number of messages in the queue. MessageRate to trigger on the published rate into the queue. (Values: `QueueLength`, `MessageRate`) -- `value` - Message backlog or Publish/sec. rate to trigger on. (This value can be a float when `mode: MessageRate`) -- `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds).(Default: `0`, Optional, This value can be a float) -- `protocol` - Protocol to be used for communication. (Values: `auto`, `http`, `amqp`, Default: `auto`, Optional) -- `vhostName` - Vhost to use for the connection, overrides any vhost set in the connection string from `host`/`hostFromEnv`. (Optional / Required if Azure AD Workload Identity authorization is used) -- `queueLength` - DEPRECATED! Use `mode: QueueLength` and `value: ##` instead. Target value for queue length passed to the scaler. Example: if one pod can handle 10 messages, set the queue length target to 10. If the actual number of messages in the queue is 30, the scaler scales to 3 pods. Default is 20 unless `publishRate` is specified, in which case `queueLength` is disabled for this trigger. -- `useRegex` - This parameter allows to use regex (in `queueName` parameter) to select queue instead of full name. (Values: `true`, `false`, Default: `false`, Optional, Only applies to hosts that use the `http` protocol) -- `pageSize` - This parameter allows setting page size. (Default: `100`, Optional, Only applies when `useRegex` is `true`) -- `operation` - Operation that will be applied to compute the number of messages in case of `useRegex` enabled. Either `sum` (default),`max`, or `avg`. (Optional) -- `timeout` - Timeout in milliseconds **for this specific trigger**. This value will override the value defined in `KEDA_HTTP_DEFAULT_TIMEOUT`. (Optional, Only applies to hosts that use the `http` protocol) -- `excludeUnacknowledged` - Set to `true` to specify that the `QueueLength` value should exclude unacknowledged messages (Ready messages only). (Values: `true`, `false`, Default: `false`, Optional, Only applies to hosts that use the `http` protocol) -- `unsafeSsl` - Whether to allow unsafe SSL (Values: `true`, `false`, Default: `false` ) - -Some parameters could be provided using environmental variables, instead of setting them directly in metadata. Here is a list of parameters you can use to retrieve values from environment variables: - -- `hostFromEnv` - The host and port of the RabbitMQ server, similar to `host`, but reads it from an environment variable on the scale target. -- `usernameFromEnv` - The username to use to connect to the broker's management endpoint. -- `passwordFromEnv` - The password to use to connect to the broker's management endpoint. - -> 💡 **Note:** `host`/`hostFromEnv` has an optional vhost name after the host slash which will be used to scope API request. - -> 💡 **Note:** When using `host`/`hostFromEnv` or TriggerAuthentication, the supplied password cannot contain special characters. - -> 💡 **Note:** `mode: MessageRate` requires protocol `http`. - -> 💡 **Note:** `useRegex: "true"` requires protocol `http`. - -> ⚠ **Important:** if you have unacknowledged messages and want to have these counted for the scaling to happen, make sure to utilize the `http` REST API interface which allows for these to be counted. - -> ⚠ **Important:** If scaling against both is desired then the `ScaledObject` should have two triggers, one for `mode: QueueLength` and the other for `mode: MessageRate`. HPA will scale based on the largest result considering each of the two triggers independently. +**Parameters list:** + +- `host` - RabbitMQ host address in the format `://:/vhost`. If the protocol is HTTP than the host may follow this format `http://://`. In example, the resolved host value could be `amqp://guest:password@localhost:5672/vhost` or `http://guest:password@localhost:15672/path/vhost`. If the host doesn't contain `vhost`, then the trailing slash is required, e.g. `http://guest:password@localhost:5672/`. When using a username with password consider using `hostFromEnv` or a `TriggerAuthentication`. +- `queueName` - Name of the queue to read required information and stats from. +- `mode` - Trigger mode. See [Choosing the right trigger mode](#choosing-the-right-trigger-mode) for additional details. Can be one of: + - `QueueLength` - trigger on number of messages in the queue + - `MessageRate` - trigger on the publishing rate reported by the queue + - `DeliverGetRate` - trigger on the rate of delivered messages (to consumers or in response to `basic.get`, both acknowledged and not) reported by the queue + - `PublishedToDeliveredRatio` - trigger on the value of ratio of `MessageRate` to `DeliverGetRate` + - `ExpectedQueueConsumptionTime` - trigger on the value of expected time (in seconds) of consumption of all messages currently available in the queue (utilizes `QueueLength`, `MessageRate` and `DeliverGetRate` metrics). +- `value` - A value defining the threshold (per instance) that, when exceeded, triggers the scaling (can be a floating-point number depending on the trigger mode). +- `activationValue` - Target value for activating the scaler. Learn more about activation [here](./../concepts/scaling-deployments.md#activating-and-scaling-thresholds) (default: `0`; optional; can be a floating-point number). +- `protocol` - Protocol to be used for communication (values: `auto`, `http`, `amqp`; default: `auto`; optional). +- `vhostName` - VHost to use for the connection, overrides any VHost set in the connection string from `host`/`hostFromEnv` (it's optional by default but **it is required** if Azure AD Workload Identity authorization is used). +- `queueLength` - **DEPRECATED: please use `mode: QueueLength` and `value: ##` instead**. Defines a threshold value for the queue length passed to the scaler. For example: if one pod can handle 10 messages, set the queue length target to `10`. If the actual number of messages in the queue is 30, the scaler will scale up to 3 pods. Default is set to `20` unless `publishRate` is specified, in which case `queueLength` is disabled for this trigger. +- `useRegex` - This parameter allows to use regex (in `queueName` parameter) to select queue instead of using full name (values: `true`, `false`; default: `false`; optional; only applies to hosts that use the `http` protocol). +- `pageSize` - This parameter allows setting the page size (default: `100`; optional; only applies when `useRegex` is set to `true`). +- `operation` - Operation that will be applied to compute the number of messages in case when `useRegex` is enabled (values: `sum`, `max`, `avg`; defaults: `sum`; optional). +- `timeout` - Timeout in milliseconds **for this specific trigger**. This value will override the value defined in `KEDA_HTTP_DEFAULT_TIMEOUT` (optional; only applies to hosts that use the `http` protocol). +- `excludeUnacknowledged` - Set to `true` to specify that the `QueueLength` value should exclude unacknowledged messages (ready messages only; values:`true`, `false`; default: `false`; optional; only applies to hosts that use the `http` protocol). +- `unsafeSsl` - Whether to allow unsafe SSL connections (values: `true`, `false`, default: `false`). + +Some parameters can be provided using environment variables instead of setting them directly in metadata: +- `hostFromEnv` - reads the host and port of the RabbitMQ server from selected environment variable (in similar format as `host` parameter) +- `usernameFromEnv` - reads the username from selected environment variable, which is used to connect to the broker’s management endpoint +- `passwordFromEnv` - reads the password from selected environment variable, which is used to connect to the broker’s management endpoint. + +> 💡 **Notes:** +> - `host`/`hostFromEnv` has an optional VHost name after the host slash which will be used to scope API request +> - when using `host`/`hostFromEnv` or `TriggerAuthentication`, the supplied password cannot contain special characters +> - trigger modes `MessageRate`, `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` require `http` protocol. +> - setting `useRegex` to `true` also requires `protocol` to be set to `http`. + +> ⚠ **Important:** +> - If you have unacknowledged messages and you want to have these counted for the scaling to happen, make sure to utilize the `http` protocol (only REST API interface allows for these to be counted). +> - If scaling against many is desired, then the `ScaledObject` should have all desired triggers defined. HPA will scale based on the largest result considering each of triggers independently. + +### Choosing the right trigger mode + +Below you can find available trigger modes with most common usage scenarios: +- `QueueLength` - Mainly used to scale messages consuming services, where it is desired to keep number of messages in the queue at selected, nominal level. +- `MessageRate` - Mainly used to scale messages consuming services, where it is desired to keep the consumption rate up to messages publication rate (or higher). +- `DeliverGetRate` - This specific trigger is actually a byproduct of the resulting implementation of `PublishedToDeliveredRatio` trigger (it was implemented to be used within `scalingModifiers` as a part of composite metric), yet it still has its use in some scenarios. E.g. assuming there's a well known consumer service performance ballpark, `DeliverGetRate` trigger can be utilized to scale out messages publishing service in order to increase publication rate. In this particular example however, upper publication rate limit must be properly guarded by another trigger or by [`maxReplicaCount`](./../reference/scaledobject-spec/#maxreplicacount) so as not to scale infinitely (which could result in overloading the broker, or consumers, or both). +- `PublishedToDeliveredRatio` - This trigger is used mainly to control consumer pods scaling to keep publishing and consuming rates at stable level. Assuming that this is the case, the principle of operation is this: + - if publishing rate is greater than `value` (usually it is a value slightly above `1`), trigger will initiate scale-out process to launch more consumer pods + - if publishing rate is equal to consumption rate (value `1`) then it is the indicator that capacity of consumers is sufficient for handling ongoing messages processing and no additional pods need to be added to the pool + - if ratio is below `1`, HPA can gracefully take down some consumers but keep messages processing rate at stable level. +- `ExpectedQueueConsumptionTime` - A trigger primarily used to scale consumer pods, which uses estimate value of pending time to deliver all available messages in the queue to the consumers. If it becomes active in this particular scenario, returned metric indicates growing number of messages due either increased publishing rate or degraded performance of currently active number of consumers. It relies on proper setting of `pollingInterval` (see below for details). + +> ⚠ **Important:** +> - With `DeliverGetRate`, `PublishedToDeliveredRatio` and `ExpectedQueueConsumptionTime` it is advised to set `metricType: Value` in the trigger configuration to rely on absolute metric value and not the average value across all scaled pods. For reference see [`triggers.metricType`](./../reference/scaledobject-spec/#triggers) and [`scalingModifiers.metricType`](./../reference/scaledobject-spec/#scalingmodifiersmetrictype). +> - When using `PublishedToDeliveredRatio`, having stable publication to consumption rate may not indicate that consumers pool is of the right size to do the job, since the messages consuming capabilities can change over time, which may result in much higher number of consumers than actually needed. It is then recommended to periodically re-evaluate consumers pool size using different, probably external metric (e.g. consumers count number, size of prefetch buffer, consumer performance, etc.). +> - Since `ExpectedQueueConsumptionTime` trigger mode is based on the expected time (in seconds) for the selected queue to be emptied of all messages (including estimated count of published messages during sample probing), it must be served with `pollingInterval` set to 1 second. However, in case where such frequent polling may be expensive, it is recommended to use `ExpectedQueueConsumptionTime` in `scalingModifiers` using additional triggers values in formula like so: `(ExpectedQueueConsumptionTime - (QueueLength / DeliverGetRate)) * pollingInterval + (QueueLength / DeliverGetRate)`. ### Authentication Parameters -TriggerAuthentication CRD is used to connect and authenticate to RabbitMQ: - +`TriggerAuthentication` CRD is used to connect and authenticate to RabbitMQ: - For AMQP, the URI should look similar to `amqp://guest:password@localhost:5672/vhost`. - For HTTP, the URI should look similar to `http://guest:password@localhost:15672/path/vhost`. + > See the [RabbitMQ Ports](https://www.rabbitmq.com/networking.html#ports) section for more details on how to configure the ports. +- `vhostName` - VHost to use for the connection, overrides any VHost set in the connection string from `host`/`hostFromEnv` (optional, but **required** if Azure AD Workload Identity authorization is used). -> See the [RabbitMQ Ports](https://www.rabbitmq.com/networking.html#ports) section for more details on how to configure the ports. - -- `vhostName` - Vhost to use for the connection, overrides any vhost set in the connection string from `host`/`hostFromEnv`. (Optional / Required if Azure AD Workload Identity authorization is used) -**Username and Password based authentication:** - -This allows sensitive credentials to be stored and managed separately from the connection string. +#### Username and Password based authentication +This allows sensitive credentials to be stored and managed separately from the connection string: - `username` - The username to use to connect to the broker's management endpoint. - `password` - The password to use to connect to the broker's management endpoint. -> 💡 **Note:** If username or password are set in TriggerAuthentication or environment variables, they will override any credentials provided in the host. +> 💡 **Note:** If username or password are set in `TriggerAuthentication` or environment variables, they will override any credentials provided in the `host` parameter. -**TLS authentication:** +#### TLS authentication -- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ is not used. (Values: `enable`, `disable`, Default: `disable`, Optional) -- `ca` - Certificate authority file for TLS client authentication. (Optional) -- `cert` - Certificate for client authentication. (Optional) -- `key` - Key for client authentication. (Optional) +- `tls` - To enable SSL auth for RabbitMQ, set this to `enable`. If not set, TLS for RabbitMQ will not be used. Valid values are `enable` or `disable` (optional; the default is `disable`). +- `ca` - Certificate authority file for TLS client authentication (optional). +- `cert` - Certificate for client authentication (optional). +- `key` - Certificate Key for client authentication (optional). -> Using RabbitMQ host with amqps will require enabling the tls settings and passing the required parameters. +> 💡 **Note:** Using RabbitMQ host with AMQPS protocol will require enabling the TLS settings and passing the required parameters. -**Azure Workload Identity authentication:** +#### Azure Workload Identity authentication -For RabbitMQ with OIDC support (>= 3.11) you can use TriggerAuthentication CRD with `podIdentity.provider = azure-workload` and with parameter `workloadIdentityResource` which would hold application identifier of App Registration in Azure AD. In this case `username:password` part in host URI should be omitted and `vHostName` has to be set explicitly in `ScaledObject`. Only HTTP protocol is supported for AKS Workload Identity currently. +For RabbitMQ with OIDC support (>= 3.11) you can use `TriggerAuthentication` CRD with `podIdentity.provider = azure-workload` and with `workloadIdentityResource` parameter, which will hold application identifier of App Registration in Azure AD. In this case `username:password` part in host URI should be omitted and `vHostName` has to be set explicitly in `ScaledObject`. Currently, only HTTP protocol is supported for AKS Workload Identity. -### Example +### Configuration examples #### AMQP protocol: @@ -144,7 +159,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### AMQP protocol with user/password auth: +#### AMQP protocol with username and password authorization: ```yaml apiVersion: v1 @@ -192,7 +207,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### AMQPS protocol with TLS auth: +#### AMQPS protocol with TLS authorization: ```yaml apiVersion: v1 @@ -248,7 +263,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`): +#### HTTP protocol (with `QueueLength` trigger): ```yaml apiVersion: v1 @@ -288,7 +303,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`MessageRate` and `QueueLength`): +#### HTTP protocol (with `MessageRate` and `QueueLength` triggers): ```yaml apiVersion: v1 @@ -336,7 +351,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`) and using regex (`useRegex`): +#### HTTP protocol (with `QueueLength` trigger) and enabled `useRegex`: ```yaml apiVersion: v1 @@ -378,7 +393,7 @@ spec: name: keda-trigger-auth-rabbitmq-conn ``` -#### HTTP protocol (`QueueLength`) with Azure Workload Identity: +#### HTTP protocol (with `QueueLength` trigger) with Azure Workload Identity: ```yaml apiVersion: v1 @@ -424,3 +439,188 @@ spec: authenticationRef: name: keda-trigger-auth-rabbitmq-conn ``` + +#### HTTP protocol (with `DeliverGetRate` trigger) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metricType: Value + metadata: + protocol: http + queueName: testqueue + mode: DeliverGetRate + value: "30" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (with `PublishedToDeliveredRatio` trigger) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metricType: Value + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1.1" + authenticationRef: + name: rabbitmq-trigger-auth +``` + +#### HTTP protocol (with `PublishedToDeliveredRatio` trigger used together with `scalingModifiers`) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + triggers: + - type: rabbitmq + metricType: Value + name: p2d_ratio + metadata: + protocol: http + queueName: testqueue + mode: PublishedToDeliveredRatio + value: "1" + authenticationRef: + name: rabbitmq-trigger-auth + - type: rabbitmq + name: qlen + metadata: + protocol: http + queueName: testqueue + mode: QueueLength + value: "100" + authenticationRef: + name: rabbitmq-trigger-auth + advanced: + # Bind QueueLength and PublishedToDeliveredRatio together to control trigger value + scalingModifiers: + metricType: Value + # Trigger if either one of conditions is met: + # - publishing to delivery rate exceeds factor of 1.2 + # - queue length contains more than 1.2K messages + formula: "max(p2d_ratio, qlen/1000)" + target: 1.2 +``` + +#### HTTP protocol (with `ExpectedQueueConsumptionTime` trigger) + +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: keda-rabbitmq-secret +data: + host: # base64 encoded value of format http://guest:password@localhost:15672/path/vhost +--- +apiVersion: keda.sh/v1alpha1 +kind: TriggerAuthentication +metadata: + name: keda-trigger-auth-rabbitmq-conn + namespace: default +spec: + secretTargetRef: + - parameter: host + name: keda-rabbitmq-secret + key: host +--- +apiVersion: keda.sh/v1alpha1 +kind: ScaledObject +metadata: + name: rabbitmq-scaledobject + namespace: default +spec: + scaleTargetRef: + name: rabbitmq-deployment + pollingInterval: 1 + triggers: + - type: rabbitmq + metricType: Value + name: eqct + metadata: + protocol: http + queueName: testqueue + mode: ExpectedQueueConsumptionTime + value: "20" + authenticationRef: + name: rabbitmq-trigger-auth +```