keda-scale-workload

---
name: keda-scale-workload
description: Use when autoscaling a Kubernetes Deployment or Job with KEDA — scale to zero, scale on queue depth, cron windows, or CPU — or when the user mentions "ScaledObject", "ScaledJob", "scale on RabbitMQ/SQS/Kafka", or "KEDA trigger". Covers writing ScaledObjects, trigger auth, and verifying scaling actually happens.
license: Apache-2.0
---

# Scale a Workload with KEDA

A `ScaledObject` tells KEDA: watch this event source, and size this Deployment
accordingly — including down to zero. KEDA creates and manages the underlying
HPA for you.

Requires KEDA installed on the cluster — do `keda-install` first.

## 1. Pick the trigger

Common scalers (70+ exist — https://keda.sh/docs/latest/scalers/):

- `rabbitmq`, `aws-sqs-queue`, `kafka`, `gcp-pubsub` — queue/stream depth
- `cron` — scale up during known busy windows
- `cpu` / `memory` — classic HPA metrics via KEDA
- `prometheus` — anything you can express as a PromQL query

## 2. Write the ScaledObject

Example: scale `worker` between 0 and 20 replicas on RabbitMQ queue depth,
one replica per ~50 messages:

```yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledObject
metadata:
  name: worker-scaler
  namespace: app
spec:
  scaleTargetRef:
    name: worker            # the Deployment to scale
  minReplicaCount: 0        # scale to zero when idle
  maxReplicaCount: 20
  cooldownPeriod: 120       # seconds idle before dropping to zero
  triggers:
    - type: rabbitmq
      metadata:
        queueName: jobs
        mode: QueueLength
        value: "50"
      authenticationRef:
        name: rabbitmq-auth
```

Credentials never go in the ScaledObject — reference a
`TriggerAuthentication` backed by a Secret:

```yaml
apiVersion: keda.sh/v1alpha1
kind: TriggerAuthentication
metadata:
  name: rabbitmq-auth
  namespace: app
spec:
  secretTargetRef:
    - parameter: host
      name: rabbitmq-conn        # Secret name
      key: connectionString      # amqp://user:pass@rabbitmq:5672/
```

Apply both:

```sh
kubectl apply -f scaledobject.yaml
```

For run-to-completion work (one Job per message batch) use `ScaledJob` instead
of `ScaledObject` — same triggers, `jobTargetRef` instead of `scaleTargetRef`.

## 3. Verify

```sh
kubectl get scaledobject -n app
kubectl get hpa -n app
```

Expected: the ScaledObject shows `READY: True`, and a `keda-hpa-worker-scaler`
HPA appeared. Now prove the loop works:

1. With the queue empty, wait `cooldownPeriod` — `kubectl get deploy worker`
   goes to 0 replicas.
2. Push messages onto the queue — replicas climb within ~30s (KEDA's default
   polling interval):

```sh
kubectl get deploy worker -n app -w
```

## Troubleshooting

- **`READY: False`** — `kubectl describe scaledobject worker-scaler -n app`;
  the condition message names the failing trigger (bad connection string,
  unreachable broker, wrong queue name).
- **Deployment never reaches zero** — something else keeps it up: a stray
  plain HPA targeting the same Deployment (delete it — KEDA owns the HPA now),
  or `minReplicaCount` unset (default is 0, but check).
- **Scales up but not from zero / not at all** — activation is a separate
  threshold: `activationThreshold` on most scalers gates the 0→1 step.
- **Auth errors in operator logs** —
  `kubectl logs -n keda deploy/keda-operator | grep -i error`; usually the
  Secret key name doesn't match `secretTargetRef.key`.