KubeVoIP documentation on KubeVoIP Docs

API reference

Mon, 01 Jan 0001 00:00:00 +0000

API reference

This page is generated from the KubeVoIP CRDs in the platform repository. Update the CRDs there, then regenerate this page.

Asterisk on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Asterisk on Kubernetes

KubeVoIP uses Asterisk application pods for call flows that need application behavior. Direct trunk-to-phone calls can avoid Asterisk and keep less state in application pods.

Cleanup

Mon, 01 Jan 0001 00:00:00 +0000

Cleanup

If you used a dedicated telephony namespace for the quickstart, uninstall the operator and delete the namespace:

helm uninstall kubevoip --namespace telephony
kubectl delete namespace telephony

If you used an existing namespace, delete only the quickstart objects instead:

Component images

Mon, 01 Jan 0001 00:00:00 +0000

Component images

ghcr.io/kubevoip/kubevoip: operator.
ghcr.io/kubevoip/kubevoip-kamailio: Kamailio runtime.
ghcr.io/kubevoip/kubevoip-rtpengine: RTPengine runtime.
ghcr.io/kubevoip/kubevoip-asterisk: Asterisk application runtime.

Install the platform chart instead of selecting component tags manually.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

FAQ

No. KubeVoIP is a SIP and VoIP platform for Kubernetes. kube-vip is a Kubernetes virtual IP project.

Helm values

Mon, 01 Jan 0001 00:00:00 +0000

Helm values

The Helm chart exposes image repositories and tags for the operator and runtime components, plus standard Kubernetes settings such as ServiceAccount, RBAC, resources, node selectors, tolerations, and affinity.

HostNetwork media mode

Mon, 01 Jan 0001 00:00:00 +0000

HostNetwork media mode

HostNetwork avoids Kubernetes Service NAT for media but binds RTPengine ports directly on selected nodes. The cluster operator must handle node selection, public addresses, firewall rules, and port conflicts.

Install KubeVoIP

Mon, 01 Jan 0001 00:00:00 +0000

Install KubeVoIP

Install the operator with Helm:

helm install kubevoip oci://ghcr.io/kubevoip/charts/kubevoip \
 --version 0.5.0 \
 --namespace telephony --create-namespace

Each Helm release watches only its installation namespace. Install a separate release for each telephony namespace. CRDs remain cluster-scoped Kubernetes resources shared by all releases.

Kamailio on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

Kamailio on Kubernetes

KubeVoIP runs Kamailio as the SIP gateway layer. Kamailio handles registration, authentication, routing, Record-Route behavior, and RTPengine integration.

Kubernetes SIP trunking

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes SIP trunking

KubeVoIP models trunks with SIPTrunk resources. Inbound trunks can trust configured source CIDRs and use an inbound DialPolicy. Outbound trunks can present caller ID and answer digest challenges.

Kubernetes VoIP

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes VoIP

KubeVoIP brings VoIP on Kubernetes into Kubernetes-native resources. It focuses on SIP signaling, RTP media relay, runtime routing, and operator-managed deployments.

Kubernetes VoIP quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Kubernetes VoIP quickstart

This quickstart creates a small SIP on Kubernetes deployment with two users: alice on extension 100 and bob on extension 101. Helm installs the operator, a short inline manifest creates the temporary database and base platform, and the kubevoip CLI creates the SIP users and routes.

LoadBalancer networking

Mon, 01 Jan 0001 00:00:00 +0000

LoadBalancer networking

LoadBalancer mode lets Kubernetes or your infrastructure allocate addresses for SIP and RTP Services. If KubeVoIP cannot resolve an address yet, it reports a waiting condition until the Service ingress is available.

Local development

Mon, 01 Jan 0001 00:00:00 +0000

Local development

In the platform repository:

uv sync --extra dev
uv run ruff check .
uv run pytest
helm lint charts/kubevoip
helm template kubevoip charts/kubevoip

Platform resources

Mon, 01 Jan 0001 00:00:00 +0000

Platform resources

NetworkProfile defines shared external addressing and local networks.
SIPGateway manages Kamailio registration, routing, and SIP edge behavior.
MediaRelay manages RTPengine replicas and media port ranges.
AsteriskPool manages private Asterisk application pods.
SIPUser represents a phone identity registered through Kamailio.
SIPTrunk represents provider-neutral inbound and outbound trunk policy.
CallScope groups searchable routes.
DialPolicy defines which scopes a caller can search.
CallRoute routes calls to users, trunks, or Asterisk applications.

See the API reference for generated field details.

PostgreSQL

Mon, 01 Jan 0001 00:00:00 +0000

PostgreSQL

KubeVoIP requires a PostgreSQL database and a standard connection Secret with host, port, dbname, user, and password.

The operator runs forward database migrations automatically during reconciliation. PostgreSQL stores route data, dial policies, subscriber hashes, registrations, trunk metadata, and digest HA1 values. HA1 is credential-equivalent for its SIP realm.

Release process

Mon, 01 Jan 0001 00:00:00 +0000

Release process

Platform releases publish the operator image, Helm chart, and GitHub release. Runtime component images are versioned separately and pinned by the platform chart.

RTPengine on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

RTPengine on Kubernetes

KubeVoIP manages RTPengine replicas with stable Services, media port ranges, and advertised external addresses.

Secrets

Mon, 01 Jan 0001 00:00:00 +0000

Secrets

KubeVoIP reads Secrets only in the operator installation namespace. SIP user passwords, trunk digest credentials, caller ID values, and database credentials should stay out of Git and ConfigMaps.

Rendered ConfigMaps, statuses, Events, and logs must not expose raw passwords or digest HA1 values.

SIP on Kubernetes

Mon, 01 Jan 0001 00:00:00 +0000

SIP on Kubernetes

SIP clients and trunks send requests to a SIPGateway. Kamailio authenticates callers, selects routes from PostgreSQL runtime data, and asks RTPengine to rewrite SDP for media relay. Calls can target registered SIP users, outbound trunks, or Asterisk application pods.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting

Start with resource status:

kubectl -n telephony get networkprofile,sipgateway,mediarelay,asteriskpool,sipuser,siptrunk,callscope,dialpolicy,callroute
kubectl -n telephony describe sipgateway main
kubectl -n telephony logs deployment/kubevoip-kubevoip

For one-way audio, check RTPengine Service addresses, firewall rules, and RTP port forwarding. SIP and RTP public ports must match the private ports.

KubeVoIP documentation on KubeVoIP Docs

API reference

API reference

Asterisk on Kubernetes

Asterisk on Kubernetes

Cleanup

Cleanup

Component images

Component images

FAQ

FAQ

Is KubeVoIP related to kube-vip?

Helm values

Helm values

HostNetwork media mode

HostNetwork media mode

Install KubeVoIP

Install KubeVoIP

Kamailio on Kubernetes

Kamailio on Kubernetes

Kubernetes SIP trunking

Kubernetes SIP trunking

Kubernetes VoIP

Kubernetes VoIP

Kubernetes VoIP quickstart

Kubernetes VoIP quickstart

LoadBalancer networking

LoadBalancer networking

Local development

Local development

Platform resources

Platform resources

PostgreSQL

PostgreSQL

Release process

Release process

RTPengine on Kubernetes

RTPengine on Kubernetes

Secrets

Secrets

SIP on Kubernetes

SIP on Kubernetes

Troubleshooting

Troubleshooting