xomoxcc/sipstuff-k8s-operator repository overview

⁠sipstuff-k8s-operator

A Kubernetes operator that exposes a FastAPI HTTP API for creating SIP call Jobs. It accepts call requests via POST /call, builds Kubernetes Jobs that run sipstuff.cli call⁠, and tracks job status. Available for linux/amd64 and linux/arm64. Source on GitHub⁠.

Quick links:

• Source: github.com/vroomfondel/sipstuff-k8s-operator⁠
• PyPI: pypi.org/project/sipstuff-k8s-operator⁠
• CI: mypy + pytest, black lint, and a multi‑arch Docker build/push workflow (see badges above)

⁠Why this is useful

• HTTP API for SIP calls — trigger phone calls from any system that can make HTTP requests (monitoring, alerting, CI/CD pipelines, home automation).
• Kubernetes‑native — each call runs as an isolated K8s Job with proper RBAC, TTL cleanup, and status tracking.
• Per‑request SIP overrides — override SIP server, credentials, transport, SRTP, and NAT traversal settings per call, or fall back to a shared K8s Secret.
• NAT traversal — STUN, ICE, TURN relay, UDP keepalive, and static public address support for complex network environments.
• Multi‑arch — runs on amd64 and arm64 (laptops, servers, SBCs).

⁠Screenshots

⁠API Endpoints

⁠Quick start

# Pull the image
docker pull xomoxcc/sipstuff-k8s-operator:latest

# Run locally (connects to your current kubeconfig context)
docker run --rm -p 8080:8080 \
  -v ~/.kube/config:/root/.kube/config:ro \
  xomoxcc/sipstuff-k8s-operator:latest

# Create a call
curl -X POST http://localhost:8080/call \
  -H "Content-Type: application/json" \
  -d '{"dest": "+4912345678", "text": "Hello from sipstuff"}'

# List jobs
curl http://localhost:8080/jobs

# Check health
curl http://localhost:8080/health

⁠Configuration

All settings are read from environment variables. Every variable is optional with sensible defaults.

Note on hostPath volumes and permissions: fsGroup only takes effect on volume types that support ownership management (e.g. emptyDir, PVCs). For hostPath volumes the host directory permissions are used as-is. When RUN_AS_USER is set and volume mounts are configured, the operator automatically adds a fix-permissions initContainer (runs as root with busybox:latest) that executes chown -R <uid>:<gid> on all mounted directories before the main container starts. This ensures the SIP call container can write to the hostPath volumes regardless of the host-side permissions.

⁠Call Request Body

POST /call accepts a JSON body with the following fields. Exactly one of text or wav must be provided.

⁠Kubernetes Deployment

Manifests are provided in the k8s/ directory of the source repository⁠:

# Create namespace
kubectl apply -f k8s/namespace.yaml

# Create RBAC (ServiceAccount, Role, RoleBinding)
kubectl apply -f k8s/rbac.yaml

# Create the SIP credentials secret (copy and edit the example first)
cp k8s/secret.yaml.example k8s/secret.yaml
# edit k8s/secret.yaml with your SIP credentials
kubectl apply -f k8s/secret.yaml

# Deploy the operator
kubectl apply -f k8s/deployment.yaml

# Expose via ClusterIP service (80 -> 8080)
kubectl apply -f k8s/service.yaml

The operator Deployment uses liveness and readiness probes against /health, runs as a single replica on port 8080, and uses a dedicated sipstuff-operator ServiceAccount with RBAC permissions for batch/jobs and pods.

⁠SIP Credentials

SIP connection parameters can be provided per‑request in the call body (sip_server, sip_port, sip_user, sip_password, sip_transport, sip_srtp, sip_tls_verify). When a field is not provided, the operator falls back to the K8s Secret specified by SIP_SECRET_NAME (default: sip-credentials).

The secret should contain these keys:

stringData:
  SIP_SERVER: "sip.example.com"
  SIP_PORT: "5060"
  SIP_USER: "sipuser"
  SIP_PASSWORD: "changeme"
  SIP_TRANSPORT: "udp"
  SIP_SRTP: "disabled"
  # SIP_TLS_VERIFY_SERVER: "false"

See k8s/secret.yaml.example⁠ for a complete example.

⁠NAT Traversal

NAT traversal settings (STUN, ICE, TURN, keepalive, public address) can be provided per‑request or configured globally via the same K8s Secret. Add any of these optional keys to the sip-credentials Secret:

stringData:
  # SIP_STUN_SERVERS: "stun.l.google.com:19302"
  # SIP_ICE_ENABLED: "false"
  # SIP_TURN_SERVER: "turn.example.com:3478"
  # SIP_TURN_USERNAME: ""
  # SIP_TURN_PASSWORD: ""
  # SIP_TURN_TRANSPORT: "udp"
  # SIP_KEEPALIVE_SEC: "0"
  # SIP_PUBLIC_ADDRESS: ""

When turn_server is provided in a request, SIP_TURN_ENABLED=true is automatically set on the job.

⁠Docker: build and image details

The image is based on python:3.14-slim, installs Python deps via requirements.txt, copies the sipstuff_k8s_operator package, and runs python3 -m sipstuff_k8s_operator as its default command.

⁠Local build

# Build the image
make build
# or
docker build -t xomoxcc/sipstuff-k8s-operator:latest .

# Run locally
docker run --rm -p 8080:8080 xomoxcc/sipstuff-k8s-operator:latest

⁠Multi‑arch build and push

The CI workflow (.github/workflows/buildmultiarchandpush.yml) builds and pushes multi‑arch images (amd64 + arm64) to Docker Hub after a successful mypy/pytest run. Tags: xomoxcc/sipstuff-k8s-operator:latest and xomoxcc/sipstuff-k8s-operator:python-3.14-slim-trixie.

⁠GitHub Actions

• mypynpytests.yml — mypy + pytest
• buildmultiarchandpush.yml — multi‑arch Docker build/push (triggers after successful tests)
• checkblack.yml — black code style check
• update-clone-badge.yml — clone count badge update

⁠License

This project is licensed under the LGPL‑3.0 — see LICENSE.md⁠. Some files/parts may use other licenses: MIT⁠ | GPL⁠ | LGPL⁠. Always check per‑file headers/comments.

⁠Authors

• Repo owner (primary author)
• Additional attributions are noted inline in code comments

⁠Note

This is a development/experimental project. For production use, review security settings, customize configurations, and test thoroughly in your environment. Provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. Use at your own risk.