{
  "schema_version": 2,
  "id": "operate/iris/agent-playbook/self-managed/reference",
  "title": "Configuration and troubleshooting",
  "url": "https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/reference/",
  "summary": "Look up Helm values and resolve common Agent Playbooks deployment problems.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-03T16:45:14-08:00",
  "page_type": "content",
  "content_hash": "ede763bb4d172753b1d5839d5a1e34043dde175aad480f38d3bec144db5298e2",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "This page is a lookup reference for self-managed Agent Playbooks. It lists the main Helm values with their defaults, and a troubleshooting table that matches common symptoms to their causes and fixes. For how to choose and set these values, see [Configuration](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration)."
    },
    {
      "id": "configuration-reference",
      "title": "Configuration reference",
      "role": "configuration",
      "text": "| Value | Default | Meaning |\n| --- | --- | --- |\n| `tenantId` | None | The one tenant the installation serves. Required. |\n| `auth.oidc.audience` | `api://redis-iris` | The audience both planes accept in operator access tokens. |\n| `security.profile` | `\"\"` | Set `fips` for the Federal Information Processing Standards (FIPS) profile. |\n| `storage.existingSecret` | None | The Secret with `playbook-storage.yaml`. Required. |\n| `storage.playbookKey` | `playbook-storage.yaml` | The key in the storage Secret. |\n| `storage.keyPrefix` | `iris:playbook` | The Redis key prefix. |\n| `storage.maxPlaybooksPerTenant` | `128` | Playbooks the tenant can hold. |\n| `license.existingSecret` | None | The Secret with the license. Required. |\n| `license.secretKey` | `license` | The key in the license Secret. |\n| `inference.models` | None | The embedding identities the deployment offers. Required. |\n| `inference.existingSecret` | None | The Secret with `embedders_connection_details`. Required for a provider other than `noop`. |\n| `inference.secretKey` | `inference.yaml` | The key in the inference Secret. |\n| `controlplane.image.repository` | `redislabs/iris-agent-playbook-control` | The control-plane image. |\n| `dataplane.image.repository` | `redislabs/iris-agent-playbook-data` | The data-plane and worker image. |\n| `controlplane.image.tag`, `dataplane.image.tag` | None | The image tags. Required. |\n| `controlplane.service.port` | `9200` | The control-plane Service port. |\n| `dataplane.service.port` | `9201` | The data-plane Service port, for REST and MCP. |\n| `controlplane.replicaCount`, `dataplane.replicaCount`, `worker.replicaCount` | `1` | Replicas of each Deployment. |\n| `dataplane.strategy` | `{}` | The data-plane Deployment's rollout `strategy`, rendered as given. |\n| `podDisruptionBudget.enabled` | `false` | Add a PodDisruptionBudget with `maxUnavailable: 1` for each Deployment that has more than one replica. |\n| `controlplane.adminToken.autoGenerate` | `true` | Generate the admin token when `existingSecret` is empty. |\n| `controlplane.internalToken.existingSecret` | None | The internal token shared with the Identity Service. |\n| `controlplane.config.existingSecret` | None | Bring your own control-plane configuration instead of the chart's rendering. |\n| `dataplane.identityServiceBaseURL` | None | The Identity Service endpoint. Required. |\n| `identityService.allowInsecureTransport` | `false` | Accept an `http://` Identity Service URL. Refused under FIPS. |\n| `identityService.credential.existingSecret` | None | The data-plane runtime credential. Required. |\n| `dataplane.oidc.enabled`, `controlplane.oidc.enabled` | `false` | Accept operator OpenID Connect (OIDC) tokens. |\n| `tls.caCertSecret` | None | A Secret with extra CA certificates for every container. |\n| `tracing.enabled` | `false` | Send spans to an OpenTelemetry collector. |\n| `tracing.capture` | `none` | Set `received` to capture bounded data-plane content in spans. |\n| `extraction.enabled`, `extraction.connection.enabled` | `false` | Allow extraction bindings and the Redis Agent Memory connection. |\n| `worker.enabled` | `false` | Run the extraction worker. |\n| `worker.port` | `9203` | The worker's health and metrics port. |\n| `tests.enabled` | `false` | Add `helm test` pods. |\n\n`imagePullSecrets`, `security.profile`, and `tls.caCertSecret` fall back to `global.imagePullSecrets`, `global.security.profile`, and `global.tls.caCertSecret` when empty. For worker tuning values, see [Tune the worker](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/extraction#tune-the-worker)."
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| `helm install` fails with a named message | A required value is missing, or two credentials share a Secret key. | Set the value named in the message, or use distinct Secrets. |\n| `helm install` fails naming `extraction.connection.workerSubjects` | The extraction connection is enabled without the worker. | Enable the worker, or disable the connection. |\n| Pods are `Pending` or `ImagePullBackOff` | Cluster capacity, image tags, registry access, or `imagePullSecrets`. | Check pod events and the image values. |\n| Readiness fails | Redis is unreachable, a Secret key is wrong, or the license is invalid or expired. | Check the service logs. For an unknown certificate authority, [trust the private CA](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration#trust-a-private-ca). |\n| A new playbook stays `PROVISIONING` or becomes `FAILED` | A dependency failed during provisioning, such as a content Redis without JSON and Search. | Check service health and logs, and the [Redis requirements](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/prerequisites#redis-databases). Use an embedding identity from `GET /iris/v1/agent-playbooks/models`. |\n| Minting a key fails | `tenantId` differs from the Identity Service's tenant, the playbook doesn't exist, or the Identity Service can't reach the control plane. | Set both tenants to the same value, check the playbook ID, and check `productValidation.products.playbook`. |\n| An application receives `401` | The key is wrong, expired, rotated, or revoked, or it sent an administrative token. | Send its current agent key. |\n| An application receives `403` | The key has no grant on the playbook, or lacks the action. | Mint a key with the right grant. See [Agent-key grants](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#agent-key-grants). |\n| Every OIDC token is rejected after an upgrade | The tokens carry the old `api://playbook-dp` audience. | Set `auth.oidc.audience` to match. See [Configure operator OIDC access](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#configure-operator-oidc-access). |\n| An MCP client can't connect | The ingress drops the path, headers, or body, or the client sends `GET`. | Route the full MCP path to the data plane and use `POST`. |\n| Updating an extraction binding returns `412` | The `expectedRevision` is stale. | Read the binding again and resend with its current `revision`. |\n| An extraction binding is `BLOCKED` | The source store is gone, or the control plane lost access to it. | Read `blockedReason`, fix the store or trust, and enable the binding again. |"
    },
    {
      "id": "references",
      "title": "References",
      "role": "related",
      "text": "- [Data-plane API reference](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/api-reference)\n- [Control-plane API reference](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/control-plane-api-reference)\n- [Service limits](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/limits)"
    }
  ],
  "examples": []
}