> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.jambonz.org/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.jambonz.org/_mcp/server.

# Kubernetes Deployment

## Overview

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

1. **Provision a Kubernetes cluster** using the provided Terraform templates for your cloud provider.
2. **Deploy jambonz** into the cluster using the [jambonz Helm chart](https://github.com/jambonz-selfhosting/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.

> **Note**
>
> 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:

1. Clone the [Terraform repository](https://github.com/jambonz-selfhosting/terraform).
2. Navigate to the appropriate provider directory and configure `terraform.tfvars`.
3. Run `terraform init && terraform plan && terraform apply` to provision the cluster.
4. Configure `kubectl` to connect to your new cluster.
5. Deploy jambonz using the [Helm chart](https://github.com/jambonz-selfhosting/helm-chart).
6. Complete the [Post-Install Steps](/self-hosting/overview/post-install-steps).
7. Generate a software license key as described in [Software Licensing](/self-hosting/overview/licensing).

## Supported Providers

* [AWS (EKS)](/self-hosting/kubernetes/aws-eks)
* [Azure (AKS)](/self-hosting/kubernetes/azure-aks)
* [GCP (GKE)](/self-hosting/kubernetes/gcp-gke)
* [Exoscale (SKS)](/self-hosting/kubernetes/exoscale-sks)

## Resources

* [Terraform templates repository](https://github.com/jambonz-selfhosting/terraform)
* [jambonz Helm chart](https://github.com/jambonz-selfhosting/helm-chart)