tylerhutcherson · Oct 23, 2026 · Oct 23, 2026
diff --git a/build/agent_playbook_docs/source-lock.json b/build/agent_playbook_docs/source-lock.json
@@ -12,6 +12,6 @@
   "sdk_example_overlay_path": ".speakeasy/playbook/overlay-code-samples.yaml",
   "sdk_example_overlay_sha256": "d5e203a097e155fb26f2032a934febee24ebc247ce5b06319c963e8b7bcc8d51",
   "control_plane_contract_path": "out/smithy/public/playbook-cp/PlaybookControlPlaneService.openapi.json",
-  "control_plane_contract_sha256": "8e168dffbe2ec1b6f7b0ee03548725e3084116bbe4534899473c54408572604b",
-  "service_revision": "304467e3e3acf5ff9e6800e03055f0a7806bc14d"
+  "control_plane_contract_sha256": "b4e5ad6ff318dcd8e9f60bb75fb2d109058891d0e211e62f9781b24f221cf7f6",
+  "service_revision": "af81d8655a5c2ff48003cc96fb7bce42daf1935f"
 }
diff --git a/content/operate/iris/agent-playbook/self-managed/_index.md b/content/operate/iris/agent-playbook/self-managed/_index.md
@@ -11,7 +11,7 @@ weight: 40
 hideListLinks: true
 ---
 
-The `redis-agent-playbook` Helm chart deploys the Playbook control plane, data plane, Identity Service, and optional extraction worker. You provide Redis databases, an embedding provider, and a Playbook license.
+The `redis-agent-playbook` Helm chart deploys the Playbook control plane, data plane, and optional extraction worker. Install Identity Service as a separate release. You provide Redis databases, an embedding provider, and a Playbook license.
 
 The chart version that matches these guides is not published yet. Set the chart version and image tags from the approved release manifest when it becomes available. Do not use the source chart's development version as a release version.
 

diff --git a/content/operate/iris/agent-playbook/self-managed/authentication.md b/content/operate/iris/agent-playbook/self-managed/authentication.md
@@ -23,7 +23,7 @@ Keep both administrative tokens out of application configuration and model promp
 
 ## Read the bootstrap credentials
 
-For [chart-generated credentials]({{< relref "/operate/iris/agent-playbook/self-managed/deploy" >}}), use an account that can read Secrets to load the administrative tokens:
+For the two releases' [chart-generated administrative credentials]({{< relref "/operate/iris/agent-playbook/self-managed/deploy" >}}), use an account that can read Secrets to load the administrative tokens:
 
 ```bash
 export PLAYBOOK_ADMIN_TOKEN="$(kubectl -n "$PLAYBOOK_NAMESPACE" get secret \
@@ -32,45 +32,42 @@ export IDENTITY_CONTROL_TOKEN="$(kubectl -n "$PLAYBOOK_NAMESPACE" get secret \
   playbook-identity-service-control-token -o jsonpath='{.data.token}' | base64 --decode)"
 ```
 
-The Secret names assume `fullnameOverride: playbook`. If you supply credentials externally, load them from your secret manager instead.
+The Secret names assume the Playbook and Identity Service naming overrides from the deployment values. If you supply credentials externally, load them from your secret manager instead.
 
 Use these tokens to [create a playbook and application keys]({{< relref "/operate/iris/agent-playbook/self-managed/api-examples" >}}). See [playbook grants]({{< relref "/develop/ai/context-engine/agent-playbook/concepts#playbooks" >}}) for allowed actions.
 
 ## Supply service credentials
 
-By default, the chart generates four service credentials. It retains their Secrets and reuses the values during live Helm upgrades.
+Use four distinct credentials. The installation procedure supplies existing Secrets for shared internal and runtime credentials; the two charts generate their own administrative tokens unless you supply them.
 
-For GitOps or offline chart rendering, supply existing Secrets to avoid generating new credentials on each render. Use a different value for each of the four credentials.
-
-| Credential | Helm Secret reference | Used by |
+| Credential | Playbook values | Identity Service values |
 | --- | --- | --- |
-| Control-plane admin token | `controlplane.adminToken.existingSecret` | Operators administering playbooks. |
-| Control-plane internal token | `controlplane.internalToken.existingSecret` | Identity Service validating playbook grants. |
-| Identity Service control token | `identityService.controlToken.existingSecret` | Operators administering application keys. |
-| Identity Service runtime token | `identityService.runtimeToken.existingSecret` | Data plane validating application keys. |
+| Control-plane admin token | `controlplane.adminToken.existingSecret` | Not shared. |
+| Control-plane internal token | `controlplane.internalToken.existingSecret` | `productValidation.products.playbook.credential.existingSecret` |
+| Identity Service control token | Not shared. | `control.existingSecret` |
+| Data-plane runtime credential | `identityService.credential.existingSecret` | `runtime.serviceCredentials[]` entry named `playbook-dp`: `existingSecret` |
 
-Each block supports `secretKey` (default `token`), `autoGenerate`, and `existingSecretChecksum`. Set `autoGenerate: false` to require an externally managed Secret.
+Secret keys default to `token`. The shared values must match on both releases. The runtime credential allows `api-key-introspect` for `playbook`; extraction needs no additional lookup operation. Preserve independently configured service-subject integrations.
 
-For example, provision four Secrets with a `token` key and add this overlay to `playbook-values.yaml`:
+To supply existing administrative tokens too, add this to `playbook-values.yaml`:
 
 ```yaml
 controlplane:
   adminToken:
     existingSecret: playbook-controlplane-admin
     autoGenerate: false
-  internalToken:
-    existingSecret: playbook-controlplane-internal
-    autoGenerate: false
+```
 
-identityService:
-  controlToken:
-    existingSecret: playbook-identity-control
-    autoGenerate: false
-  runtimeToken:
-    existingSecret: playbook-identity-runtime
-    autoGenerate: false
+Add this to `identity-values.yaml`:
+
+```yaml
+control:
+  existingSecret: playbook-identity-control
+  autoGenerate: false
 ```
 
+Provision those Secrets before installing. Load externally managed credentials from your secret manager instead of the chart-generated names.
+
 ## Tenant and grant scope
 
 Set each grant's `tenant` to the deployment's `tenantId` and scope it to a playbook and allowed actions. The [key examples]({{< relref "/operate/iris/agent-playbook/self-managed/api-examples#create-application-keys" >}}) show the complete request.
@@ -113,33 +110,30 @@ The control plane applies these role tiers:
 | Role | Control-plane access |
 | --- | --- |
 | `viewer` | List models and read playbooks. |
-| `operator` | Viewer access plus create and update playbooks and manage extraction bindings. |
-| `product_admin`, `suite_admin` | Operator access plus clear or delete playbooks. |
+| `operator` | Viewer access plus create and update playbooks; inspect extraction bindings, update their FAQ policy, pause, or delete them. |
+| `product_admin`, `suite_admin` | Operator access plus clear or delete playbooks; list extraction sources, create bindings, and enable or recover them. |
 
 On the data plane, explicitly mapped `product_admin` and `suite_admin` users receive full access within the configured tenant. Unmapped claim values grant no access, even when a value matches an Iris role name. Keep service identities out of human administrator groups.
 
 The issuer and JSON Web Key Set (JWKS) endpoints must use HTTPS unless you set the development-only `allowInsecureTransport: true`. The Federal Information Processing Standards (FIPS)-oriented profile requires HTTPS. Mount a private certificate authority through `tls.caCertSecret` when required.
 
 ## Configure OIDC access to API-key administration
 
-Identity Service Control has a separate OIDC policy. Configure it when operators must manage application keys without the bootstrap control token:
+Identity Service Control has a separate OIDC policy. Add this to `identity-values.yaml` when operators must manage application keys without the bootstrap control token:
 
 ```yaml
-identityService:
-  controlAuth:
-    oidc:
-      enabled: true
-      issuer: https://<identity-provider-host>/<issuer-path>
-      jwks_uri: https://<identity-provider-host>/<jwks-path>
-      audience:
-        - <identity-service-audience>
-      role_mappings:
-        <playbook-admin-group>: product_admin
-    roleBindings:
-      - claim_value: <playbook-admin-group>
-        scope: product
-        product: playbook
-        role: product_admin
+controlAuth:
+  oidc:
+    enabled: true
+    issuer: https://<identity-provider-host>/<issuer-path>
+    jwks_uri: https://<identity-provider-host>/<jwks-path>
+    audience:
+      - <identity-service-audience>
+  roleBindings:
+    - claim_value: <playbook-admin-group>
+      scope: product
+      product: playbook
+      role: product_admin
 ```
 
-The control token remains available as a deployment-administration credential. By default, `identityService.apiKeyTenant.singleTenantID` inherits `tenantId`. Identity Service fills an omitted grant tenant with that value and rejects grants for another tenant.
+The control token remains available as a deployment-administration credential. Set `runtime.apiKeyTenant.singleTenantID` in the Identity Service values to Playbook's `tenantId`. Identity Service fills an omitted grant tenant with that value and rejects grants for another tenant.
diff --git a/content/operate/iris/agent-playbook/self-managed/configuration.md b/content/operate/iris/agent-playbook/self-managed/configuration.md
@@ -35,7 +35,7 @@ metadata:
     - rediss://<identity-user>:<identity-password>@<metadata-host>:6379
 ```
 
-The [deploy procedure]({{< relref "/operate/iris/agent-playbook/self-managed/deploy#create-prerequisite-secrets" >}}) puts both files in one Secret under the chart's expected keys.
+The [deploy procedure]({{< relref "/operate/iris/agent-playbook/self-managed/deploy#create-prerequisite-secrets" >}}) creates separate Secrets for Playbook storage and the standalone Identity Service metadata.
 
 ## Embedding configuration
 
@@ -74,14 +74,17 @@ tenantId: <tenant-id>
 controlplane:
   image:
     tag: <playbook-control-plane-image-tag>
+  internalToken:
+    existingSecret: playbook-controlplane-internal
 
 dataplane:
   image:
     tag: <playbook-data-plane-image-tag>
+  identityServiceBaseURL: https://<identity-service-tls-endpoint>
 
 identityService:
-  image:
-    tag: <identity-service-image-tag>
+  credential:
+    existingSecret: playbook-dp-credential
 
 storage:
   existingSecret: playbook-storage
@@ -100,21 +103,52 @@ tests:
   enabled: true
 ```
 
-Use image tags from one approved release manifest. The chart generates the service credentials unless you set [existing credential Secrets]({{< relref "/operate/iris/agent-playbook/self-managed/authentication#supply-service-credentials" >}}).
+Use image tags from the approved release manifest. The shared internal and runtime credentials must match the standalone Identity Service values. See [service credentials]({{< relref "/operate/iris/agent-playbook/self-managed/authentication#supply-service-credentials" >}}).
+
+Save `identity-values.yaml` for the separate Identity Service release, using the same tenant as Playbook:
+
+```yaml
+fullnameOverride: playbook-identity-service
+image:
+  tag: <identity-service-image-tag>
+metadata:
+  existingSecret: playbook-identity-metadata
+runtime:
+  apiKeyTenant:
+    singleTenantID: <tenant-id>
+  serviceCredentials:
+    - name: playbook-dp
+      subject: playbook-dp
+      allowedOperations: [api-key-introspect]
+      allowedProducts: [playbook]
+      existingSecret: playbook-dp-credential
+      secretKey: token
+productValidation:
+  products:
+    playbook:
+      baseURL: https://<playbook-control-plane-tls-endpoint>
+      credential:
+        existingSecret: playbook-controlplane-internal
+        secretKey: token
+```
+
+Provide certificate-verified routes to both configured TLS endpoints; the charts do not create TLS termination. Identity Service validates playbook grants through the control-plane endpoint. Configure it before installing, then wait for both releases and their routes before minting application keys.
+
+An existing Identity Service release can also serve Playbook. Merge the `playbook-dp` runtime credential and `playbook` validator into its existing lists and maps instead of replacing other products' configuration. Set `dataplane.identityServiceBaseURL` to that release's endpoint. Its single-tenant policy must match Playbook's `tenantId`.
 
 | Area | Values | Purpose |
 | --- | --- | --- |
 | Tenant | `tenantId` | Tenant shared by this deployment and its application grants. |
-| Storage | `storage.existingSecret`, `storage.playbookKey`, `storage.identityServiceKey`, `storage.keyPrefix`, `storage.maxPlaybooksPerTenant` | Storage Secret, key namespace, and tenant inventory limit. The default maximum is 128 playbooks. |
+| Storage | `storage.existingSecret`, `storage.playbookKey`, `storage.keyPrefix`, `storage.maxPlaybooksPerTenant` | Storage Secret, key namespace, and tenant inventory limit. The default maximum is 128 playbooks. |
 | Storage rollout | `storage.existingSecretChecksum` | Roll consuming pods after the storage Secret changes. |
 | License | `license.existingSecret`, `license.secretKey`, `license.existingSecretChecksum` | License Secret and rollout marker. The default key is `license`. |
 | Embeddings | `inference.models`, `inference.existingSecret`, `inference.secretKey`, `inference.existingSecretChecksum` | Public model identities and private configuration. The default Secret key is `inference.yaml`. |
-| Images | `controlplane.image.*`, `dataplane.image.*`, `identityService.image.*`, `imagePullSecrets` | Pin or mirror the release images. |
-| Capacity | `controlplane.replicaCount`, `dataplane.replicaCount`, `identityService.replicaCount`, each component's `resources` | Service replicas and Kubernetes resource requests and limits. |
-| Services | `controlplane.service.*`, `dataplane.service.*`, `identityService.service.*` | Service type and port. |
-| Service connections | `dataplane.identityServiceBaseURL`, `identityService.playbookControlPlaneBaseURL` | Override the chart's in-cluster service endpoints. |
+| Images | `controlplane.image.*`, `dataplane.image.*`, `imagePullSecrets` | Pin or mirror the release images. |
+| Capacity | `controlplane.replicaCount`, `dataplane.replicaCount`, each component's `resources` | Service replicas and Kubernetes resource requests and limits. |
+| Services | `controlplane.service.*`, `dataplane.service.*`, standalone Identity Service `service.*` | Service type and port. |
+| Service connections | `dataplane.identityServiceBaseURL`, standalone `productValidation.products.playbook.baseURL` | Connect the data plane to Identity Service and Identity Service to the control-plane validator. |
 | Private certificate authority | `tls.caCertSecret`, `tls.caCertSecretChecksum` | Trust additional certificate authorities and roll pods when they change. |
-| Operator OpenID Connect (OIDC) | `auth.oidc.audience`, `dataplane.oidc`, `controlplane.oidc`, `identityService.controlAuth` | Validate operator identity provider tokens. |
+| Operator OpenID Connect (OIDC) | `auth.oidc.audience`, `dataplane.oidc`, `controlplane.oidc`, standalone `controlAuth` | Validate operator identity provider tokens. |
 | Security | `serviceAccount`, `security.profile`, pod security contexts | Configure workload identity and the optional FIPS-oriented profile. |
 | Tracing | `tracing.enabled`, `tracing.otlpGRPCEndpoint`, `tracing.capture` | Send OpenTelemetry spans to a deployment-owned collector. |
 | Extraction | `extraction`, `worker` | Connect Redis Agent Memory and run optional background FAQ extraction. |
@@ -131,7 +165,7 @@ kubectl -n '<namespace-name>' create secret generic playbook-redis-ca \
   --from-file=ca.crt=./ca.crt
 ```
 
-Add this to `playbook-values.yaml` before installing:
+Add this to both `playbook-values.yaml` and `identity-values.yaml` before installing:
 
 ```yaml
 tls:
@@ -142,7 +176,7 @@ The chart mounts the CA for all enabled workloads. Keep certificate verification
 
 ## Configure security and tracing
 
-Set `security.profile: fips` only with images built for the Federal Information Processing Standards (FIPS) profile. Storage URLs must use `rediss://`. Set explicit HTTPS values for `dataplane.identityServiceBaseURL` and `identityService.playbookControlPlaneBaseURL`. The profile configures the processes but does not provide Transport Layer Security (TLS) termination or establish compliance by itself.
+Set `security.profile: fips` only with images built for the Federal Information Processing Standards (FIPS) profile. Storage URLs must use `rediss://`. Set explicit HTTPS values for `dataplane.identityServiceBaseURL` and standalone `productValidation.products.playbook.baseURL`. The profile configures the processes but does not provide Transport Layer Security (TLS) termination or establish compliance by itself.
 
 To export traces, configure a trusted local OpenTelemetry Protocol (OTLP) collector: