Event-Driven Triggers

The Triggers framework allows you to delay chaos injection until specific environmental conditions are met. Instead of simply waiting a fixed amount of time or relying entirely on manual signaling, Krkn can actively poll your environment and automatically proceed with the scenario once all your defined triggers are satisfied.

This is especially useful for event-driven chaos, such as waiting for a background deployment to finish, waiting for a service to become healthy, or synchronizing Krkn with an external CI/CD pipeline.

Configuration

Triggers are configured inside your Krkn scenario files under the triggers block.

triggers:
  mode: all_of      # Optional: all_of | any_of (default: all_of)
  timeout: 300      # Optional: Max time to wait in seconds (default: 300)
  interval: 5       # Optional: Polling interval in seconds (default: 5)
  on_timeout: skip  # Optional: skip | fail | run_anyway (default: skip)
  conditions:
    - type: command
      cmd: "kubectl get pods -n my-app | grep Running"
    - type: http
      url: "http://my-service.default.svc:8080/health"
      expected_status: 200
    - type: k8s
      apiVersion: apps/v1
      kind: Deployment
      name: nginx
      namespace: default
      condition: "status.readyReplicas >= 1"

Global Trigger Settings

Trigger Types

1. Command Trigger

The command trigger runs a shell command and passes if the command exits with a 0 (success) return code.

  - type: command
    cmd: "kubectl get nodes | grep Ready"

2. HTTP Trigger

The http trigger polls an HTTP/HTTPS endpoint and passes when the endpoint returns the expected status code and (optionally) matches a substring in the response body.

  - type: http
    url: "https://api.my-app.com/ready"
    method: "GET"
    expected_status: 200
    bearer_token: "my-secret-token"
    body_contains: "status: healthy"

3. Kubernetes Trigger

The k8s trigger polls a Kubernetes resource and passes when a field on the resource matches a condition. It is kind-agnostic — the same code path handles built-in resources (Deployments, Pods, Nodes) and CRDs (e.g. KubeVirt VirtualMachineInstanceMigration) using the Kubernetes dynamic client.

This is useful for waiting on rollout readiness, catching narrow timing windows during live migrations, or any case where a native API check replaces a brittle kubectl wrapper.

Basic example — wait for a Deployment to be ready

  - type: k8s
    apiVersion: apps/v1
    kind: Deployment
    name: nginx
    namespace: default
    condition: "status.readyReplicas >= 1"

CRD example — wait for a KubeVirt live migration to reach Running

  - type: k8s
    apiVersion: kubevirt.io/v1
    kind: VirtualMachineInstanceMigration
    name: test-migration
    namespace: vm-ns
    condition: "status.phase == Running"

Cross-cluster example — use a specific kubeconfig context

  - type: k8s
    context: staging-cluster
    apiVersion: apps/v1
    kind: Deployment
    name: frontend
    namespace: production
    condition: "status.readyReplicas >= 3"

Condition syntax

Conditions follow the format field.path <operator> value:

The field path uses dot notation to traverse nested fields (e.g. status.readyReplicas). For == and !=, numeric values are compared numerically when possible, falling back to string comparison. For ordering operators (>=, <=, >, <), both sides must be numeric.