{
  "schema_version": 2,
  "id": "operate/iris/agent-playbook/self-managed/configuration",
  "title": "Configure self-managed Agent Playbooks",
  "url": "https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/configuration/",
  "summary": "Prepare Helm values, the storage and embedding Secrets, Identity Service connection settings, private CA trust, security, and tracing for Agent Playbooks.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-03T09:59:49-05:00",
  "page_type": "content",
  "content_hash": "4216ae07bac669ad0daab5140cd0ea85c5f4c293854093a435bf3a485471b435",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The chart renders the control-plane and data-plane configuration from Helm values. Storage URLs, provider credentials, the license, and tokens stay in existing Secrets. These examples use release `playbook`, `fullnameOverride: playbook`, tenant `default`, and chart `1.0.0`."
    },
    {
      "id": "storage-configuration",
      "title": "Storage configuration",
      "role": "content",
      "text": "Save `playbook-storage.yaml` with the two Redis endpoints:\n\n[code example]\n\nThe control plane and data plane both mount this file. The Identity Service's metadata Redis belongs to the Identity Service release. Save `ids-metadata.yaml` for it, with credentials for its own Redis user:\n\n[code example]\n\nThe [deploy steps](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/deploy#2-create-secrets) put each file in its own Secret."
    },
    {
      "id": "embedding-configuration",
      "title": "Embedding configuration",
      "role": "content",
      "text": "Put provider endpoints and credentials in `inference.yaml`. Helm values contain only the model identity.\n\nEach key under `embedders_connection_details` names a connection. A model's `provider` in `inference.models` selects the connection with the same name. This example names the connection `openai`, which also lets the [Iris command-line interface (CLI)](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples#use-the-iris-cli) create playbooks with it. Use the provider and model approved for your deployment.\n\nSave `inference.yaml`:\n\n[code example]\n\nThe endpoint and credential reach only the data plane. The control plane receives only the public model list. A connection accepts `protocol` (defaults to the connection name), `base_url`, `azure`, `credentials`, `http_client`, `embedding_input_max_chars`, `embedding_input_fast_truncate`, and `batching.embeddings`. Batching is off unless you enable it.\n\nWhen you change a connection, keep the vector space it serves. A model or dimension change needs a new playbook."
    },
    {
      "id": "helm-values",
      "title": "Helm values",
      "role": "content",
      "text": "Save `playbook-values.yaml`:\n\n[code example]\n\n- `tenantId` must equal `runtime.apiKeyTenant.singleTenantID` on the Identity Service release. Neither chart can check that the two match.\n- `dataplane.identityServiceBaseURL` is the Identity Service release's TLS endpoint. The data plane checks agent keys there.\n- `identityService.credential` is the data plane's runtime credential. Register the same Secret on the Identity Service release.\n- `controlplane.internalToken` is the token the Identity Service presents when it validates grants. Register the same Secret on the Identity Service release.\n- The chart generates the admin token and keeps it across upgrades unless you set `controlplane.adminToken.existingSecret`. See [Credentials](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/authentication#credentials).\n- `tls.caCertSecret` names the CA bundle that the planes trust for the Identity Service endpoint and other private endpoints. See [Trust a private CA](#trust-a-private-ca).\n- `tests.enabled` adds the pods that `helm test` runs.\n\nWith `fullnameOverride: playbook`, the chart creates the Services `playbook-controlplane` and `playbook-dataplane`. Without it, names start with `<release>-redis-agent-playbook`.\n\nThe install fails with a named message when a required value is missing: the image tags, `tenantId`, the storage and license Secrets, at least one model, the Identity Service URL and credential, and a generated or existing Secret for each control-plane token. It also fails when two credentials reference the same Secret key. Keep every credential value distinct, even in differently named Secrets.\n\nFor every value and its default, see the [configuration reference](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/reference#configuration-reference), or run:\n\n[code example]"
    },
    {
      "id": "isolated-lab-without-tls",
      "title": "Isolated lab without TLS",
      "role": "content",
      "text": "For a network-isolated lab without the Federal Information Processing Standards (FIPS) profile, you can point the data plane at the in-cluster Identity Service Service instead of a TLS endpoint:\n\n[code example]\n\nOn the Identity Service release, set `productValidation.products.playbook.baseURL: http://playbook-controlplane:9200`. Tokens travel over plaintext HTTP on these two hops; use TLS for production. The FIPS profile refuses this configuration."
    },
    {
      "id": "identity-service-in-another-namespace",
      "title": "Identity Service in another namespace",
      "role": "content",
      "text": "The tested layout puts both releases in one namespace. If the Identity Service runs in another namespace:\n\n- Point `dataplane.identityServiceBaseURL` at its fully qualified Service or TLS endpoint, for example `http://ids-iris-identity-service.<identity-namespace>.svc:9200`.\n- Set its `productValidation.products.playbook.baseURL` to `http://playbook-controlplane.<namespace-name>.svc:9200`, or to that endpoint's TLS frontend.\n- Provision both shared Secrets with the same values in both namespaces. A pod mounts Secrets only from its own namespace.\n- Allow the Identity Service to reach the control plane on port `9200`, and both planes to reach the Identity Service."
    },
    {
      "id": "trust-a-private-ca",
      "title": "Trust a private CA",
      "role": "content",
      "text": "If Redis, the Identity Service endpoint, or another dependency uses a private CA, save the CA certificates as `ca.crt` and create a Secret in the deployment namespace:\n\n[code example]\n\nSet `tls.caCertSecret: playbook-ca` in `playbook-values.yaml`. The chart mounts the CA at `/etc/ssl/custom` in every container, on top of the system CAs. Keep certificate verification enabled."
    },
    {
      "id": "configure-security-and-tracing",
      "title": "Configure security and tracing",
      "role": "configuration",
      "text": "Set `security.profile: fips` only with images built for the FIPS profile and with all dependency transport ready:\n\n[code example]\n\nUnder this profile:\n\n- Storage URLs must use `rediss://`. Both planes check this at startup.\n- `dataplane.identityServiceBaseURL` must be an `https://` endpoint, and the chart refuses `identityService.allowInsecureTransport`.\n- On the Identity Service release, set its own `security.profile` and an `https://` validator URL for `productValidation.products.playbook.baseURL`.\n\nThe profile configures the processes. It does not provide TLS termination or establish compliance by itself; the workloads still listen on HTTP.\n\nTo export traces from the control plane, data plane, and extraction worker, configure a trusted OpenTelemetry Protocol (OTLP) collector:\n\n[code example]\n\nThe exporter uses plaintext gRPC for the collector hop, so keep the collector on a trusted network. `tracing.capture: received` adds bounded query and returned content to data-plane serving spans; `tracing.capture` doesn't affect the control plane or worker."
    },
    {
      "id": "playbook-settings",
      "title": "Playbook settings",
      "role": "content",
      "text": "Select a configured embedding model when you [create a playbook](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/api-examples#create-a-playbook). Use the control plane to update discovery settings and the proposal review policy. When you omit them, a playbook uses FAQ and skill minimum scores of `0.7`, at most 10 results, a review window of 2,592,000 seconds (30 days), and at most 5,000 open proposals.\n\n`storage.maxPlaybooksPerTenant` limits how many playbooks the tenant can hold. The default is `128`.\n\nSee the [control-plane API reference](https://redis.io/docs/latest/operate/iris/agent-playbook/self-managed/control-plane-api-reference) for fields and limits, and [Retrieval](https://redis.io/docs/latest/develop/ai/context-engine/agent-playbooks/retrieval) for how applications use these settings."
    }
  ],
  "examples": [
    {
      "id": "storage-configuration-ex0",
      "language": "yaml",
      "code": "storage:\n  metadata:\n    urls:\n      - rediss://<metadata-user>:<metadata-password>@<metadata-host>:6379\n  content:\n    urls:\n      - rediss://<content-user>:<content-password>@<content-host>:6379",
      "section_id": "storage-configuration"
    },
    {
      "id": "storage-configuration-ex1",
      "language": "yaml",
      "code": "metadata:\n  urls:\n    - rediss://<identity-user>:<identity-password>@<metadata-host>:6379",
      "section_id": "storage-configuration"
    },
    {
      "id": "embedding-configuration-ex0",
      "language": "yaml",
      "code": "embedders_connection_details:\n  openai:\n    protocol: openai\n    base_url: https://<embedding-provider-host>/v1\n    credentials:\n      type: static\n      api_key: <embedding-provider-api-key>\n    http_client:\n      timeout: 30s\n      max_retry_attempts: 3\n    batching:\n      embeddings:\n        enabled: true",
      "section_id": "embedding-configuration"
    },
    {
      "id": "helm-values-ex0",
      "language": "yaml",
      "code": "fullnameOverride: playbook\ntenantId: default\n\ncontrolplane:\n  image:\n    tag: \"1.0.0\"\n  internalToken:\n    existingSecret: playbook-controlplane-internal\n\ndataplane:\n  image:\n    tag: \"1.0.0\"\n  identityServiceBaseURL: https://<identity-service-tls-endpoint>\n\nidentityService:\n  credential:\n    existingSecret: playbook-dp-credential\n\nstorage:\n  existingSecret: playbook-storage\n\nlicense:\n  existingSecret: playbook-license\n\ninference:\n  existingSecret: playbook-inference\n  models:\n    - provider: openai\n      model: <embedding-model-name>\n      dimensions: <embedding-dimensions>\n\ntls:\n  caCertSecret: playbook-ca\n\ntests:\n  enabled: true",
      "section_id": "helm-values"
    },
    {
      "id": "helm-values-ex1",
      "language": "bash",
      "code": "helm show values redis-ai/redis-agent-playbook --version 1.0.0",
      "section_id": "helm-values"
    },
    {
      "id": "isolated-lab-without-tls-ex0",
      "language": "yaml",
      "code": "dataplane:\n  identityServiceBaseURL: http://ids-iris-identity-service:9200\nidentityService:\n  allowInsecureTransport: true\n  credential:\n    existingSecret: playbook-dp-credential",
      "section_id": "isolated-lab-without-tls"
    },
    {
      "id": "trust-a-private-ca-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic playbook-ca \\\n  --from-file=ca.crt=./ca.crt",
      "section_id": "trust-a-private-ca"
    },
    {
      "id": "configure-security-and-tracing-ex0",
      "language": "yaml",
      "code": "security:\n  profile: fips\ndataplane:\n  identityServiceBaseURL: https://<identity-service-tls-endpoint>\ntls:\n  caCertSecret: playbook-ca",
      "section_id": "configure-security-and-tracing"
    },
    {
      "id": "configure-security-and-tracing-ex1",
      "language": "yaml",
      "code": "tracing:\n  enabled: true\n  otlpGRPCEndpoint: <collector-host>:4317\n  capture: none",
      "section_id": "configure-security-and-tracing"
    }
  ]
}