{
  "id": "oss-cluster-api",
  "title": "Enable OSS Cluster API",
  "url": "https://redis.io/docs/latest/operate/rs/8.0/databases/configure/oss-cluster-api/",
  "summary": "",
  "content": "\nReview [OSS Cluster API](https://redis.io/docs/latest/operate/rs/clusters/optimize/oss-cluster-api) to determine if you should enable this feature for your database.\n\n## Prerequisites\n\nThe OSS Cluster API is supported only when a database meets specific criteria.\n\nThe database must:\n\n- Use the standard [hashing policy](https://redis.io/docs/latest/operate/rs/databases/durability-ha/clustering#supported-hashing-policies).\n- Have the [proxy policy](https://redis.io/docs/latest/operate/rs/databases/configure/proxy-policy) set to either _All primary shards_ or _All nodes_.\n\nIn addition, the database must _not_:\n\n- Use node `include` or `exclude` in the proxy policy.\n- Use [RedisTimeSeries](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/timeseries) or [RedisGears](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/deprecated-features/gears-v1) modules.\n\nThe OSS Cluster API setting applies to individual databases instead of the entire cluster.\n\n\nFor Kubernetes deployments, see [Enable cluster-aware clients (OSS Cluster API)](https://redis.io/docs/latest/operate/kubernetes/networking/cluster-aware-clients).\n\n\n## Enable OSS Cluster API support\n\nYou can use the Cluster Manager UI, the `rladmin` utility, or the REST API to enable OSS Cluster API support for a database.\n\nWhen you enable OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change.\n\n**Cluster Manager UI:**\n\nWhen you use the Cluster Manager UI to enable the OSS Cluster API, it automatically configures the [prerequisites](https://redis.io/docs/latest/operate/rs/databases/configure/oss-cluster-api#prerequisites).\n\nTo enable the OSS Cluster API for an existing database in the Cluster Manager UI:\n\n1. From the database's **Configuration** tab, click **Edit**.\n\n1. Expand the **Clustering** section.\n\n1. Enable **Sharding**.\n\n1. Select **OSS Cluster API**.\n\n    \u003cimg src=\"../../../../../images/rs/screenshots/databases/config-clustering-oss-cluster-api-7-22.png\" alt=\"Use the *OSS Cluster API* setting to enable the API for the selected database.\"\u003e\n\n1. Click **Save**.\n\nYou can also use the Cluster Manager UI to enable the setting when creating a new database.\n\n**rladmin:**\n\nYou can use the [`rladmin` utility](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/) to enable the OSS Cluster API for Redis Software databases, including Replica Of databases.\n\nFor Active-Active (CRDB) databases, [use the crdb-cli utility](#active-active-databases).\n\nEnsure the [prerequisites](https://redis.io/docs/latest/operate/rs/databases/configure/oss-cluster-api#prerequisites) have been configured.  Then, enable the OSS Cluster API for a Redis database from the command line:\n\n```sh\n$ rladmin tune db \u003cdatabase name or ID\u003e oss_cluster enabled\n```\n\nTo determine the current setting for a database from the command line, use `rladmin info db` to return the value of the `oss_cluster` setting.\n\n```sh\n$ rladmin info db test | grep oss_cluster:\n  oss_cluster: enabled\n```\n\nThe OSS Cluster API setting applies to the specified database only; it does not apply to the cluster.\n\n**REST API:**\n\nYou can enable the OSS Cluster API when you [create a database](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#post-bdbs-v1) using the REST API:\n\n```sh\nPOST /v1/bdbs\n{ \n  \"oss_cluster\": true,\n  // Other database configuration parameters\n}\n```\n\nTo enable the OSS Cluster API for an existing database, you can use an [update database configuration](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bdbs#put-bdbs) REST API request:\n\n```sh\nPUT /v1/bdbs/\u003cdatabase-id\u003e\n{ \"oss_cluster\": true }\n```\n\n\n\n### Active-Active databases\n\nThe OSS Cluster API setting applies to all instances of the Active-Active database across participating clusters. To enable the OSS Cluster API for Active-Active databases, use the [Cluster Manager UI](#cluster-manager-ui) or the [`crdb-cli`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli) utility.\n\n**Cluster Manager UI:**\n\nWhen you use the Cluster Manager UI to enable the OSS Cluster API, it automatically configures the [prerequisites](https://redis.io/docs/latest/operate/rs/databases/configure/oss-cluster-api#prerequisites).\n\nTo enable the OSS Cluster API for an existing Active-Active database in the Cluster Manager UI:\n\n1. From the database's **Configuration** tab, click **Edit**.\n\n1. Expand the **Clustering** section.\n\n1. Sharding must be enabled during Active-Active database creation.\n\n1. Select **OSS Cluster API**.\n\n    \u003cimg src=\"../../../../../images/rs/screenshots/databases/config-clustering-oss-cluster-api-active-active-7-22.png\" alt=\"Use the *OSS Cluster API* setting to enable the API for the selected database.\"\u003e\n\n1. Click **Save**.\n\nYou can also use the Cluster Manager UI to enable the setting when creating a new database.\n\n**crdb-cli:**\n\nTo create an Active-Active database and enable the OSS Cluster API with `crdb-cli`:\n\n```sh\n$ crdb-cli crdb create --name \u003cname\u003e \\\n    --memory-size 10g --port \u003cport\u003e \\\n    --sharding true --shards-count 2  \\\n    --replication true --oss-cluster true --proxy-policy all-master-shards \\\n    --instance fqdn=\u003cfqdn\u003e,username=\u003cuser\u003e,password=\u003cpass\u003e \\\n    --instance fqdn=\u003cfqdn\u003e,username=\u003cuser\u003e,password=\u003cpass\u003e \\\n    --instance fqdn=\u003cfqdn\u003e,username=\u003cuser\u003e,password=\u003cpass\u003e\n```\n\nSee the [`crdb-cli crdb create`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/crdb-cli/crdb/create) reference for more options.\n\nTo enable the OSS Cluster API for an existing Active-Active database with `crdb-cli`:\n\n1. Obtain the `CRDB-GUID` for the new database:\n\n    ```sh\n    $ crdb-cli crdb list\n    CRDB-GUID    NAME   REPL-ID  CLUSTER-FQDN\n    \u003cCRDB-GUID\u003e  Test   4        cluster1.local\n    ```\n\n1. Use the `CRDB-GUID` to enable the OSS Cluster API:\n\n    ```sh\n    $ crdb-cli crdb update --crdb-guid \u003cCRDB-GUID\u003e \\\n        --oss-cluster true\n    ```\n\n\n\n## Change preferred IP type\n\nBy default, using [`CLUSTER SLOTS`](https://redis.io/docs/latest/commands/cluster-slots) and [`CLUSTER SHARDS`](https://redis.io/docs/latest/commands/cluster-shards) in a Redis Software cluster exposes the internal IP addresses for databases with the OSS Cluster API enabled.\n\nTo use external IP addresses instead of internal IP addresses, run the following [`rladmin tune db`](https://redis.io/docs/latest/operate/rs/references/cli-utilities/rladmin/tune#tune-db) command for each affected database:\n\n```sh\n$ rladmin tune db db:\u003cdatabase-id\u003e oss_cluster_api_preferred_ip_type external\n```\n\n## Turn off OSS Cluster API support\n\nTo deactivate OSS Cluster API support for a database, use one of the following methods:\n\n**Cluster Manager UI:**\n\nTo turn off the OSS Cluster API for standard databases or Active-Active databases in the Cluster Manager UI:\n\n1. From the database's **Configuration** tab, click **Edit**.\n\n1. Expand the **Clustering** section.\n\n1. Clear the **OSS Cluster API** checkbox.\n\n1. Click **Save**.\n\n**rladmin:**\n\nFor standard databases, including Replica Of, you can use `rladmin` to turn off the OSS Cluster API:\n\n```sh\n$ rladmin tune db \u003cname or ID\u003e oss_cluster disabled\n```\n\n**crdb-cli:**\n\nFor Active-Active databases, you can use `crdb-cli` to turn off the OSS Cluster API:\n\n```sh\n$ crdb-cli crdb update --crdb-guid \u003cCRDB-GUID\u003e \\\n        --oss-cluster false\n```\n\n\n\nWhen you turn off OSS Cluster API support for an existing database, the change applies to new connections but does not affect existing connections. Clients must close existing connections and reconnect to apply the change.\n\n## Multi-key command support\n\nWhen you enable the OSS Cluster API for a database, \n[multi-key commands](https://redis.io/docs/latest/operate/rc/databases/configuration/clustering#multikey-operations) are only allowed when all keys are mapped to the same slot.\n\nTo verify that your database meets this requirement, make sure that the `CLUSTER KEYSLOT` reply is the same for all keys affected by the multi-key command.  To learn more, see [multi-key operations](https://redis.io/docs/latest/operate/rs/databases/durability-ha/clustering#multikey-operations).\n",
  "tags": ["docs","operate","rs"],
  "last_updated": "2026-07-23T12:00:25-05:00"
}