{
  "schema_version": 2,
  "id": "operate/iris/agent-playbook/self-managed/deploy",
  "title": "Deploy Redis Agent Playbooks",
  "url": "https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/deploy/",
  "summary": "Install the Identity Service and Redis Agent Playbooks, then create a playbook, mint an agent key, and make one authenticated call.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-03T16:45:14-08:00",
  "page_type": "content",
  "content_hash": "9b36f50bb02901d76061bd1ce5fc15696f01bc545587fd9a56e2af1ea6ddc1d4",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "> [!NOTE]\n> For a supported install, see [Install with the Redis Iris suite chart](#install-with-the-redis-iris-suite-chart). The standalone steps on this page show what each value does.\n\nFollow these steps to install the Agent Playbooks control plane and data plane with the `redis-agent-playbook` Helm chart, connect them to an Identity Service release, and end with one authenticated call to the data plane.\n\nInstall Identity Service as release `ids`, then Agent Playbooks as release `playbook`, in one namespace. These steps use Agent Playbooks chart `1.0.0` and Identity Service chart `1.0.0`. You create the two credentials both releases share and the Identity Service control token; Agent Playbooks generates its admin token. See [Credentials](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#credentials).\n\n\nBefore installing, provide two Transport Layer Security (TLS) endpoints through your hosting environment: one forwarding to `ids-iris-identity-service:9200`, and one forwarding to `playbook-controlplane:9200`. Neither chart terminates TLS. Obtain their certificate authority (CA) certificates as a PEM bundle named `ca.crt`. For a network-isolated lab without TLS, see [Isolated lab without TLS](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#isolated-lab-without-tls).\n\nIf an Identity Service release already serves Redis Agent Memory in this namespace, use it: add the Agent Playbooks entries from [step 3](#3-install-identity-service-first) to its values and upgrade it instead of installing a second release. Both products must use the same tenant.\n\nBefore you begin, review the [prerequisites](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/prerequisites)."
    },
    {
      "id": "1-create-the-namespace",
      "title": "1. Create the namespace",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "2-create-secrets",
      "title": "2. Create Secrets",
      "role": "content",
      "text": "Prepare `playbook-storage.yaml`, `ids-metadata.yaml`, and `inference.yaml` as shown in [Configuration](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration), and save your license as `license`. Then create the Secrets:\n\n[code example]\n\nBoth releases mount `playbook-dp-credential` and `playbook-controlplane-internal`. You own these Secrets; neither release generates them in this procedure. The runtime credential lets the data plane check agent keys. The internal token lets the Identity Service validate grants against the control plane. The `ids-control-token` Secret is used only by the Identity Service."
    },
    {
      "id": "3-install-identity-service-first",
      "title": "3. Install Identity Service first",
      "role": "content",
      "text": "For every Identity Service setting, and for running one release that serves several products, see the [Identity Service guide](https://redis.io/docs/latest/operate/iris/identity-service).\n\nSave this as `values-ids.yaml`:\n\n[code example]\n\nIf the release also serves Agent Memory, keep its `memory-dp` credential, `memory` validator, and `runtime.unscopedGrantsProduct: memory`, and add these `playbook-dp` and `playbook` entries next to them.\n\n[code example]\n\nThe Agent Playbooks control plane doesn't exist yet. Configure its endpoint now, but wait until both releases and the TLS routes are ready before you mint keys: the Identity Service calls the control plane to validate each playbook grant."
    },
    {
      "id": "4-create-playbook-valuesyaml",
      "title": "4. Create `playbook-values.yaml`",
      "role": "content",
      "text": "Write the values file from [Helm values](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#helm-values), with your embedding model and the Identity Service TLS endpoint."
    },
    {
      "id": "before-you-install-check-your-values",
      "title": "Before you install: check your values",
      "role": "content",
      "text": "Check each value before you install. If one is wrong, you see the symptom in its row.\n\n| Check | Symptom | Fix |\n| --- | --- | --- |\n| `controlplane.image.tag` and `dataplane.image.tag` are set | Rendering fails with a named message, or pods `ImagePullBackOff` | Set both tags. |\n| `dataplane.identityServiceBaseURL` is `https://`, or `identityService.allowInsecureTransport` is `true` | Rendering fails | Use the TLS endpoint, or the [lab option](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#isolated-lab-without-tls). |\n| The admin token, internal token, and runtime credential reference three different Secret keys | Rendering fails | Use distinct Secrets. |\n| `inference.models` lists at least one model | Rendering fails | List each model the deployment offers. |\n| Each model's `provider` names an `embedders_connection_details` entry in `inference.yaml` | Creating a playbook fails, or it doesn't become `READY` | Add the entry under that provider name. |\n| `tenantId` equals the Identity Service's `runtime.apiKeyTenant.singleTenantID` | Minting a key fails, or agent keys get `403` | Set both to the same tenant. |\n| The content Redis has JSON and Search | The data plane isn't ready, or a playbook is `FAILED` | Use a Redis 8 build that includes JSON and Search. |"
    },
    {
      "id": "5-install",
      "title": "5. Install",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "6-verify-pods-and-health",
      "title": "6. Verify pods and health",
      "role": "content",
      "text": "[code example]\n\n`helm test` checks readiness on both planes and the configured security profile. It doesn't check that the two releases are consistent with each other; the remaining steps do.\n\nRun each port-forward in its own terminal and leave it running:\n\n[code example]\n\n[code example]\n\n[code example]\n\nThen check readiness on every service:\n\n[code example]\n\nRerun a port-forward after its pod is replaced."
    },
    {
      "id": "7-create-a-playbook",
      "title": "7. Create a playbook",
      "role": "content",
      "text": "[Load the administrative credentials](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#load-the-administrative-credentials), then follow [Create a playbook](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples#create-a-playbook). Continue when its state is `READY`."
    },
    {
      "id": "8-mint-an-agent-key",
      "title": "8. Mint an agent key",
      "role": "content",
      "text": "Mint a key with a grant on the playbook through the Identity Service. See [Create agent keys](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples#create-agent-keys)."
    },
    {
      "id": "9-make-one-authenticated-call",
      "title": "9. Make one authenticated call",
      "role": "content",
      "text": "Check the playbook with the key against the data plane:\n\n[code example]\n\nThe response reports `READY` for the playbook and for its metadata Redis, content Redis, embedding provider, and license. A `401` means the key is wrong, expired, or revoked. A `403` means it has no grant on the playbook."
    },
    {
      "id": "install-with-the-redis-iris-suite-chart",
      "title": "Install with the Redis Iris suite chart",
      "role": "setup",
      "text": "The `redis-iris` Helm chart installs Agent Playbooks with the Identity Service and the user interface (UI) in one release. Agent Playbooks is on by default (`global.iris.products.playbook.enabled: true`); set `global.iris.products.<product>.enabled: false` for each other product you don't install. Agent Playbooks values go under the `playbook:` key.\n\nThe suite sets these Agent Playbooks values itself. Don't set them under `playbook:`: a value that differs fails the render and names the field.\n\n- `tenantId`, from `global.iris.tenantId`.\n- `license.existingSecret` and `license.secretKey`, from `global.iris.license`.\n- `dataplane.identityServiceBaseURL` and `identityService.allowInsecureTransport`, for the suite's own Identity Service.\n- `identityService.credential` and `controlplane.internalToken`, from the credentials the suite generates or that you supply in `global.iris.secrets`. The admin token is in the Secret `iris-playbook-admin-token`.\n- `auth.oidc.audience`, `dataplane.oidc`, and `controlplane.oidc.enabled`, from `global.iris.auth.oidc` and `global.iris.auth.roleBindings`.\n- The extraction connection and worker settings, from `global.iris.extraction.enabled`. See [Configure background FAQ extraction](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/extraction#extraction-with-the-redis-iris-suite-chart).\n- `fullnameOverride` (`redis-agent-playbook`), the Service ports, `dataplane.strategy`, and `podDisruptionBudget.enabled`, which the suite fixes. The suite runs two data-plane replicas by default.\n\nYou still set `playbook.storage.existingSecret`, `playbook.inference.models`, and `playbook.inference.existingSecret` (unless every model is `noop`). Then install:\n\n[code example]\n\nThe rest of this guide applies to the values under `playbook:`."
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "- [Publish and retrieve your first FAQ](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/quickstart).\n- [Operate the deployment](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/operations)."
    }
  ],
  "examples": [
    {
      "id": "1-create-the-namespace-ex0",
      "language": "bash",
      "code": "kubectl create namespace <namespace-name>",
      "section_id": "1-create-the-namespace"
    },
    {
      "id": "2-create-secrets-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic playbook-storage \\\n  --from-file=playbook-storage.yaml=./playbook-storage.yaml\nkubectl -n <namespace-name> create secret generic playbook-license \\\n  --from-file=license=./license\nkubectl -n <namespace-name> create secret generic playbook-inference \\\n  --from-file=inference.yaml=./inference.yaml\nkubectl -n <namespace-name> create secret generic ids-metadata \\\n  --from-file=metadata.yaml=./ids-metadata.yaml\nkubectl -n <namespace-name> create secret generic playbook-dp-credential \\\n  --from-literal=token=\"$(openssl rand -hex 32)\"\nkubectl -n <namespace-name> create secret generic playbook-controlplane-internal \\\n  --from-literal=token=\"$(openssl rand -hex 32)\"\nkubectl -n <namespace-name> create secret generic ids-control-token \\\n  --from-literal=token=\"$(openssl rand -hex 32)\"\nkubectl -n <namespace-name> create secret generic playbook-ca \\\n  --from-file=ca.crt=./ca.crt",
      "section_id": "2-create-secrets"
    },
    {
      "id": "3-install-identity-service-first-ex0",
      "language": "yaml",
      "code": "metadata:\n  existingSecret: ids-metadata\ncontrol:\n  existingSecret: ids-control-token\n  autoGenerate: false\nruntime:\n  apiKeyTenant:\n    singleTenantID: default\n  serviceCredentials:\n    - name: playbook-dp\n      subject: playbook-dp\n      allowedOperations: [api-key-introspect]\n      allowedProducts: [playbook]\n      existingSecret: playbook-dp-credential\n      secretKey: token\nproductValidation:\n  products:\n    playbook:\n      baseURL: https://<playbook-control-plane-tls-endpoint>\n      credential:\n        existingSecret: playbook-controlplane-internal\n        secretKey: token\ntls:\n  caCertSecret: playbook-ca",
      "section_id": "3-install-identity-service-first"
    },
    {
      "id": "3-install-identity-service-first-ex1",
      "language": "bash",
      "code": "helm repo add redis-ai https://helm.redis.io/ai\nhelm repo update redis-ai\nhelm install ids redis-ai/iris-identity-service \\\n  --version 1.0.0 \\\n  --namespace <namespace-name> \\\n  -f values-ids.yaml",
      "section_id": "3-install-identity-service-first"
    },
    {
      "id": "5-install-ex0",
      "language": "bash",
      "code": "helm install playbook redis-ai/redis-agent-playbook \\\n  --version 1.0.0 \\\n  --namespace <namespace-name> \\\n  -f playbook-values.yaml \\\n  --wait --timeout 10m",
      "section_id": "5-install"
    },
    {
      "id": "6-verify-pods-and-health-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> rollout status deployment/playbook-controlplane\nkubectl -n <namespace-name> rollout status deployment/playbook-dataplane\nkubectl -n <namespace-name> get pods -l app.kubernetes.io/instance=ids\nhelm test playbook --namespace <namespace-name> --logs",
      "section_id": "6-verify-pods-and-health"
    },
    {
      "id": "6-verify-pods-and-health-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/playbook-controlplane 9200:9200",
      "section_id": "6-verify-pods-and-health"
    },
    {
      "id": "6-verify-pods-and-health-ex2",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/playbook-dataplane 9201:9201",
      "section_id": "6-verify-pods-and-health"
    },
    {
      "id": "6-verify-pods-and-health-ex3",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/ids-iris-identity-service 9202:9200",
      "section_id": "6-verify-pods-and-health"
    },
    {
      "id": "6-verify-pods-and-health-ex4",
      "language": "bash",
      "code": "curl -sS http://localhost:9200/health/readiness\ncurl -sS http://localhost:9201/health/readiness\ncurl -sS http://localhost:9202/health/readiness",
      "section_id": "6-verify-pods-and-health"
    },
    {
      "id": "9-make-one-authenticated-call-ex0",
      "language": "bash",
      "code": "curl --fail-with-body -sS \\\n  \"$IRIS_AGENT_PLAYBOOKS_URL/iris/data/v1/agent-playbooks/playbooks/$IRIS_AGENT_PLAYBOOKS_PLAYBOOK_ID/health\" \\\n  -H \"Authorization: Bearer $IRIS_AGENT_PLAYBOOKS_API_KEY\"",
      "section_id": "9-make-one-authenticated-call"
    },
    {
      "id": "install-with-the-redis-iris-suite-chart-ex0",
      "language": "bash",
      "code": "helm install iris redis-ai/redis-iris \\\n  --version 1.0.0 \\\n  --namespace <namespace-name> \\\n  -f iris-values.yaml",
      "section_id": "install-with-the-redis-iris-suite-chart"
    }
  ]
}