{
  "schema_version": 2,
  "id": "operate/iris/agent-playbook/self-managed/operations",
  "title": "Operate self-managed Agent Playbooks",
  "url": "https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/operations/",
  "summary": "Check health, rotate keys and Secrets, clear, suspend, or delete playbooks, back up storage, and upgrade Agent Playbooks.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-03T16:45:14-08:00",
  "page_type": "content",
  "content_hash": "3b4fd2f2fc61093f393b3f50a0b1df7abaa8abeb5115ea4389293463d000aa57",
  "sections": [
    {
      "id": "check-service-health",
      "title": "Check service health",
      "role": "overview",
      "text": "With the [local port-forwards](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/deploy#6-verify-pods-and-health) running:\n\n[code example]\n\nInspect pods and the affected service's logs when readiness fails:\n\n[code example]\n\nRedact credentials and content before you share logs or configuration. For common symptoms, see [Troubleshooting](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/reference#troubleshooting).\n\nScrape `/metrics` on every control-plane and data-plane pod, on ports `9200` and `9201`, and on the [extraction worker](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/extraction#monitor-extraction). Metrics use bounded operation and outcome labels. Agent Playbooks doesn't emit per-entry usage records. All three services can export traces through the shared [tracing configuration](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#configure-security-and-tracing)."
    },
    {
      "id": "rotate-or-revoke-agent-keys",
      "title": "Rotate or revoke agent keys",
      "role": "content",
      "text": "Use the Identity Service control token and connection values from [Load the administrative credentials](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#load-the-administrative-credentials).\n\nRotate a key with a one-hour grace period:\n\n[code example]\n\nStore the returned token and update its consumers before the grace period ends. The Identity Service caps the grace period with `apiKeys.maxRotateGraceSeconds`, 604,800 seconds (seven days) by default.\n\nRevoke a key:\n\n[code example]\n\nWith the Iris command-line interface (CLI), run `iris identity keys rotate <key-id> --grace 1h` or `iris identity keys revoke <key-id>`.\n\nKey validation is cached. The Identity Service release's `runtime.cache.hardTtlSeconds` defaults to 300 seconds. Allow for cached decisions, and verify that the old key is denied before you treat revocation as complete."
    },
    {
      "id": "clear-playbook-content",
      "title": "Clear playbook content",
      "role": "content",
      "text": "Clearing removes entries, proposals, or both, and keeps the playbook and its configuration. It needs the admin token or an OpenID Connect (OIDC) token with the `product_admin` or `suite_admin` role. For example, clear entries:\n\n[code example]\n\nSet `scope` to `ENTRIES`, `PROPOSALS`, or `ALL`. The scope is required. A successful clear returns `204`. The playbook must be `READY`.\n\nClearing isn't atomic across content. After a failure, resolve it and retry the same scope. Clearing doesn't suspend the playbook or stop concurrent writers, including the extraction worker.\n\nWith the CLI, run `iris agent-playbooks clear --scope entries`."
    },
    {
      "id": "suspend-or-remove-a-playbook",
      "title": "Suspend or remove a playbook",
      "role": "content",
      "text": "Suspend a playbook to stop runtime access and keep its content and configuration:\n\n[code example]\n\nResume it by setting `state` to `READY`.\n\nDeleting a playbook permanently removes its content and configuration. Back up what you need and revoke its agent keys first:\n\n[code example]\n\nDeleting needs the same roles as clearing."
    },
    {
      "id": "update-configuration-license-and-credential-secrets",
      "title": "Update configuration, license, and credential Secrets",
      "role": "content",
      "text": "Update an existing Secret from its source files. For example, update the storage configuration:\n\n[code example]\n\nCalculate the updated Secret payload's checksum:\n\n**Linux:**\n\n[code example]\n\n**macOS:**\n\n[code example]\n\n\n\nCopy it into `storage.existingSecretChecksum` in `playbook-values.yaml` and [upgrade the chart](#upgrade-the-chart). A changed checksum rolls only the workloads that consume that Secret. It triggers a rollout; it doesn't validate integrity. If a Secret controller already restarts consumers on rotation, leave the checksum empty. Without a checksum, restart the affected Deployment after you change a Secret in place.\n\nThe same pattern applies to these Secrets:\n\n| Secret | Checksum value | Rolls |\n| --- | --- | --- |\n| License | `license.existingSecretChecksum` | Control plane, data plane, and extraction worker |\n| Embedding configuration | `inference.existingSecretChecksum` | Data plane |\n| Private certificate authority (CA) | `tls.caCertSecretChecksum` | Every workload |\n| Admin token | `controlplane.adminToken.existingSecretChecksum` | Control plane and data plane |\n| Internal token | `controlplane.internalToken.existingSecretChecksum` | Control plane |\n| Data-plane runtime credential | `identityService.credential.existingSecretChecksum` | Data plane |\n| Extraction worker configuration | `worker.existingSecretChecksum` | Extraction worker |\n\nBoth planes reread the admin-token file on each request, but Kubernetes updates mounted Secrets eventually, so rotation isn't atomic across pods. The internal token and the runtime credential are shared with the Identity Service release: update the Secret, then roll both releases. For immutable Secrets, create a new name and update the reference."
    },
    {
      "id": "back-up-the-deployment",
      "title": "Back up the deployment",
      "role": "content",
      "text": "- Back up the metadata Redis, which holds playbook configuration and extraction bindings.\n- Back up the content Redis, which holds entries, proposals, and search indexes.\n- Back up the Identity Service metadata Redis, which holds agent-key records.\n- Keep the values files, configuration files, license material, and secret-manager records you need to recreate the services.\n\nCoordinate metadata and content snapshots. A metadata-only restore can't recover authored content. Validate restore procedures in an isolated environment before you rely on them."
    },
    {
      "id": "upgrade-the-chart",
      "title": "Upgrade the chart",
      "role": "content",
      "text": "Review the target release's configuration and compatibility notes. Keep the control-plane and data-plane image tags on the same release, and recalculate checksums for changed Secrets.\n\n[code example]\n\nInclude `-f playbook-extraction-values.yaml` when extraction is configured. Then check the rollouts and rerun the chart tests:\n\n[code example]\n\nIf the worker is enabled, also run `kubectl -n <namespace-name> rollout status deployment/playbook-worker`. Reconnect the local port-forwards, then repeat the [application-access check](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples#verify-application-access). Review release compatibility before a rollback; Helm doesn't restore Redis data."
    },
    {
      "id": "upgrade-from-earlier-charts",
      "title": "Upgrade from earlier charts",
      "role": "content",
      "text": "- **`0.1.x`**: those charts bundled the Identity Service. `helm upgrade` to `1.0.0` is unsupported. Install a separate Identity Service release that uses the same metadata Redis and key namespace, so existing agent keys keep working, then install `1.0.0` with the connection values. Remove every old `identityService.*` key except `allowInsecureTransport` and `credential`, and remove `storage.identityServiceKey`; the schema rejects them.\n- **Embedding configuration**: the data plane and control plane reject the legacy `inference.models[].client` field. Keep only `provider`, `model`, and `dimensions` in `inference.models`, and move endpoints and credentials into `embedders_connection_details` in the [embedding Secret](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#embedding-configuration). Keep the same vector-space identity.\n- **OIDC audience**: see [Configure operator OIDC access](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#configure-operator-oidc-access).\n\nUpgrades from the published `0.10.x` preview charts aren't supported. Reinstall with the suite chart against the same Redis databases, as [Move from a preview or standalone install](https://redis.io/docs/latest/operate/iris/self-managed#move-from-a-preview-or-standalone-install) describes."
    },
    {
      "id": "uninstall",
      "title": "Uninstall",
      "role": "content",
      "text": "[code example]\n\nHelm keeps the generated admin-token Secret, which is annotated `helm.sh/resource-policy: keep`. Delete it, the Secrets you created, and the Redis data if you don't plan to reinstall. Uninstalling Agent Playbooks doesn't remove the Identity Service release or its agent-key records."
    }
  ],
  "examples": [
    {
      "id": "check-service-health-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS http://localhost:9200/health/readiness\ncurl --fail-with-body -sS http://localhost:9201/health/readiness\ncurl --fail-with-body -sS http://localhost:9202/health/readiness",
      "section_id": "check-service-health"
    },
    {
      "id": "check-service-health-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get pods -l app.kubernetes.io/instance=playbook\nkubectl -n <namespace-name> describe pod <pod-name>\nkubectl -n <namespace-name> logs deployment/playbook-dataplane",
      "section_id": "check-service-health"
    },
    {
      "id": "rotate-or-revoke-agent-keys-ex0",
      "language": "bash",
      "code": "umask 077\ncurl --fail-with-body -sS \\\n  -X POST \"$IRIS_IDENTITY_URL/v1/api-keys/<key-id>/rotate?graceSeconds=3600\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\" > rotated-key.json",
      "section_id": "rotate-or-revoke-agent-keys"
    },
    {
      "id": "rotate-or-revoke-agent-keys-ex1",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  -X DELETE \"$IRIS_IDENTITY_URL/v1/api-keys/<key-id>\" \\\n  -H \"Authorization: Bearer $IRIS_IDENTITY_TOKEN\"",
      "section_id": "rotate-or-revoke-agent-keys"
    },
    {
      "id": "clear-playbook-content-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  -X POST \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID/clear?scope=ENTRIES\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\"",
      "section_id": "clear-playbook-content"
    },
    {
      "id": "suspend-or-remove-a-playbook-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  -X PATCH \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\" \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"state\":\"SUSPENDED\"}'",
      "section_id": "suspend-or-remove-a-playbook"
    },
    {
      "id": "suspend-or-remove-a-playbook-ex1",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  -X DELETE \"$IRIS_AGENT_PLAYBOOKS_SERVICE_URL/iris/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_SERVICE_TOKEN\"",
      "section_id": "suspend-or-remove-a-playbook"
    },
    {
      "id": "update-configuration-license-and-credential-secrets-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic playbook-storage \\\n  --from-file=playbook-storage.yaml=./playbook-storage.yaml \\\n  --dry-run=client -o yaml | kubectl apply -f -",
      "section_id": "update-configuration-license-and-credential-secrets"
    },
    {
      "id": "update-configuration-license-and-credential-secrets-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret playbook-storage -o json \\\n  | jq -cS '.data' | sha256sum | awk '{print $1}'",
      "section_id": "update-configuration-license-and-credential-secrets"
    },
    {
      "id": "update-configuration-license-and-credential-secrets-ex2",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret playbook-storage -o json \\\n  | jq -cS '.data' | shasum -a 256 | awk '{print $1}'",
      "section_id": "update-configuration-license-and-credential-secrets"
    },
    {
      "id": "upgrade-the-chart-ex0",
      "language": "bash",
      "code": "helm upgrade playbook redis-ai/redis-agent-playbook \\\n  --version <chart-version> \\\n  --namespace <namespace-name> \\\n  -f playbook-values.yaml \\\n  --wait --timeout 10m",
      "section_id": "upgrade-the-chart"
    },
    {
      "id": "upgrade-the-chart-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> rollout status deployment/playbook-controlplane\nkubectl -n <namespace-name> rollout status deployment/playbook-dataplane\nhelm test playbook --namespace <namespace-name> --logs",
      "section_id": "upgrade-the-chart"
    },
    {
      "id": "uninstall-ex0",
      "language": "bash",
      "code": "helm uninstall playbook --namespace <namespace-name>",
      "section_id": "uninstall"
    }
  ]
}