Oracle Cloud Infrastructure Documentation

Creating an OCI Cache Cluster

Create a standalone cluster, a secondary cluster for cross-region replication, or a cluster from an existing backup.

Each non-sharded cluster includes a primary node and, optionally one or more data nodes, based on the options you specify when you create the cluster.
Note

For reliability, we recommend using a cluster with at least three nodes. Clusters with one or two nodes are not reliable.
Each sharded cluster consists of at least three shards, with each shard containing one primary node and, optionally, one to four data nodes, depending on your configuration. The maximum number of nodes per sharded cluster is 100. For more information, see OCI Cache Sharded Clusters.
Caution

You can create clusters only in subnets that don't have IPv6 enabled. If you select a subnet with IPv6 enabled, cluster creation fails.

A secondary cluster replicates data from a primary cluster in another OCI region. The secondary cluster accepts read operations but doesn't accept write operations while it participates in a cross-region replication relationship. For more information, see OCI Cache Cross-Region Replication.

  • On the Clusters list page, select Create cluster. If you need help finding the list page, see Listing OCI Cache Clusters.

    Creating an OCI Cache cluster involves the following pages:

    Run each of the following workflows in order. You can return to a previous page by selecting Previous.

    1. Creation type

    On the Creation type page, select how to create the OCI Cache cluster in one of the following ways:

    • OCI Cache cluster: Create a standalone cluster.
    • OCI Cache cluster from backup: Creates a cluster from an existing backup or an imported snapshot.
    • Secondary cluster: Create a cluster that replicates data from a primary cluster in another region.

    To create a standalone cluster, select OCI Cache cluster, and then select Next.

    To create a secondary cluster, select Secondary cluster, and then enter the following information:

    • Select the region that contains the primary cluster.
    • Select the compartment that contains the primary cluster.
    • From the list of clusters, select the cluster for replication.

    The primary cluster must be in the Active state, must not already have a secondary cluster, and must not have another operation in progress.

    Note

    To create a secondary cluster, you need permissions to manage the new secondary cluster and to perform replication operations on the selected primary cluster. For details, see OCI Cache IAM Policies.

    Select Next.

    To create a cluster from an existing backup, see Restoring an OCI Cache Cluster from a Backup. To create a cluster by importing a snapshot from Object Storage, see Importing Backups.

    2. Configure cluster

    On the Configure cluster page, provide the basic information for the cluster:

    • Name: Accept the prefilled name or enter a descriptive name for the cluster.

      The cluster name can include only letters, numbers, dashes, periods, and underscores.

    • Create in compartment: Select the compartment for the cluster.
    • OCI Cache engine version: Select an available engine version.
      Note

      For a secondary cluster, the engine version matches the primary cluster and can't be changed.
    • Select configuration: Select a custom or default configuration for the selected engine version. If you don't select a configuration, OCI Cache applies the latest default configuration for the engine version.

      For a secondary cluster, select a custom configuration that meets the cross-region replication requirements. The primary and secondary configuration sets must use the same values for the reserved-memory-percentage and maxmemory-policy parameters. If you set databases to a value other than the default of 16, you must use the same value in both configuration sets.

      Note

      Configurations and ACL users are not copied from the primary cluster. Keep the cluster configuration consistent between the primary and secondary clusters.

      As a best practice, use the same ACL users and maintain consistent ACL permissions on both clusters when possible. This simplifies management and helps prevent authorization issues after a cluster role change. You can use different ACL users on the secondary cluster if required by your application.

    Tagging

    (Optional) In the Tags section, add one or more tags to the cluster. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.

    Zero Trust Packet Routing security

    (Optional) If your tenancy and environment have the Zero Trust Packet Routing permissions to create security attributes for a cluster, you might also have permissions to apply these attributes to that cluster. To apply a security attribute, you must have permissions to use the security attribute namespace. For more information about security attributes and security attribute namespaces, see Zero Trust Packet Routing. If you're not sure whether to apply security attributes, skip this option or ask an administrator. You can apply security attributes later.

    To apply security attributes to a cluster, select Show security attributes and then select Add security attribute.

    Enter the following information:
    • Security attribute namespace: Select a security attribute namespace from the list. This list contains those security attribute namespaces already configured. See Creating a Security Attribute Namespace for more information.
    • Security attribute key: Select a key from the list.
    • Security attribute value: Select a value for the corresponding key from the list.

    Select the Add security attribute button to add another attribute (to a maximum of three).

    Select Next.

    3. Configure nodes

    On the Configure nodes page, select the cluster mode (non-sharded or sharded) and configure the cluster node settings.

    • Cluster mode: Select one of the following modes:
      • Non-sharded: A single primary node and up to four replica nodes for reliable performance and manual or on-demand backup support.
        Note

        For optimal high availability, configure a non-sharded cluster with one primary node and two replica nodes.
      • Sharded: Distribute data across multiple shards to increase capacity and speed up processing. Sharded clusters are ideal for large or high-traffic datasets.
      Note

      For a secondary cluster, the cluster mode is set to Non-sharded and can't be changed.
    • Node count (Non-sharded only): Enter a value from 1 to 5.
      Note

      You can configure a different node count for the secondary cluster.
    • Shard count (Sharded mode only): Enter an odd number between 3 and 99.
    • Nodes per shard (Sharded mode only): Enter a value from 1 to 5.
    • Memory (GB) per node: Enter a value from 2 to 500.
      Note

      For a secondary cluster, memory per node is set to match the primary cluster and can't be changed.

      For cross-region replication, ensure that memory per node is at least 8 GB for both the primary and secondary clusters.

    A running tally at the bottom of the page displays the total node count, total memory (in gigabytes), and bandwidth (in gigabits per second per node). These numbers are updated as you change the settings in the page.

    Select Next.

    4. Configure networking

    On the Configure networking page, configure the network resources for the cluster.

    Note

    OCI Cache manages the private cross-region connectivity for replication. You don't need to create a remote peering connection.

    VCN

    Select one of the following options for the VCN:

    • Select existing virtual cloud network: Select a VCN from the current compartment.
    • New virtual cloud network name: Enter the following information:
      • New virtual cloud network name: Accept the default name or enter a friendly name for the new VCN.
      • Create in compartment: Select the compartment for the new VCN.
    • Enter subnet OCID: Enter the OCID of the subnet you want. The VCN is automatically determined based on the subnet you select.

    Subnet

    Subnet settings depend on the VCN option you select. You cannot change the cluster's subnet after you create the cluster.

    Before you create the cluster, ensure that the selected subnet has enough free IP addresses available.

    • For non-sharded clusters, you need at least the node count plus two additional addresses (for the primary endpoint and the read endpoint).
    • For sharded clusters, you need at least the node count plus one additional address (for the discovery endpoint).

    Select one of the following subnet options:

    • Select existing subnet: Select a subnet from the current compartment.
    • Create new public subnet: Enter the following information:
      • Create new public subnet: Accept the default name or enter a friendly name for the subnet.
      • Create in compartment: Select the compartment for the subnet.
      • CIDR block: Enter the CIDR block IP addresses, for example, 10.0.0.0/16, 209.128.0.0/10
    • Enter subnet OCID: Enter the OCID of the subnet you want to use.

    Network security group

    (Optional) Add one or more network security groups (NSGs) available for the selected VCN. The NSG must contain a rule that allows traffic to the cluster's VNIC using the required protocols and ports. For more information, see Security Rule for Connecting to Clusters.

    Select Add network security group and select an available NSG in the current compartment from the list.

    Select Next.

    5. Review and create

    On the Review and create page, review your settings. Edit or return to previous pages to make changes. When your settings are correct, select Create cluster.

    The new cluster appears on the Clusters list page.

    If you selected Secondary cluster, the new cluster is assigned the Secondary role, and the selected source cluster is assigned the Primary role. Initial synchronization begins. The secondary cluster is read-only and accepts only read operations.

    To verify the secondary cluster, on the cluster details page, confirm the cluster role is secondary, the source cluster is shown as the associated primary cluster, and the cluster is in the Active state. Initial synchronization starts after the cluster is created.

  • Use the oci redis redis-cluster redis-cluster create command and required parameters to create a cluster:

    oci redis redis-cluster redis-cluster create --compartment-id <compartment_OCID> --display-name <text> --node-count <node_count> --node-memory-in-gbs <memory in gigabytes> --software-version <text> --subnet-id <subnet_OCID> [OPTIONS]

    To create a secondary cluster:

    1. Create a custom OCI Cache configuration that meets the cross-region replication requirements. For more information, see Creating an OCI Cache Configuration.
    2. Use the oci redis redis-cluster redis-cluster create command. Specify the primary cluster and the custom configuration to associate with the secondary cluster. 
    oci redis redis-cluster redis-cluster create \
  --compartment-id <compartment_OCID> \
  --display-name <text> \
  --oci-cache-config-set-id <config_set_OCID> \
  --primary-cluster-id <primary_cluster_OCID> \
  --cluster-mode NONSHARDED \
  --node-count <node_count> \
  --node-memory-in-gbs <memory_in_gigabytes> \
  --software-version <text> \
  --subnet-id <subnet_OCID> \
  [OPTIONS]
    For information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see the CLI Command Reference.
  • For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

    Run the CreateRedisCluster operation to create a cluster.

    To create a secondary cluster:

    1. Create a custom OCI Cache configuration set that includes the required cross-region replication values.
    2. Run the CreateRedisCluster operation. Specify the primary cluster and the custom configuration set to associate with the secondary cluster.

  • To create a cluster as a secondary:

    1. Create a custom OCI Cache configuration that meets the cross-region replication requirements. For more information, see Creating an OCI Cache Configuration.
    2. In the oci_redis_redis_cluster resource configuration, specify the primary_cluster_id and oci_cache_config_set_id parameters.

    Sample Terraform Configuration

    resource "oci_redis_redis_cluster" "secondary_cluster" {
  # Required
  compartment_id     = var.compartment_id
  display_name       = var.redis_cluster_display_name
  node_count         = var.redis_cluster_node_count
  node_memory_in_gbs = var.redis_cluster_node_memory_in_gbs
  software_version   = var.redis_cluster_software_version
  subnet_id          = oci_core_subnet.test_subnet.id

  # Required for a secondary cluster
  primary_cluster_id      = var.primary_cluster_id
  oci_cache_config_set_id = var.oci_cache_config_set_id
}

    The custom configuration associated with the secondary cluster must meet the cross-region replication requirements and have values compatible with the configuration associated with the primary cluster. For more information, see the Considerations for Cross-Region Replication.