Skip to main content

Semaphore API

The Semaphore resource controls concurrent access to shared resources by limiting the number of permits available.

Resource Definition​

apiVersion: konductor.io/v1
kind: Semaphore
metadata:
  name: batch-limit
  namespace: default
spec:
  permits: 10
  ttl: 30m
status:
  inUse: 3
  available: 7
  phase: Ready
  conditions:
  - type: Ready
    status: "True"
    reason: SemaphoreReady

Spec Fields​

FieldTypeRequiredDescription
permitsintegerYesMaximum number of concurrent permits
ttldurationNoTime-to-live for individual permits (default: 5m)

Status Fields​

FieldTypeDescription
inUseintegerNumber of permits currently in use
availableintegerNumber of permits available for acquisition
phasestringCurrent phase: Ready, NotReady
holders[]stringList of current permit holders

Phases​

  • Ready: Semaphore is operational and can grant permits
  • NotReady: Semaphore is not ready (initialization, errors)

Examples​

Basic Semaphore​

apiVersion: konductor.io/v1
kind: Semaphore
metadata:
  name: api-quota
spec:
  permits: 5
  ttl: 10m

Job with Semaphore​

apiVersion: batch/v1
kind: Job
metadata:
  name: batch-processor
spec:
  template:
    spec:
      initContainers:
      - name: acquire-permit
        image: logiciq/koncli:latest
        command:
        - koncli
        - semaphore
        - acquire
        - api-quota
        - --wait
        - --ttl=10m
      containers:
      - name: processor
        image: my-processor:latest
        command:
        - /bin/sh
        - -c
        - |
          process-data
          koncli semaphore release api-quota

CLI Usage​

# Acquire a permit
koncli semaphore acquire api-quota --ttl=5m

# Acquire with wait
koncli semaphore acquire api-quota --wait --timeout=30m

# Release a permit
koncli semaphore release api-quota

# Check status
koncli semaphore status api-quota

Use Cases​

Batch Job Throttling​

Limit concurrent batch jobs to prevent resource exhaustion:

apiVersion: konductor.io/v1
kind: Semaphore
metadata:
  name: batch-limit
spec:
  permits: 10  # Max 10 concurrent jobs

API Rate Limiting​

Control external API calls:

apiVersion: konductor.io/v1
kind: Semaphore
metadata:
  name: external-api
spec:
  permits: 3   # Max 3 concurrent API calls
  ttl: 1m      # Short TTL for API calls

Database Connection Pool​

Limit database connections:

apiVersion: konductor.io/v1
kind: Semaphore
metadata:
  name: db-connections
spec:
  permits: 20  # Max 20 concurrent connections
  ttl: 15m     # Connection timeout

Best Practices​

  1. Set appropriate TTL: Use shorter TTL for quick operations, longer for batch jobs
  2. Monitor usage: Check inUse and available fields regularly
  3. Handle failures: Always release permits in error cases
  4. Use initContainers: Preferred pattern for job gating
  5. Namespace isolation: Use different namespaces for different environments

Troubleshooting​

Permits Not Available​

# Check current usage
kubectl describe semaphore my-semaphore

# List current holders
kubectl get semaphore my-semaphore -o jsonpath='{.status.holders}'

Stuck Permits​

Permits automatically expire based on TTL. To force cleanup:

# Delete and recreate semaphore
kubectl delete semaphore my-semaphore
kubectl apply -f semaphore.yaml