Self-managed Context Gateway prerequisites

Review software, Identity Service, Redis, credential storage, network, Secret, and image prerequisites for self-managed Context Gateway.

What you need

Item Where it comes from
Container images The Context Gateway Control Plane and Data Plane images for the release
Helm chart redis-context-gateway chart in the Redis AI Helm repository, or a chart package provided by Redis
Identity Service An Identity Service release for the same tenant, shared with other Iris services
Redis databases You provide Metadata Redis, credential storage, and the databases Gateways use
License key Contact your Redis representative or contact sales.
Upstream credentials You provide the tokens or header values each Model Context Protocol (MCP) server needs

Required software

Software Purpose
Kubernetes 1.28 or later, and kubectl Run both planes and create Secrets in the installation namespace.
Helm 3, v3.10.3 or later Install the chart.
Bash, curl, and jq Run the API examples.

Redis databases

The chart consumes existing Redis deployments. It does not provision them.

Redis deployment Requirements Use
Metadata Redis Shared by the Control Plane and Data Plane. Gateway and Upstream records.
Credential Redis A separate access control list (ACL) user. Only with the encrypted Redis backend. Encrypted Upstream credentials.
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.
Gateway database JSON support and maxmemory-policy noeviction for compression. Only for the cache or compression. Cached results and handles.

Use separately managed Redis deployments for metadata, credentials, and customer data. Redis endpoint aliases do not prove that two databases are separate.

  • 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.
  • Never use one Redis database as both a Surface database and a Gateway database. Keep the two default databases on separate Redis endpoints when compression is on, because noeviction would otherwise apply to customer data.
  • Size the Gateway database for handles: the rate of calls that become handles, times the stored result size, times the handle lifetime.

Use rediss:// URLs with certificate verification. The Federal Information Processing Standards (FIPS)-oriented profile rejects plaintext Redis URLs.

Redis users for Surface databases

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. Both users need the @connection commands, PING, INFO, and MODULE LIST.

Plane Commands Keys
Data Plane FT.SEARCH, FT.AGGREGATE, FT.HYBRID, JSON.GET, HMGET Read access to each Surface key prefix only
Control Plane FT.CREATE, FT.DROPINDEX, FT._LIST, COMMAND INFO None

For example, for a Surface whose entities use the key prefixes provider: and location::

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
ACL SETUSER surface-cp on ><cp-password> resetkeys -@all +@connection +ping +info +module|list +ft.create +ft.dropindex +ft._list +command|info

On 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.

Credential storage

Backend What you provide
Encrypted Redis (default) Credential Redis and a keyring of base64-encoded 32-byte Advanced Encryption Standard (AES) keys.
HashiCorp Vault key-value (KV) version 2 A writer token for the Control Plane and a reader token for the Data Plane.
AWS Secrets Manager An Identity and Access Management (IAM) role for each plane through workload identity.

Network access

From To Purpose
MCP clients Data Plane, through your ingress at publicBaseURL Tool listing and calls.
Data Plane Every Upstream MCP server Tool calls.
Data Plane Identity Service Agent-key checks.
Identity Service Control Plane Grant validation.
Operators Control Plane and Identity Service Administration. Keep both private.

The 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. Your platform owns the ingress controller, network policy, Domain Name System (DNS) records, and Transport Layer Security (TLS) certificates.

Configure the ingress for Streamable HTTP:

  • Pass the MCP request headers through unchanged, including Authorization, X-Api-Key, Accept, Mcp-Protocol-Version, Mcp-Method, and Mcp-Name.
  • Pass the WWW-Authenticate response header, which MCP clients need to start identity provider sign-in.
  • Allow read timeouts longer than the slowest tool call.

Credentials and Secrets

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 for each credential and Configuration for each file reference.

Release artifacts and image tags

Component Image
Control Plane redislabs/iris-context-gateway-control:<control-plane-image-tag>
Data Plane redislabs/iris-context-gateway-data:<data-plane-image-tag>

The chart defaults to these repositories and pins the image tags that match its chart version. Leave image.repository and image.tag unset for a public install, and override them only to pull from a mirror.

Chart 1.0.0 pins both images to tag 1.0.0.

Air-gapped and private registry installs

For a disconnected installation, mirror both images to your registry with their tags unchanged, set each component's image.repository and image.tag, and set imagePullSecrets. Install from a downloaded chart package instead of the Redis AI Helm repository.

Helm values to review

Value Decide
tenantId One tenant per release, equal to the Identity Service's single tenant ID.
publicBaseURL The Data Plane origin MCP clients reach.
credentialStorage.provider redis, vault, or aws_secrets_manager.
security.profile standard (default) or fips.
RATE THIS PAGE
Back to top ↑