Run CoreSDK as a sidecar container alongside your service in Docker and Kubernetes.

Available in Phase 1b. This feature ships with the sidecar daemon and wrapper SDKs. Phase 1a (Rust crate only) users access this via the core engine directly.

Docker & Kubernetes

CoreSDK ships as a lightweight container image that runs as a sidecar next to your application. The sidecar handles policy evaluation, JWT verification, and trace export so your application binary stays zero-dependency.

Dockerfile

Add the CoreSDK sidecar image to your Compose or pod spec. For local development, a minimal Dockerfile for your app service needs no CoreSDK changes — the SDK auto-discovers the sidecar over localhost.

# Your application image — unchanged
FROM rust:1.78-slim AS builder
WORKDIR /app
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/my-service /usr/local/bin/my-service
EXPOSE 8080
CMD ["my-service"]

Run the CoreSDK sidecar alongside it:

# Quickstart — run the sidecar locally
docker run -d -p 50051:50051 \
  -e CORESDK_JWKS_URL=https://your-idp/.well-known/jwks.json \
  -e CORESDK_FAIL_MODE=open \
  ghcr.io/coresdk-dev/sidecar:latest

Or reference the image in a multi-container setup:

# CoreSDK sidecar — pulled separately, no modification needed
FROM ghcr.io/coresdk-dev/sidecar:latest

Environment Variable Configuration

The sidecar and SDK both read from environment variables. All variables are prefixed with CORESDK_.

Variable	Description	Default
`CORESDK_TENANT`	Your tenant identifier	required
`CORESDK_CONTROL_PLANE_URL`	Control plane endpoint	`https://api.coresdk.io`
`CORESDK_JWKS_URL`	JWKS endpoint for JWT verification	derived from control plane
`CORESDK_POLICY_DIR`	Path to local `.rego` policy files	—
`CORESDK_LOG_LEVEL`	Log verbosity (`debug`, `info`, `warn`, `error`)	`info`
`CORESDK_OTEL_ENDPOINT`	OpenTelemetry collector endpoint	—
`CORESDK_LISTEN_ADDR`	Sidecar gRPC listen address	`[::1]:50051`

Kubernetes Deployment

deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
  namespace: production
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-service
  template:
    metadata:
      labels:
        app: my-service
    spec:
      containers:
        # --- Your application container ---
        - name: my-service
          image: my-org/my-service:latest
          ports:
            - containerPort: 8080
          env:
            - name: CORESDK_TENANT
              valueFrom:
                secretKeyRef:
                  name: coresdk-secrets
                  key: tenant
          resources:
            requests:
              cpu: 100m
              memory: 128Mi
            limits:
              cpu: 500m
              memory: 256Mi

        # --- CoreSDK sidecar ---
        - name: coresdk-sidecar
          image: ghcr.io/coresdk-dev/sidecar:latest
          ports:
            - containerPort: 50051
              name: grpc
            - containerPort: 50052
              name: health
          env:
            - name: CORESDK_TENANT
              valueFrom:
                secretKeyRef:
                  name: coresdk-secrets
                  key: tenant
            - name: CORESDK_API_KEY
              valueFrom:
                secretKeyRef:
                  name: coresdk-secrets
                  key: api-key
            - name: CORESDK_CONTROL_PLANE_URL
              value: "https://api.coresdk.io"
            - name: CORESDK_LOG_LEVEL
              value: "info"
          livenessProbe:
            httpGet:
              path: /healthz
              port: 50052
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /readyz
              port: 50052
            initialDelaySeconds: 3
            periodSeconds: 5
          resources:
            requests:
              cpu: 50m
              memory: 64Mi
            limits:
              cpu: 200m
              memory: 128Mi

Secrets Management

Create a Kubernetes Secret to hold sensitive values. Never commit secret values to source control.

kubectl create secret generic coresdk-secrets \
  --from-literal=tenant=acme \
  --from-literal=api-key=csk_live_xxxxxxxxxxxxxxxx \
  --namespace=production

For GitOps workflows, use Sealed Secrets or External Secrets Operator to manage coresdk-secrets declaratively.

Health Checks

The CoreSDK sidecar exposes two HTTP endpoints on port 50052:

Endpoint	Purpose
`GET /healthz`	Liveness — returns `200` if the process is alive
`GET /readyz`	Readiness — returns `200` only after the control plane connection and policy cache are ready

Your application's readiness gate should depend on the sidecar being ready. Add an initContainer if you require the sidecar to be healthy before your app starts:

initContainers:
  - name: wait-for-coresdk
    image: busybox:latest
    command:
      - sh
      - -c
      - |
        until wget -qO- http://localhost:50052/readyz; do
          echo "waiting for coresdk sidecar..."
          sleep 2
        done

Helm Values

If you use the CoreSDK Helm chart (helm repo add coresdk https://charts.coresdk.io), configure the sidecar via values.yaml:

coresdk:
  enabled: true
  image:
    repository: ghcr.io/coresdk/sidecar
    tag: latest
    pullPolicy: IfNotPresent

  tenant: acme                          # or use existingSecret
  existingSecret: coresdk-secrets       # reads tenant + api-key from here

  controlPlaneUrl: https://api.coresdk.io

  resources:
    requests:
      cpu: 50m
      memory: 64Mi
    limits:
      cpu: 200m
      memory: 128Mi

  livenessProbe:
    enabled: true
    initialDelaySeconds: 5
    periodSeconds: 10

  readinessProbe:
    enabled: true
    initialDelaySeconds: 3
    periodSeconds: 5

  otel:
    enabled: true
    endpoint: http://otel-collector:4317

  podAnnotations:
    prometheus.io/scrape: "true"
    prometheus.io/port: "7702"

Install or upgrade:

helm upgrade --install my-service coresdk/service-chart \
  --namespace production \
  --values values.yaml

Next Steps

CoreSDK Cloud — managed control plane with zero infra overhead
Self-Hosted Control Plane — run the control plane on-prem
Observability — connect the sidecar to your OTEL collector

Docker & Kubernetes

On this page