Skip to content

Quickstart

Get Kysira protecting your application in under 15 minutes.

Step 1 — Get your image credentials

Log in to app.kysira.ai and navigate to Image Access → Add access. Pick how you deploy:

  • Kubernetes / Docker → issues a pull credential (JSON key). Give it a name and copy the key — it is shown only once.
  • Google Cloud Run → grant by project number instead (no key). See GCP Cloud Run deployment.

A pull credential grants read access to the Kysira release registry:

us-central1-docker.pkg.dev/cs-poc-uv5os9gxrjsncireus36uzd/kysira-agent-releases

The three images you'll use:

Image Role
kysira-inference ML scoring engine — runs entirely offline, no data leaves your infra
kysira-ext-proc Envoy ext_proc adapter — for Istio, Cloud Run Service Extensions, or standalone Envoy
kysira-nginx-auth-adapter nginx auth_request adapter — for nginx-based stacks

Full image paths:

us-central1-docker.pkg.dev/cs-poc-uv5os9gxrjsncireus36uzd/kysira-agent-releases/{kysira-ext-proc,kysira-inference,kysira-nginx-auth-adapter}

Authenticate

The JSON key is a Google service-account key. Authenticate Docker with the special username _json_key (the key contents are the password):

# Save the JSON key from the console to kysira-key.json, then:
cat kysira-key.json | docker login -u _json_key --password-stdin https://us-central1-docker.pkg.dev

Verify access — list the tags for an image:

gcloud artifacts tags list \
  --package=kysira-inference \
  --location=us-central1 \
  --repository=kysira-agent-releases \
  --project=cs-poc-uv5os9gxrjsncireus36uzd

Or, without gcloud, using skopeo and the key inline:

skopeo list-tags \
  --creds "_json_key_base64:$(base64 < kysira-key.json | tr -d '\n')" \
  docker://us-central1-docker.pkg.dev/cs-poc-uv5os9gxrjsncireus36uzd/kysira-agent-releases/kysira-inference

Step 2 — Choose your deployment path

Best for: stacks where traffic flows through a Google Cloud Application Load Balancer to Cloud Run services.

Kysira integrates as a Service Extensions traffic extension on the ALB. You deploy two Cloud Run services (kysira-ext-proc and kysira-inference) and attach them to your existing load balancer — no changes to your application.

Internet → Cloud Application LB → (ext_proc gRPC) → kysira-ext-proc → kysira-inference
                    │
                    ↓
            Your Cloud Run service

→ Full Cloud Run deployment guide

Best for: clusters running Istio, or any cluster with an Envoy-based gateway (Contour, Envoy Gateway, standalone Envoy).

kysira-ext-proc implements the Envoy ext_proc protocol. It sits alongside your application and is called per-request by the Envoy sidecar or gateway — no extra proxy hop in the data path.

Client → Envoy sidecar / gateway
              │ ext_proc gRPC
              ↓
      kysira-ext-proc → kysira-inference
              │
              ↓ verdict (CONTINUE or deny)

Deploy both services to your cluster using the image URLs from the Kysira Admin Console.

→ Full Kubernetes deployment guide — Model 2 (Istio) and Model 3 (standalone Envoy)

Best for: clusters where nginx is the ingress controller or reverse proxy.

kysira-nginx-auth-adapter acts as the target for nginx's auth_request directive. nginx calls it on every request; the adapter scores it against kysira-inference and returns 200 (pass) or 403 (block).

Client → nginx
           │ auth_request
           ↓
 kysira-nginx-auth-adapter → kysira-inference
           │
           ↓ 200 or 403

→ Full Kubernetes deployment guide — Model 4 (nginx)

Step 3 — Start in shadow mode

Regardless of deployment path, start with KYSIRA_MODE=shadow. In shadow mode Kysira scores every request and logs the verdict but never blocks traffic. Run shadow for at least a week to validate scoring quality against your real traffic before switching to active enforcement.

All deployment guides walk through the shadow → active promotion process.

What's next