From a2224bf28f26d5dd1ad4103e69e310de97fa6f33 Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Mon, 2 Nov 2026 07:32:08 -0500 Subject: [PATCH 1/2] Iris docs: align Context Gateway and Intent Router self-managed docs with the operator runbooks Context Gateway: use chart-default images, document the 0.2.0 cache/compression key migration and rollback limits, and describe probe and autoscaling overrides. Intent Router: the chart connects to a separate Identity Service release; replace bundled-Identity Service values with identityService.credential, identityService.allowInsecureTransport and dataplane.identityServiceBaseURL, add the product contract and startupBudget. Co-Authored-By: Claude Opus 5.5 --- .../context-gateway/self-managed/_index.md | 2 +- .../self-managed/configuration.md | 4 +- .../context-gateway/self-managed/deploy.md | 12 ++---- .../self-managed/operations.md | 4 +- .../self-managed/prerequisites.md | 4 +- .../iris/intent-router/self-managed/_index.md | 4 +- .../self-managed/authentication.md | 6 +-- .../self-managed/configuration.md | 35 +++++++--------- .../iris/intent-router/self-managed/deploy.md | 42 ++++++++++++------- .../self-managed/prerequisites.md | 15 +++---- .../intent-router/self-managed/reference.md | 9 ++-- 11 files changed, 72 insertions(+), 65 deletions(-) diff --git a/content/operate/iris/context-gateway/self-managed/_index.md b/content/operate/iris/context-gateway/self-managed/_index.md index cf91d2b1a0..31def44def 100644 --- a/content/operate/iris/context-gateway/self-managed/_index.md +++ b/content/operate/iris/context-gateway/self-managed/_index.md @@ -17,7 +17,7 @@ The `redis-context-gateway` Helm chart deploys one tenant's Context Gateway Cont Agents call the Data Plane's Model Context Protocol (MCP) endpoint, described in the [MCP API reference](/content/develop/ai/context-engine/context-gateway/api-reference.md). The [Control Plane API reference](/content/operate/iris/context-gateway/self-managed/control-plane-api-reference.md) documents the self-managed administration endpoints for Gateways and Upstreams. -Set the chart version and image tags from the approved release manifest. Use a release that includes the unified Gateway API and GA hardening described in these guides. +Set the chart version from the approved release. Each chart release pins its matching Control Plane and Data Plane images by default. Use a release that includes the unified Gateway API and GA hardening described in these guides. diff --git a/content/operate/iris/context-gateway/self-managed/configuration.md b/content/operate/iris/context-gateway/self-managed/configuration.md index 6dd38a57be..2fc7fc9b06 100644 --- a/content/operate/iris/context-gateway/self-managed/configuration.md +++ b/content/operate/iris/context-gateway/self-managed/configuration.md @@ -237,6 +237,8 @@ Both planes serve Prometheus metrics at `/metrics`. Set `shared.config.opentelem ## Scale and schedule the planes -Each plane starts one replica. Set `replicaCount`, or turn on `autoscaling`, with `resources`, `nodeSelector`, `tolerations`, and `affinity` under `controlplane` and `dataplane`. The probes are chart-managed. Leave headroom for old and new pods during upgrades. +Each plane starts one replica. Set `replicaCount`, or turn on `autoscaling`, with `resources`, `nodeSelector`, `tolerations`, and `affinity` under `controlplane` and `dataplane`. Autoscaling is off by default, needs Metrics Server, and needs `resources.requests.cpu` or `resources.requests.memory` for each target it uses. Leave headroom for old and new pods during upgrades. + +The `startupProbe`, `livenessProbe`, and `readinessProbe` of each plane use `/health/liveness` and `/health/readiness` by default, and accept native Kubernetes probe fields. Set a probe to `null` to turn it off. The default startup probe allows 150 seconds before liveness checks begin. diff --git a/content/operate/iris/context-gateway/self-managed/deploy.md b/content/operate/iris/context-gateway/self-managed/deploy.md index 84fe74ef67..eaace5b921 100644 --- a/content/operate/iris/context-gateway/self-managed/deploy.md +++ b/content/operate/iris/context-gateway/self-managed/deploy.md @@ -76,7 +76,7 @@ Create a `databaseConnections` Secret for the registered databases. See [Databas ## 3. Create `gateway-values.yaml` -Save this file, replacing the angle-bracket placeholders with your tenant, public Data Plane origin, and approved release image tags. It uses the Secrets created in step 2 and an Identity Service release named `ids` in the same namespace. +Save this file, replacing the angle-bracket placeholders with your tenant and public Data Plane origin. The chart's default images match its version, so the file sets no image values. It uses the Secrets created in step 2 and an Identity Service release named `ids` in the same namespace. ```yaml tenantId: @@ -101,9 +101,6 @@ credentialStorage: k1: k1 activeKeyId: k1 controlplane: - image: - repository: redislabs/iris-context-gateway-control - tag: adminToken: existingSecret: gateway-admin secretKey: token @@ -111,9 +108,6 @@ controlplane: existingSecret: gateway-grant-validation secretKey: token dataplane: - image: - repository: redislabs/iris-context-gateway-data - tag: runtimeToken: existingSecret: gateway-runtime secretKey: token @@ -135,7 +129,7 @@ Check each value in `gateway-values.yaml` before you install. If one is wrong, y | `identityService.allowInsecureTransport` is `true` for an `http://` Identity Service URL | Rendering fails with `HTTP Identity Service requires explicit allowInsecureTransport`. | Set it, or use an `https://` URL. | | The admin, internal, and runtime tokens come from three different Secrets or keys | Rendering fails, or the Identity Service cannot check keys | Create three distinct token files. | | `license` points to a valid license | The Control Plane's `/health/readiness` answers `503`, and an invalid license stops either plane at startup | Mount the license file as issued. | -| Both component `image.repository` and `image.tag` are set | Pods `ImagePullBackOff` | Set both to the release images. | +| Any `image.repository` or `image.tag` override names an image your cluster can pull | Pods `ImagePullBackOff` | Remove the overrides to use the chart's default images, or mirror those images unchanged. | {{< /table-scrollable >}} ## 4. Install @@ -150,7 +144,7 @@ helm install gateway redis-ai/redis-context-gateway \ --wait --timeout 5m ``` -Use the chart version and image tags supplied for the same release. A merged server change does not by itself publish a chart or image. +Use a published chart version. A merged server change does not by itself publish a chart or image. ## 5. Verify pods and health diff --git a/content/operate/iris/context-gateway/self-managed/operations.md b/content/operate/iris/context-gateway/self-managed/operations.md index 23e2645ac1..2959d6b903 100644 --- a/content/operate/iris/context-gateway/self-managed/operations.md +++ b/content/operate/iris/context-gateway/self-managed/operations.md @@ -90,7 +90,9 @@ Back up Metadata Redis and credential storage together. A Gateway record without ## Upgrade the chart -Upgrade both planes together and roll forward, not back. An older Data Plane cannot read tool policy members that a newer Control Plane wrote, and serves those tools uncached. +Upgrade both planes together and roll forward, not back. An older Data Plane cannot read tool policy members that a newer Control Plane wrote, and serves those tools uncached. `helm rollback` restores the release's Kubernetes resources only. It does not undo database writes or restore external Secrets. + +Chart 0.2.0 renamed the `dataplane.config` blocks `result_cache` to `cache` and `result_handles` to `compression`. Every nested key keeps its name. Move these settings before you upgrade: the values schema rejects the old blocks, and a Data Plane ignores them. Upgrade the chart and images together, because an older image ignores the new keys and leaves both features off. The same release renamed the Gateway fields `resultCache` and `resultHandles` to `cache` and `compression`. Gateways stored under the old names lose their settings and tool policies, so set them again. After an upgrade, refresh an Upstream's catalog when the release notes ask for it. diff --git a/content/operate/iris/context-gateway/self-managed/prerequisites.md b/content/operate/iris/context-gateway/self-managed/prerequisites.md index 9c2e260550..50bf907ec7 100644 --- a/content/operate/iris/context-gateway/self-managed/prerequisites.md +++ b/content/operate/iris/context-gateway/self-managed/prerequisites.md @@ -108,13 +108,13 @@ Redis URLs, tokens, keyrings, and the license belong in Kubernetes Secrets or Se | Control Plane | `redislabs/iris-context-gateway-control:` | | Data Plane | `redislabs/iris-context-gateway-data:` | -Set both `image.repository` and `image.tag` from the release manifest. +The chart defaults to these repositories and pins the image tags that match its chart version. Leave `image.repository` and `image.tag` unset for a public install, and override them only to pull from a mirror. ## Air-gapped and private registry installs -For a disconnected installation, mirror both images to your registry, set each component's `image.repository`, and set `imagePullSecrets`. Install from a downloaded chart package instead of the Redis AI Helm repository. +For a disconnected installation, mirror both images to your registry with their tags unchanged, set each component's `image.repository` and `image.tag`, and set `imagePullSecrets`. Install from a downloaded chart package instead of the Redis AI Helm repository. ## Helm values to review diff --git a/content/operate/iris/intent-router/self-managed/_index.md b/content/operate/iris/intent-router/self-managed/_index.md index aa4d5541e6..6e8af8b8d3 100644 --- a/content/operate/iris/intent-router/self-managed/_index.md +++ b/content/operate/iris/intent-router/self-managed/_index.md @@ -15,7 +15,7 @@ Intent Router classifies each incoming user message by intent, so your applicati This guide is for that administrator. It covers deploying Intent Router on your own Kubernetes cluster with a Helm chart, then configuring, securing, and operating it. To install, start with the [prerequisites](/content/operate/iris/intent-router/self-managed/prerequisites.md). -The `redis-intent-router` Helm chart deploys one tenant's Intent Router control plane and data plane. By default it also deploys an Identity Service that issues and checks agent keys. You provide the Redis databases, the embedding provider credentials, and the license. +The `redis-intent-router` Helm chart deploys one tenant's Intent Router control plane and data plane. It deploys no Identity Service: it connects to an Identity Service release that you install separately, which issues and checks agent keys. You provide the Identity Service release, the Redis databases, the embedding provider credentials, and the license. Applications call the data plane to author intents and match queries, as described in the [data-plane API reference](/content/develop/ai/context-engine/intent-router/api-reference.md). The [control-plane API reference](/content/operate/iris/intent-router/self-managed/control-plane-api-reference.md) documents the administration endpoints for Routers. @@ -28,7 +28,7 @@ Set the chart version and image tags from the release manifest for your deployme | --- | --- | --- | | Control plane | Create and manage Routers, and validate agent-key grants. | `9400` | | Data plane | Store intents and examples, build each Router's vector index, and serve matching. | `9401` | -| Identity Service | Issue agent keys and check them for the data plane. | `9200` | +| Identity Service | Issue agent keys and check them for the data plane. Installed as its own release. | `9200` | | Metadata Redis | Store Router records and the mailbox the planes coordinate through. | Customer-provided | | Data-plane Redis | Store intents, examples, and a vector index for each Router. Needs Redis Search. | Customer-provided | | Embedding provider | Embed examples and queries. | Customer-provided | diff --git a/content/operate/iris/intent-router/self-managed/authentication.md b/content/operate/iris/intent-router/self-managed/authentication.md index d0a7f608d5..e9fb1bc273 100644 --- a/content/operate/iris/intent-router/self-managed/authentication.md +++ b/content/operate/iris/intent-router/self-managed/authentication.md @@ -11,7 +11,7 @@ weight: 60 hideListLinks: true --- -Self-managed Intent Router uses two kinds of credentials. Service tokens authenticate operators and the Intent Router components to each other, and the chart generates them for you by default. Agent keys authenticate applications to the data plane, and each key's grants control which Routers it can use and what it can do on them. +Self-managed Intent Router uses two kinds of credentials. Service tokens authenticate operators and the Intent Router components to each other. The chart generates the control-plane tokens for you by default. Agent keys authenticate applications to the data plane, and each key's grants control which Routers it can use and what it can do on them. This page lists each credential and what it unlocks. It also shows how to load the administration tokens and how grants authorize agent keys. It then covers connecting an Identity Service deployed outside this chart and rotating credentials. @@ -22,10 +22,10 @@ This page lists each credential and what it unlocks. It also shows how to load t | Control-plane admin token | Operator → control plane (`:9400`) | The Secret in `controlplane.adminToken` | Yes, by default | Router administration: `/iris/v1/intent/routers` and `/iris/v1/intent/models` | | Control-plane internal token | Identity Service → control plane | The Secret in `controlplane.internalToken` | Yes, by default | Checking that the Router in a grant exists | | Identity Service control token | Operator → Identity Service (`:9200`) | The Secret in `identityService.controlToken` | Yes, by default | Creating, listing, rotating, and revoking agent keys | -| Identity Service runtime token | Data plane → Identity Service | The Secret in `identityService.runtimeToken` | Yes, by default | Checking agent keys for `intent` | +| Identity Service runtime token | Data plane → Identity Service | The Secret in `identityService.credential` / `token` | No. Register it on the Identity Service release | Checking agent keys for `intent` | | Agent key | Application → data plane (`:9401`) | None. Returned once when minted or rotated | No | Authoring and matching on the Routers its grants name | -Every token defaults to `autoGenerate: true`: without `existingSecret`, the chart creates a random Secret named `-redis-intent-router--token`, with the key `token`, keeps it across upgrades, and never rotates it. For a release named `intent`, the admin token is in `intent-redis-intent-router-controlplane-admin-token`. Set `existingSecret` to supply your own, and set the matching `existingSecretChecksum` so the pods roll when the Secret changes. Two credentials can't reference the same Secret key, and rendering fails if they do. +`controlplane.adminToken` and `controlplane.internalToken` default to `autoGenerate: true`: without `existingSecret`, the chart creates a random Secret named `-redis-intent-router-controlplane-admin-token` or `-internal-token`, with the key `token`, keeps it across upgrades, and never rotates it. For a release named `intent`, the admin token is in `intent-redis-intent-router-controlplane-admin-token`. The chart never generates `identityService.credential`. Set `existingSecret` to supply your own, and set the matching `existingSecretChecksum` so the pods roll when the Secret changes. Two credentials can't reference the same Secret key, and rendering fails if they do. An agent key gets `401` from the control plane. A key without a grant on a Router, or without the action an operation needs, gets `403` from the data plane. The data plane holds no credential for the control plane: the planes never call each other. diff --git a/content/operate/iris/intent-router/self-managed/configuration.md b/content/operate/iris/intent-router/self-managed/configuration.md index 410ddbc0d6..165208a878 100644 --- a/content/operate/iris/intent-router/self-managed/configuration.md +++ b/content/operate/iris/intent-router/self-managed/configuration.md @@ -25,9 +25,11 @@ Set these values for every install: | `storage.existingSecret` | The Secret that holds the Redis connection overlays. Required. | | `license.existingSecret` | The Secret that holds the license. Required. | | `inference.models` | The embedding model the deployment offers. Required. | -| `controlplane.image`, `dataplane.image`, `identityService.image` | An explicit `tag` for each image. The repositories default to `redislabs/iris-intent-router-control`, `redislabs/iris-intent-router-data`, and `redislabs/iris-identity-service`. | +| `controlplane.image`, `dataplane.image` | An explicit `tag` for each image. The repositories default to `redislabs/iris-intent-router-control` and `redislabs/iris-intent-router-data`. | | `controlplane.adminToken`, `controlplane.internalToken` | The control plane's tokens. | -| `identityService.controlToken`, `identityService.runtimeToken` | The Identity Service's tokens. | +| `dataplane.identityServiceBaseURL` | The URL of your Identity Service release. The data plane checks agent keys there. Required. | +| `identityService.credential` | The data plane's runtime credential, registered on the Identity Service release. Required. | +| `identityService.allowInsecureTransport` | `true` to accept an `http://` Identity Service URL. Default `false`. | A minimal values file looks like this: @@ -44,19 +46,15 @@ controlplane: existingSecret: intent-controlplane-internal dataplane: - allowInsecureIdentityService: true image: repository: redislabs/iris-intent-router-data tag: + identityServiceBaseURL: http://iris-identity-service:9200 identityService: - image: - repository: redislabs/iris-identity-service - tag: - controlToken: - existingSecret: intent-identity-control - runtimeToken: - existingSecret: intent-identity-runtime + allowInsecureTransport: true + credential: + existingSecret: intent-dp-credential license: existingSecret: intent-license @@ -74,7 +72,7 @@ inference: To let the chart generate a token instead, delete its `existingSecret` line. See [Credentials](/content/operate/iris/intent-router/self-managed/authentication.md#credentials). -The bundled Identity Service speaks plain Hypertext Transfer Protocol (HTTP) inside the cluster, and the data plane rejects an `http://` introspection URL. Rendering fails until you choose: set `dataplane.identityServiceBaseURL` to an `https://` endpoint, or set `dataplane.allowInsecureIdentityService=true` to accept cleartext introspection on the pod network. +The `identityService` block holds only `allowInsecureTransport` and `credential`. The chart deploys no Identity Service. An in-cluster Identity Service Service speaks plain Hypertext Transfer Protocol (HTTP), and the chart rejects an `http://` Identity Service URL by default. Rendering fails until you choose: set `dataplane.identityServiceBaseURL` to an `https://` endpoint, or set `identityService.allowInsecureTransport=true` to accept cleartext introspection on the pod network. The FIPS profile refuses `allowInsecureTransport`. ## Storage Secret @@ -84,7 +82,6 @@ One Secret holds a YAML overlay for each service, merged over the rendered confi | --- | --- | --- | | `intent-controlplane-storage.yaml` | `storage.controlplaneKey` | `storage.metadata.urls`: Router records. | | `intent-dataplane-storage.yaml` | `storage.dataplaneKey` | `storage.redis.urls`: intents, examples, and the per-Router vector indexes. `runtime.redis.urls`: the mailbox Redis, which is the control plane's metadata Redis. | -| `identity-service-metadata.yaml` | `storage.identityServiceKey` | `metadata.urls`: agent-key records. | `intent-controlplane-storage.yaml`: @@ -108,13 +105,7 @@ runtime: - rediss://:@:6379 ``` -`identity-service-metadata.yaml`: - -```yaml -metadata: - urls: - - rediss://:@:6379 -``` +The Identity Service's metadata Redis belongs to the Identity Service release, not to this Secret. In the mailbox Redis, the data plane reads and writes only the mailbox keys under `storage.keyPrefix`. Nothing else of the control plane's data is touched. Keep real URLs and passwords in the Secret, not in values files. @@ -129,6 +120,7 @@ embedders_connection_details: openai: base_url: https://api.openai.com/v1 credentials: + type: static api_key: ``` @@ -178,6 +170,7 @@ Tune `dataplane.search` for index recall and memory: `hnsw.m`, `hnsw.ef_construc | `controlplane.reconcile.interval` | `5s` | How often the control plane reconciles Routers with the data plane's status. | | `controlplane.reconcile.provisioningDeadline` | `10m` | How long a new Router can stay `PROVISIONING` before it fails. | | `dataplane.pollInterval` | `2s` | How often the data plane reads the mailbox for Router changes. | +| `dataplane.startupBudget` | `20s` | How long the data plane's first convergence pass can run before it opens its listener. At most `40s`, because the liveness probe restarts the pod 50 seconds after start. Routers the pass doesn't reach are picked up by later passes. | A Router change reaches the data plane within about one poll interval. @@ -187,10 +180,10 @@ Set `tls.caCertSecret` to a Secret that holds additional certificate authority ( ## FIPS and tracing -Set `security.profile: fips` to select the FIPS runtime. Rendering rejects a FIPS release without explicit HTTP Secure (HTTPS) peers: `dataplane.identityServiceBaseURL` and, with the bundled Identity Service, `identityService.controlPlaneBaseURL`. Use `rediss://` URLs in the storage Secret, including `runtime.redis.urls` and any customer databases: each service checks them when it starts and refuses to run without them. FIPS never allows cleartext Identity Service transport. +Set `security.profile: fips` to select the FIPS runtime. Rendering rejects a FIPS release unless `dataplane.identityServiceBaseURL` is an explicit HTTP Secure (HTTPS) endpoint, and refuses `identityService.allowInsecureTransport`. Set the FIPS profile and an `https://` grant-validation URL on the Identity Service release too. Use `rediss://` URLs in the storage Secret, including `runtime.redis.urls` and any customer databases. Rendering can't check them, because they live in the Secret, and the data plane refuses to start in the FIPS profile if any of them isn't `rediss://`. Set `tracing.enabled` and `tracing.otlpGRPCEndpoint` to send spans to your OpenTelemetry collector over the OpenTelemetry Protocol (OTLP). The exporter uses plaintext gRPC, so use a trusted local hop. ## Scale and schedule the planes -The control plane, data plane, and Identity Service scale independently. Set `replicaCount`, `resources`, `nodeSelector`, `tolerations`, and `affinity` for each in the chart values. The data plane carries the matching load, so scale it first. +The control plane and data plane scale independently. Set `replicaCount`, `resources`, `nodeSelector`, `tolerations`, and `affinity` for each in the chart values. Scale the Identity Service in its own release. The data plane carries the matching load, so scale it first. diff --git a/content/operate/iris/intent-router/self-managed/deploy.md b/content/operate/iris/intent-router/self-managed/deploy.md index eb7b2cd2c3..0ad0a83017 100644 --- a/content/operate/iris/intent-router/self-managed/deploy.md +++ b/content/operate/iris/intent-router/self-managed/deploy.md @@ -11,7 +11,7 @@ weight: 50 hideListLinks: true --- -Follow these steps to install the Intent Router control plane, data plane, and Identity Service with the `redis-intent-router` Helm chart, and end with one authenticated match request. +Follow these steps to install the Intent Router control plane and data plane with the `redis-intent-router` Helm chart, connect them to your Identity Service release, and end with one authenticated match request. You use three credentials along the way: the control-plane admin token, the Identity Service control token, and an agent key. For what each credential unlocks, see [Credentials](/content/operate/iris/intent-router/self-managed/authentication.md#credentials). @@ -25,31 +25,45 @@ kubectl create namespace ## 2. Create Secrets +### Configure the Identity Service release first + +The chart deploys no Identity Service. Set these values on your Identity Service release so that it checks Router grants and accepts the data plane's runtime credential. The examples assume this chart is installed as release `intent` in the same namespace as an Identity Service release named `iris-identity-service`. + +| Identity Service value | Setting | +| --- | --- | +| `runtime.serviceCredentials[]` | An entry with `name: intent-dp`, `subject: intent-dp`, `allowedOperations: [api-key-introspect]`, `allowedProducts: [intent]`, and the same `existingSecret` and `secretKey` as `identityService.credential`. | +| `productValidation.products.intent.enabled` | `true` | +| `productValidation.products.intent.baseURL` | The control-plane Service, `http://intent-redis-intent-router-controlplane:9400`. | +| `productValidation.products.intent.credential` | The same Secret and key as `controlplane.internalToken`. | +| `runtime.apiKeyTenant.singleTenantID` | The same value as `tenantId`. | + +Neither chart checks these values against the other. If the Identity Service release also serves other Iris products, add these entries to its existing lists. All products use the one tenant. + ### Create the connection files -Save the three Redis connections as `intent-controlplane-storage.yaml`, `intent-dataplane-storage.yaml`, and `identity-service-metadata.yaml`, as shown in [Storage Secret](/content/operate/iris/intent-router/self-managed/configuration.md#storage-secret). The file names become the Secret's keys. +Save the two Redis connections as `intent-controlplane-storage.yaml` and `intent-dataplane-storage.yaml`, as shown in [Storage Secret](/content/operate/iris/intent-router/self-managed/configuration.md#storage-secret). The file names become the Secret's keys. ### Create the Secrets -Generate four distinct tokens, then create the Secrets: +Generate three distinct tokens, then create the Secrets: ```bash umask 077 -for token in admin-token internal-token identity-control-token identity-runtime-token; do +for token in admin-token internal-token dp-credential; do openssl rand -base64 32 > "$token" done kubectl -n create secret generic intent-storage \ --from-file=intent-controlplane-storage.yaml \ - --from-file=intent-dataplane-storage.yaml \ - --from-file=identity-service-metadata.yaml + --from-file=intent-dataplane-storage.yaml kubectl -n create secret generic intent-license --from-file=license=./license kubectl -n create secret generic intent-controlplane-admin --from-file=token=./admin-token kubectl -n create secret generic intent-controlplane-internal --from-file=token=./internal-token -kubectl -n create secret generic intent-identity-control --from-file=token=./identity-control-token -kubectl -n create secret generic intent-identity-runtime --from-file=token=./identity-runtime-token +kubectl -n create secret generic intent-dp-credential --from-file=token=./dp-credential ``` -To let the chart generate a token instead, skip its Secret and delete its `existingSecret` line from the values file. The chart keeps a generated token across upgrades and never rotates it. +The Identity Service release mounts `intent-controlplane-internal` and `intent-dp-credential` too, so create them in its namespace as well if it runs in another one. + +To let the chart generate the admin or internal token instead, skip its Secret and delete its `existingSecret` line from the values file. The chart keeps a generated token across upgrades and never rotates it. The chart never generates `intent-dp-credential`. For an embedding provider other than `noop`, also create the inference Secret, as shown in [Embedding models](/content/operate/iris/intent-router/self-managed/configuration.md#embedding-models). @@ -65,9 +79,10 @@ Check each value before you install. If one is wrong, you see the symptom in its | Check | Symptom | Fix | | --- | --- | --- | | `tenantId` is set | Rendering fails with a named message | Set the tenant. | -| Each image has a `repository` and a `tag` | Rendering fails, or pods `ImagePullBackOff` | Set both for all three images. | -| The four tokens come from four different Secrets or keys | Rendering fails | Create four distinct token files. | -| `dataplane.identityServiceBaseURL` is `https://`, or `allowInsecureIdentityService` is `true` | Rendering fails | Choose one. | +| Each image has a `tag` | Rendering fails, or pods `ImagePullBackOff` | Set `controlplane.image.tag` and `dataplane.image.tag`. | +| The admin token, internal token, and Identity Service credential come from three different Secrets or keys | Rendering fails | Create three distinct token files. | +| `dataplane.identityServiceBaseURL` is `https://`, or `identityService.allowInsecureTransport` is `true` | Rendering fails | Choose one. | +| `tenantId` equals the Identity Service's `runtime.apiKeyTenant.singleTenantID` | Minting an agent key for a Router fails | Set both to the same tenant. | | `inference.models` lists one model, and `noop` only with `inference.allowLocalModels=true` | Rendering fails | List the one model the deployment offers. | | The inference Secret has an `embedders_connection_details` entry named after the model's `provider` | A new Router stays `PROVISIONING` or fails | Add the entry under that provider name. | | The data-plane Redis has Search | A new Router is `FAILED` and `failureReason` mentions vector search | Use a Redis 8 build that includes Search, or load the Search and Query engine. | @@ -92,7 +107,6 @@ To add `helm test` pods that probe each service and run the shared security-prof ```bash kubectl -n rollout status deployment/intent-redis-intent-router-controlplane kubectl -n rollout status deployment/intent-redis-intent-router-dataplane -kubectl -n rollout status deployment/intent-redis-intent-router-identity-service ``` Run each port-forward in its own terminal and leave it running: @@ -106,7 +120,7 @@ kubectl -n port-forward svc/intent-redis-intent-router-dataplan ``` ```bash -kubectl -n port-forward svc/intent-redis-intent-router-identity-service 9200:9200 +kubectl -n port-forward svc/iris-identity-service 9200:9200 ``` Then check readiness on every service: diff --git a/content/operate/iris/intent-router/self-managed/prerequisites.md b/content/operate/iris/intent-router/self-managed/prerequisites.md index 0f1e894317..73ef69692f 100644 --- a/content/operate/iris/intent-router/self-managed/prerequisites.md +++ b/content/operate/iris/intent-router/self-managed/prerequisites.md @@ -16,10 +16,11 @@ Self-managed Intent Router runs on your Kubernetes cluster and depends on Redis ## What you need - A Kubernetes cluster and a namespace for the release. -- Two Redis databases, kept separate: one for Router records and one for intents and examples. The Identity Service's agent-key records can share the first. +- Two physically separate Redis deployments: one for Router records and one for intents and examples. The services reject aliased endpoints. +- An Identity Service release, installed separately, that knows the `intent` product. - An embedding provider. The `noop` provider is for development only. - A license, delivered by Redis. -- Image repositories and tags for the control plane, data plane, and Identity Service images. +- Image tags for the control-plane and data-plane images. ## Required software @@ -38,7 +39,7 @@ The chart creates no Redis databases. Create them first. | --- | --- | --- | | Metadata Redis | Router records, and the mailbox the planes coordinate through. | Persistence. Needs no Search. | | Data-plane Redis | Intents, examples, and one vector index for each Router. | The Search and Query engine (RediSearch 2.4.3 or later): a Redis 8 build that includes it, such as the official `redis:8` image, or a database with the module loaded. | -| Identity Service metadata | Agent-key records. | Persistence. It can share the metadata Redis. | +| Identity Service metadata | Agent-key records. Configured on the Identity Service release, not in this chart. | Persistence. It can share the metadata Redis deployment, with its own least-privileged Redis user. | Without Search, the data plane's `vectorSearch` readiness check fails and a new Router is `FAILED` with a reason that says so. Where the platform allows it, set `search-on-timeout` to `FAIL` on the data-plane Redis. The default, `RETURN`, lets a search that hits the server timeout return partial results. @@ -73,7 +74,7 @@ The chart ships `networkpolicy.reference.yaml`, a default-deny starting point. R ## Credentials and Secrets -Create these Secrets before you install: the storage Secret that holds the Redis URLs, the license Secret, and an inference Secret when you use a provider other than `noop`. The four tokens can be generated by the chart or supplied by you. See [Authentication and authorization](/content/operate/iris/intent-router/self-managed/authentication.md#credentials). +Create these Secrets before you install: the storage Secret that holds the Redis URLs, the license Secret, the data plane's Identity Service credential, and an inference Secret when you use a provider other than `noop`. The chart can generate the control-plane admin and internal tokens, or you can supply them. It never generates the data plane's Identity Service credential: you create it and register it on the Identity Service release. See [Authentication and authorization](/content/operate/iris/intent-router/self-managed/authentication.md#credentials). ## Release artifacts and image tags @@ -83,10 +84,10 @@ The chart requires an explicit `tag` for each image. Rendering fails with a name Rendering fails with a named message when: -- `tenantId`, `storage.existingSecret`, `license.existingSecret`, or an image tag is missing. +- `tenantId`, `storage.existingSecret`, `license.existingSecret`, `dataplane.identityServiceBaseURL`, `identityService.credential.existingSecret`, or an image tag is missing. - `inference.models` doesn't list exactly one model, or lists `noop` without `inference.allowLocalModels=true`. - `inference.existingSecret` is missing for a provider other than `noop`. -- Two tokens reference the same Secret key. -- `dataplane.identityServiceBaseURL` isn't `https://` and `dataplane.allowInsecureIdentityService` isn't `true`. +- Two of the admin token, the internal token, and the Identity Service credential reference the same Secret key. +- `dataplane.identityServiceBaseURL` isn't `https://` and `identityService.allowInsecureTransport` isn't `true`. See [Configuration](/content/operate/iris/intent-router/self-managed/configuration.md). diff --git a/content/operate/iris/intent-router/self-managed/reference.md b/content/operate/iris/intent-router/self-managed/reference.md index 527f668741..59531881e2 100644 --- a/content/operate/iris/intent-router/self-managed/reference.md +++ b/content/operate/iris/intent-router/self-managed/reference.md @@ -23,15 +23,16 @@ This page is a lookup reference for self-managed Intent Router. It lists the mai | `storage.keyPrefix` | `iris:intent` | The Redis key prefix both planes derive their keys from. | | `storage.maxRoutersPerTenant` | `128` | Routers the tenant can hold. | | `controlplane.reconcile.provisioningDeadline` | `10m` | How long a Router can stay `PROVISIONING` before it fails. | -| `identityService.runtimeCache.hardTTLSeconds` | `300` | The longest a revoked agent key keeps working. | | `license.existingSecret` | None | The Secret with the license. Required. | | `inference.models` | None | The deployment's embedding model. Required. | | `inference.existingSecret` | None | The Secret with `embedders_connection_details` under the key `inference.yaml`. | | `inference.allowLocalModels` | `false` | Allow the development-only `noop` provider. | -| `identityService.enabled` | `true` | Deploy the bundled Identity Service. | | `controlplane.requireDatabase` | `false` | Require every Router to name a customer database. | -| `dataplane.allowInsecureIdentityService` | `false` | Accept an `http://` Identity Service URL. | -| `dataplane.identityServiceBaseURL` | None | An `https://` Identity Service endpoint. | +| `controlplane.image.tag`, `dataplane.image.tag` | None | The image tags. Required. | +| `dataplane.identityServiceBaseURL` | None | The URL of your Identity Service release. Required. Must be `https://` unless `identityService.allowInsecureTransport` is `true`. | +| `identityService.allowInsecureTransport` | `false` | Accept an `http://` Identity Service URL. Refused in the FIPS profile. | +| `identityService.credential.existingSecret` | None | The Secret with the data plane's runtime credential, under the key `token`. Required. | +| `dataplane.startupBudget` | `20s` | How long the data plane's first convergence pass can run. At most `40s`. | | `tests.enabled` | `false` | Add `helm test` pods. | | `tracing.enabled` | `false` | Send spans to an OpenTelemetry collector. | From 72c6c47c0ac4ef953d38804f6e6bb03c6f8729e4 Mon Sep 17 00:00:00 2001 From: Robert Shelton Date: Tue, 3 Nov 2026 09:47:51 -0500 Subject: [PATCH 2/2] Update content/operate/iris/intent-router/self-managed/prerequisites.md Co-authored-by: mich-elle-luna <153109578+mich-elle-luna@users.noreply.github.com> --- .../operate/iris/intent-router/self-managed/prerequisites.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/operate/iris/intent-router/self-managed/prerequisites.md b/content/operate/iris/intent-router/self-managed/prerequisites.md index 73ef69692f..4fb261fdf9 100644 --- a/content/operate/iris/intent-router/self-managed/prerequisites.md +++ b/content/operate/iris/intent-router/self-managed/prerequisites.md @@ -87,7 +87,7 @@ Rendering fails with a named message when: - `tenantId`, `storage.existingSecret`, `license.existingSecret`, `dataplane.identityServiceBaseURL`, `identityService.credential.existingSecret`, or an image tag is missing. - `inference.models` doesn't list exactly one model, or lists `noop` without `inference.allowLocalModels=true`. - `inference.existingSecret` is missing for a provider other than `noop`. -- Two of the admin token, the internal token, and the Identity Service credential reference the same Secret key. +- Two of the admin tokens, the internal token, and the Identity Service credential reference the same Secret key. - `dataplane.identityServiceBaseURL` isn't `https://` and `identityService.allowInsecureTransport` isn't `true`. See [Configuration](/content/operate/iris/intent-router/self-managed/configuration.md).