Skip to main content

mypy and pytests BuildAndPushMultiarch black-lint Cumulative Clones Docker Pulls PyPI Downloads PyPI

Gemini_Generated_Image_23m8jo23m8jo23m8_250x250.png

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.

Screenshots

Operator running a SIP call with transcription

Operator startup and call execution

Operator startup with configuration overview

API Endpoints

Method Path Description
POST /call Create a K8s Job that executes a SIP call
GET /jobs List all SIP call jobs
GET /jobs/{name} Get status of a specific job
GET /health Liveness / readiness probe

Quick Start

# Install dependencies (creates a Python 3.14 venv)
make install

# Run the operator locally (starts uvicorn on :8080)
python -m sipstuff_k8s_operator

# Test K8s API connectivity only
python -m sipstuff_k8s_operator conntest

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.

Variable Default Description
JOB_NAMESPACE Downward API namespace or "sipstuff" K8s namespace for created jobs
JOB_IMAGE "xomoxcc/sipstuff:latest" Container image for SIP call jobs
SIP_SECRET_NAME "sip-credentials" K8s Secret name for default SIP credentials
JOB_TTL_SECONDS 3600 TTL in seconds after job completion before cleanup
JOB_BACKOFF_LIMIT 0 Number of retries before marking a job as failed
JOB_HOST_NETWORK "true" Use host networking for SIP/RTP
PORT 8080 HTTP listen port
PIPER_DATA_DIR null Host path for Piper TTS model cache; mounted at /data/piper
WHISPER_DATA_DIR null Host path for Whisper STT model cache; mounted at /data/whisper
RECORDING_DIR null Host path for call recordings; mounted at /data/recordings
RUN_AS_USER null UID to run the job container as
RUN_AS_GROUP null GID to run the job container as
FS_GROUP null fsGroup for the job pod security context
NODE_SELECTOR null Default node selector for job pods (key=value,key2=value2); can be overridden or cleared per request

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.

Kubernetes Deployment

Manifests are provided in the k8s/ directory:

# 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.

In-cluster clients reach the operator at http://sipstuff-operator.<namespace>.svc.cluster.local/call.

Optional: External Access via Traefik

The operator has no built-in authentication — POST /call places real phone calls. If you need to reach it from outside the cluster, k8s/ingressroute.yaml.example provides a Traefik setup that puts both an IP allowlist and basic auth in front of it:

# Basic auth credentials for the Traefik middleware
htpasswd -nbB sipstuff 'changeme' > ./users
kubectl create secret generic sipstuff-auth \
  --namespace sipstuff --from-file=users=./users
rm ./users

# Certificate, middlewares and IngressRoutes (edit host + source ranges first)
cp k8s/ingressroute.yaml.example k8s/ingressroute.yaml
kubectl apply -f k8s/ingressroute.yaml

It contains:

Resource Purpose
Certificate sipstuff-tls cert-manager TLS cert for the host (via ClusterIssuer)
Middleware sipstuff-ip-allowlist Restricts access to the configured source ranges
Middleware sipstuff-auth Basic auth against the sipstuff-auth secret
Middleware sipstuff-redirect-https HTTP → HTTPS redirect
IngressRoute sipstuff-http-redirect web entrypoint, redirect only
IngressRoute sipstuff-https websecure entrypoint → sipstuff-operator:80

Requires the Traefik CRDs (traefik.io/v1alpha1) and cert-manager. Adjust the host, the sourceRange entries and the issuerRef to match your cluster.

Call Request Body

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

Field Type Default Description
dest string (required) Destination phone number or SIP URI
text string null Text to speak via TTS (mutually exclusive with wav)
wav string null Path to a WAV file to play (mutually exclusive with text)
sip_server string null SIP server override
sip_port integer null SIP port override (1-65535)
sip_user string null SIP username override
sip_password string null SIP password override
sip_transport string null Transport protocol: "udp", "tcp", or "tls"
sip_srtp string null SRTP mode: "disabled", "optional", or "mandatory"
sip_tls_verify boolean null TLS server certificate verification
stun_servers string null Comma-separated STUN servers
ice_enabled boolean null Enable ICE for NAT traversal
turn_server string null TURN relay server (host:port)
turn_username string null TURN auth username
turn_password string null TURN auth password
turn_transport string null TURN transport: "udp", "tcp", or "tls"
keepalive_sec integer null UDP keepalive interval in seconds (0-600)
public_address string null Public IP address for SDP/Contact headers
timeout integer 60 Call timeout in seconds (1-600)
pre_delay float 0.0 Delay before call in seconds (0-30)
inter_delay float 0.0 Delay between WAV repeats in seconds (0-30)
post_delay float 0.0 Delay after call in seconds (0-30)
wait_for_silence float null Wait for N seconds of remote silence before playback (0-30)
repeat integer 1 Number of call repetitions (1-100)
tts_model string null TTS model name
tts_sample_rate integer null TTS sample rate in Hz (0-48000)
tts_data_dir string null TTS data directory
stt_model string null Whisper model size for STT transcription (e.g. "tiny", "base", "small", "medium", "large-v3")
stt_language string null Language code for STT transcription (e.g. "de")
stt_data_dir string null Directory for Whisper STT models
record string null Record remote party audio to this WAV file path (should be below /data/recordings/ when RECORDING_DIR is configured)
transcribe boolean false Transcribe recorded audio via STT and write a JSON call report (requires record)
verbose boolean false Enable verbose logging in the call job
node_selector object null K8s node selector for the job pod (e.g. {"mayplacecalls": "true"}). Overrides the operator default from NODE_SELECTOR. Set to {} to explicitly clear the default.

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.

Development

make lint           # Black formatter (line length: 120)
make isort          # Sort imports
make tcheck         # MyPy type checking (strict mode)
make tests          # Run pytest
make prepare        # Run tests + commit-checks
make commit-checks  # Run all pre-commit hooks
make gitleaks       # Scan for secrets

Run a single test:

source .venv/bin/activate && pytest tests/test_base.py::test_version_exists -v

Initial Setup (GitHub + Docker Hub)

The repo_scripts/initial_setup_github_dockerhub.sh script automates first-time project setup:

  1. Creates the Docker Hub repository (if no OAT exists yet)
  2. Creates a scoped Organization Access Token (OAT) with push+pull for the target repo
  3. Validates that the OAT actually has push+pull access via check_dockerhub_token.py
    • If permissions are missing, offers to create a new OAT with the correct scopes
  4. Ensures the Docker Hub repo exists (handles both public and private repos)
  5. Creates a GitHub repo and a public gist for clone tracking badges
  6. Sets all required GitHub Actions secrets (DOCKERHUB_TOKEN, DOCKERHUB_USERNAME, GIST_ID, GIST_TOKEN, REPO_PRIV_TOKEN)

Configuration is read from repo_scripts/include.local.sh (not checked in). See repo_scripts/include.sh for the variable template.

# Run the setup
./repo_scripts/initial_setup_github_dockerhub.sh

Docker

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

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

The image is based on python:3.14-slim and runs python3 -m sipstuff_k8s_operator as its entrypoint.

License

This project is licensed under the LGPL where applicable/possible — 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

Acknowledgments

  • Inspirations and snippets are referenced in code comments where appropriate.

⚠️ 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.

Metadata

Release files for sipstuff-k8s-operator 0.0.9

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sipstuff-k8s-operator 0.0.9
File Size Uploaded Provenance Actions
sipstuff_k8s_operator-0.0.9.tar.gz 21.3 kB Without provenance Details for sipstuff_k8s_operator-0.0.9.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sipstuff-k8s-operator 0.0.9
File Interpreter ABI Platform Actions
sipstuff_k8s_operator-0.0.9-py3-none-any.whl Python 3 none any Details for sipstuff_k8s_operator-0.0.9-py3-none-any.whl

Total release size: 45.6 kB

Release files / sipstuff_k8s_operator-0.0.9.tar.gz

Download URL sipstuff_k8s_operator-0.0.9.tar.gz
Size 21.3 kB
Tags Source
SHA-256 checksum
How to use checksums
1eaf4abccf4b15e7228d6e9704713b95f336caeff57cb8f2ed4c8ea0ef6b5bb6
BLAKE2b-256 checksum
How to use checksums
07a61c98d85c7e51b1d1cdcfc3be671d49ecf4334a8fdefdbb03e1d816d0088a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.16.3 cpython/3.14.4 HTTPX/0.28.1

Release files / sipstuff_k8s_operator-0.0.9-py3-none-any.whl

Download URL sipstuff_k8s_operator-0.0.9-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0fa0ce160b6e8cffe789f951e033680c6b93c3218d1e3da6b42a1dc9ed3a4b2d
BLAKE2b-256 checksum
How to use checksums
db0b340e60b1502297ea05a9e1aa1f42363f7b9bd0411d7704efa915304c707a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.16.3 cpython/3.14.4 HTTPX/0.28.1

Security for sipstuff-k8s-operator 0.0.9

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page