Elestio KeyDB Cluster Terraform module

Benefits of a KeyDB cluster

A Multi-Master KeyDB cluster is a great option to ensure high availability, it allows for easy scalability to meet changing demands without replacing the entire system. It can handle more requests without slowing down or crashing, and provides fault tolerance to ensure that the system remains operational.

A multi-master scenario means that one node can be taken offline (e.g. for maintenance or upgrade purposes) without impacting availability, as the other node will continue to serve production traffic. Further, it doubles your capacity to read or write to the database and provides an additional layer of protection against data loss.

Module requirements

1 Elestio account https://dash.elest.io/signup
1 API key https://dash.elest.io/account/security
1 SSH public/private key (see how to create one here)

Module usage

This is a minimal example of how to use the module:

module "cluster" {
  source = "elestio-examples/keydb-cluster/elestio"

  project_id = "xxxxxx"
  keydb_pass = "xxxxxx"

  configuration_ssh_key = {
    username    = "something"
    public_key  = chomp(file("~/.ssh/id_rsa.pub"))
    private_key = file("~/.ssh/id_rsa")
  }

  nodes = [
    {
      server_name   = "keydb-1"
      provider_name = "scaleway"
      datacenter    = "fr-par-1"
      server_type   = "SMALL-2C-2G"
    },
    {
      server_name   = "keydb-2"
      provider_name = "scaleway"
      datacenter    = "fr-par-2"
      server_type   = "SMALL-2C-2G"
    },
  ]
}

Keep your keydb password safe, you will need it to access the admin panel.

If you want to know more about node configuration, check the keydb service documentation here.

If you want to choose your own provider, datacenter or server type, check the guide here.

If you want to generated a valid SSH Key, check the guide here.

If you add more nodes, you may attains the resources limit of your account, please visit your account quota page.

Quick configuration

The following example will create a KeyDB cluster with 2 nodes.

You may need to adjust the configuration to fit your needs.

Create a main.tf file at the root of your project, and fill it with your Elestio credentials:

terraform {
  required_providers {
    elestio = {
      source = "elestio/elestio"
    }
  }
}

provider "elestio" {
  email     = "xxxx@xxxx.xxx"
  api_token = "xxxxxxxxxxxxx"
}

resource "elestio_project" "project" {
  name = "keydb-cluster"
}

Now you can use the module to create keydb nodes:

module "cluster" {
  source = "elestio-examples/keydb-cluster/elestio"

  project_id    = elestio_project.project.id
  keydb_version = null # null means latest version
  keydb_pass    = "xxxxxxxxxxxxx"

  configuration_ssh_key = {
    username    = "terraform"
    public_key  = chomp(file("~/.ssh/id_rsa.pub"))
    private_key = file("~/.ssh/id_rsa")
  }

  nodes = [
    {
      server_name   = "keydb-1"
      provider_name = "scaleway"
      datacenter    = "fr-par-1"
      server_type   = "SMALL-2C-2G"
    },
    {
      server_name   = "keydb-2"
      provider_name = "scaleway"
      datacenter    = "fr-par-2"
      server_type   = "SMALL-2C-2G"
    },
  ]
}

Finally, let's add some outputs to retrieve useful information:

output "nodes_admins" {
  value     = { for node in module.cluster.nodes : node.server_name => node.admin }
  sensitive = true
}

output "nodes_database_admins" {
  value     = { for node in module.cluster.nodes : node.server_name => node.database_admin }
  sensitive = true
}

You can now run terraform init and terraform apply to create your KeyDB cluster. After a few minutes, the cluster will be ready to use. You can access your outputs with terraform output:

$ terraform output nodes_admins
$ terraform output nodes_database_admins

If you want to update some parameters, you can edit the main.tf file and run terraform apply again. Terraform will automatically update the cluster to match the new configuration. Please note that changing the node count requires to change the .env of existing nodes. This is done automatically by the module.

Ready-to-deploy example

We created a ready-to-deploy example which creates the same infrastructure as the previous example. You can find it here. Follow the instructions to deploy the example.

How to use the cluster

Use terraform output nodes_database_admins command to output database secrets:

# nodes_database_admins
{
  "keydb-1" = {
    "command" = "redis-cli -h keydb-1-u525.vm.elestio.app -p 23647 -a '*****'"
    "host" = "keydb-1-u525.vm.elestio.app"
    "password" = "*****"
    "port" = "23647"
    "user" = "root"
  }
  "keydb-2" = {
    "command" = "redis-cli -h keydb-2-u525.vm.elestio.app -p 23647 -a '*****'"
    "host" = "keydb-2-u525.vm.elestio.app"
    "password" = "*****"
    "port" = "23647"
    "user" = "root"
  }
}

Here is an example of how to use the KeyDB cluster and all its nodes in the Javascript client.

// Javascript example
const Redis = require('ioredis');

const cluster = new Redis.Cluster([
  {
    port: 23647,
    password: '****',
    host: 'keydb-1-u525.vm.elestio.app',
  },
  {
    port: 23647,
    password: '****',
    host: 'keydb-2-u525.vm.elestio.app',
  },
]);

cluster.set('foo', 'bar');
cluster.get('foo', (err, res) => {
  // res === 'bar'
});

Inputs

Name	Description	Type	Default	Required
configuration_ssh_key	After the nodes are created, Terraform must connect to apply some custom configuration. This configuration is done using SSH from your local machine. The Public Key will be added to the nodes and the Private Key will be used by your local machine to connect to the nodes. Read the guide "How generate a valid SSH Key for Elestio". Example: configuration_ssh_key = { username = "admin" public_key = chomp(file("~/.ssh/id_rsa.pub")) private_key = file("~/.ssh/id_rsa") }	object({ username = string public_key = string private_key = string })	n/a	yes
keydb_pass	The password can only contain alphanumeric characters or hyphens `-`. Require at least 10 characters, one uppercase letter, one lowercase letter and one number. Example: `rfxE42snU-bt0y-1KwqweZDq` DO NOT USE THIS EXAMPLE PASSWORD.	`string`	n/a	yes
keydb_version	The cluster nodes must share the same keydb version. Leave empty or set to `null` to use the Elestio recommended version.	`string`	`null`	no
nodes	Each element of this list will create an Elestio KeyDB Resource in your cluster. Read the following documentation to understand what each attribute does, plus the default values: Elestio KeyDB Resource.	list( object({ server_name = string provider_name = string datacenter = string server_type = string admin_email = optional(string) alerts_enabled = optional(bool) app_auto_update_enabled = optional(bool) backups_enabled = optional(bool) firewall_enabled = optional(bool) keep_backups_on_delete_enabled = optional(bool) remote_backups_enabled = optional(bool) support_level = optional(string) system_auto_updates_security_patches_only_enabled = optional(bool) ssh_public_keys = optional(list( object({ username = string key_data = string }) ), []) }) )	`[]`	no
project_id	n/a	`string`	n/a	yes

Modules

No modules.

Outputs

Name	Description
nodes	This is the created nodes full information

Providers

Name	Version
elestio	>= 0.17.0
null	>= 3.2.0

Requirements

Name	Version
terraform	>= 1.0
elestio	>= 0.17.0
null	>= 3.2.0

Resources

Name	Type
elestio_keydb.nodes	resource
null_resource.update_nodes_env	resource

elestio-examples/terraform-elestio-keydb-cluster