Installation and Setup

This walks you through the process of installing Redis Enterprise Software, which includes several steps:

1. Plan your deployment
2. Install Redis Software
3. Set up a multi-node cluster
4. Create your database

Here, you’ll learn how to perform each step.

Plan your deployment

Before installing Redis Software, you need to:

• Set up your hardware according to the hardware requirements.

  What hardware do I need?

  The hardware requirements for Redis Enterprise Software (RS) are different for development and production environments.

  • In a development environment you can test your application with a live RS database.

    If you want to test your application under production conditions, use the production environment requirements.

  • In a production environment you must have enough resources to handle the load on the database and recover from failures.

  Development environment

  You can build your development environment with non-production hardware, such as a laptop, desktop, or small VM or instance, and with these hardware requirements:

  Item	Description	Minimum Requirements	Recommended
  Nodes per cluster	You can install on one node but many features require at least two nodes.	1 node	>= 2 nodes
  RAM per node	The amount of RAM for each node.	4GB	>= 8GB
  Storage per node	The amount of storage space for each node.	10GB	>= 20GB

  Production environment

  We recommend these hardware requirements for production systems or for development systems that are designed to demonstrate production use cases:

  Item	Description	Minimum Requirements	Recommended
  Nodes per cluster	At least 3 nodes are required to support a reliable, highly available deployment that handles process failure, node failure, and network split events in a consistent manner.	3 nodes	>= 3 nodes (Must be an odd number of nodes)
  Cores* per node	RS is based on a multi-tenant architecture and can run multiple Redis processes (or shards) on the same core without significant performance degradation.	4 cores	>=8 cores
  RAM* per node	Defining your RAM size must be part of the capacity planning for your Redis usage.	15GB	>=30GB
  Ephemeral Storage	Used for storing replication files (RDB format) and cluster log files.	RAM x 2	>= RAM x 4
  Persistent Storage	Used for storing snapshot (RDB format) and AOF files over a persistent storage media, such as AWS Elastic Block Storage (EBS) or Azure Data Disk.	RAM x 3	In-memory >= RAM x 6 (except for extreme ‘write’ scenarios); Redis on Flash >= (RAM + Flash) x 5.
  Network	We recommend using multiple NICs per node where each NIC is >100Kbps, but RS can also run over a single 1Gbps interface network used for processing application requests, inter-cluster communication, and storage access.	1G	>=10G

  ^*Additional considerations:

  • Cores:
    • When the CPU load reaches a certain level, Redis Enterprise Software sends an alert to the operator.
    • If your application is designed to put a lot of load on your Redis database, make sure that you have at least one available core for each shard of your database.
    • If some of the cluster nodes are utilizing more than 80% of the CPU, consider migrating busy resources to less busy nodes.
    • If all the cluster nodes are utilizing over 80% of the CPU, consider scaling out the cluster by adding a node.
  • RAM:
    • Since Redis uses a relatively large amount of buffers (such as for slave communication, client communication, and pub/sub commands) make sure that at least 30% of the RAM is “unused” on each node.
    • If some of the cluster nodes are utilizing more than 65% of the RAM, you should look at migrating busy resources to less busy nodes.
    • If all the cluster nodes are utilizing over 70% of the RAM, you should look to scale out the cluster by adding a node.
    • Do not run other memory-consuming systems on the RS node.

• Choose the platform that you want to deploy on.

  What platforms are supported?

  Redis Enterprise Software (RS) is supported on several operating systems, cloud environments, and virtual environments.

  Note:

  Make sure your system meets these requirements:

  • Only 64-bit operating systems are supported.
  • You must install Redis Enterprise Software directly on the host, not through system cloning.
  • You must install on a clean host with no other applications running so that all RAM is allocated to the OS and RS only.
  • Linux distributions must be installed with at least “Minimal Install” configuration.

  Platform	Versions/Information
  Ubuntu	14.04 (Support ends on November 30, 2020) 16.04, 18.04 Server version is recommended for production installations. Desktop version is only recommended for development deployments.
  RHEL/CentOS 6	6.7, 6.8, 6.9 (Support ends on November 30, 2020)
  RHEL/CentOS 7	7.0, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.8, 7.9 Requires OpenSSL 1.0.2 and firewall configuration
  Oracle Linux 6	Based on the corresponding RHEL version
  Oracle Linux 7	Based on the corresponding RHEL version
  Amazon Linux	Version 1
  Docker	Docker images of Redis Enterprise Software are certified for Development and Testing only.
  Kubernetes, Pivotal Platform (PCF) and other orchestration and cloud environments	See the Platform documentation

  VMware

  Redis Enterprise is compatible with VMware, but make sure that you:

  • Configure your memory, CPU, network, and storage settings to allow for optimal Redis Enterprise performance.
  • Pin each Redis Enterprise shard to a specific ESX/ESXi host by setting the appropriate affinity rules.
  • If you must manually migrate a virtual machine to another host, follow the best practices for shard maintenance and contact support if you have questions.
  • Disable VMware VMotion because Redis Enterprise is not compatible with VMotion.
  • Don’t use VMware snapshots because Redis Enterprise cluster manages state dynamically, so a snapshot might not have the correct node and cluster state.

  In addition to Linux operating systems (Ubuntu, RHEL/CentOS, Oracle Linux), you can also deploy Redis Software to:

  • Amazon AWS AMI
  • Docker container (for development and testing only)
  • Pivotal Cloud Foundry
  • Kubernetes

• Open network ports in the firewall to allow connections to the nodes.

  What network ports are used

  To make sure that Redis Enterprise Software (RS) servers can pass necessary communications between them, we recommend that all RS servers have all of the ports listed here open between them.

  By default, the cluster assigns ports in the range of 10,000 - 19,999 to database endpoints. If you assign a specific port for a database when you create it, even outside of this range, the cluster only verifies that the assigned port is not already in use. You must manually update your firewall with the port for that new database endpoint.

  Ports and port ranges used by Redis Enterprise Software

  Protocol	Port	Connection Source	Description
  ICMP	*	Internal	For connectivity checking between nodes
  TCP	1968	Internal	Proxy traffic
  TCP	3333, 3334, 3335, 3336, 3337, 3338, 3339, 36379, 36380	Internal	Cluster traffic
  TCP	8001	Internal, External	Traffic from application to RS Discovery Service
  TCP	8002, 8004	Internal	System health monitoring
  TCP	8443	Internal, External	Secure (HTTPS) access to the management web UI
  TCP	8444, 9080	Internal	For nginx <-> cnm_http/cm traffic
  TCP	9081	Internal, Active-Active	For Active-Active management
  TCP	8070, 8071	Internal, External	For metrics exported and managed by nginx
  TCP	9443 (Recommended), 8080	Internal, External, Active-Active	REST API traffic, including cluster management and node bootstrap
  TCP	10000-19999	Internal, External, Active-Active	Database traffic
  TCP	20000-29999	Internal	Database shard traffic
  UDP	53, 5353	Internal, External	DNS/mDNS traffic

  Connection sources are:

  • Internal - The traffic is from other cluster nodes
  • External - The traffic is from client applications or external monitoring resources
  • Active-Active - The traffic is from clusters that host Active-Active databases

  Changing the management web UI port

  If for any reason you want to use a custom port for the RS Web UI instead of the default port (8443), you can change the port. Before you change the RS Web UI port, make sure that the new port is not in use by another process.

  Note:

  After you change the RS Web UI port, when you add a new node to the cluster you must connect to the web UI with the custom port number:

  https://newnode.mycluster.example.com:<nonstandard-port-number>

  To change the default port for the RS Web UI, on any node in the cluster run:

  rladmin cluster config cm_port <new-port>
  

  Disabling HTTP support for API endpoints

  To harden deployments, you can disable the HTTP support for API endpoints that is supported by default. Before you disable HTTP support, make sure that you migrate any scripts or proxy configurations that use HTTP to the encrypted API endpoint to prevent broken connections. After you disable HTTP support, traffic sent to the unencrypted API endpoint is blocked.

  To disable HTTP support for API endpoints, run:

  rladmin cluster config http_support disabled
  

• Configure cluster DNS so that cluster nodes can reach each other by DNS names.

  How do I configure DNS for my cluster?

  DNS is critical to the default operation of Redis Enterprise Software (RS) deployments. This can be altered, but instead using the Discovery Service, which utilizes pure IP-based connectivity as it is compliant with the Redis Sentinel API.

  As part of the high availability capabilities in RS, each node includes a small DNS server for managing various internal cluster functionalities, such as automatic failover or automatic migration. Therefore, the node on which you are provisioning RS should not run any other DNS server except for the one included with the RS installation. The existence of another DNS server on the same machine can cause unexpected behavior in RS.

  Cluster name (FQDN) and connection management

  When connecting to the cluster for administration or connecting to databases for data access, there are 2 options:

  • URL-based Connections - URL-based connections require DNS setup for resolution of the cluster name (FQDN) when connecting to the cluster for administration or connecting to databases for data access. As the topology of the cluster changes and new nodes are added or existing nodes are removed from the cluster, DNS records may need to be modified. However, with URL-based connections, applications simply have to remember the URL for the cluster or the database.
  • IP-based Connections - IP-based connections do not require DNS setup and instead use IP addresses of the nodes in the cluster for connecting to the cluster for administration or data access. As the topology of the cluster changes and new nodes are added or existing nodes are removed from the cluster, no DNS records need to be modified. However, administrators and applications connecting to the cluster and to the databases need to maintain the IP address of at least one node in the cluster to discover and access the cluster topology.

  URL-based connections and how to set up cluster name (FQDN)

  The Fully Qualified Domain Name (FQDN) is the unique cluster identifier that enables clients to connect to the different components that are part of the Redis Enterprise Software. The FQDN is a crucial component of the high-availability mechanism in RS because it is used by the internal DNS to enable the automatic and transparent failover of nodes, databases shards, and endpoints, by automatically updating their IP addresses.

  Note:

  Setting the cluster’s FQDN is a one-time operation. After the FQDN is set it cannot be updated.

  The FQDN must always comply with the IETF’s RFC 952 standard and section 2.1 of the RFC 1123 standard.

  Naming the cluster FQDN

  You have two options for naming the cluster FQDN:

  DNS

  Use this option if you already have your own domain, would like to make the cluster part of your domain and are able to update the DNS.

  1. Make sure that the cluster and at least one node (preferably all nodes) in the cluster are correctly configured in the DNS with the appropriate NS entries.

     For example:

      - Your domain is: mydomain.com
      - You would like to name the Redis Enterprise Software cluster:
          redislabscluster
      - You have three nodes in the cluster:
         - node1 with IP 1.1.1.1
         - node2 with IP 2.2.2.2
         - node3 with IP 3.3.3.3
     

  2. In the FQDN field, enter the value redislabscluster.mydomain.com and add the following records in the DNS for mydomain.com:

     redislabscluster.mydomain.com         NS   node1.redislabscluster.mydomain.com
                                                node2.redislabscluster.mydomain.com
                                                node3.redislabscluster.mydomain.com 
     node1.redislabscluster.mydomain.com   A    1.1.1.1
     node2.redislabscluster.mydomain.com   A    2.2.2.2
     node3.redislabscluster.mydomain.com   A    3.3.3.3
     

  Zero-configuration using mDNS (Development option only)

  Note:

  mDNS is not supported for use with production environments and should only be used in development or test environments.

  mDNS (Multicast DNS) is a standard protocol that provides DNS-like name resolution and service discovery capabilities to machines on local networks with minimal to no configuration. Because not all clients support mDNS, ensure first that the clients that are connecting to the cluster actually have mDNS support, and that the network infrastructure permits mDNS/multi-casting between them and the cluster nodes.

  Configuring the cluster to support mDNS requires you to assign the cluster a .local name.

  For example, if you want to name the Redis Enterprise Software cluster redislabscluster, enter redislabscluster.local in the FQDN field.

  When using the DNS or mDNS option, failover can be done transparently and the DNS is updated automatically to point to the IP of the new master.

  IP-based connections

  When you use the IP-based connection option, the FQDN does not need to have any special format because clients use IP addresses instead of hostnames to access the databases so you are free to choose whatever name you want. Using the IP-based connection option does not require any DNS configuration either.

  To administer the cluster you do need to know the IP address of at least one of the nodes in the cluster. Once you have the IP address, you can simply connect to port number 8443 (for example: https://10.0.0.12:8443). However, as the topology of the cluster changes and node with the given IP address is removed, you need to remember the IP address of another node participating in this cluster to connect to the admin console and manage the cluster.

  Applications connecting to RS databases for data access have the same constraints. When using the IP-based connection method, you can use the Discovery Service to discover the database endpoint for a given database name as long as you have an IP address for at least one of the nodes in the cluster. The API used for discovery service is compliant with the Redis Sentinel API.

  You can find a simple example of URL and IP-based connection in the “Testing Connectivity to your Database” section of Creating a new database.

Download the installation package

To download the installation package for any of the supported platforms:

1. Go to the Redis Labs download page.
2. Sign in with your Redis Labs credentials or create a new account.
3. In the Downloads section for Redis Enterprise Software, select the installation package for your platform then select Go.

Prepare to install on Linux

Before installing, review these notes:

• Review the security considerations for your deployment.

• If you want to use Redis on Flash (RoF) for your databases, review the prerequisites, storage requirements, and other considerations for RoF databases and prepare and format the flash memory.

  To prepare and format the flash memory:

  Run:

  sudo /opt/redislabs/sbin/prepare_flash.sh
  

  This command finds all of the unformatted disks and mounts them as RAID partitions in /var/opt/redislabs/flash.

  To verify the disk configuration, run:

  sudo lsblk
  

• Disable Linux swap on all cluster nodes.

• Make sure that you have root-level access to each node, either directly or with sudo.

• If you require the redislabs UID (user ID) and GID (group ID) numbers to be the same on all the nodes, create the redislabs user and group with the required numbers on each node.

• When port 53 is in use, the installation fails. This is known to happen in default Ubuntu 18.04 installations in which systemd-resolved (DNS server) is running. To work around this issue, change the system configuration to make this port available before installation.

  Example steps to resolve the port 53 conflict:

  1. Run: sudo vi /etc/systemd/resolved.conf
  2. Add DNSStubListener=no as the last line in the file and save the file.
  3. Run: sudo mv /etc/resolv.conf /etc/resolv.conf.orig
  4. Run: sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
  5. Run: sudo service systemd-resolved restart

• Make sure that the OS is not using ports in the range that Redis assigns to databases.

  We recommend that you restrict the OS from using Redis ports range in /etc/sysctl.conf with `net.ipv4.ip_local_port_range = 30000 65535’.

Install on Linux

After you download the .tar file installation package, install the package on one of the nodes in the cluster.

To install from the CLI:

1. Copy the installation package to the node.

   How do I know the package is authentic?

   For Ubuntu DEB packages and RHEL RPM packages, you can use the GPG key file to confirm authenticity of the package:

   • For Ubuntu:
     1. Import the key with: gpg --import <path to GPG key>
     2. Verify the package signature with: dpkg-sig --verify <path to installation package>
   • For RHEL:
     1. Import the key with: rpm --import <path to GPG key>
     2. Verify the package signature with: rpm --checksig <path to installation package>

2. On the node, change to the directory where the installation package is and extract the installation files:

   tar vxf <tarfile name>
   

3. To install RS, run:

   sudo ./install.sh
   

   Note:

   • The RS files are installed in the default file locations.
   • By default, Redis Software runs on the OS as the redislabs user and redislabs group. If needed, you can specify a different user and group during the installation.
   • You must either be logged in as the root user or use sudo to run the install process.

4. Answer the installation questions when shown to complete the installation process, including the rlcheck installation verification.

   Note:

   To install without answering the installation questions, either:

   • Run ./install.sh -y to answer yes to all of the questions.
   • Use an answer file to answer the installation questions.

   When the installation completes sucessfully, the IP address of the admin console is diplayed:

   Summary:
   -------
   ALL TESTS PASSED.
   2017-04-24 10:54:15 [!] Please logout and login again to make
   sure all environment changes are applied.
   2017-04-24 10:54:15 [!] Point your browser at the following
   URL to continue:
   2017-04-24 10:54:15 [!] https://<your_ip_here>:8443
   

   Redis Software is now installed on the node. Repeat this process for each node in the cluster.

5. Create or join an existing Redis Software cluster.

6. Create a database.

   For geo-distributed Active-Active replication, create an Active-Active database.

Custom installation directories

sudo ./install.sh --install-dir <path> --config-dir <path> --var-dir <path>

• Redis Software is installed with the system user and group redislabs:redislabs
  How can I install using specific system user and group?

  By default, Redis Software is installed with the user:group redislabs:redislabs. During the installation you can specify the OS user and group, which owns all Redis Software processes. If you specify the user only, then installation is run with the primary group that the user belongs to.

  Note:

  • Custom installation user is supported on RedHat Enterprise Linux version 7.
  • When you install with custom directories, the installation does not run as an RPM file.
  • You must create the user and group befor attempting to install Redis Software.
  • You can specify an LDAP user as the installation user.

  To specify the user and group, run:

  sudo ./install.sh --os-user <user> --os-group <group>
  

To install on Linux from the CLI:

1. Copy the installation package to the node.

   scp redislabs-X.Y.Z-32-bionic-amd64.tar <username>@<ip_address>:/home
   

2. On the node, change to the directory where the installation package is and extract the installation files:

   tar vxf <tarfile name>
   

3. To install, run:

   sudo ./install.sh
   

   Note:

   • Files are installed in the default file locations.
   • Redis Software is installed and run under the redislabs user and redislabs group. You can also specify a different user during the installation.
   • You must either be logged in as the root user or use sudo to run the install process.

4. Answer the installation questions when shown to complete the installation process, and run rlcheck to verify the installation.

   What are the installation questions?

   The questions that the installation process asks are:

   • Linux swap file - Swap is enabled. Do you want to proceed? [Y/N]?

     We recommend that you disable Linux swap in the operating system configuration to give Redis Software control of the memory allocation.

   • Automatic OS tuning - Do you want to automatically tune the system for best performance [Y/N]?

     To allow the installation process to optimize the OS for Redis Software, answer Y. The installation process prompts you for additional information.

     The /opt/redislabs/sbin/systune.sh file contains details about the tuning process.

   • Network time - Do you want to set up NTP time synchronization now [Y/N]?

     Redis Software requires that all cluster nodes have synchronized time. You can either let the installation process configure NTP or you can configure NTP manually.

   • Firewall ports - Would you like to open RedisLabs cluster ports on the default firewall zone [Y/N]?

     Redis Software requires that all nodes have specific network ports open. You can either:

     • Answer Y to let the installation process open these ports.
     • Answer N and configure the firewall manually for RHEL/CentOS firewall.
     • Answer N and configure the firewall on the node manually for your OS.

   • Installation verification (rlcheck) - Would you like to run rlcheck to verify proper configuration? [Y/N]?

     We recommend running the rlcheck installation verification to make sure that the installation completed successfully. If you want to run this verification at a later time, you can run: /opt/redislabs/bin/rlcheck

   How can I do a silent install of RS?

   To install without answering the installation questions, either:

   • Run ./install.sh -y to answer yes to all of the questions.
   • Prepare an answer file and use it to do a silent installation.

   To install with an answer file:

   1. Prepare the answer file with the answers to the installation questions.

      The answer file can contain any of the parameters for the installation questions and indicate the answer for the question with yes or no.

      For example:

      ignore_swap=no
      systune=yes
      ntp=no
      firewall=no
      rlcheck=yes
      

      If you use systune=yes, the installation answers yes to all of the system tuning questions.

   2. Run the install script with -c and the path to the answer file.

      For example:

      ./install.sh -c /home/user/answers
      

   When install suceeds, the IP address of the admin console is shown:

   Summary:
   -------
   ALL TESTS PASSED.
   2017-04-24 10:54:15 [!] Please logout and login again to make
   sure all environment changes are applied.
   2017-04-24 10:54:15 [!] Point your browser at the following
   URL to continue:
   2017-04-24 10:54:15 [!] https://<your_ip_here>:8443
   

   Redis Software is now installed on the node. Repeat this process for each node in the cluster.

5. Create or join an existing RS cluster.

6. Create a database.

   For geo-distributed Active-Active replication, create an Active-Active database.

Set up the new cluster

A Redis Enterprise Software (RS) cluster typically consists of several nodes. For production deployments, Redis Labs recommends an uneven number of nodes, with a minimum of three.

To set up a new cluster, you must first install the Redis Enterprise Software package and then set up the cluster as described below. After the cluster is created you can add multiple nodes to the cluster.

To create a cluster:

1. In a browser, navigate to https://<name or IP address of the machine with RS installed>:8443. For example, if you installed RS on a machine with IP address 10.0.1.34, then navigate to https://10.0.1.34:8443.

   Note:

   • The RS management UI uses a self-signed SSL/TLS encryption.
   • If the machine has both an internal IP address and an external IP address, use the external IP address to access the setup UI.

2. Click Setup.

3. In the Node Configuration page that appears:

   1. Enter a path for Persistent storage, or leave the default path.

   2. Enter a path for Ephemeral storage, or leave the default path.

   3. If you want to enable Redis on Flash, select the Enable flash storage support checkbox and enter the path to the Flash storage.

   4. If your machine is configured to have multiple IP addresses, the section IP Addresses Usage is shown. Use the IP Addresses Usage section to assign a single IPv4 type address for internal traffic and multiple IPv4/IPv6 type addresses for external traffic.

   5. In Cluster configuration, select Create new cluster.

   6. In Cluster name (FQDN), enter a unique name for the cluster. Also, make sure that you look at the [instructions for setting up DNS](/rs/installing-upgrading/configuring/cluster-dns/ to make sure your cluster is reachable by name.

   7. Choose whether to Enable private & public endpoints support.

   8. Choose whether to Enable rack-zone awareness. Enabling rack-zone awareness requires setting the Rack-zone ID for the node.

   9. Click Next.

4. If you purchased a cluster key, use the Cluster authentication page to enter the key. Otherwise, you get the trial license by default. Read the product Terms and Conditions and click Next.

5. Click OK to confirm that you are aware of the replacement of the HTTPS SSL/TLS certificate on the node, and proceed through the browser warning.

6. In the Set admin credentials fields, enter the credentials of the cluster administrator.

7. Click Next.

After a short wait, your cluster is created and you can log in to the RS admin console.

Add nodes to the cluster

When you install Redis Enterprise Software (RS) on the first node of a cluster, you create the new cluster. After you install the first node, you can add more nodes to the cluster.

To add a node in RS:

1. Install the RS installation package on a clean installation of a supported operating system.

2. To connect to the RS management UI of the new RS installation, go to: <https://URL or IP address:8443>

   For example, if you installed RS on a machine with IP address 10.0.1.34, go to https://10.0.1.34:8443.

   Tip -

   The RS management UI uses SSL encryption with a default certificate. You can also replace the TLS certificate with a custom certificate.

3. To start configuring RS, click Setup.

4. Configure the RS network and storage settings:

   1. You can enter a path for Persistent storage, or leave the default path.
   2. You can enter a path for Ephemeral storage, or leave the default path.
   3. If you want to enable Redis on Flash, select Enable flash storage support and enter the path to the Flash storage to use as RAM extension.
   4. If your machine has multiple IP addresses, in IP Addresses Usage assign a single IPv4 type address for internal traffic and multiple IPv4/IPv6 type addresses for external traffic.

5. Join the new RS node to the cluster:

   1. In Cluster configuration, select Join cluster.

   2. Enter the internal IP address or DNS name of a node that is a cluster member.

      If the node only has one IP address, enter that IP address.

   3. Enter the credentials of the cluster administrator.

      The cluster administrator is the user account that you create when you configure the first node in the cluster.

6. Click Next.

   If the cluster is configured to support rack-zone awareness, you are redirected to a page in which you must set the Rack-zone ID for the new node.

The node is added to the cluster. You can see it in the list of nodes in the cluster.

If you see an error when you add the node, try adding the node again.

Next steps

Now that your cluster is set up with nodes, you can:

• Add users to the cluster with specific permissions.
• Create databases to use with your applications.