From 6f63ac4f9148ef1fc75866cbe54bf502568ae9d0 Mon Sep 17 00:00:00 2001 From: Ivo Bardarov Date: Thu, 15 Oct 2026 12:03:45 +0300 Subject: [PATCH 1/4] docs(iris): MOD-19813 Agent Memory self-managed docs for the iris-identity-service subchart --- .../iris/agent-memory/self-managed/_index.md | 8 ++- .../self-managed/authentication.md | 4 +- .../self-managed/configuration.md | 10 +-- .../iris/agent-memory/self-managed/deploy.md | 24 ++++--- .../agent-memory/self-managed/operations.md | 49 +++++++++++--- .../self-managed/prerequisites.md | 67 +++++++++++-------- .../agent-memory/self-managed/reference.md | 11 ++- 7 files changed, 117 insertions(+), 56 deletions(-) diff --git a/content/operate/iris/agent-memory/self-managed/_index.md b/content/operate/iris/agent-memory/self-managed/_index.md index 1801e918eb..d7dac7eab8 100644 --- a/content/operate/iris/agent-memory/self-managed/_index.md +++ b/content/operate/iris/agent-memory/self-managed/_index.md @@ -31,15 +31,17 @@ documents the self-managed admin endpoints for stores. ## What you are deploying -The chart always deploys the Data Plane, the workers, the Control Plane, and the Identity Service. -You provide the Redis databases. +The chart deploys the Data Plane, the workers, and the Control Plane, and bundles the Identity +Service by default. You provide the Redis databases. To point the Data Plane at an Identity +Service the chart does not install, see the `identityService.enabled=false` entries in +[Helm values to review](/content/operate/iris/agent-memory/self-managed/prerequisites.md#helm-values-to-review). | Component | Purpose | Default service | | --- | --- | --- | | Redis Agent Memory Data Plane | Store-scoped runtime memory API. | `redis-agent-memory:9000` | | Redis Agent Memory worker | Background promotion, summarization, and forgetting work. | No public service | | Redis Agent Memory Control Plane | Admin API for creating and managing stores. | `redis-agent-memory-controlplane:9100` | -| Identity Service | Mints, rotates, revokes, and checks agent keys. | `redis-agent-memory-identity-service:9200` | +| Identity Service (bundled) | Mints, rotates, revokes, and checks agent keys. | `redis-agent-memory-iris-identity-service:9200` | | Store Redis | Holds session memory, long-term memory, indexes, and TTL data. | Customer-provided | | Job Redis | Holds background work for Redis Agent Memory workers. | Customer-provided | | Metadata Redis | Holds Control Plane store records. The Identity Service keeps agent-key records in the Metadata Redis named in its own metadata Secret. | Customer-provided | diff --git a/content/operate/iris/agent-memory/self-managed/authentication.md b/content/operate/iris/agent-memory/self-managed/authentication.md index a9431450c0..72a67e0365 100644 --- a/content/operate/iris/agent-memory/self-managed/authentication.md +++ b/content/operate/iris/agent-memory/self-managed/authentication.md @@ -26,8 +26,8 @@ grants. | --- | --- | --- | --- | --- | | Control Plane admin token | Operator → Control Plane (`:9100`) | `redis-agent-memory-controlplane-admin-token` / `token` | Yes (`controlplane.adminToken.autoGenerate`) | Store management: `/v1/stores`, `/v1/detectors` | | Control Plane internal token | Identity Service → Control Plane | `redis-agent-memory-controlplane-internal-token` / `token` | Yes (`controlplane.internalToken.autoGenerate`) | Checking that the store in a grant exists. Chart-managed; you handle it only with bring-your-own (BYO) configuration | -| Identity Service control token | Operator → Identity Service (`:9200`) | `redis-agent-memory-identity-service-control-token` / `token` | Yes (`identityService.controlToken.autoGenerate`) | Creating, listing, updating, rotating and revoking agent keys | -| Data Plane service credential | Data Plane → Identity Service | `redis-agent-memory-identity-service-runtime-memory-dp` / `token` | Yes (`identityService.runtime.serviceCredentials`) | Checking agent keys for `memory`. Chart-managed; you handle it only with bring-your-own (BYO) configuration | +| Identity Service control token | Operator → Identity Service (`:9200`) | `redis-agent-memory-iris-identity-service-control-token` / `token` | Yes (`identityService.control.autoGenerate`) | Creating, listing, updating, rotating and revoking agent keys | +| Data Plane service credential | Data Plane → Identity Service | `redis-agent-memory-iris-identity-service-runtime-memory-dp` / `token` | Yes (`identityService.runtime.serviceCredentials`) | Checking agent keys for `memory`. Chart-managed; you handle it only with bring-your-own (BYO) configuration | | Agent key | Application → Data Plane (`:9000`) | None; returned once when minted or rotated | No | The Data Plane operations its grants allow | Each generated Secret keeps its value across upgrades (`helm.sh/resource-policy: keep`). To bring diff --git a/content/operate/iris/agent-memory/self-managed/configuration.md b/content/operate/iris/agent-memory/self-managed/configuration.md index 4daff23f61..cdebd5f8b2 100644 --- a/content/operate/iris/agent-memory/self-managed/configuration.md +++ b/content/operate/iris/agent-memory/self-managed/configuration.md @@ -28,7 +28,7 @@ To supply complete configuration files in your own Secrets instead, see | `shared` | Settings common to the Data Plane and the Control Plane, such as `databases`. The chart merges them under `memory` and `controlplane.configData`. | | `memory` | The Data Plane and worker configuration file. | | `controlplane.configData` | The Control Plane configuration file. | -| `identityService.*` | The Identity Service. `identityService.metadata.existingSecret` names the Secret with its Metadata Redis URL. | +| `identityService.*` | The bundled Identity Service, from the published `iris-identity-service` chart; every key is that chart's values contract. `identityService.metadata.existingSecret` names the Secret with its Metadata Redis URL, and extra service configuration goes in `identityService.configData`. | | Overlay Secret (`secrets.secretName`, key `overlay.yaml`) | `metadata.urls`, `metadata.namespace`, `databases."1".urls`, `background_jobs.redis.urls`, and provider `api_key` values. The Data Plane, the workers, and the Control Plane all read it. | ## Data Plane settings @@ -53,8 +53,10 @@ Data Plane settings go under `memory`, or at the top level of a BYO Data Plane c An `llm` block names its provider with `llm.provider`, which must match an `inference_providers` entry. The endpoint goes in `inference_providers..endpoint`, not in the `llm` block. -In the chart-rendered configuration, the chart writes the agent-key introspection settings for you. -Leave `auth.method` unset to keep the `agent_key` default. +In the chart-rendered configuration, the chart writes the agent-key introspection settings for you: +it owns `auth.agent_keys.introspection.base_url`, `credential`, and `allow_insecure_transport`, and +refuses hand-set values. Set `dataplane.identityServiceBaseURL` to point at a non-default Identity +Service endpoint. Leave `auth.method` unset to keep the `agent_key` default. ## Bring-your-own (BYO) configuration @@ -106,7 +108,7 @@ databases: auth: agent_keys: introspection: - base_url: http://redis-agent-memory-identity-service:9200 + base_url: http://redis-agent-memory-iris-identity-service:9200 allow_insecure_transport: true product: memory credential: diff --git a/content/operate/iris/agent-memory/self-managed/deploy.md b/content/operate/iris/agent-memory/self-managed/deploy.md index da6029a575..b1ef473773 100644 --- a/content/operate/iris/agent-memory/self-managed/deploy.md +++ b/content/operate/iris/agent-memory/self-managed/deploy.md @@ -83,7 +83,7 @@ chart's defaults disagree here: the Data Plane defaults to `agent_key` authentic `workerAuth.enabled` defaults to `false`. With `agent_key`, you must configure worker identity. The values in [step 3](#3-create-ram-valuesyaml) do this. -In version 0.7.0, the Data Plane fetches the JWKS without credentials and trusts only the +The Data Plane fetches the JWKS without credentials and trusts only the certificate authority (CA) bundle in its image. What you set up depends on where the cluster's issuer is served: @@ -118,7 +118,7 @@ kubectl create clusterrolebinding redis-agent-memory-oidc-discovery \ This binding grants only `get` on `/.well-known/openid-configuration` and `/openid/v1/jwks`, which serve issuer metadata and public signing keys, not secrets. It applies to unauthenticated callers across the whole cluster. It has no effect where the API server disables anonymous authentication. -On those clusters, version 0.7.0 has no working setup for `agent_key` with workers. +On those clusters, there is no working setup for `agent_key` with workers. ## 3. Create `ram-values.yaml` @@ -197,7 +197,11 @@ memory: enabled: false session_summary_view: enabled: false +image: + tag: controlplane: + image: + tag: config: render: true configData: @@ -228,7 +232,9 @@ tls: - `tls.caCertSecret` names the CA Secret from [step 2](#prepare-worker-identity-for-your-platform). Remove it on EKS and AKS. - The chart writes the agent-key introspection settings and the Control Plane internal token for you. -- Image tags are not set, so the chart defaults (`0.7.0`) apply. +- `` is the Redis Agent Memory version you deploy. `image.tag` and + `controlplane.image.tag` are required; the chart has no default. The bundled Identity Service + takes its image tag from the pinned chart, so it needs none. {{< note >}} No external model provider? To try the API with local models, see [Evaluate locally](#evaluate-locally). @@ -246,7 +252,7 @@ its row. The rows are checklist items CL-1 to CL-6. | CL-2 | `memory.promote_session_memory.strategies.instruct.llm` is set | Worker pods `CrashLoopBackOff` (server stays Ready); log: `promote_session_memory: Strategies: strategies.instruct.llm is required.` | Add the `instruct.llm` block | | CL-3 | Each `llm.provider` names an `inference_providers` entry | Server and worker pods `CrashLoopBackOff`; log: `panic: config validation failed: promote_session_memory.strategies.instruct.llm: provider "" is not defined in inference_providers (defined: )` | Add `memory.inference_providers.` or fix the name | | CL-4 | `memory.dataplane_client.base_url` is `http://redis-agent-memory:9000` | Pods Ready, but no memories appear; worker log: `getting session memory: Get "http://:9000/v1/stores//session-memory/..."` … `dial tcp: lookup ` (the rest depends on the cluster DNS) | Set `http://redis-agent-memory:9000` | -| CL-5 | No image tag is set, or it exists on Docker Hub | Server and worker pods `ImagePullBackOff`; event: `Failed to pull image "redislabs/agent-memory:": … not found` | Remove `*.image.tag` (defaults `0.7.0`) | +| CL-5 | `image.tag` and `controlplane.image.tag` are set, and each tag exists on Docker Hub | `helm install` fails with `image.tag is required and must be set explicitly to the RAM version being deployed`; or server and worker pods `ImagePullBackOff`, event: `Failed to pull image "redislabs/agent-memory:": … not found` | Set both tags to the Redis Agent Memory version you deploy | | CL-6 | `auth.worker_identity` matches the worker (issuer, audience, subject with your namespace) | Pods Ready, but no memories appear; worker log: `memory-dataplane API error: status 401`; the Data Plane logs `401` on `GET /v1/stores//session-memory/` with no reason | Fix `issuer` from `/.well-known/openid-configuration` and the namespace in `subject`. The same symptom appears when the Data Plane cannot fetch the cluster JWKS, so also check [worker identity for your platform](#prepare-worker-identity-for-your-platform) | {{< /table-scrollable >}} @@ -256,7 +262,7 @@ its row. The rows are checklist items CL-1 to CL-6. helm repo add redis-ai https://helm.redis.io/ai helm repo update redis-ai helm install redis-agent-memory redis-ai/redis-agent-memory \ - --version 0.7.0 \ + --version 1.0.0 \ --namespace \ -f ram-values.yaml kubectl -n get pods -w @@ -268,7 +274,7 @@ If you want Helm to wait, set an explicit timeout that matches the environment: ```bash helm install redis-agent-memory redis-ai/redis-agent-memory \ - --version 0.7.0 \ + --version 1.0.0 \ --namespace \ -f ram-values.yaml \ --wait \ @@ -281,7 +287,7 @@ helm install redis-agent-memory redis-ai/redis-agent-memory \ kubectl -n get pods -l app.kubernetes.io/name=redis-agent-memory ``` -The server, worker, `redis-agent-memory-controlplane`, and `redis-agent-memory-identity-service` +The server, worker, `redis-agent-memory-controlplane`, and `redis-agent-memory-iris-identity-service` pods are Ready. Run each `port-forward` in this guide in its own terminal. Port-forward the Data Plane and check its @@ -319,9 +325,9 @@ The response carries `storeId`. Use the Identity Service control token: ```bash -kubectl -n port-forward svc/redis-agent-memory-identity-service 9200:9200 +kubectl -n port-forward svc/redis-agent-memory-iris-identity-service 9200:9200 IDS_CONTROL_TOKEN=$(kubectl -n get secret \ - redis-agent-memory-identity-service-control-token -o jsonpath='{.data.token}' | base64 -d) + redis-agent-memory-iris-identity-service-control-token -o jsonpath='{.data.token}' | base64 -d) curl -sS -X POST http://localhost:9200/v1/api-keys \ -H "Authorization: Bearer $IDS_CONTROL_TOKEN" \ -H "Content-Type: application/json" \ diff --git a/content/operate/iris/agent-memory/self-managed/operations.md b/content/operate/iris/agent-memory/self-managed/operations.md index 4b382cd4f0..1e15bca9de 100644 --- a/content/operate/iris/agent-memory/self-managed/operations.md +++ b/content/operate/iris/agent-memory/self-managed/operations.md @@ -185,24 +185,52 @@ environments where the in-cluster test path is allowed. ## FIPS-oriented posture -The chart supports an opt-in FIPS-oriented posture for regulated environments: +The chart supports an opt-in FIPS-oriented posture for regulated environments. +Set it through `global.security.profile`, which the chart and the bundled Identity Service both +read. The chart's local `security.profile` does not reach the Identity Service, and the chart +refuses a FIPS Redis Agent Memory with a non-FIPS bundled Identity Service: ```yaml -security: - profile: fips +global: + security: + profile: fips ``` +Enabling the posture also takes two `https://` endpoints. The chart's in-cluster defaults for +both are plaintext `http://`, and the posture refuses them: + +```yaml +dataplane: + # Data Plane to Identity Service agent-key introspection. + identityServiceBaseURL: https:// +identityService: + productValidation: + products: + memory: + # Identity Service to Control Plane grant validation. + baseURL: https:// +``` + +The chart doesn't terminate Transport Layer Security (TLS) for either endpoint. Your hosting +environment must provide both, for example with a service mesh, ingress, or TLS-terminating +proxy in front of the Identity Service and Control Plane Services. The calling pods must trust +both certificates; the Data Plane trusts `tls.caCertSecret` (or `global.tls.caCertSecret`) on +top of the system CAs. + You can also apply the bundled FIPS values overlay with the normal values file. -Download the chart to get `values-fips.yaml` from the chart root: +Download the chart to get `values-fips.yaml` from the chart root, and set the two endpoints in +`ram-values.yaml` or on the command line: ```bash -helm pull redis-ai/redis-agent-memory --version 0.7.0 --untar +helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar helm upgrade --install redis-agent-memory redis-ai/redis-agent-memory \ --version \ --namespace \ -f ram-values.yaml \ - -f redis-agent-memory/values-fips.yaml + -f redis-agent-memory/values-fips.yaml \ + --set dataplane.identityServiceBaseURL=https:// \ + --set identityService.productValidation.products.memory.baseURL=https:// ``` When enabled, the chart sets `GODEBUG=fips140=on` on the Data Plane, worker, @@ -215,12 +243,17 @@ customer's compliance boundary. When the posture is active, the Data Plane and worker reject config that: -- enables `skip_verify` on outbound HTTP clients; or +- enables `skip_verify` on outbound HTTP clients; +- sets `allow_insecure_transport` on any authentication block, even a disabled one; or - uses non-`rediss://` URLs for Redis connections covered by the posture. The Control Plane runs under the same posture and rejects non-`rediss://` `metadata.urls` or `databases."1".urls`. +The Identity Service sends the Control Plane internal token on every grant validation. Under +the posture it refuses to start unless each product validator URL uses `https://`, and the +chart refuses to render one that doesn't. + The Redis Agent Memory API listener itself speaks HTTP inside the cluster. Edge TLS termination is owned by the hosting environment, such as ingress, service mesh, or external load balancer. Outbound TLS to Redis, embedding providers, LLM providers, and @@ -247,7 +280,7 @@ the direct caller also has a valid Redis Agent Memory credential. The chart includes `networkpolicy.reference.yaml` at the chart root as a reference manifest. Get it with -`helm pull redis-ai/redis-agent-memory --version 0.7.0 --untar`. It is not templated because allowed callers are +`helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar`. It is not templated because allowed callers are environment-specific. Customize the placeholders before applying it: diff --git a/content/operate/iris/agent-memory/self-managed/prerequisites.md b/content/operate/iris/agent-memory/self-managed/prerequisites.md index 8928d190db..f6108ff098 100644 --- a/content/operate/iris/agent-memory/self-managed/prerequisites.md +++ b/content/operate/iris/agent-memory/self-managed/prerequisites.md @@ -115,15 +115,18 @@ To supply a complete configuration file in your own Secret instead, see ## Release artifacts and image tags -Chart `0.7.0` defaults every image tag to `0.7.0`. Set an image tag only to pin a mirrored image. +Chart `1.0.0` requires `image.tag` and `controlplane.image.tag` at install or upgrade time; set +each to the Redis Agent Memory version you deploy. The bundled Identity Service needs no tag of +its own: it runs the image version the pinned `iris-identity-service` chart carries. Set +`identityService.image.*` only to mirror the image or pin another tag. Use the chart version supplied by Redis for the release. The published chart is `redis-ai/redis-agent-memory` from `https://helm.redis.io/ai`. Standard customer installs use the public Docker Hub images published by the -Redis Agent Memory self-managed release: `docker.io/redislabs/agent-memory:0.7.0`, -`docker.io/redislabs/agent-memory-control-plane:0.7.0`, and -`docker.io/redislabs/iris-identity-service:0.7.0`. +Redis Agent Memory self-managed release: `docker.io/redislabs/agent-memory:` and +`docker.io/redislabs/agent-memory-control-plane:`, plus +`docker.io/redislabs/iris-identity-service` at the version the pinned chart carries. ## Air-gapped and private registry installs @@ -131,28 +134,33 @@ Mirror these images into your internal registry: | Image | Needed | | --- | --- | -| `redislabs/agent-memory:0.7.0` | Always (Data Plane and workers) | -| `redislabs/agent-memory-control-plane:0.7.0` | Always | -| `redislabs/iris-identity-service:0.7.0` | Always | +| `redislabs/agent-memory:` | Always (Data Plane and workers) | +| `redislabs/agent-memory-control-plane:` | Always | +| `redislabs/iris-identity-service:` | With the bundled Identity Service (the default); skip only with `identityService.enabled=false` | | `replicated/troubleshoot:0.131.0` | Support-bundle health checks, on by default (`supportPackage.*`) | | `hibiken/asynqmon:0.7.2` | Optional, with `controlplane.queueMonitor` | | `python:3.13-alpine` | Optional, with `tests.smoke` | +`` is the `appVersion` of the `iris-identity-service` chart the Redis Agent Memory +chart pins. Read it with +`helm show chart redis-ai/redis-agent-memory --version ` and +`helm show chart redis-ai/iris-identity-service --version `. + ```bash -docker pull redislabs/agent-memory:0.7.0 -docker tag redislabs/agent-memory:0.7.0 \ - registry.example.com/redislabs/agent-memory:0.7.0 -docker push registry.example.com/redislabs/agent-memory:0.7.0 - -docker pull redislabs/agent-memory-control-plane:0.7.0 -docker tag redislabs/agent-memory-control-plane:0.7.0 \ - registry.example.com/redislabs/agent-memory-control-plane:0.7.0 -docker push registry.example.com/redislabs/agent-memory-control-plane:0.7.0 - -docker pull redislabs/iris-identity-service:0.7.0 -docker tag redislabs/iris-identity-service:0.7.0 \ - registry.example.com/redislabs/iris-identity-service:0.7.0 -docker push registry.example.com/redislabs/iris-identity-service:0.7.0 +docker pull redislabs/agent-memory: +docker tag redislabs/agent-memory: \ + registry.example.com/redislabs/agent-memory: +docker push registry.example.com/redislabs/agent-memory: + +docker pull redislabs/agent-memory-control-plane: +docker tag redislabs/agent-memory-control-plane: \ + registry.example.com/redislabs/agent-memory-control-plane: +docker push registry.example.com/redislabs/agent-memory-control-plane: + +docker pull redislabs/iris-identity-service: +docker tag redislabs/iris-identity-service: \ + registry.example.com/redislabs/iris-identity-service: +docker push registry.example.com/redislabs/iris-identity-service: ``` If the registry requires authentication, create an image pull Secret: @@ -178,12 +186,15 @@ identityService: image: repository: registry.example.com/redislabs/iris-identity-service -imagePullSecrets: - - name: ram-registry +global: + imagePullSecrets: + - name: ram-registry ``` -Omit `imagePullSecrets` if the internal registry does not require -authentication. +Use `global.imagePullSecrets`, which the chart and the bundled Identity Service both read; the +local `imagePullSecrets` reaches only the Redis Agent Memory pods, and the chart refuses it when +the Identity Service image is mirrored. Omit pull Secrets if the internal registry does not +require authentication. For air-gapped deployments, also set: @@ -257,8 +268,10 @@ namespace. | Secret rollouts | `license.existingSecretChecksum`, `config.existingSecretChecksum`, `controlplane.config.existingSecretChecksum` | Rolling pods after externally managed Secret changes. | | Control Plane | `controlplane.image.*`, `controlplane.configData`, `controlplane.adminToken.*` | Mirroring the Control Plane image, setting its configuration, or bringing your own admin token. | | Control Plane internal token | `controlplane.internalToken.*` | Bringing your own token for Identity Service checks against the Control Plane. | -| Identity Service | `identityService.*` | Mirroring the Identity Service image, naming its metadata Secret, or bringing your own control token. | -| Security profile | `security.profile` | Selecting the [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | +| Identity Service (bundled) | `identityService.*` | The published `iris-identity-service` subchart's contract: naming its metadata Secret, mirroring its image, bringing your own control token (`identityService.control.*`), or adding service configuration (`identityService.configData`). | +| External Identity Service | `identityService.enabled=false`, `dataplane.identityServiceBaseURL`, `externalIdentityService.*` | Installing no Identity Service objects and pointing the Data Plane at one you run elsewhere. | +| Umbrella fallbacks | `global.*` | Sharing `security.profile`, `imagePullSecrets`, and `tls.caCertSecret` with the bundled Identity Service; the chart's own `security.profile`, `imagePullSecrets`, and `tls.caCertSecret` do not reach it. | +| Security profile | `global.security.profile` | Selecting the [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture) for Redis Agent Memory and the bundled Identity Service. | | Support bundles | `supportPackage.*` | Configuring support-bundle collection and its health checks. | | Preflight checks | `preflight.*` | Rendering the preflight checks spec as a ConfigMap. | | Helm tests | `tests.*` | Running [chart tests](/content/operate/iris/agent-memory/self-managed/operations.md#chart-tests) with `helm test`. | diff --git a/content/operate/iris/agent-memory/self-managed/reference.md b/content/operate/iris/agent-memory/self-managed/reference.md index 0f1bf4970b..2b1363607e 100644 --- a/content/operate/iris/agent-memory/self-managed/reference.md +++ b/content/operate/iris/agent-memory/self-managed/reference.md @@ -46,19 +46,24 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Symptom | Likely cause | Fix | | --- | --- | --- | | `helm search repo redis-ai/redis-agent-memory --versions` returns no results | Helm repo not added/updated, or the chart version has not been published to the repo yet | Run `helm repo add`, `helm repo update`, or install from the chart package provided by Redis. | +| `helm template` or `helm upgrade` fails with `image.tag is required and must be set explicitly to the RAM version being deployed` | Chart 1.0.0 carries no default image tags | Set `image.tag` and `controlplane.image.tag` to the Redis Agent Memory version you deploy. The bundled Identity Service takes its tag from the pinned chart. | +| `helm template` or `helm upgrade` fails with `security.profile=fips does not reach the bundled Identity Service` | FIPS is set through the chart's local `security.profile`, which the bundled Identity Service does not read | Set `global.security.profile=fips` (the bundled `values-fips.yaml` does). See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | +| `helm template` or `helm upgrade` fails with `security.profile=fips requires dataplane.identityServiceBaseURL to be an explicit https:// URL` | FIPS is enabled and the Data Plane would use the chart's in-cluster `http://` Identity Service default | Set `dataplane.identityServiceBaseURL` to an `https://` Identity Service endpoint. See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | +| `helm template` or `helm upgrade` fails with `security.profile=fips requires identityService.productValidation.products.memory.baseURL to be https://` | FIPS is enabled and the memory product validator uses the chart's in-cluster `http://` Control Plane default, or an `http://` URL | Set `identityService.productValidation.products.memory.baseURL` to an `https://` Control Plane endpoint. See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | +| `helm template` or `helm upgrade` fails with `identityService.enabled=false with agent-key auth … requires dataplane.identityServiceBaseURL` | The bundled Identity Service is disabled, but nothing says how the Data Plane authenticates | Set `dataplane.identityServiceBaseURL` and `externalIdentityService.credential` for an external Identity Service, or set `memory.auth.method: none` behind an infrastructure access boundary. | | Docker pull fails for the configured image tag | Image tag is wrong or has not been published to the configured registry | Use the image tag listed for the release on Docker Hub or provided by Redis. | | Server and worker pods `CrashLoopBackOff`; log: `license validation failed; refusing to start: invalid license format` | `memory.license.license_path` is not set | See [CL-1](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-1). | | Worker pods `CrashLoopBackOff`; log: `strategies.instruct.llm is required` | The `instruct.llm` block is missing | See [CL-2](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-2). | | Pods `CrashLoopBackOff`; log: `provider "" is not defined in inference_providers` | An `llm.provider` doesn't name an `inference_providers` entry | See [CL-3](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-3). | | Worker callback cannot resolve the Data Plane host | `memory.dataplane_client.base_url` is wrong | See [CL-4](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-4). | -| Pod is stuck in `ImagePullBackOff` or `ErrImagePull` | Cluster cannot pull the configured image, image tag is wrong, registry requires credentials, or `imagePullSecrets` is missing/wrong | Verify `image.repository`, `image.tag`, registry reachability, and `imagePullSecrets`; use the Redis Agent Memory release image tag. See [CL-5](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-5). | +| Pod is stuck in `ImagePullBackOff` or `ErrImagePull` | Cluster cannot pull the configured image, image tag is wrong, registry requires credentials, or `imagePullSecrets` is missing/wrong | Verify `image.repository`, `image.tag`, registry reachability, and `imagePullSecrets`; use the Redis Agent Memory release image tag. The bundled Identity Service reads `identityService.imagePullSecrets` or `global.imagePullSecrets`, not the chart's local `imagePullSecrets`. See [CL-5](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-5). | | Worker callbacks rejected with `401` | `auth.worker_identity` doesn't match the worker, or the Data Plane cannot fetch the cluster JWKS | See [CL-6](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-6). | | `helm install --atomic --wait` times out and rolls back | Cluster is small or image pull/startup takes longer than Helm's default timeout | Install without `--atomic --wait`, or set a longer `--timeout` and ensure enough cluster capacity. | | Pods are pending during install or upgrade | CPU/memory capacity is insufficient for default replicas and rollout overlap | Add nodes/headroom or lower replicas for test deployments. | | Data Plane health fails | Pod not ready, config invalid, Redis unavailable, or license invalid | Check pod logs and call `/health`, `/health/liveness`, and `/health/readiness`. | | Data Plane fails with `agent_keys.introspection.base_url is required` | Bring-your-own (BYO) Data Plane config uses agent-key auth, the default when no auth method is set, without the `auth.agent_keys.introspection` block | Add the `auth.agent_keys.introspection` block, or set `auth.method: none`. See [Configuration](/content/operate/iris/agent-memory/self-managed/configuration.md#bring-your-own-byo-configuration). | | Data Plane fails with `removed metadata configuration keys: …` | Config uses metadata keys that version 0.7.0 removed, such as `metadata.source` or `metadata.live` | Configure `metadata.urls`, `metadata.namespace`, and `databases`, then create stores through the Control Plane. | -| Pod fails to start in FIPS posture | A Redis URL is not `rediss://` or an outbound HTTP client uses `skip_verify: true` | Update Redis URLs and HTTP client config to satisfy the posture checks. | +| Pod fails to start in FIPS posture | A Redis URL is not `rediss://`, an outbound HTTP client uses `skip_verify: true`, an authentication block sets `allow_insecure_transport: true`, or the Identity Service logs `product_validation..base_url must be an https URL in FIPS profile` | Update Redis URLs, HTTP client config, authentication blocks, and the Identity Service product validator URL to satisfy the posture checks. The error names the exact config path. | | Agent receives `401` | Key is missing, revoked, expired, or wrong | Check `Authorization` / `X-Api-Key` and key status. | | Agent receives `503` | Identity Service is unreachable, or the Data Plane's miss budget for rejected keys is exhausted | Check that the Identity Service pod is Ready and reachable from the Data Plane. | | Agent receives `403` | Key exists but lacks the required store grant or action | Update grants with `PATCH http://localhost:9200/v1/api-keys/{keyId}` and the Identity Service control token. | @@ -74,7 +79,7 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Need | Reference | | --- | --- | -| Helm chart values | `values.yaml` at the chart root (`helm pull redis-ai/redis-agent-memory --version 0.7.0 --untar`) | +| Helm chart values | `values.yaml` at the chart root (`helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar`) | | FIPS values overlay | `values-fips.yaml` at the chart root | | NetworkPolicy reference | `networkpolicy.reference.yaml` at the chart root | | Chart README | `README.md` at the chart root | From 6d6e397a8963d387335104c0db75f4d0ee3bbd4d Mon Sep 17 00:00:00 2001 From: Ivo Bardarov Date: Wed, 21 Oct 2026 16:10:44 +0300 Subject: [PATCH 2/4] docs: MOD-19813 install Memory with a standalone Identity Service --- .../iris/agent-memory/self-managed/_index.md | 11 +- .../iris/agent-memory/self-managed/deploy.md | 146 ++++++++++++++---- .../self-managed/prerequisites.md | 84 +++++----- 3 files changed, 166 insertions(+), 75 deletions(-) diff --git a/content/operate/iris/agent-memory/self-managed/_index.md b/content/operate/iris/agent-memory/self-managed/_index.md index d7dac7eab8..bfb8962722 100644 --- a/content/operate/iris/agent-memory/self-managed/_index.md +++ b/content/operate/iris/agent-memory/self-managed/_index.md @@ -31,17 +31,18 @@ documents the self-managed admin endpoints for stores. ## What you are deploying -The chart deploys the Data Plane, the workers, and the Control Plane, and bundles the Identity -Service by default. You provide the Redis databases. To point the Data Plane at an Identity -Service the chart does not install, see the `identityService.enabled=false` entries in -[Helm values to review](/content/operate/iris/agent-memory/self-managed/prerequisites.md#helm-values-to-review). +The `redis-agent-memory` chart `0.8.0` deploys the Data Plane, workers, and Control Plane. +Install the `iris-identity-service` chart `0.10.0` as a separate release first, then connect +Memory to it. Memory does not deploy Identity Service resources or include it as a subchart. +You provide the Redis databases. Follow [Deploy](/content/operate/iris/agent-memory/self-managed/deploy.md) +to configure both releases. | Component | Purpose | Default service | | --- | --- | --- | | Redis Agent Memory Data Plane | Store-scoped runtime memory API. | `redis-agent-memory:9000` | | Redis Agent Memory worker | Background promotion, summarization, and forgetting work. | No public service | | Redis Agent Memory Control Plane | Admin API for creating and managing stores. | `redis-agent-memory-controlplane:9100` | -| Identity Service (bundled) | Mints, rotates, revokes, and checks agent keys. | `redis-agent-memory-iris-identity-service:9200` | +| Identity Service (separate release) | Mints, rotates, revokes, and checks agent keys. | `ids-iris-identity-service:9200` for release `ids` | | Store Redis | Holds session memory, long-term memory, indexes, and TTL data. | Customer-provided | | Job Redis | Holds background work for Redis Agent Memory workers. | Customer-provided | | Metadata Redis | Holds Control Plane store records. The Identity Service keeps agent-key records in the Metadata Redis named in its own metadata Secret. | Customer-provided | diff --git a/content/operate/iris/agent-memory/self-managed/deploy.md b/content/operate/iris/agent-memory/self-managed/deploy.md index b1ef473773..4ce2657b04 100644 --- a/content/operate/iris/agent-memory/self-managed/deploy.md +++ b/content/operate/iris/agent-memory/self-managed/deploy.md @@ -21,9 +21,17 @@ aliases: These steps install Redis Agent Memory with chart-rendered configuration and agent-key authentication, and end with one authenticated call to the Data Plane. -You use three credentials along the way: the Control Plane admin token, the Identity Service -control token, and an agent key. The chart generates the first two. For what each credential -unlocks, see [Credentials](/content/operate/iris/agent-memory/self-managed/authentication.md#credentials). +Install Identity Service as release `ids`, then Memory as release `redis-agent-memory`. +These steps use Memory chart `0.8.0` and Identity Service chart `0.10.0` in one namespace. +You create the shared credentials and Identity Service control token; Memory generates its +Control Plane admin token. See [Credentials](/content/operate/iris/agent-memory/self-managed/authentication.md#credentials). + +Before installing, provide two Transport Layer Security (TLS) endpoints through your hosting +environment: one forwarding to `ids-iris-identity-service:9200`, and one forwarding to +`redis-agent-memory-controlplane:9100`. Neither chart terminates TLS. Replace the endpoint +placeholders with addresses reachable from the calling pods. Obtain their certificate authority +(CA) certificates as a PEM bundle named `service-ca.crt`; use your organization's trust bundle +if the endpoints use public certificates. Before you begin, review the [prerequisites](/content/operate/iris/agent-memory/self-managed/prerequisites.md). @@ -42,8 +50,21 @@ kubectl -n create secret generic ram-secrets \ --from-file=overlay.yaml=./overlay.yaml kubectl -n create secret generic ram-ids-metadata \ --from-file=metadata.yaml=./ids-metadata.yaml +kubectl -n create secret generic memory-dp-credential \ + --from-literal=token="$(openssl rand -hex 32)" +kubectl -n create secret generic memory-internal-token \ + --from-literal=token="$(openssl rand -hex 32)" +kubectl -n create secret generic ids-control-token \ + --from-literal=token="$(openssl rand -hex 32)" +kubectl -n create secret generic ram-ca \ + --from-file=ca.crt=./service-ca.crt ``` +Both releases mount `memory-dp-credential` and `memory-internal-token`. You own these Secrets; +neither release generates them in this procedure. The runtime credential lets Memory check +agent keys. The internal token lets Identity Service validate grants against Memory's Control +Plane. The `ids-control-token` Secret is separate and is used only by Identity Service. + `overlay.yaml` holds the Redis addresses and provider credentials. The Data Plane, the workers, and the Control Plane all mount it: @@ -75,6 +96,51 @@ metadata: urls: ["redis://:6379"] ``` +### Install Identity Service first + +Save this as `values-ids.yaml`: + +```yaml +metadata: + existingSecret: ram-ids-metadata +control: + existingSecret: ids-control-token + autoGenerate: false +runtime: + unscopedGrantsProduct: memory + apiKeyTenant: + singleTenantID: default + serviceCredentials: + - name: memory-dp + subject: memory-dp + allowedOperations: [api-key-introspect] + allowedProducts: [memory] + existingSecret: memory-dp-credential + secretKey: token +productValidation: + products: + memory: + baseURL: https:// + credential: + existingSecret: memory-internal-token + secretKey: token +tls: + caCertSecret: ram-ca +``` + +```bash +helm repo add redis-ai https://helm.redis.io/ai +helm repo update redis-ai +helm install ids redis-ai/iris-identity-service \ + --version 0.10.0 \ + --namespace \ + -f values-ids.yaml +``` + +The Memory Control Plane does not exist yet. Configure its endpoint now, but wait until both +releases and the TLS routes are ready before minting keys: Identity Service calls the Control +Plane to validate each store grant. + ### Prepare worker identity for your platform With agent-key authentication, workers call the Data Plane with their projected service account @@ -89,22 +155,24 @@ issuer is served: | Cluster | `issuer` | `jwks_uri` | Extra steps | Tested | |---------|----------|------------|-------------|--------| -| Self-managed (kind, kubeadm, on-premises) | from `kubectl get --raw /.well-known/openid-configuration` (kind: `https://kubernetes.default.svc.cluster.local`) | `https://kubernetes.default.svc/openid/v1/jwks` | `cluster-ca` Secret + `tls.caCertSecret: cluster-ca` + ClusterRoleBinding (cluster admin's decision) | Yes, on kind | +| Self-managed (kind, kubeadm, on-premises) | from `kubectl get --raw /.well-known/openid-configuration` (kind: `https://kubernetes.default.svc.cluster.local`) | `https://kubernetes.default.svc/openid/v1/jwks` | `ram-ca` Secret containing the cluster CA + `tls.caCertSecret: ram-ca` + ClusterRoleBinding (cluster admin's decision) | Yes, on kind | | Amazon Elastic Kubernetes Service (EKS) | `aws eks describe-cluster --name --query cluster.identity.oidc.issuer --output text` | the `jwks_uri` field of `/.well-known/openid-configuration` | Data Plane egress to the issuer host, or the `com.amazonaws..oidc-eks` PrivateLink endpoint with private DNS. The hostname differs for IPv6 clusters and AWS China, so copy it, don't type it | No | | Azure Kubernetes Service (AKS), OpenID Connect (OIDC) issuer enabled | `az aks show -n -g --query oidcIssuerProfile.issuerUrl -o tsv` (exact, including the trailing slash) | the `jwks_uri` field of `.well-known/openid-configuration` | Data Plane egress. The issuer is on by default only for new Standard clusters on 1.34+ and on AKS Automatic. `--enable-oidc-issuer` on an existing cluster restarts the API server and cannot be undone | No | | Google Kubernetes Engine (GKE) | as self-managed | as self-managed | as self-managed, because anonymous access to the GKE `jwks` endpoint is not verified | No | | Air-gapped (any) | as self-managed | as self-managed | as self-managed | Yes, on kind | Always take `jwks_uri` from the discovery document. Don't build it from the issuer, because the AKS -path differs. On EKS and AKS, replace `issuer` and `jwks_uri` in the values, remove `tls`, and skip -the rest of this section. +path differs. On EKS and AKS, replace `issuer` and `jwks_uri` in the values and skip +the rest of this section. Keep `tls.caCertSecret: ram-ca` for the service endpoints. -On self-managed, GKE, and air-gapped clusters, create a Secret from the cluster CA so the Data -Plane trusts the API server certificate: +On self-managed, GKE, and air-gapped clusters, add the cluster CA to the service CA bundle +so the Data Plane also trusts the API server certificate: ```bash kubectl -n get configmap kube-root-ca.crt -o jsonpath="{.data.ca\.crt}" >./cluster-ca.crt -kubectl -n create secret generic cluster-ca --from-file=ca.crt=./cluster-ca.crt +cat service-ca.crt cluster-ca.crt > ram-ca.crt +kubectl -n create secret generic ram-ca \ + --from-file=ca.crt=./ram-ca.crt --dry-run=client -o yaml | kubectl apply -f - ``` The Data Plane also needs to read the JWKS without logging in. Allowing that is the cluster @@ -123,6 +191,13 @@ On those clusters, there is no working setup for `agent_key` with workers. ## 3. Create `ram-values.yaml` ```yaml +tenantId: default +dataplane: + identityServiceBaseURL: https:// +identityService: + credential: + existingSecret: memory-dp-credential + secretKey: token license: existingSecret: ram-license config: @@ -178,6 +253,7 @@ memory: type: service_account_token token_file: /var/run/secrets/redis-agent-memory-worker/token auth: + method: agent_key worker_identity: enabled: true issuer: @@ -198,10 +274,12 @@ memory: session_summary_view: enabled: false image: - tag: + tag: "0.8.0" controlplane: + internalToken: + existingSecret: memory-internal-token image: - tag: + tag: "0.8.0" config: render: true configData: @@ -214,11 +292,8 @@ controlplane: license_path: /etc/redis-agent-memory/license embedding: dimensions: 1536 -identityService: - metadata: - existingSecret: ram-ids-metadata tls: - caCertSecret: cluster-ca + caCertSecret: ram-ca ``` - `` is any chat model the endpoint serves. @@ -229,12 +304,14 @@ tls: kubectl get --raw /.well-known/openid-configuration | jq -r .issuer ``` -- `tls.caCertSecret` names the CA Secret from [step 2](#prepare-worker-identity-for-your-platform). - Remove it on EKS and AKS. -- The chart writes the agent-key introspection settings and the Control Plane internal token for you. -- `` is the Redis Agent Memory version you deploy. `image.tag` and - `controlplane.image.tag` are required; the chart has no default. The bundled Identity Service - takes its image tag from the pinned chart, so it needs none. +- `tls.caCertSecret` names the CA bundle from [step 2](#2-create-secrets). +- The chart writes the agent-key introspection settings and mounts `memory-dp-credential` at + `/etc/identity-service/runtime/memory-dp/token`. Do not hand-set the introspection endpoint or credential under `memory.auth` or `shared.auth`. +- `tenantId: default` matches `runtime.apiKeyTenant.singleTenantID` in `values-ids.yaml`. + The Control Plane creates admin-token stores in this tenant. +- The published Memory chart defaults `image.tag` and `controlplane.image.tag` to `0.8.0`; + the example pins them explicitly. Identity Service uses its own chart's application version, + `0.10.0`, independently. {{< note >}} No external model provider? To try the API with local models, see [Evaluate locally](#evaluate-locally). @@ -252,7 +329,7 @@ its row. The rows are checklist items CL-1 to CL-6. | CL-2 | `memory.promote_session_memory.strategies.instruct.llm` is set | Worker pods `CrashLoopBackOff` (server stays Ready); log: `promote_session_memory: Strategies: strategies.instruct.llm is required.` | Add the `instruct.llm` block | | CL-3 | Each `llm.provider` names an `inference_providers` entry | Server and worker pods `CrashLoopBackOff`; log: `panic: config validation failed: promote_session_memory.strategies.instruct.llm: provider "" is not defined in inference_providers (defined: )` | Add `memory.inference_providers.` or fix the name | | CL-4 | `memory.dataplane_client.base_url` is `http://redis-agent-memory:9000` | Pods Ready, but no memories appear; worker log: `getting session memory: Get "http://:9000/v1/stores//session-memory/..."` … `dial tcp: lookup ` (the rest depends on the cluster DNS) | Set `http://redis-agent-memory:9000` | -| CL-5 | `image.tag` and `controlplane.image.tag` are set, and each tag exists on Docker Hub | `helm install` fails with `image.tag is required and must be set explicitly to the RAM version being deployed`; or server and worker pods `ImagePullBackOff`, event: `Failed to pull image "redislabs/agent-memory:": … not found` | Set both tags to the Redis Agent Memory version you deploy | +| CL-5 | Any overridden image tags exist in the chosen registry | Pods `ImagePullBackOff`, event: `Failed to pull image "redislabs/agent-memory:": … not found` | Use the published defaults or valid mirrored tags for each release | | CL-6 | `auth.worker_identity` matches the worker (issuer, audience, subject with your namespace) | Pods Ready, but no memories appear; worker log: `memory-dataplane API error: status 401`; the Data Plane logs `401` on `GET /v1/stores//session-memory/` with no reason | Fix `issuer` from `/.well-known/openid-configuration` and the namespace in `subject`. The same symptom appears when the Data Plane cannot fetch the cluster JWKS, so also check [worker identity for your platform](#prepare-worker-identity-for-your-platform) | {{< /table-scrollable >}} @@ -262,7 +339,7 @@ its row. The rows are checklist items CL-1 to CL-6. helm repo add redis-ai https://helm.redis.io/ai helm repo update redis-ai helm install redis-agent-memory redis-ai/redis-agent-memory \ - --version 1.0.0 \ + --version 0.8.0 \ --namespace \ -f ram-values.yaml kubectl -n get pods -w @@ -274,7 +351,7 @@ If you want Helm to wait, set an explicit timeout that matches the environment: ```bash helm install redis-agent-memory redis-ai/redis-agent-memory \ - --version 1.0.0 \ + --version 0.8.0 \ --namespace \ -f ram-values.yaml \ --wait \ @@ -287,8 +364,15 @@ helm install redis-agent-memory redis-ai/redis-agent-memory \ kubectl -n get pods -l app.kubernetes.io/name=redis-agent-memory ``` -The server, worker, `redis-agent-memory-controlplane`, and `redis-agent-memory-iris-identity-service` -pods are Ready. +The server, worker, and `redis-agent-memory-controlplane` pods must be Ready. +Check the separate Identity Service release too: + +```bash +kubectl -n get pods -l app.kubernetes.io/instance=ids +``` + +Wait for its pod to be Ready, and verify that both configured TLS endpoints route to their +Services before creating a key. Run each `port-forward` in this guide in its own terminal. Port-forward the Data Plane and check its health. The health check doesn't need an agent key: @@ -325,9 +409,9 @@ The response carries `storeId`. Use the Identity Service control token: ```bash -kubectl -n port-forward svc/redis-agent-memory-iris-identity-service 9200:9200 +kubectl -n port-forward svc/ids-iris-identity-service 9200:9200 IDS_CONTROL_TOKEN=$(kubectl -n get secret \ - redis-agent-memory-iris-identity-service-control-token -o jsonpath='{.data.token}' | base64 -d) + ids-control-token -o jsonpath='{.data.token}' | base64 -d) curl -sS -X POST http://localhost:9200/v1/api-keys \ -H "Authorization: Bearer $IDS_CONTROL_TOKEN" \ -H "Content-Type: application/json" \ @@ -335,7 +419,7 @@ curl -sS -X POST http://localhost:9200/v1/api-keys \ "name": "my-agent-key", "grants": [ { - "tenant": "", + "tenant": "default", "product": "memory", "resourceType": "mem-store", "resourceId": "", @@ -345,8 +429,8 @@ curl -sS -X POST http://localhost:9200/v1/api-keys \ }' ``` -Use the same tenant on every grant of a key. Any string is accepted. Use `1` if you manage stores with the Control Plane admin token. The response's `token` is the agent key. It is shown -only once. +Use the same tenant as `tenantId` and `runtime.apiKeyTenant.singleTenantID`, here `default`. +The response's `token` is the agent key. It is shown only once. ## 8. Make one authenticated call diff --git a/content/operate/iris/agent-memory/self-managed/prerequisites.md b/content/operate/iris/agent-memory/self-managed/prerequisites.md index f6108ff098..52153de1af 100644 --- a/content/operate/iris/agent-memory/self-managed/prerequisites.md +++ b/content/operate/iris/agent-memory/self-managed/prerequisites.md @@ -17,7 +17,8 @@ aliases: Redis Agent Memory is distributed as container images on Docker Hub plus a Helm chart in the Redis AI Helm repository. The chart deploys the Redis Agent Memory Data -Plane, Redis Agent Memory workers, the Redis Agent Memory Control Plane, and the Identity Service. +Plane, Redis Agent Memory workers, and the Redis Agent Memory Control Plane. Install Identity +Service separately with the `iris-identity-service` chart `0.10.0` before connecting Memory chart `0.8.0`. You provide the Redis databases, provider credentials, Kubernetes exposure, and license material used by the deployment. @@ -31,7 +32,7 @@ license material used by the deployment. | Item | Where it comes from | | ---- | ------------------- | | Container images | Docker Hub: `redislabs/agent-memory`, `redislabs/agent-memory-control-plane`, and `redislabs/iris-identity-service` | -| Helm chart | `redis-agent-memory` chart in the Redis AI Helm repository, or a chart package provided by Redis | +| Helm charts | `redis-agent-memory` `0.8.0` and `iris-identity-service` `0.10.0` in the Redis AI Helm repository | | Redis databases | You provide Store Redis, Job Redis, and Metadata Redis | | License key | Contact your Redis representative or [contact sales](https://redis.io/contact/). | | Provider credentials | You provide embedding provider credentials and, when worker features are enabled, promotion or summarization LLM credentials | @@ -93,13 +94,17 @@ Plane store records, and losing the Identity Service Metadata Redis removes agen chart package or locally downloaded chart. - **Runtime access:** Redis Agent Memory pods must reach the Redis databases and any embedding or LLM provider endpoints used by the deployment. +- **Identity Service:** the Data Plane must reach its runtime endpoint. Identity Service must + reach the Memory Control Plane's grant validator and its own Metadata Redis. Provide TLS + endpoints and trust for both service hops; see [Deploy](/content/operate/iris/agent-memory/self-managed/deploy.md). - **Data Plane exposure:** use NetworkPolicy, ingress, gateway, service mesh, private load balancer, or equivalent controls to restrict API access. ## Credentials and Secrets The chart renders the configuration from Helm values (`config.render: true`). Credentials stay out -of the values: you put them in an overlay Secret. You create three Secrets: +of the values: you put them in an overlay Secret. Create the following Secrets for the +[two-release installation](/content/operate/iris/agent-memory/self-managed/deploy.md#2-create-secrets): | Secret | Default key | Holds | | --- | --- | --- | @@ -107,26 +112,24 @@ of the values: you put them in an overlay Secret. You create three Secrets: | Overlay Secret | `overlay.yaml` | Redis URLs and provider credentials. | | Identity Service metadata Secret | `metadata.yaml` | The Identity Service's Metadata Redis URL. | -The chart generates four more Secrets for the tokens and service credentials listed in -[Credentials](/content/operate/iris/agent-memory/self-managed/authentication.md#credentials). +Also create `memory-dp-credential` and `memory-internal-token`, shared by both releases, +and `ids-control-token`, read only by Identity Service. The walkthrough supplies a `ram-ca` +certificate bundle for service trust. Memory generates its Control Plane admin token unless +you provide one. See [Credentials](/content/operate/iris/agent-memory/self-managed/authentication.md#credentials). To supply a complete configuration file in your own Secret instead, see [Bring-your-own (BYO) configuration](/content/operate/iris/agent-memory/self-managed/configuration.md#bring-your-own-byo-configuration). ## Release artifacts and image tags -Chart `1.0.0` requires `image.tag` and `controlplane.image.tag` at install or upgrade time; set -each to the Redis Agent Memory version you deploy. The bundled Identity Service needs no tag of -its own: it runs the image version the pinned `iris-identity-service` chart carries. Set -`identityService.image.*` only to mirror the image or pin another tag. +The published Memory chart `0.8.0` defaults `image.tag` and `controlplane.image.tag` to `0.8.0`. +Identity Service chart `0.10.0` defaults its image to its own application version, `0.10.0`. +Set tags explicitly when pinning images or using a mirror. The releases have independent versions. -Use the chart version supplied by Redis for the release. The published chart is -`redis-ai/redis-agent-memory` from `https://helm.redis.io/ai`. - -Standard customer installs use the public Docker Hub images published by the -Redis Agent Memory self-managed release: `docker.io/redislabs/agent-memory:` and -`docker.io/redislabs/agent-memory-control-plane:`, plus -`docker.io/redislabs/iris-identity-service` at the version the pinned chart carries. +Both charts are published at `https://helm.redis.io/ai` as `redis-ai/redis-agent-memory` +and `redis-ai/iris-identity-service`. Their standard images are +`redislabs/agent-memory:0.8.0`, `redislabs/agent-memory-control-plane:0.8.0`, and +`redislabs/iris-identity-service:0.10.0`. ## Air-gapped and private registry installs @@ -136,15 +139,15 @@ Mirror these images into your internal registry: | --- | --- | | `redislabs/agent-memory:` | Always (Data Plane and workers) | | `redislabs/agent-memory-control-plane:` | Always | -| `redislabs/iris-identity-service:` | With the bundled Identity Service (the default); skip only with `identityService.enabled=false` | +| `redislabs/iris-identity-service:` | On the separate Identity Service release, required for default agent-key authentication | | `replicated/troubleshoot:0.131.0` | Support-bundle health checks, on by default (`supportPackage.*`) | | `hibiken/asynqmon:0.7.2` | Optional, with `controlplane.queueMonitor` | | `python:3.13-alpine` | Optional, with `tests.smoke` | -`` is the `appVersion` of the `iris-identity-service` chart the Redis Agent Memory -chart pins. Read it with -`helm show chart redis-ai/redis-agent-memory --version ` and -`helm show chart redis-ai/iris-identity-service --version `. +For this release, `` is `0.8.0` and `` is `0.10.0`. +Inspect each package with `helm show chart redis-ai/redis-agent-memory --version 0.8.0` +and `helm show chart redis-ai/iris-identity-service --version 0.10.0`. Memory does not pin +or install the Identity Service chart. ```bash docker pull redislabs/agent-memory: @@ -182,19 +185,25 @@ controlplane: image: repository: registry.example.com/redislabs/agent-memory-control-plane -identityService: - image: - repository: registry.example.com/redislabs/iris-identity-service +global: + imagePullSecrets: + - name: ram-registry +``` +Configure the separate Identity Service release in `values-ids.yaml`: + +```yaml +image: + repository: registry.example.com/redislabs/iris-identity-service + tag: "0.10.0" global: imagePullSecrets: - name: ram-registry ``` -Use `global.imagePullSecrets`, which the chart and the bundled Identity Service both read; the -local `imagePullSecrets` reaches only the Redis Agent Memory pods, and the chart refuses it when -the Identity Service image is mirrored. Omit pull Secrets if the internal registry does not -require authentication. +Each release reads its own `imagePullSecrets`, falling back to `global.imagePullSecrets`. +Values passed to Memory do not configure Identity Service. Omit pull Secrets if the registry +does not require authentication. For air-gapped deployments, also set: @@ -203,16 +212,13 @@ airgap: enabled: true ``` -With `airgap.enabled: true`, the chart fails if a repository still points at Docker Hub. For the -Identity Service, the error is: - -```text -airgap.enabled=true requires identityService.image.repository to point to a mirrored registry reachable from the cluster -``` +Memory's `airgap.enabled: true` checks Memory's own image repositories. It does not validate +the separate Identity Service release. Mirror that release's image and chart dependencies +separately, and confirm that every configured repository is reachable from the cluster. ## System requirements -Default chart values: +Default values for Memory and the separate Identity Service chart: | Component | Default | Purpose | | --------- | ------- | ------- | @@ -268,10 +274,10 @@ namespace. | Secret rollouts | `license.existingSecretChecksum`, `config.existingSecretChecksum`, `controlplane.config.existingSecretChecksum` | Rolling pods after externally managed Secret changes. | | Control Plane | `controlplane.image.*`, `controlplane.configData`, `controlplane.adminToken.*` | Mirroring the Control Plane image, setting its configuration, or bringing your own admin token. | | Control Plane internal token | `controlplane.internalToken.*` | Bringing your own token for Identity Service checks against the Control Plane. | -| Identity Service (bundled) | `identityService.*` | The published `iris-identity-service` subchart's contract: naming its metadata Secret, mirroring its image, bringing your own control token (`identityService.control.*`), or adding service configuration (`identityService.configData`). | -| External Identity Service | `identityService.enabled=false`, `dataplane.identityServiceBaseURL`, `externalIdentityService.*` | Installing no Identity Service objects and pointing the Data Plane at one you run elsewhere. | -| Umbrella fallbacks | `global.*` | Sharing `security.profile`, `imagePullSecrets`, and `tls.caCertSecret` with the bundled Identity Service; the chart's own `security.profile`, `imagePullSecrets`, and `tls.caCertSecret` do not reach it. | -| Security profile | `global.security.profile` | Selecting the [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture) for Redis Agent Memory and the bundled Identity Service. | +| Identity Service connection | `dataplane.identityServiceBaseURL`, `identityService.credential.*`, `identityService.allowInsecureTransport` | Connecting to the separately installed runtime endpoint. The credential Secret is registered on that release. | +| Identity Service configuration | Separate `values-ids.yaml`: `metadata`, `control`, `runtime`, `productValidation`, `subjectGrants` | Configuring the Identity Service release, not Memory. | +| Shared fallbacks | `global.security.profile`, `global.imagePullSecrets`, `global.tls.caCertSecret` | Providing fallback values within each release. Pass shared values to both releases; local values take precedence. | +| Security profile | `security.profile` or `global.security.profile` | Selecting the [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture); configure it separately on each release. | | Support bundles | `supportPackage.*` | Configuring support-bundle collection and its health checks. | | Preflight checks | `preflight.*` | Rendering the preflight checks spec as a ConfigMap. | | Helm tests | `tests.*` | Running [chart tests](/content/operate/iris/agent-memory/self-managed/operations.md#chart-tests) with `helm test`. | From 04a0aa18e522bdaad6389a6476cac97f526a413c Mon Sep 17 00:00:00 2001 From: Ivo Bardarov Date: Wed, 21 Oct 2026 16:40:24 +0300 Subject: [PATCH 3/4] docs: MOD-19813 align authentication and operations with separate releases --- .../self-managed/authentication.md | 27 +++- .../self-managed/configuration.md | 69 +++++++-- .../agent-memory/self-managed/operations.md | 136 +++++++++++------- .../agent-memory/self-managed/reference.md | 27 ++-- 4 files changed, 183 insertions(+), 76 deletions(-) diff --git a/content/operate/iris/agent-memory/self-managed/authentication.md b/content/operate/iris/agent-memory/self-managed/authentication.md index 72a67e0365..ad2934664c 100644 --- a/content/operate/iris/agent-memory/self-managed/authentication.md +++ b/content/operate/iris/agent-memory/self-managed/authentication.md @@ -25,13 +25,15 @@ grants. | Credential | Who presents it to whom | Secret / key | Auto-generated? | What it unlocks | | --- | --- | --- | --- | --- | | Control Plane admin token | Operator → Control Plane (`:9100`) | `redis-agent-memory-controlplane-admin-token` / `token` | Yes (`controlplane.adminToken.autoGenerate`) | Store management: `/v1/stores`, `/v1/detectors` | -| Control Plane internal token | Identity Service → Control Plane | `redis-agent-memory-controlplane-internal-token` / `token` | Yes (`controlplane.internalToken.autoGenerate`) | Checking that the store in a grant exists. Chart-managed; you handle it only with bring-your-own (BYO) configuration | -| Identity Service control token | Operator → Identity Service (`:9200`) | `redis-agent-memory-iris-identity-service-control-token` / `token` | Yes (`identityService.control.autoGenerate`) | Creating, listing, updating, rotating and revoking agent keys | -| Data Plane service credential | Data Plane → Identity Service | `redis-agent-memory-iris-identity-service-runtime-memory-dp` / `token` | Yes (`identityService.runtime.serviceCredentials`) | Checking agent keys for `memory`. Chart-managed; you handle it only with bring-your-own (BYO) configuration | +| Control Plane internal token | Identity Service → Control Plane | `memory-internal-token` / `token` in the walkthrough | You provision it for both releases | Checking that the store in a grant exists. Set `controlplane.internalToken.existingSecret` on Memory and `productValidation.products.memory.credential.existingSecret` on Identity Service. | +| Identity Service control token | Operator → Identity Service (`:9200`) | `ids-control-token` / `token` in the walkthrough | Supplied through `control.existingSecret` on Identity Service; that chart can also generate one | Creating, listing, updating, rotating and revoking agent keys | +| Data Plane service credential | Data Plane → Identity Service | `memory-dp-credential` / `token` in the walkthrough | You provision it for both releases | Checking agent keys for `memory`. Set `identityService.credential.existingSecret` on Memory and register it in `runtime.serviceCredentials[]` on Identity Service. | | Agent key | Application → Data Plane (`:9000`) | None; returned once when minted or rotated | No | The Data Plane operations its grants allow | -Each generated Secret keeps its value across upgrades (`helm.sh/resource-policy: keep`). To bring -your own, set `existingSecret` on the matching value. +Generated token Secrets are retained across upgrades and uninstalls (`helm.sh/resource-policy: keep`). +Use existing Secrets for shared credentials and for reproducible deployment automation. +Secret names and keys must agree between releases. See +[Secret rotation](/content/operate/iris/agent-memory/self-managed/operations.md#secret-rotation). ## Control Plane admin token @@ -63,7 +65,8 @@ The Data Plane defaults to agent-key authentication whenever no auth method is s The [`deploy` walkthrough](/content/operate/iris/agent-memory/self-managed/deploy.md) uses agent-key authentication from the start. In the chart-rendered configuration, the chart writes the agent-key -introspection settings for you, so you add nothing more. +introspection settings from `dataplane.identityServiceBaseURL` and `identityService.credential`. +These must point to the standalone release and its registered `memory-dp` credential. A bring-your-own (BYO) Data Plane configuration needs the `auth.agent_keys.introspection` block, including a BYO configuration without `auth`. See @@ -83,10 +86,16 @@ Treat agent keys as opaque credentials. Do not parse their contents. Use auth-disabled mode for development and testing only: ```yaml +profile: dev auth: method: none ``` +These are application configuration fields; put them under `memory` in Helm values. +The Data Plane refuses `auth.method: none` unless `profile` is exactly `dev`. +Chart-rendered configuration fails to render otherwise. With a supplied configuration Secret, +the same rule is enforced at process startup. + > [!WARNING] > Do not expose an auth-disabled Data Plane to untrusted callers. In auth-disabled > mode, Redis Agent Memory does not authenticate or authorize Data Plane requests; any @@ -116,7 +125,11 @@ A grant names the tenant, product, store, and actions: } ``` -Use the same tenant on every grant of a key. Any string is accepted. Use `1` if you manage stores with the Control Plane admin token. +Use the installation's tenant on every grant, for example `default`. Set Memory's `tenantId` +and Identity Service's `runtime.apiKeyTenant.singleTenantID` to that same value. With a rendered +Control Plane configuration, `tenantId` sets `auth.admin_tenant_id`, so admin-token stores belong +to that tenant too. With a supplied Control Plane configuration Secret, set `auth.admin_tenant_id` +yourself. Neither release checks the other release's tenant setting. Grant actions: diff --git a/content/operate/iris/agent-memory/self-managed/configuration.md b/content/operate/iris/agent-memory/self-managed/configuration.md index cdebd5f8b2..909d1e9835 100644 --- a/content/operate/iris/agent-memory/self-managed/configuration.md +++ b/content/operate/iris/agent-memory/self-managed/configuration.md @@ -14,8 +14,9 @@ aliases: - /operate/iris/agent-memory/self-managed/data-plane-configuration/ --- -The chart renders the Data Plane, Control Plane, and Identity Service configuration from Helm values -(`config.render: true`). Credentials stay out of the values, in the overlay Secret. For a complete +The Memory chart renders Data Plane and Control Plane configuration from Helm values +(`config.render: true` and `controlplane.config.render: true`). Identity Service uses its own +release and `values-ids.yaml`. Credentials stay in existing Secrets. For a complete example, see the values in [step 3 of Deploy](/content/operate/iris/agent-memory/self-managed/deploy.md#3-create-ram-valuesyaml). To supply complete configuration files in your own Secrets instead, see @@ -28,7 +29,8 @@ To supply complete configuration files in your own Secrets instead, see | `shared` | Settings common to the Data Plane and the Control Plane, such as `databases`. The chart merges them under `memory` and `controlplane.configData`. | | `memory` | The Data Plane and worker configuration file. | | `controlplane.configData` | The Control Plane configuration file. | -| `identityService.*` | The bundled Identity Service, from the published `iris-identity-service` chart; every key is that chart's values contract. `identityService.metadata.existingSecret` names the Secret with its Metadata Redis URL, and extra service configuration goes in `identityService.configData`. | +| `dataplane.identityServiceBaseURL`, `identityService.credential.*`, `identityService.allowInsecureTransport` | Memory's connection to the standalone Identity Service. These values do not configure that service. | +| Separate `values-ids.yaml` | Identity Service's `metadata`, `control`, `runtime`, `productValidation`, and optional `subjectGrants` values. | | Overlay Secret (`secrets.secretName`, key `overlay.yaml`) | `metadata.urls`, `metadata.namespace`, `databases."1".urls`, `background_jobs.redis.urls`, and provider `api_key` values. The Data Plane, the workers, and the Control Plane all read it. | ## Data Plane settings @@ -55,8 +57,16 @@ entry. The endpoint goes in `inference_providers..endpoint`, not in the `l In the chart-rendered configuration, the chart writes the agent-key introspection settings for you: it owns `auth.agent_keys.introspection.base_url`, `credential`, and `allow_insecure_transport`, and -refuses hand-set values. Set `dataplane.identityServiceBaseURL` to point at a non-default Identity -Service endpoint. Leave `auth.method` unset to keep the `agent_key` default. +refuses hand-set values in either `memory.auth` or `shared.auth`. Cache tuning under +`auth.agent_keys.introspection.cache` is still allowed. Set `dataplane.identityServiceBaseURL` +and `identityService.credential.existingSecret`; optional `secretKey` defaults to `token`, and +`existingSecretChecksum` triggers a rollout after credential rotation. Set `memory.auth.method: agent_key` +explicitly when combining agent keys with worker or other authentication methods. + +The runtime endpoint must use `https://`. An `http://` endpoint is accepted only when +`identityService.allowInsecureTransport: true` is set and the FIPS profile is not enabled. +Subjects using the `identity_service` authority also need this connection for grant lookup, +even when another authentication method is selected. ## Bring-your-own (BYO) configuration @@ -64,10 +74,16 @@ With BYO configuration, you supply each complete configuration file in your own chart injects nothing into it. Add the keys the chart would otherwise write: - **Data Plane**: the `auth.agent_keys.introspection` block. -- **Control Plane**: `auth.internal_token.token_file: /etc/controlplane-onprem/internal/token`. +- **Control Plane**: `auth.internal_token.token_file: /etc/controlplane-onprem/internal/token` + and `auth.admin_tenant_id` matching the installation's tenant. + +With `config.existingSecret`, the chart does not inspect the supplied file. Rendering cannot +catch missing introspection settings or an invalid development profile in that file; startup +validation still applies. Connection Secrets must still be named in Helm values so they are mounted. The Data Plane defaults to `agent_key` whenever no auth method is set. A BYO Data Plane configuration -without `auth` therefore needs the `auth.agent_keys.introspection` block, or `auth.method: none`. +without `auth` therefore needs the `auth.agent_keys.introspection` block. For development only, +`auth.method: none` requires exact `profile: dev`. The `MEM_AUTH_METHOD` environment variable overrides the method. ### Data Plane configuration file @@ -106,10 +122,10 @@ databases: - redis://:6379 auth: + method: agent_key agent_keys: introspection: - base_url: http://redis-agent-memory-iris-identity-service:9200 - allow_insecure_transport: true + base_url: https:// product: memory credential: token_file: /etc/identity-service/runtime/memory-dp/token @@ -192,6 +208,7 @@ auth: token_file: /etc/controlplane-onprem/admin/token internal_token: token_file: /etc/controlplane-onprem/internal/token + admin_tenant_id: default license: license_path: /etc/redis-agent-memory/license @@ -227,9 +244,43 @@ In `ram-values.yaml`, replace `config.render`, `shared`, `memory`, `controlplane `config.existingSecret` and `config.render` are set. ```yaml +tenantId: default config: existingSecret: ram-config +identityService: + credential: + existingSecret: memory-dp-credential controlplane: + internalToken: + existingSecret: memory-internal-token config: existingSecret: ram-controlplane-config ``` + +## Connect releases across namespaces + +For another namespace, resolve the standalone Service using its full address, such as +`ids-iris-identity-service..svc:9200`, and the Memory Control Plane as +`redis-agent-memory-controlplane..svc:9100`. Configure their TLS frontends +for the two connection URLs. With a naming override, use the rendered Service name. + +Pods can mount Secrets only from their own namespace. Provision the same runtime credential +and internal token values in both namespaces, plus each namespace's trust bundle. Allow Memory +to reach Identity Service and Identity Service to reach the Control Plane, including any +TLS proxies. See [Network policy](/content/operate/iris/agent-memory/self-managed/operations.md#network-policy). + +## Optional Playbook extraction + +On the Identity Service release, allow Memory subject grants for Playbook extraction: + +```yaml +subjectGrants: + allowed: + - product: memory + resourceType: mem-store + actions: [read, read_all_owners] +``` + +Also add `subject-grant-lookup` to the `memory-dp` runtime credential's `allowedOperations` +alongside `api-key-introspect`. These are Identity Service values, not Memory's `identityService` +values. `read_all_owners` is a subject-grant action; do not add it to agent-key grants. diff --git a/content/operate/iris/agent-memory/self-managed/operations.md b/content/operate/iris/agent-memory/self-managed/operations.md index 1e15bca9de..1b6bb2b536 100644 --- a/content/operate/iris/agent-memory/self-managed/operations.md +++ b/content/operate/iris/agent-memory/self-managed/operations.md @@ -45,7 +45,7 @@ only when a key is minted or rotated. Rotation returns a new `keyId` with the new token. Use the new `keyId` for later updates, rotations, and revocations. The old key stays valid for `graceSeconds`, which defaults to 3600 and has a chart maximum of 604800 -(`identityService.apiKeys.maxRotateGraceSeconds`). The response adds +(`apiKeys.maxRotateGraceSeconds` on the Identity Service release). The response adds `oldExpiresAt`, the time the old key stops working. Revoking the old `keyId` ends its grace period early. For the full request and response, see [API examples](/content/operate/iris/agent-memory/self-managed/api-examples.md#identity-service-api-examples). @@ -61,6 +61,20 @@ kubectl -n create secret generic redis-agent-memory-controlplan -o yaml | kubectl apply -f - ``` +The runtime credential and Control Plane internal token are shared by both releases. +When rotating either, keep the values equal in every namespace that mounts them, update the +corresponding checksums, and roll the affected workloads on both releases: + +| Credential | Memory checksum value | Identity Service checksum value | +| --- | --- | --- | +| `memory-dp-credential` | `identityService.credential.existingSecretChecksum` | `existingSecretChecksum` on the matching `runtime.serviceCredentials[]` entry | +| `memory-internal-token` | `controlplane.internalToken.existingSecretChecksum` | `productValidation.products.memory.credential.existingSecretChecksum` | + +Apply `ram-values.yaml` to Memory and `values-ids.yaml` to Identity Service separately. +Coordinate rotation: mismatched runtime credentials reject authentication, and mismatched +internal tokens prevent grant validation. Identity Service's operator control token is separate; +its checksum is `control.existingSecretChecksum` on that release. + Rotate the Redis Agent Memory license by updating the license Secret and changing `license.existingSecretChecksum` so Helm rolls the Data Plane, worker, and Control Plane pods. @@ -131,7 +145,12 @@ kubectl -n rollout restart deployment ## Updates -For every update: +Memory and Identity Service have independent release versions. Upgrade each with its own +values file and verify their shared connection contract afterward. A Memory upgrade does not +upgrade Identity Service. The published pair documented here is Memory `0.8.0` and Identity +Service `0.10.0`. + +For updates within a supported release path: 1. Update chart version and image tags. 2. Recalculate Secret checksums for changed files. @@ -150,6 +169,21 @@ helm upgrade redis-agent-memory redis-ai/redis-agent-memory \ On small clusters, avoid `--atomic` unless the timeout and capacity are known to be sufficient. +### Upgrade from a bundled Identity Service + +Direct `helm upgrade` from an earlier chart with bundled Identity Service, including Memory +`0.7.0`, to `0.8.0` is unsupported. Use a fresh installation. The following manual migration +outline is untested guidance, not a supported upgrade procedure: + +1. Back up store and agent-key metadata. Preserve the existing runtime credential, Control Plane + internal token, metadata Redis addresses, and key namespaces. +2. Provision the shared Secrets with those existing values and configure a standalone Identity + Service to use the same agent-key metadata. Do not let two independent releases manage one Secret. +3. Retain the tenant used by existing stores and keys. Earlier admin-token stores used tenant `1`; + set `tenantId` and `runtime.apiKeyTenant.singleTenantID` accordingly, or migrate metadata first. +4. Plan the replacement of the old Memory release and removal of bundled resources with Redis. + Keep backups and retained Secrets until the new installation and existing keys are verified. + ## Chart tests The chart can render optional `helm test` resources when `tests.enabled=true`. @@ -185,57 +219,62 @@ environments where the in-cluster test path is allowed. ## FIPS-oriented posture -The chart supports an opt-in FIPS-oriented posture for regulated environments. -Set it through `global.security.profile`, which the chart and the bundled Identity Service both -read. The chart's local `security.profile` does not reach the Identity Service, and the chart -refuses a FIPS Redis Agent Memory with a non-FIPS bundled Identity Service: +Both releases support an opt-in Federal Information Processing Standards (FIPS) posture. +Set `security.profile: fips` or its fallback `global.security.profile: fips` on each release. +A value passed only to Memory does not configure Identity Service. + +In `ram-values.yaml`: ```yaml -global: - security: - profile: fips +security: + profile: fips +dataplane: + identityServiceBaseURL: https:// +tls: + caCertSecret: ram-ca ``` -Enabling the posture also takes two `https://` endpoints. The chart's in-cluster defaults for -both are plaintext `http://`, and the posture refuses them: +In `values-ids.yaml`: ```yaml -dataplane: - # Data Plane to Identity Service agent-key introspection. - identityServiceBaseURL: https:// -identityService: - productValidation: - products: - memory: - # Identity Service to Control Plane grant validation. - baseURL: https:// +security: + profile: fips +productValidation: + products: + memory: + baseURL: https:// + credential: + existingSecret: memory-internal-token +tls: + caCertSecret: ram-ca ``` -The chart doesn't terminate Transport Layer Security (TLS) for either endpoint. Your hosting -environment must provide both, for example with a service mesh, ingress, or TLS-terminating -proxy in front of the Identity Service and Control Plane Services. The calling pods must trust -both certificates; the Data Plane trusts `tls.caCertSecret` (or `global.tls.caCertSecret`) on -top of the system CAs. +The Memory chart refuses `identityService.allowInsecureTransport: true` under FIPS. +Identity Service refuses to start with a non-HTTPS product validator URL under FIPS. +Neither chart terminates Transport Layer Security (TLS). Your hosting environment supplies +both endpoints through a service mesh, ingress, or TLS proxy. Memory trusts its runtime +endpoint through its own `tls.caCertSecret`; Identity Service trusts the validator endpoint +through that release's `tls.caCertSecret`, each in addition to system certificate authorities. -You can also apply the bundled FIPS values overlay with the normal values file. -Download the chart to get `values-fips.yaml` from the chart root, and set the two endpoints in -`ram-values.yaml` or on the command line: +Memory also ships a `values-fips.yaml` overlay. Apply it only to Memory, and configure the +Identity Service release's posture separately: ```bash -helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar - -helm upgrade --install redis-agent-memory redis-ai/redis-agent-memory \ - --version \ +helm pull redis-ai/redis-agent-memory --version 0.8.0 --untar +helm upgrade redis-agent-memory redis-ai/redis-agent-memory \ + --version 0.8.0 \ --namespace \ -f ram-values.yaml \ - -f redis-agent-memory/values-fips.yaml \ - --set dataplane.identityServiceBaseURL=https:// \ - --set identityService.productValidation.products.memory.baseURL=https:// + -f redis-agent-memory/values-fips.yaml + +helm upgrade ids redis-ai/iris-identity-service \ + --version 0.10.0 \ + --namespace \ + -f values-ids.yaml ``` -When enabled, the chart sets `GODEBUG=fips140=on` on the Data Plane, worker, -Control Plane, and Identity Service pods and enables FIPS-oriented runtime -checks. The Identity Service also gets `IDS_SECURITY_PROFILE`. +Both charts set `GODEBUG=fips140=on` on their application containers and enable +FIPS-oriented runtime checks. This is not a formal FIPS 140 compliance or validation claim. Treat it as a deployment posture and guardrail that must still be reviewed against the @@ -251,8 +290,8 @@ The Control Plane runs under the same posture and rejects non-`rediss://` `metadata.urls` or `databases."1".urls`. The Identity Service sends the Control Plane internal token on every grant validation. Under -the posture it refuses to start unless each product validator URL uses `https://`, and the -chart refuses to render one that doesn't. +the posture it refuses to start unless each product validator URL uses `https://`. +Configure that URL on the Identity Service release, not under Memory's `identityService`. The Redis Agent Memory API listener itself speaks HTTP inside the cluster. Edge TLS termination is owned by the hosting environment, such as ingress, service mesh, or external @@ -280,15 +319,15 @@ the direct caller also has a valid Redis Agent Memory credential. The chart includes `networkpolicy.reference.yaml` at the chart root as a reference manifest. Get it with -`helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar`. It is not templated because allowed callers are +`helm pull redis-ai/redis-agent-memory --version 0.8.0 --untar`. It is not templated because allowed callers are environment-specific. Customize the placeholders before applying it: - ``: namespace where Redis Agent Memory is installed. - ``: Helm release name. This guide uses `redis-agent-memory`. - The release name also prefixes release-derived service and deployment names. - `nameOverride` and `fullnameOverride` change rendered resource names, but the + `fullnameOverride` fixes Memory's default resource names to `redis-agent-memory`. + Naming overrides change rendered resource names, but the `app.kubernetes.io/instance` selector remains the Helm release name. - `` and caller pod labels: ingress controller, service mesh gateway, application pod, or approved internal caller allowed to call Redis Agent Memory. @@ -298,11 +337,12 @@ traffic to server pods on port `9000` from approved callers and the worker Deployment. It also includes a Control Plane stanza for port `9100`, which always applies. -The reference policy has no Identity Service stanza. Under default-deny, add -rules that allow: - -- Data Plane to Identity Service on port `9200`, for agent-key checks. -- Identity Service to Control Plane on port `9100`. +The reference includes Control Plane ingress from the separate Identity Service release. +Set `` and `` to its namespace and +release name (`ids` in the walkthrough). It does not manage ingress for Identity Service itself. +Under default-deny, allow Data Plane requests to that release on port `9200`, and Identity +Service requests to the Control Plane on port `9100`. If TLS proxies sit between them, allow +the proxy ports and actual source pods too. Add corresponding egress rules when egress is restricted. Review the manifest against the customer's CNI, ingress path, and service mesh behavior before production use. diff --git a/content/operate/iris/agent-memory/self-managed/reference.md b/content/operate/iris/agent-memory/self-managed/reference.md index 2b1363607e..933fe27f33 100644 --- a/content/operate/iris/agent-memory/self-managed/reference.md +++ b/content/operate/iris/agent-memory/self-managed/reference.md @@ -19,7 +19,8 @@ Use these files to configure a self-managed deployment: | File | Purpose | | --- | --- | -| `ram-values.yaml` | Helm values, including the chart-rendered Data Plane, Control Plane, and Identity Service configuration. See [step 3](/content/operate/iris/agent-memory/self-managed/deploy.md#3-create-ram-valuesyaml). | +| `ram-values.yaml` | Memory configuration and its connection to Identity Service. See [step 3](/content/operate/iris/agent-memory/self-managed/deploy.md#3-create-ram-valuesyaml). | +| `values-ids.yaml` | Separate Identity Service release configuration, including runtime credential registration, tenant, and Memory grant validation. | | `overlay.yaml` | Redis addresses and provider credentials. The Data Plane, the workers, and the Control Plane all mount it. | | `ids-metadata.yaml` | Tells the Identity Service where Metadata Redis is. | | `license` | Redis Agent Memory license file provided by Redis. | @@ -28,8 +29,8 @@ Use these files to configure a self-managed deployment: If you use an external secret manager, expose the license, config, admin-token, Identity Service metadata, Identity Service control token, Data Plane service credential, -and Control Plane internal token material to the chart as Kubernetes Secrets and set the chart's -`existingSecret` values to those Secret names. +and Control Plane internal token material as Kubernetes Secrets. Set `existingSecret` on the +owning release. Shared credentials must have matching contents in both releases' namespaces. Direct CSI file mounts that bypass Kubernetes Secrets are not supported for the Redis Agent Memory license, Data Plane config, Control Plane config, or Control Plane @@ -46,22 +47,23 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Symptom | Likely cause | Fix | | --- | --- | --- | | `helm search repo redis-ai/redis-agent-memory --versions` returns no results | Helm repo not added/updated, or the chart version has not been published to the repo yet | Run `helm repo add`, `helm repo update`, or install from the chart package provided by Redis. | -| `helm template` or `helm upgrade` fails with `image.tag is required and must be set explicitly to the RAM version being deployed` | Chart 1.0.0 carries no default image tags | Set `image.tag` and `controlplane.image.tag` to the Redis Agent Memory version you deploy. The bundled Identity Service takes its tag from the pinned chart. | -| `helm template` or `helm upgrade` fails with `security.profile=fips does not reach the bundled Identity Service` | FIPS is set through the chart's local `security.profile`, which the bundled Identity Service does not read | Set `global.security.profile=fips` (the bundled `values-fips.yaml` does). See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | -| `helm template` or `helm upgrade` fails with `security.profile=fips requires dataplane.identityServiceBaseURL to be an explicit https:// URL` | FIPS is enabled and the Data Plane would use the chart's in-cluster `http://` Identity Service default | Set `dataplane.identityServiceBaseURL` to an `https://` Identity Service endpoint. See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | -| `helm template` or `helm upgrade` fails with `security.profile=fips requires identityService.productValidation.products.memory.baseURL to be https://` | FIPS is enabled and the memory product validator uses the chart's in-cluster `http://` Control Plane default, or an `http://` URL | Set `identityService.productValidation.products.memory.baseURL` to an `https://` Control Plane endpoint. See [FIPS-oriented posture](/content/operate/iris/agent-memory/self-managed/operations.md#fips-oriented-posture). | -| `helm template` or `helm upgrade` fails with `identityService.enabled=false with agent-key auth … requires dataplane.identityServiceBaseURL` | The bundled Identity Service is disabled, but nothing says how the Data Plane authenticates | Set `dataplane.identityServiceBaseURL` and `externalIdentityService.credential` for an external Identity Service, or set `memory.auth.method: none` behind an infrastructure access boundary. | +| Rendering fails because `identityService` has an additional property | Memory values still use the removed bundled contract, such as `identityService.enabled` or `identityService.runtime` | Move service configuration to `values-ids.yaml`. Memory accepts only `identityService.credential` and `identityService.allowInsecureTransport`; remove `externalIdentityService` too. | +| Rendering fails with `requires dataplane.identityServiceBaseURL` | Agent-key authentication or an `identity_service` subject needs the standalone runtime endpoint | Set `dataplane.identityServiceBaseURL` and `identityService.credential.existingSecret`. See [Deploy](/content/operate/iris/agent-memory/self-managed/deploy.md). | +| Rendering fails with `requires identityService.credential.existingSecret` | The endpoint is configured but the runtime credential Secret is missing | Name the existing Secret also registered on Identity Service as `memory-dp`. | +| Rendering fails with `must be https://` or `identityService.allowInsecureTransport=true is refused under the fips security profile` | The runtime endpoint uses HTTP without an allowed exception, or insecure transport is enabled under FIPS | Use an HTTPS endpoint. An HTTP exception requires `identityService.allowInsecureTransport: true` and is refused under FIPS. | +| Rendering fails with `is chart-owned` for an introspection field | An endpoint, credential, or transport flag was hand-set under `memory.auth` or `shared.auth` | Use `dataplane.identityServiceBaseURL` and `identityService.credential` for chart-rendered configuration; cache settings remain configurable. | +| Rendering or startup refuses `auth.method: none` | Authentication is disabled outside the development profile | Use agent-key authentication. For isolated development only, set both `memory.profile: dev` and `memory.auth.method: none`; supplied configuration files use `profile: dev` and `auth.method: none`. | | Docker pull fails for the configured image tag | Image tag is wrong or has not been published to the configured registry | Use the image tag listed for the release on Docker Hub or provided by Redis. | | Server and worker pods `CrashLoopBackOff`; log: `license validation failed; refusing to start: invalid license format` | `memory.license.license_path` is not set | See [CL-1](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-1). | | Worker pods `CrashLoopBackOff`; log: `strategies.instruct.llm is required` | The `instruct.llm` block is missing | See [CL-2](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-2). | | Pods `CrashLoopBackOff`; log: `provider "" is not defined in inference_providers` | An `llm.provider` doesn't name an `inference_providers` entry | See [CL-3](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-3). | | Worker callback cannot resolve the Data Plane host | `memory.dataplane_client.base_url` is wrong | See [CL-4](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-4). | -| Pod is stuck in `ImagePullBackOff` or `ErrImagePull` | Cluster cannot pull the configured image, image tag is wrong, registry requires credentials, or `imagePullSecrets` is missing/wrong | Verify `image.repository`, `image.tag`, registry reachability, and `imagePullSecrets`; use the Redis Agent Memory release image tag. The bundled Identity Service reads `identityService.imagePullSecrets` or `global.imagePullSecrets`, not the chart's local `imagePullSecrets`. See [CL-5](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-5). | +| Pod is stuck in `ImagePullBackOff` or `ErrImagePull` | Cluster cannot pull the configured image, image tag is wrong, registry requires credentials, or `imagePullSecrets` is missing/wrong | Verify `image.repository`, `image.tag`, registry reachability, and `imagePullSecrets`; use the Redis Agent Memory release image tag. Configure Identity Service's image and pull Secrets on its own release. See [CL-5](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-5). | | Worker callbacks rejected with `401` | `auth.worker_identity` doesn't match the worker, or the Data Plane cannot fetch the cluster JWKS | See [CL-6](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-6). | | `helm install --atomic --wait` times out and rolls back | Cluster is small or image pull/startup takes longer than Helm's default timeout | Install without `--atomic --wait`, or set a longer `--timeout` and ensure enough cluster capacity. | | Pods are pending during install or upgrade | CPU/memory capacity is insufficient for default replicas and rollout overlap | Add nodes/headroom or lower replicas for test deployments. | | Data Plane health fails | Pod not ready, config invalid, Redis unavailable, or license invalid | Check pod logs and call `/health`, `/health/liveness`, and `/health/readiness`. | -| Data Plane fails with `agent_keys.introspection.base_url is required` | Bring-your-own (BYO) Data Plane config uses agent-key auth, the default when no auth method is set, without the `auth.agent_keys.introspection` block | Add the `auth.agent_keys.introspection` block, or set `auth.method: none`. See [Configuration](/content/operate/iris/agent-memory/self-managed/configuration.md#bring-your-own-byo-configuration). | +| Data Plane fails with `agent_keys.introspection.base_url is required` | Bring-your-own (BYO) Data Plane config uses agent-key auth, the default when no auth method is set, without the `auth.agent_keys.introspection` block | Add the `auth.agent_keys.introspection` block. Only isolated development can use `auth.method: none` with `profile: dev`. See [Configuration](/content/operate/iris/agent-memory/self-managed/configuration.md#bring-your-own-byo-configuration). | | Data Plane fails with `removed metadata configuration keys: …` | Config uses metadata keys that version 0.7.0 removed, such as `metadata.source` or `metadata.live` | Configure `metadata.urls`, `metadata.namespace`, and `databases`, then create stores through the Control Plane. | | Pod fails to start in FIPS posture | A Redis URL is not `rediss://`, an outbound HTTP client uses `skip_verify: true`, an authentication block sets `allow_insecure_transport: true`, or the Identity Service logs `product_validation..base_url must be an https URL in FIPS profile` | Update Redis URLs, HTTP client config, authentication blocks, and the Identity Service product validator URL to satisfy the posture checks. The error names the exact config path. | | Agent receives `401` | Key is missing, revoked, expired, or wrong | Check `Authorization` / `X-Api-Key` and key status. | @@ -69,7 +71,7 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Agent receives `403` | Key exists but lacks the required store grant or action | Update grants with `PATCH http://localhost:9200/v1/api-keys/{keyId}` and the Identity Service control token. | | Store created by the Control Plane is not visible to the Data Plane | Control Plane and Data Plane point at different Metadata Redis URLs or namespaces | Make `metadata.urls` / `metadata.namespace` match on the Control Plane and the Data Plane. | | Agent key is rejected by the Data Plane | Data Plane cannot reach the Identity Service, the key was rotated or revoked, or the key secret is wrong | Check Identity Service reachability and, with BYO configuration only, `auth.agent_keys.introspection`. After a rotate or revoke, pods can disagree for up to 5 minutes. Send the latest credential returned by mint or rotate. | -| Minting an agent key returns `400` for a grant | Unknown store ID, grant lacks `product: "memory"`, or invalid grant shape | Create the store first, because unknown stores fail the Control Plane check. With BYO Control Plane config, also set `auth.internal_token.token_file: /etc/controlplane-onprem/internal/token`. Use `product: "memory"`, `resourceType: "mem-store"`, and `actions: ["read"]`, `["write"]`, or both. | +| Minting an agent key returns `400` for a grant | Unknown store ID, mismatched tenant, missing `product: "memory"`, or invalid grant shape | Create the store first, match `tenantId` with Identity Service's `runtime.apiKeyTenant.singleTenantID`, and verify its `productValidation.products.memory` endpoint and internal-token Secret match Memory. With BYO Control Plane config, also set `auth.internal_token.token_file: /etc/controlplane-onprem/internal/token`. Use `product: "memory"`, `resourceType: "mem-store"`, and `actions: ["read"]`, `["write"]`, or both. | | Worker jobs fail after agent-key auth is enabled | Worker callback request has no accepted credential, the projected token is not mounted, or `auth.worker_identity` does not trust the worker subject/audience/issuer | Enable `workerAuth`, set `dataplane_client.auth.type=service_account_token`, and configure `auth.worker_identity.subjects` with the worker ServiceAccount subject and required store grants. | | Gateway path succeeds but direct external path also works | Data Plane is reachable outside the intended gateway path | Add NetworkPolicy, ingress, service mesh, or load balancer controls. | | NetworkPolicy blocks expected traffic | Placeholder namespace, release name, or caller selectors were not customized correctly | Check the Helm release label `app.kubernetes.io/instance`, caller namespace, and caller pod labels. | @@ -79,7 +81,8 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Need | Reference | | --- | --- | -| Helm chart values | `values.yaml` at the chart root (`helm pull redis-ai/redis-agent-memory --version 1.0.0 --untar`) | +| Helm chart values | `values.yaml` at the chart root (`helm pull redis-ai/redis-agent-memory --version 0.8.0 --untar`) | +| Identity Service chart values | `helm show values redis-ai/iris-identity-service --version 0.10.0` | | FIPS values overlay | `values-fips.yaml` at the chart root | | NetworkPolicy reference | `networkpolicy.reference.yaml` at the chart root | | Chart README | `README.md` at the chart root | From 1edb30458d555ac910df0b4f753925b687386c86 Mon Sep 17 00:00:00 2001 From: Ivo Bardarov Date: Wed, 21 Oct 2026 18:51:10 +0300 Subject: [PATCH 4/4] docs: MOD-19813 fix deployed documentation report findings --- .../iris/agent-memory/self-managed/_index.md | 6 +- .../self-managed/configuration.md | 5 ++ .../iris/agent-memory/self-managed/deploy.md | 85 +++++++++++++++++-- .../agent-memory/self-managed/operations.md | 31 ++++++- .../self-managed/prerequisites.md | 9 +- .../agent-memory/self-managed/reference.md | 3 +- 6 files changed, 122 insertions(+), 17 deletions(-) diff --git a/content/operate/iris/agent-memory/self-managed/_index.md b/content/operate/iris/agent-memory/self-managed/_index.md index bfb8962722..f29b360132 100644 --- a/content/operate/iris/agent-memory/self-managed/_index.md +++ b/content/operate/iris/agent-memory/self-managed/_index.md @@ -69,8 +69,8 @@ and the Identity Service handles agent keys. ### API surfaces -All Data Plane APIs except `/health` are scoped to a store. A store is the logical isolation -boundary for memory data. +Memory data APIs are scoped to a store, the logical isolation boundary for memory data. +Service liveness and readiness endpoints are not store-scoped. When agent-key authentication is enabled, the grants on each agent key determine which stores and actions the key can access. @@ -82,7 +82,7 @@ actions the key can access. | Namespaces | `/v1/stores/{storeId}/namespaces` | Namespace resources within a store. | | Model Context Protocol (MCP) | `/v1/stores/{storeId}/mcp` | The MCP streamable-HTTP endpoint for a store. | | Store health | `/v1/stores/{storeId}/health` | Read-only health for store-scoped features. | -| Service health | `/health` | Operational status of the Data Plane. | +| Service health | `/health/liveness`, `/health/readiness` | Process liveness and readiness to serve requests; neither requires an agent key. | | Control Plane | `/v1/stores`, `/v1/detectors` | Self-managed administration for stores, and the catalog of built-in sensitive-data detectors. | | Identity Service | `/v1/api-keys` | Self-managed administration for agent keys. | diff --git a/content/operate/iris/agent-memory/self-managed/configuration.md b/content/operate/iris/agent-memory/self-managed/configuration.md index 909d1e9835..b0fd76882b 100644 --- a/content/operate/iris/agent-memory/self-managed/configuration.md +++ b/content/operate/iris/agent-memory/self-managed/configuration.md @@ -48,6 +48,7 @@ Data Plane settings go under `memory`, or at the top level of a BYO Data Plane c | `license.license_path` | Path where the license Secret is mounted. | | `request_region` | Region used for background work routing. | | `background_jobs.redis` | Job Redis connection used by background workers. | +| `background_jobs.idempotency` | Enable execution idempotency and extraction serialization for production workers. Requires `enabled: true` and `urls`; it can share Job Redis. | | `embedders_connection_details` | Embedding provider endpoint and credentials. | | `dataplane_client` | Worker callback client configuration. | | `promote_session_memory` | Promotion strategy and LLM connection used by workers. | @@ -103,6 +104,10 @@ request_region: default: eu1 background_jobs: + idempotency: + enabled: true + urls: + - redis://:6379 redis: enabled: true queue_prefix: ram diff --git a/content/operate/iris/agent-memory/self-managed/deploy.md b/content/operate/iris/agent-memory/self-managed/deploy.md index 4ce2657b04..cbbf9b3c71 100644 --- a/content/operate/iris/agent-memory/self-managed/deploy.md +++ b/content/operate/iris/agent-memory/self-managed/deploy.md @@ -35,6 +35,30 @@ if the endpoints use public certificates. Before you begin, review the [prerequisites](/content/operate/iris/agent-memory/self-managed/prerequisites.md). +### Isolated lab without TLS + +For a network-isolated lab without the Federal Information Processing Standards (FIPS) profile, +you can use the in-cluster HTTP Services instead of TLS frontends. In `ram-values.yaml`, change: + +```yaml +dataplane: + identityServiceBaseURL: http://ids-iris-identity-service:9200 +identityService: + allowInsecureTransport: true + credential: + existingSecret: memory-dp-credential +``` + +In `values-ids.yaml`, change the validator URL to +`productValidation.products.memory.baseURL: http://redis-agent-memory-controlplane:9100`. +Keep the other settings in both files. Tokens travel over plaintext HTTP on these two hops; +use TLS for production. FIPS refuses this configuration. + +For this lab option, skip `service-ca.crt` and the initial `ram-ca` creation in step 2, and omit +`tls` from `values-ids.yaml`. For self-managed worker identity, still create `ram-ca` from the +cluster CA as described in [Prepare worker identity](#prepare-worker-identity-for-your-platform). +On EKS and AKS, omit Memory's `tls` block too unless another connection requires a private CA. + ## 1. Create the namespace ```bash @@ -57,7 +81,7 @@ kubectl -n create secret generic memory-internal-token \ kubectl -n create secret generic ids-control-token \ --from-literal=token="$(openssl rand -hex 32)" kubectl -n create secret generic ram-ca \ - --from-file=ca.crt=./service-ca.crt + --from-file=ca.crt=./service-ca.crt --save-config ``` Both releases mount `memory-dp-credential` and `memory-internal-token`. You own these Secrets; @@ -77,6 +101,8 @@ databases: background_jobs: redis: urls: ["redis://:6379"] + idempotency: + urls: ["redis://:6379"] embedders_connection_details: openai: credentials: @@ -163,7 +189,9 @@ issuer is served: Always take `jwks_uri` from the discovery document. Don't build it from the issuer, because the AKS path differs. On EKS and AKS, replace `issuer` and `jwks_uri` in the values and skip -the rest of this section. Keep `tls.caCertSecret: ram-ca` for the service endpoints. +the rest of this section. With TLS service endpoints, keep `tls.caCertSecret: ram-ca` +for their trust bundle. For the HTTP-only lab option, omit this block unless another connection +requires a private CA. On self-managed, GKE, and air-gapped clusters, add the cluster CA to the service CA bundle so the Data Plane also trusts the API server certificate: @@ -175,6 +203,9 @@ kubectl -n create secret generic ram-ca \ --from-file=ca.crt=./ram-ca.crt --dry-run=client -o yaml | kubectl apply -f - ``` +For the HTTP-only lab option, use `cp cluster-ca.crt ram-ca.crt` instead of the `cat` command; +there is no service CA file to combine. + The Data Plane also needs to read the JWKS without logging in. Allowing that is the cluster admin's decision: @@ -240,6 +271,8 @@ memory: models: default_chat_model: background_jobs: + idempotency: + enabled: true redis: enabled: true queue_prefix: ram @@ -298,6 +331,11 @@ tls: - `` is any chat model the endpoint serves. - `controlplane.configData.embedding.dimensions` must equal `memory.embedding.models.dimensions`. +- `background_jobs.idempotency.enabled` prevents successful jobs from running again after + redelivery and serializes extraction for the same session. The walkthrough enables it for + workers and supplies its Redis URL through the overlay. Keep it enabled in production; + without it, workers warn that duplicate memories remain possible. This is separate from + queue submission deduplication. - `` is the cluster's issuer. Read it with: ```bash @@ -371,21 +409,22 @@ Check the separate Identity Service release too: kubectl -n get pods -l app.kubernetes.io/instance=ids ``` -Wait for its pod to be Ready, and verify that both configured TLS endpoints route to their -Services before creating a key. +Wait for its pod to be Ready. With TLS frontends, verify that both configured endpoints route +to their Services before creating a key. For the HTTP-only lab option, verify that both +in-cluster Service addresses are reachable from the calling pods. Run each `port-forward` in this guide in its own terminal. Port-forward the Data Plane and check its health. The health check doesn't need an agent key: ```bash kubectl -n port-forward svc/redis-agent-memory 9000:9000 -curl http://localhost:9000/health +curl http://localhost:9000/health/readiness ``` The response is: ```json -{"status":"healthy"} +{"status":"ready"} ``` ## 6. Create a store @@ -515,7 +554,14 @@ kubectl -n apply -f ollama.yaml The first start downloads about 2 GB. -In `ram-values.yaml`, replace the provider blocks with: +Edit the existing `ram-values.yaml`: replace the complete `memory.embedding`, +`memory.embedders_connection_details`, `memory.inference_providers`, and +`memory.promote_session_memory` maps with the corresponding maps in this snippet. Also update +`controlplane.configData.embedding.dimensions`. Keep the other settings, including authentication, +worker callbacks, and `background_jobs.idempotency`. + +Apply these edits to the existing file. Passing the snippet as another `-f` file merges the maps +and retains old OpenAI entries. ```yaml memory: @@ -553,7 +599,30 @@ controlplane: `api_key: ollama` is a placeholder. The client requires a key, and Ollama ignores it. -In `overlay.yaml`, remove `embedders_connection_details.openai` and both `api_key` entries. +Replace `overlay.yaml` with the Redis-only overlay, removing the complete +`embedders_connection_details` and `promote_session_memory` blocks: + +```yaml +metadata: + urls: ["redis://:6379"] +databases: + "1": + urls: ["redis://:6379"] +background_jobs: + redis: + urls: ["redis://:6379"] + idempotency: + urls: ["redis://:6379"] +``` + +If Memory is already installed, update the `ram-secrets` Secret from this file, upgrade with +the edited values, and restart the Data Plane, workers, and Control Plane so they reload the +overlay. See [Secret rotation](/content/operate/iris/agent-memory/self-managed/operations.md#secret-rotation). + +Use this provider switch only in a disposable evaluation installation. Changing the settings +does not migrate existing stores or their vector indexes. After switching, create a new store +and agent key using steps 6–7 for local evaluation. Existing stores retain their original +embedding dimensions and cannot be reused with this example. ## Next steps diff --git a/content/operate/iris/agent-memory/self-managed/operations.md b/content/operate/iris/agent-memory/self-managed/operations.md index 1b6bb2b536..585e6bef46 100644 --- a/content/operate/iris/agent-memory/self-managed/operations.md +++ b/content/operate/iris/agent-memory/self-managed/operations.md @@ -32,9 +32,11 @@ aliases: ## Secret rotation -Rotate Redis Agent Memory agent keys through the Identity Service API: +Use the [Identity Service port-forward and control token](/content/operate/iris/agent-memory/self-managed/deploy.md#7-mint-an-agent-key) +from the deployment procedure to rotate agent keys: ```bash +IDS_URL=http://localhost:9200 curl -sS -X POST "$IDS_URL/v1/api-keys//rotate?graceSeconds=3600" \ -H "Authorization: Bearer $IDS_CONTROL_TOKEN" ``` @@ -70,7 +72,32 @@ corresponding checksums, and roll the affected workloads on both releases: | `memory-dp-credential` | `identityService.credential.existingSecretChecksum` | `existingSecretChecksum` on the matching `runtime.serviceCredentials[]` entry | | `memory-internal-token` | `controlplane.internalToken.existingSecretChecksum` | `productValidation.products.memory.credential.existingSecretChecksum` | -Apply `ram-values.yaml` to Memory and `values-ids.yaml` to Identity Service separately. +For example, rotate `memory-dp-credential` in the walkthrough's namespace: + +```bash +umask 077 +openssl rand -hex 32 | tr -d '\n' > memory-dp-token +kubectl -n create secret generic memory-dp-credential \ + --from-file=token=./memory-dp-token --save-config --dry-run=client -o yaml | kubectl apply -f - +RUNTIME_CREDENTIAL_CHECKSUM="$(shasum -a 256 ./memory-dp-token | awk '{print $1}')" + +helm upgrade ids redis-ai/iris-identity-service \ + --version 0.10.0 \ + --namespace \ + -f values-ids.yaml \ + --set-string "runtime.serviceCredentials[0].existingSecretChecksum=$RUNTIME_CREDENTIAL_CHECKSUM" +helm upgrade redis-agent-memory redis-ai/redis-agent-memory \ + --version 0.8.0 \ + --namespace \ + -f ram-values.yaml \ + --set-string "identityService.credential.existingSecretChecksum=$RUNTIME_CREDENTIAL_CHECKSUM" +``` + +In the walkthrough, `memory-dp` is entry `0` in `runtime.serviceCredentials`. With another list, +update the matching entry. Persist the checksum in both values files for later upgrades, and +verify the affected Deployments are Ready. For the internal token, use the corresponding paths +in the table. For multiple namespaces, provision the new token value in each namespace. + Coordinate rotation: mismatched runtime credentials reject authentication, and mismatched internal tokens prevent grant validation. Identity Service's operator control token is separate; its checksum is `control.existingSecretChecksum` on that release. diff --git a/content/operate/iris/agent-memory/self-managed/prerequisites.md b/content/operate/iris/agent-memory/self-managed/prerequisites.md index 9eb34b0882..75138b4ff0 100644 --- a/content/operate/iris/agent-memory/self-managed/prerequisites.md +++ b/content/operate/iris/agent-memory/self-managed/prerequisites.md @@ -62,7 +62,7 @@ databases. | --- | --- | --- | --- | | Store Redis | Always | `databases."1".urls` | Session memory JSON, long-term memory hashes, RediSearch indexes, vectors, and TTL-managed data. | | Metadata Redis | Always | `metadata.urls`, and optionally `metadata.namespace` (default `iris:memory`) | Store records. | -| Job Redis | Always | `background_jobs.redis.urls` | Background work, retry state, delayed jobs, and idempotency markers. | +| Job Redis | Always | `background_jobs.redis.urls` and, when execution idempotency is enabled, `background_jobs.idempotency.urls` | Background work, retry state, delayed jobs, and execution markers. The two settings can use the same Redis. | {{< /table-scrollable >}} The Identity Service reads its Metadata Redis from `metadata.urls` in its own metadata Secret and @@ -104,8 +104,8 @@ Plane store records, and losing the Identity Service Metadata Redis removes agen ## Credentials and Secrets -The chart renders the configuration from Helm values (`config.render: true`). Credentials stay out -of the values: you put them in an overlay Secret. Create the following Secrets for the +When `config.render: true` is set, as in the walkthrough, the chart renders configuration from +Helm values. This option defaults to `false`. Credentials stay in an overlay Secret. Create the following Secrets for the [two-release installation](/content/operate/iris/agent-memory/self-managed/deploy.md#2-create-secrets): | Secret | Default key | Holds | @@ -145,6 +145,7 @@ Mirror these images into your internal registry: | `replicated/troubleshoot:0.131.0` | Support-bundle health checks, on by default (`supportPackage.*`) | | `hibiken/asynqmon:0.7.2` | Optional, with `controlplane.queueMonitor` | | `python:3.13-alpine` | Optional, with `tests.smoke` | +| `curlimages/curl:8.17.0` | Optional, for `helm test` on the Identity Service release (`tests.image` in `values-ids.yaml`) | For this release, `` is `0.8.0` and `` is `0.10.0`. Inspect each package with `helm show chart redis-ai/redis-agent-memory --version 0.8.0` @@ -198,6 +199,8 @@ Configure the separate Identity Service release in `values-ids.yaml`: image: repository: registry.example.com/redislabs/iris-identity-service tag: "0.10.0" +tests: + image: registry.example.com/curlimages/curl:8.17.0 global: imagePullSecrets: - name: ram-registry diff --git a/content/operate/iris/agent-memory/self-managed/reference.md b/content/operate/iris/agent-memory/self-managed/reference.md index 933fe27f33..80d5199240 100644 --- a/content/operate/iris/agent-memory/self-managed/reference.md +++ b/content/operate/iris/agent-memory/self-managed/reference.md @@ -48,6 +48,7 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | --- | --- | --- | | `helm search repo redis-ai/redis-agent-memory --versions` returns no results | Helm repo not added/updated, or the chart version has not been published to the repo yet | Run `helm repo add`, `helm repo update`, or install from the chart package provided by Redis. | | Rendering fails because `identityService` has an additional property | Memory values still use the removed bundled contract, such as `identityService.enabled` or `identityService.runtime` | Move service configuration to `values-ids.yaml`. Memory accepts only `identityService.credential` and `identityService.allowInsecureTransport`; remove `externalIdentityService` too. | +| Rendering fails at `/externalIdentityService` with `'not' failed` | Values contain the removed external-mode block | Remove `externalIdentityService` and use `dataplane.identityServiceBaseURL` plus `identityService.credential` for the standalone connection. | | Rendering fails with `requires dataplane.identityServiceBaseURL` | Agent-key authentication or an `identity_service` subject needs the standalone runtime endpoint | Set `dataplane.identityServiceBaseURL` and `identityService.credential.existingSecret`. See [Deploy](/content/operate/iris/agent-memory/self-managed/deploy.md). | | Rendering fails with `requires identityService.credential.existingSecret` | The endpoint is configured but the runtime credential Secret is missing | Name the existing Secret also registered on Identity Service as `memory-dp`. | | Rendering fails with `must be https://` or `identityService.allowInsecureTransport=true is refused under the fips security profile` | The runtime endpoint uses HTTP without an allowed exception, or insecure transport is enabled under FIPS | Use an HTTPS endpoint. An HTTP exception requires `identityService.allowInsecureTransport: true` and is refused under FIPS. | @@ -62,7 +63,7 @@ CSI-synced Secrets, make sure a Control Plane pod also mounts the corresponding | Worker callbacks rejected with `401` | `auth.worker_identity` doesn't match the worker, or the Data Plane cannot fetch the cluster JWKS | See [CL-6](/content/operate/iris/agent-memory/self-managed/deploy.md#cl-6). | | `helm install --atomic --wait` times out and rolls back | Cluster is small or image pull/startup takes longer than Helm's default timeout | Install without `--atomic --wait`, or set a longer `--timeout` and ensure enough cluster capacity. | | Pods are pending during install or upgrade | CPU/memory capacity is insufficient for default replicas and rollout overlap | Add nodes/headroom or lower replicas for test deployments. | -| Data Plane health fails | Pod not ready, config invalid, Redis unavailable, or license invalid | Check pod logs and call `/health`, `/health/liveness`, and `/health/readiness`. | +| Data Plane health fails | Pod not ready, config invalid, Redis unavailable, or license invalid | Check pod logs and call `/health/liveness` and `/health/readiness`. | | Data Plane fails with `agent_keys.introspection.base_url is required` | Bring-your-own (BYO) Data Plane config uses agent-key auth, the default when no auth method is set, without the `auth.agent_keys.introspection` block | Add the `auth.agent_keys.introspection` block. Only isolated development can use `auth.method: none` with `profile: dev`. See [Configuration](/content/operate/iris/agent-memory/self-managed/configuration.md#bring-your-own-byo-configuration). | | Data Plane fails with `removed metadata configuration keys: …` | Config uses metadata keys that version 0.7.0 removed, such as `metadata.source` or `metadata.live` | Configure `metadata.urls`, `metadata.namespace`, and `databases`, then create stores through the Control Plane. | | Pod fails to start in FIPS posture | A Redis URL is not `rediss://`, an outbound HTTP client uses `skip_verify: true`, an authentication block sets `allow_insecure_transport: true`, or the Identity Service logs `product_validation..base_url must be an https URL in FIPS profile` | Update Redis URLs, HTTP client config, authentication blocks, and the Identity Service product validator URL to satisfy the posture checks. The error names the exact config path. |