Kubernetes Deployment

Overview

jambonz can be deployed on Kubernetes using a two-step process:

Provision a Kubernetes cluster using the provided Terraform templates for your cloud provider.
Deploy jambonz into the cluster using the jambonz Helm chart.

VoIP and Kubernetes: Why Host Networking is Required

Deploying VoIP applications on Kubernetes has some unique requirements that differ from typical web workloads. Most jambonz components — the web portal, monitoring, databases, Redis, and application-layer feature servers — run normally using Kubernetes’ default overlay networking on the system node pool. However, the SIP and RTP pods that handle the front-end telephony processing must run with host networking enabled (hostNetwork: true).

This is not optional — it is a hard requirement of the SIP protocol. SIP embeds IP addresses directly in the signaling messages (SDP, Via headers, Contact headers). If a SIP or RTP pod uses overlay networking, the IP addresses in the SIP messages will be internal cluster IPs that are unreachable from the outside world. Calls will fail because remote endpoints cannot route media or signaling back to an internal pod IP.

By running the SIP and RTP pods with host networking, these pods use the node’s actual network interface and public IP address. This ensures that the IP addresses advertised in SIP signaling are routable and that carriers and endpoints can reach the jambonz SBC directly.

If you’re experienced with Kubernetes, host networking may feel like an anti-pattern. For VoIP workloads it is an absolute necessity due to how SIP and RTP protocols operate at the network level.

Cluster Architecture

All supported cloud providers use the same general cluster architecture with three node pools:

Node Pool	Purpose	Public IPs	Host Networking	Taint	Label
System	Web portal, monitoring, databases, Redis	No	No	None	`pool=system`
SIP	SBC for SIP signaling	Yes	Yes	`sip=true:NoSchedule`	`voip-environment=sip`
RTP	Media processing (RTP streams)	Yes	Yes	`rtp=true:NoSchedule`	`voip-environment=rtp`

The SIP and RTP node pools require public IP addresses and host networking so they can be reached directly by SIP trunking carriers and endpoints. The taints ensure that only jambonz VoIP workloads are scheduled onto those nodes.

Deployment Workflow

The general deployment workflow is the same for all providers:

Clone the Terraform repository.
Navigate to the appropriate provider directory and configure terraform.tfvars.
Run terraform init && terraform plan && terraform apply to provision the cluster.
Configure kubectl to connect to your new cluster.
Deploy jambonz using the Helm chart.
Complete the Post-Install Steps.
Generate a software license key as described in Software Licensing.