Create Runbook

{
  "name": "disk-cleanup",
  "namespace": "production",
  "description": "Free disk space when a StatefulSet reports disk pressure",
  "trigger": {
    "signalType": "disk_pressure",
    "severity": "medium",
    "resourceKind": "StatefulSet"
  },
  "steps": [
    {
      "name": "diagnose",
      "action": "ExecDiagnostic",
      "description": "Check filesystem usage",
      "params": {
        "command": "df -h"
      }
    },
    {
      "name": "restart-pod",
      "action": "RestartStatefulSetPod",
      "description": "Restart the affected pod"
    }
  ],
  "labels": {
    "team": "storage"
  }
}

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d @runbook.json http://localhost:8090/api/v1/runbooks

{
  "apiVersion": "v1",
  "kind": "Runbook",
  "spec": {
    "name": "disk-cleanup",
    "namespace": "production",
    "description": "Free disk space when a StatefulSet reports disk pressure",
    "trigger": {
      "signalType": "disk_pressure",
      "severity": "medium",
      "resourceKind": "StatefulSet"
    },
    "steps": [
      {
        "name": "diagnose",
        "action": "ExecDiagnostic",
        "description": "Check filesystem usage",
        "params": {
          "command": "df -h"
        }
      },
      {
        "name": "restart-pod",
        "action": "RestartStatefulSetPod",
        "description": "Restart the affected pod"
      }
    ],
    "maxAttempts": 3,
    "creationTimestamp": "2026-03-19T16:00:00Z"
  },
  "resourceMeta": {
    "name": "disk-cleanup",
    "namespace": "production",
    "uid": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a",
    "creationTimestamp": "2026-03-19T16:00:00Z",
    "labels": {
      "team": "storage"
    }
  }
}

POST

runbooks

{
  "name": "disk-cleanup",
  "namespace": "production",
  "description": "Free disk space when a StatefulSet reports disk pressure",
  "trigger": {
    "signalType": "disk_pressure",
    "severity": "medium",
    "resourceKind": "StatefulSet"
  },
  "steps": [
    {
      "name": "diagnose",
      "action": "ExecDiagnostic",
      "description": "Check filesystem usage",
      "params": {
        "command": "df -h"
      }
    },
    {
      "name": "restart-pod",
      "action": "RestartStatefulSetPod",
      "description": "Restart the affected pod"
    }
  ],
  "labels": {
    "team": "storage"
  }
}

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d @runbook.json http://localhost:8090/api/v1/runbooks

{
  "apiVersion": "v1",
  "kind": "Runbook",
  "spec": {
    "name": "disk-cleanup",
    "namespace": "production",
    "description": "Free disk space when a StatefulSet reports disk pressure",
    "trigger": {
      "signalType": "disk_pressure",
      "severity": "medium",
      "resourceKind": "StatefulSet"
    },
    "steps": [
      {
        "name": "diagnose",
        "action": "ExecDiagnostic",
        "description": "Check filesystem usage",
        "params": {
          "command": "df -h"
        }
      },
      {
        "name": "restart-pod",
        "action": "RestartStatefulSetPod",
        "description": "Restart the affected pod"
      }
    ],
    "maxAttempts": 3,
    "creationTimestamp": "2026-03-19T16:00:00Z"
  },
  "resourceMeta": {
    "name": "disk-cleanup",
    "namespace": "production",
    "uid": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a",
    "creationTimestamp": "2026-03-19T16:00:00Z",
    "labels": {
      "team": "storage"
    }
  }
}

string

required

Runbook name (a Kubernetes resource name, e.g., disk-cleanup)

string

default:"default"

Namespace to create the runbook in

string

Purpose of the runbook

object

required

When the runbook applies. All three fields are required by the CRD.

Show Trigger properties

string

required

Anomaly signal, e.g. oom_kill, crashloop_backoff, error_rate, latency, pod_restart, cpu_high, memory_high, disk_pressure, image_pull_error (full list in the Anomaly CRD enum)

string

required

critical, high, medium or low

string

required

Kind of the affected resource, e.g. Deployment, StatefulSet, DaemonSet, Job, CronJob

object[]

required

Ordered steps

Show Step properties

string

required

Step name

string

required

Remediation action type, e.g. AdjustResources, RestartDeployment, ScaleDeployment, RollbackDeployment, ExecDiagnostic

string

Why the step is needed and what it does

object

String key/value parameters for the action (e.g. {"memory_limit": "1Gi"}, {"replicas": "5"})

integer

default:"3"

Maximum number of remediation attempts; 0 or omitted means 3

object

Kubernetes labels for the Runbook

The response is 201 Created with the runbook in spec and its metadata in resourceMeta. A missing name or malformed JSON returns 400; a Kubernetes API failure returns the API server’s message with a status that matches it: 409 only when a runbook with that name already exists, 422 when the API server rejects the object (a value outside the CRD enums, a missing required field), 403 when the operator may not create it, and 500 otherwise.

{
  "name": "disk-cleanup",
  "namespace": "production",
  "description": "Free disk space when a StatefulSet reports disk pressure",
  "trigger": {
    "signalType": "disk_pressure",
    "severity": "medium",
    "resourceKind": "StatefulSet"
  },
  "steps": [
    {
      "name": "diagnose",
      "action": "ExecDiagnostic",
      "description": "Check filesystem usage",
      "params": {
        "command": "df -h"
      }
    },
    {
      "name": "restart-pod",
      "action": "RestartStatefulSetPod",
      "description": "Restart the affected pod"
    }
  ],
  "labels": {
    "team": "storage"
  }
}

curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d @runbook.json http://localhost:8090/api/v1/runbooks

{
  "apiVersion": "v1",
  "kind": "Runbook",
  "spec": {
    "name": "disk-cleanup",
    "namespace": "production",
    "description": "Free disk space when a StatefulSet reports disk pressure",
    "trigger": {
      "signalType": "disk_pressure",
      "severity": "medium",
      "resourceKind": "StatefulSet"
    },
    "steps": [
      {
        "name": "diagnose",
        "action": "ExecDiagnostic",
        "description": "Check filesystem usage",
        "params": {
          "command": "df -h"
        }
      },
      {
        "name": "restart-pod",
        "action": "RestartStatefulSetPod",
        "description": "Restart the affected pod"
      }
    ],
    "maxAttempts": 3,
    "creationTimestamp": "2026-03-19T16:00:00Z"
  },
  "resourceMeta": {
    "name": "disk-cleanup",
    "namespace": "production",
    "uid": "7d8e9f0a-1b2c-4d3e-9f4a-5b6c7d8e9f0a",
    "creationTimestamp": "2026-03-19T16:00:00Z",
    "labels": {
      "team": "storage"
    }
  }
}

{
  "apiVersion": "v1",
  "kind": "Error",
  "error": "Bad Request",
  "code": 400,
  "message": "name is required"
}

{
  "apiVersion": "v1",
  "kind": "Error",
  "error": "Conflict",
  "code": 409,
  "message": "failed to create runbook: runbooks.platform.chatcli.io \"disk-cleanup\" already exists"
}

Authorizations

X-API-Key

string

header

required

API key sent in the X-API-Key header. Keys are read from the Secret chatcli-operator-secrets, key api-keys (fallback: ConfigMap chatcli-operator-config, key api-keys) in the operator namespace, as a YAML list of {key, role, name, description} (name is the identity recorded on approval decisions); the operator chart creates it only with apiKeys.create: true. Roles: viewer < operator < admin — any other role string is denied everywhere. Changes are picked up within about 30 seconds; deleting both the Secret and the ConfigMap revokes every key. With no keys configured every /api/ call returns 401, unless CHATCLI_OPERATOR_DEV_MODE=true, which grants admin without a key (development only).

Body

application/json

name

string

required

Required on create; ignored on update.

Example:

"oom-standard"

namespace

string

default:default

Create only; ignored on update.

description

string

trigger

object

Show child attributes

steps

object[]

Show child attributes

maxAttempts

integer

Defaults to 3 on create; on update only values > 0 are applied.

labels

object

Show child attributes

Response

Runbook created

apiVersion

string

Example:

"v1"

kind

string

Example:

"Runbook"

spec

object

Show child attributes

resourceMeta

object

Show child attributes

Get started

Documentation

Authorizations

Body

Response