Jitsi Kubernetes: Scaling Videobridges with Octo

Deploy the base stack with Helm

Do not hand-write the manifests. The jitsi-contrib/jitsi-helm chart is the practical starting point and it already models the four components and their XMPP wiring correctly:

helm repo add jitsi https://jitsi-contrib.github.io/jitsi-helm/
helm repo update
helm install jitsi-meet jitsi/jitsi-meet -f values.yaml --namespace jitsi --create-namespace

The defaults are deliberately conservative, and worth knowing because they are exactly the ones you have to change:

jvb:
  replicaCount: 1
  useNodeIP: false
  useHostPort: false
  useHostNetwork: false
  UDPPort: 10000
  portRangeSize: 1
  service:
    type: ClusterIP

octo:
  enabled: false

Note that octo is a top-level key in this chart, not nested under jvb. That trips people up when they go looking for it.

Get JVB media out of the cluster

This is the step that fixes the three-participant failure. Two things have to be true: UDP 10000 has to physically reach the pod, and the JVB has to advertise an address that browsers can actually route to.

For the first, use hostPort. The pod binds UDP 10000 on the node it lands on:

jvb:
  replicaCount: 3
  useHostPort: true
  useNodeIP: true
  UDPPort: 10000
  service:
    type: NodePort

Because a host port can only be claimed once per node, this quietly enforces one bridge per node. That is a feature. Two videobridges sharing a node's NIC and CPU is a bad idea anyway, and if replicaCount exceeds your node count the extra pods just sit in Pending, which is a clear signal rather than a silent degradation.

For the second, the JVB has to know its own public address. By default it advertises the pod IP, something like 10.244.3.17, which is meaningless to a browser on the internet. useNodeIP: true handles this in the chart by passing the node's IP through. If your nodes sit behind NAT with separate public addresses, set it explicitly:

jvb:
  extraEnvs:
    JVB_ADVERTISE_IPS: "203.0.113.10"

JVB_ADVERTISE_IPS replaced the older DOCKER_HOST_ADDRESS, which you will still see in a lot of tutorials. If a guide tells you to set DOCKER_HOST_ADDRESS, it predates the current images.

Then open the firewall. UDP 10000 inbound to every node running a bridge, plus TCP 443 for the web tier. On AWS that means the node security group, not just a Kubernetes NetworkPolicy.

More bridges does not mean bigger meetings

Here is the part that surprises people, and the reason a lot of Jitsi Meet horizontal scaling attempts quietly fail.

Jicofo's default bridge selection strategy is SingleBridgeSelectionStrategy. The name is literal: one conference lives on one bridge, and it will not be split. Scale to ten JVB replicas and a single meeting still sits entirely on one of them. What you have bought is the ability to run ten meetings at once, spread across bridges. The maximum size of any one meeting has not moved.

Two Jicofo defaults set that ceiling:

So the honest question to ask before touching Octo is: do you need many meetings, or one huge meeting? Many meetings is the common case, and it is satisfied by replicas alone. If you are sizing for a specific participant count, our write-up on pushing Jitsi to 1000 users works through where the real limits sit.

Turning on Octo: it is called relay now

If you searched for Jitsi videobridge Octo documentation, this is the single most useful thing on this page: almost everything written about Octo documents the old org.jitsi.videobridge.octo.* properties from sip-communicator.properties, and current builds do not read them.

In modern jvb.conf the block is called relay. Octo is the name of the feature and the protocol. Relay is the config key. The comment in the videobridge source says as much, describing the block as whether relays (octo) are enabled:

videobridge {
  relay {
    enabled = true
    region = "us-east-1"
    relay-id = "jvb-1"
  }
}

Both region and relay-id are mandatory once enabled is true, and relay-id has to be unique per bridge. In Kubernetes the obvious source for that is the pod name, injected through the downward API, which gives you a distinct stable value per replica for free.

What Octo actually does: bridges connect to each other and forward streams between themselves, so a conference can span several bridges while every participant still only talks to their local one. That is what lets a meeting outgrow a single machine, and it is also what lets participants in different regions each hit a nearby bridge.

On the Jicofo side, enabling relay on the bridges is not enough. Jicofo still has to be told it is allowed to split conferences, which is the next section.

Bridge selection strategies and regions

Jicofo decides which bridge each participant lands on. The strategy is set in jicofo.conf:

jicofo {
  bridge {
    selection-strategy = RegionBasedBridgeSelectionStrategy
    max-bridge-participants = 80
    stress-threshold = 0.8
  }
}

The options that matter in production:

For one region with meetings that occasionally get big, IntraRegionBridgeSelectionStrategy is usually the right answer. It keeps the simple case simple and only pulls in a second bridge when a meeting genuinely outgrows the first. Region-based selection is for when you actually run bridges in multiple regions, and it depends on the region value in each bridge's relay block matching the region names Jicofo knows about.

And use SplitBridgeSelectionStrategy exactly once, to prove your Octo mesh works, then change it back. It forces every participant onto a different bridge, which is a superb smoke test and a terrible production setting.

Jitsi autoscaling without dropping live calls

Scaling videobridges up is easy. Scaling down is where people lose meetings, and a naive HPA will do exactly that.

The problem: a JVB running a busy conference sits at high CPU for the whole meeting. That is normal, not overload. A CPU-based HPA sees sustained high utilisation, and when the meeting load dips it removes a pod, which may be a pod with fifty people on it. They get dropped mid-call.

Two things fix this. First, scale on the right signal. The chart ships a Prometheus exporter, which exposes the bridge's own stress_level and participant counts:

jvb:
  metrics:
    enabled: true
    serviceMonitor:
      enabled: true
      interval: 10s

Stress level is the number Jicofo itself uses for bridge selection, so scaling on it means your autoscaler and your conference focus agree about what "busy" means. CPU does not carry that meaning.

Second, drain before terminating. The videobridge supports graceful shutdown: it tells Jicofo to stop allocating new conferences to it, then waits for existing ones to end naturally. Wire that into the pod lifecycle:

lifecycle:
  preStop:
    exec:
      command:
        - /bin/sh
        - -c
        - >
          curl -s -X POST
          -H "Content-Type: application/json"
          -d '{"graceful-shutdown": "true"}'
          http://localhost:8080/colibri/shutdown;
          sleep 5
terminationGracePeriodSeconds: 3600

That grace period is not a typo. An hour is a reasonable ceiling for a meeting to finish on its own. The default 30 seconds guarantees you kill live calls, so if you change one thing about a default JVB deployment, change this.

Worth being honest about the trade: draining means scale-down is slow and unpredictable, because you are waiting on humans to leave meetings. You are paying for idle-ish bridges in exchange for never dropping a call. For most businesses that is obviously the right trade, but it does mean Jitsi autoscaling saves less money than the same setup on a stateless web service.