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

API Endpoints

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.

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.

Call Request Body

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

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.