{
  "schema_version": 2,
  "id": "operate/iris/context-gateway/self-managed/prerequisites",
  "title": "Self-managed Context Gateway prerequisites",
  "url": "https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/prerequisites/",
  "summary": "Review software, Identity Service, Redis, credential storage, network, Secret, and image prerequisites for self-managed Context Gateway.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-11-04T01:09:56+02:00",
  "page_type": "content",
  "content_hash": "c24cef297f442573bb1f760e928b1b7e14c9afd0eda9165b62d02d16354ac3d6",
  "sections": [
    {
      "id": "what-you-need",
      "title": "What you need",
      "role": "overview",
      "text": "| Item | Where it comes from |\n| --- | --- |\n| Container images | The Context Gateway Control Plane and Data Plane images for the release |\n| Helm chart | `redis-context-gateway` chart in the Redis AI Helm repository, or a chart package provided by Redis |\n| Identity Service | An Identity Service release for the same tenant, shared with other Iris services |\n| Redis databases | You provide Metadata Redis, credential storage, and the databases Gateways use |\n| License key | Contact your Redis representative or [contact sales](https://redis.io/contact/). |\n| Upstream credentials | You provide the tokens or header values each Model Context Protocol (MCP) server needs |"
    },
    {
      "id": "required-software",
      "title": "Required software",
      "role": "content",
      "text": "| Software | Purpose |\n| --- | --- |\n| Kubernetes 1.28 or later, and `kubectl` | Run both planes and create Secrets in the installation namespace. |\n| [Helm 3, v3.10.3 or later](https://docs.helm.sh/docs/v3/intro/install/) | Install the chart. |\n| Bash, curl, and jq | Run the API examples. |"
    },
    {
      "id": "redis-databases",
      "title": "Redis databases",
      "role": "content",
      "text": "The chart consumes existing Redis deployments. It does not provision them.\n\n| Redis deployment | Requirements | Use |\n| --- | --- | --- |\n| Metadata Redis | Shared by the Control Plane and Data Plane. | Gateway and Upstream records. |\n| Credential Redis | A separate access control list (ACL) user. Only with the encrypted Redis backend. | Encrypted Upstream credentials. |\n| Surface databases | The Search module, the JSON module for entities stored as JSON, and `FT.HYBRID` support for hybrid search tools. | Records that Context Surfaces serve as tools. |\n| Gateway database | JSON support and `maxmemory-policy noeviction` for compression. Only for the cache or compression. | Cached results and handles. |\n\nUse separately managed Redis deployments for metadata, credentials, and customer data. Redis endpoint aliases do not prove that two databases are separate.\n\n- Give a Context Surface its own database when its records must stay separate from other Gateways. Gateways whose Surfaces share a database can read each other's records.\n- Never use one Redis database as both a Surface database and a Gateway database. Keep the two [default databases](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/configuration#default-databases) on separate Redis endpoints when compression is on, because `noeviction` would otherwise apply to customer data.\n- Size the Gateway database for handles: the rate of calls that become handles, times the stored result size, times the handle lifetime.\n\nUse `rediss://` URLs with certificate verification. The Federal Information Processing Standards (FIPS)-oriented profile rejects plaintext Redis URLs."
    },
    {
      "id": "redis-users-for-surface-databases",
      "title": "Redis users for Surface databases",
      "role": "content",
      "text": "Give each plane its own Redis user on every Surface database, and supply each plane's login through its own overlay. See [Context Surface databases](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/configuration#context-surface-databases). Both users need the `@connection` commands, `PING`, `INFO`, and `MODULE LIST`.\n\n| Plane | Commands | Keys |\n| --- | --- | --- |\n| Data Plane | `FT.SEARCH`, `FT.AGGREGATE`, `FT.HYBRID`, `JSON.GET`, `HMGET` | Read access to each Surface key prefix only |\n| Control Plane | `FT.CREATE`, `FT.DROPINDEX`, `FT._LIST`, `COMMAND INFO` | None |\n\nFor example, for a Surface whose entities use the key prefixes `provider:` and `location:`:\n\n[code example]\n\nOn an OSS Redis Cluster, also grant `+cluster|slots` to both users. Search commands check key permissions differently across Redis versions, so test the users against your Redis version."
    },
    {
      "id": "credential-storage",
      "title": "Credential storage",
      "role": "content",
      "text": "| Backend | What you provide |\n| --- | --- |\n| Encrypted Redis (default) | Credential Redis and a keyring of base64-encoded 32-byte Advanced Encryption Standard (AES) keys. |\n| HashiCorp Vault key-value (KV) version 2 | A writer token for the Control Plane and a reader token for the Data Plane. |\n| AWS Secrets Manager | An Identity and Access Management (IAM) role for each plane through workload identity. |"
    },
    {
      "id": "network-access",
      "title": "Network access",
      "role": "content",
      "text": "| From | To | Purpose |\n| --- | --- | --- |\n| MCP clients | Data Plane, through your ingress at `publicBaseURL` | Tool listing and calls. |\n| Data Plane | Every Upstream MCP server | Tool calls. |\n| Data Plane | Identity Service | Agent-key checks. |\n| Identity Service | Control Plane | Grant validation. |\n| Operators | Control Plane and Identity Service | Administration. Keep both private. |\n\nThe chart creates `ClusterIP` services. It can also create an Ingress for the Data Plane with `dataplane.ingress`, which is off by default. See [Helm values](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/configuration#helm-values). Your platform owns the ingress controller, network policy, Domain Name System (DNS) records, and Transport Layer Security (TLS) certificates.\n\nConfigure the ingress for Streamable HTTP:\n\n- Pass the MCP request headers through unchanged, including `Authorization`, `X-Api-Key`, `Accept`, `Mcp-Protocol-Version`, `Mcp-Method`, and `Mcp-Name`.\n- Pass the `WWW-Authenticate` response header, which MCP clients need to start identity provider sign-in.\n- Allow read timeouts longer than the slowest tool call."
    },
    {
      "id": "credentials-and-secrets",
      "title": "Credentials and Secrets",
      "role": "content",
      "text": "Redis URLs, tokens, keyrings, and the license belong in Kubernetes Secrets or Secrets Store Container Storage Interface (CSI) Driver files, never in Helm values or source control. See [Credentials](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/authentication#credentials) for each credential and [Configuration](https://redis.io/docs/latest/operate/iris/context-gateway/self-managed/configuration) for each file reference."
    },
    {
      "id": "release-artifacts-and-image-tags",
      "title": "Release artifacts and image tags",
      "role": "content",
      "text": "| Component | Image |\n| --- | --- |\n| Control Plane | `redislabs/iris-context-gateway-control:<control-plane-image-tag>` |\n| Data Plane | `redislabs/iris-context-gateway-data:<data-plane-image-tag>` |\n\nThe chart defaults to these repositories and pins the image tags that match its chart version. Leave `image.repository` and `image.tag` unset for a public install, and override them only to pull from a mirror.\n\nChart `1.0.0` pins both images to tag `1.0.0`."
    },
    {
      "id": "air-gapped-and-private-registry-installs",
      "title": "Air-gapped and private registry installs",
      "role": "content",
      "text": "For a disconnected installation, mirror both images to your registry with their tags unchanged, set each component's `image.repository` and `image.tag`, and set `imagePullSecrets`. Install from a downloaded chart package instead of the Redis AI Helm repository."
    },
    {
      "id": "helm-values-to-review",
      "title": "Helm values to review",
      "role": "content",
      "text": "| Value | Decide |\n| --- | --- |\n| `tenantId` | One tenant per release, equal to the Identity Service's single tenant ID. |\n| `publicBaseURL` | The Data Plane origin MCP clients reach. |\n| `credentialStorage.provider` | `redis`, `vault`, or `aws_secrets_manager`. |\n| `security.profile` | `standard` (default) or `fips`. |"
    }
  ],
  "examples": [
    {
      "id": "redis-users-for-surface-databases-ex0",
      "language": "text",
      "code": "ACL SETUSER surface-dp on ><dp-password> resetkeys %R~provider:* %R~location:* -@all +@connection +ping +info +module|list +ft.search +ft.aggregate +ft.hybrid +json.get +hmget\nACL SETUSER surface-cp on ><cp-password> resetkeys -@all +@connection +ping +info +module|list +ft.create +ft.dropindex +ft._list +command|info",
      "section_id": "redis-users-for-surface-databases"
    }
  ]
}