Creating a Valkey™ cluster

If you do not have the Yandex Cloud (CLI) command line interface yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To create a Yandex Managed Service for Valkey™ cluster:

1. Check whether the folder has any subnets for the cluster hosts:

   yc vpc subnet list
   

   If there are no subnets in the folder, create the required subnets in VPC.

2. View the description of the CLI command to create a cluster:

   yc managed-redis cluster create --help
   

3. When you create a cluster from the CLI, you cannot explicitly specify the host type and amount of RAM. Choose the applicable host class instead. To see what host classes are available, run the command:

   yc managed-redis resource-preset list
   

4. Specify the cluster parameters in the create command (not all flags are shown in the example):

   yc managed-redis cluster create \
     --name <cluster_name> \
     --environment <environment> \
     --network-name <network_name> \
     --host zone-id=<availability_zone>,`
           `subnet-id=<subnet_ID>,`
           `assign-public-ip=<public_access>,`
           `replica-priority=<host_priority> \
     --security-group-ids <list_of_security_group_IDs> \
     --enable-tls \
     --resource-preset <host_class> \
     --disk-size <storage_size_in_GB> \
     --disk-type-id <network-ssd|network-ssd-nonreplicated|local-ssd> \
     --password=<user_password> \
     --backup-window-start <time> \
     --deletion-protection \
     --announce-hostnames <using_FQDNs_instead_of_IP_addresses>
   

   Where:

   • --environment: Environment, prestable or production.

   • --host: Host parameters:

     • zone-id: Availability zone.
     • subnet-id: Subnet ID. Specify if two or more subnets are created in the selected availability zone.
     • assign-public-ip: Internet access to the host via a public IP address, true or false.
     • replica-priority: Host priority for assignment as a master if the primary master fails.

   • --disk-type-id: Disk type.

   • --websql-access: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value is false.

   • --backup-window-start: Backup start time in HH:MM:SS format.

   • --deletion-protection: Cluster protection from accidental deletion, true or false.

     Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

   • --announce-hostnames: Enables or disables using FQDNs instead of IP addresses: true or false.

     Note

     Some clients do not support this setting and will fail to connect to the cluster hosts. Such clients expect an IP address and will produce errors if you provide an FQDN instead.

   You need to specify the subnet-id if the selected availability zone has two or more subnets.

   The password must be between 8 and 128 characters long. The password must meet the [a-zA-Z0-9@=+?*.,!&#$^<>_-]* regular expression.

   If you are creating a sharded cluster with the local-ssd disk type, specify at least two hosts per shard in the command.

   Note

   When creating a cluster, the anytime maintenance mode is set by default. You can set a specific maintenance period when updating the cluster settings.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the documentation on the Terraform website or mirror website.

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

To create a Yandex Managed Service for Valkey™ cluster:

1. In the configuration file, describe the resources you want to create:

   • Database cluster: Description of the cluster and its hosts. You can also configure DBMS settings here if necessary.

   • Network: Description of the cloud network where the cluster will be hosted. If you already have a suitable network, you do not need to describe it again.

   • Subnets: Subnets to connect the cluster hosts to. If you already have suitable subnets, you do not need to describe them again.

   Sample configuration file structure for creating a non-sharded cluster with SSL support:

   resource "yandex_mdb_redis_cluster" "<cluster_name>" {
     name                = "<cluster_name>"
     environment         = "<environment>"
     network_id          = "<network_ID>"
     security_group_ids  = [ "<list_of_security_group_IDs>" ]
     tls_enabled         = true
     deletion_protection = <cluster_deletion_protection>
     announce_hostnames  = <using_FQDNs_instead_of_IP_addresses>
   
     config {
       password = "<password>"
       version  = "<Valkey™_version>"
     }
   
     resources {
       resource_preset_id = "<host_class>"
       disk_type_id       = "<disk_type>"
       disk_size          = <storage_size_in_GB>
     }
   
     host {
       zone             = "<availability_zone>"
       subnet_id        = "<subnet_ID>"
       assign_public_ip = <public_access>
       replica_priority = <host_priority>
     }
   }
   
   resource "yandex_vpc_network" "<network_name>" { name = "<network_name>" }
   
   resource "yandex_vpc_subnet" "<subnet_name>" {
     name           = "<subnet_name>"
     zone           = "<availability_zone>"
     network_id     = "<network_ID>"
     v4_cidr_blocks = ["<range>"]
   }
   

   Where:

   • environment: Environment, PRESTABLE or PRODUCTION.

   • deletion_protection: Cluster protection from accidental deletion, true or false.

     Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

   • announce_hostnames: Enables or disables using FQDNs instead of IP addresses: true or false.

     Note

     Some clients do not support this setting and will fail to connect to the cluster hosts. Such clients expect an IP address and will produce errors if you provide an FQDN instead.

   • version: Valkey™ version, 7.2.

   • host: Host parameters:

     • zone_id: Availability zone.
     • subnet_id: ID of a subnet in the selected availability zone.
     • assign_public_ip: Public access to the host, true or false.
     • replica_priority: Host priority for assignment as a master if the primary master fails.

   The password must be between 8 and 128 characters long. The password must meet the [a-zA-Z0-9@=+?*.,!&#$^<>_-]* regular expression.

   If you are creating a sharded cluster with the local-ssd disk type, specify at least two hosts per shard in the configuration file.

   To set up the maintenance window (for example, for disabled clusters), add the maintenance_window section to the cluster description:

   resource "yandex_mdb_redis_cluster" "<cluster_name>" {
     ...
     maintenance_window {
       type = <maintenance_type>
       day  = <day_of_week>
       hour = <hour>
     }
     ...
   }
   

   Where:

   • type: Maintenance type. The possible values include:
     • anytime: Anytime.
     • weekly: By schedule.
   • day: Day of the week for the weekly type in DDD format, e.g., MON.
   • hour: Hour of the day for the weekly type in the HH format, e.g., 21.

   To learn more about the resources you can create with Terraform, see the Terraform documentation.

2. Make sure the settings are correct.

   1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

3. Create a cluster.

   1. Run this command to view the planned changes:

      terraform plan
      

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

   After this, all required resources will be created in the specified folder, and the FQDNs of the cluster hosts will be displayed in the terminal. You can check the new resources and their settings using the management console.

   Time limits

   A Terraform provider sets the timeout for Yandex Managed Service for Valkey™ cluster operations:

   • Creating a cluster, including by restoring one from a backup: 15 minutes.
   • Editing a cluster: 60 minutes.
   • Deleting a cluster: 15 minutes.

   Operations exceeding the set timeout are interrupted.

   How do I change these limits?

   Add the timeouts block to the cluster description, for example:

   resource "yandex_mdb_redis_cluster" "<cluster_name>" {
     ...
     timeouts {
       create = "1h30m" # 1 hour 30 minutes
       update = "2h"    # 2 hours
       delete = "30m"   # 30 minutes
     }
   }
   

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Create a file named body.json and add the following contents to it:

   {
     "folderId": "<folder_ID>",
     "name": "<cluster_name>",
     "environment": "<environment>",
     "configSpec": {
       "version": "<Valkey™_version>",
       "resources": {
         "resourcePresetId": "<host_class>",
         "diskSize": "<storage_size_in_bytes>",
         "diskTypeId": "<disk_type>"
       },
       "access": {
         "webSql": <access_from_WebSQL>
       },
       "redis": {
         "password": "<user_password>"
       }
     },
     "hostSpecs": [
       {
         "zoneId": "<availability_zone>",
         "subnetId": "<subnet_ID>",
         "shardName": "<shard_name>",
         "replicaPriority": "<host_priority>",
         "assignPublicIp": <public_access_to_cluster_host>
       },
       { <similar_configuration_for_host_2> },
       { ... },
       { <similar_configuration_for_host_N> }
     ],
     "networkId": "<network_ID>",
     "sharded": <cluster_sharding>,
     "securityGroupIds": [
       "<security_group_1_ID>",
       "<security_group_2_ID>",
       ...
       "<security_group_N_ID>"
     ],
     "tlsEnabled": <encrypted_TLS_connection_support>,
     "deletionProtection": <cluster_deletion_protection>,
     "announceHostnames": <using_FQDNs_instead_of_IP_addresses>
   }
   

   Where:

   • folderId: Folder ID. You can request it with the list of folders in the cloud.

   • name: Cluster name.

   • environment: Environment, PRESTABLE or PRODUCTION.

   • configSpec: Cluster settings:

     • version: Valkey™ version.

     • resources: Cluster resources:

       • resourcePresetId: Host class.
       • diskSize: Disk size in bytes.
       • diskTypeId: Disk type.

     • access.webSql: Access to cluster databases from the Yandex Cloud management console through Yandex WebSQL, true or false.

     • redis.password: User password.

   • hostSpecs: Host parameters:

     • zoneId: Availability zone.
     • subnetId: Subnet ID. Specify if two or more subnets are created in the selected availability zone.
     • shardName: Shard name for the host. Only used if the sharded parameter is set to true.
     • replicaPriority: Host priority for assignment as a master if the primary master fails.
     • assignPublicIp: Internet access to the host via a public IP address, true or false. You can enable public access only if the tlsEnabled parameter is set to true.

   • networkId: ID of the network the cluster will be in.

   • sharded: Cluster sharding, true or false.

     Warning

     You cannot disable sharding in a cluster where it is already enabled. You can create a non-sharded cluster and enable sharding later, if required.

     If you are creating a sharded cluster with the local-ssd disk type, specify at least two hosts per shard, adding the appropriate number of hostSpecs blocks.

   • securityGroupIds: Security group IDs.

   • tlsEnabled: Support for encrypted TLS connections to the cluster, true or false.

     Warning

     You can only enable connection encryption when creating a new cluster. You cannot disable encryption for a cluster that it is enabled for.

   • deletionProtection: Cluster protection from accidental deletion, true or false.

     Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

   • announceHostnames: Using FQDNs instead of IP addresses, true or false.

     Note

     Some clients do not support this setting and will fail to connect to the cluster hosts. Such clients expect an IP address and will produce errors if you provide an FQDN instead.

3. Use the Cluster.Create method and send the following request, e.g., via cURL:

   curl \
       --request POST \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --header "Content-Type: application/json" \
       --url 'https://mdb.api.cloud.yandex.net/managed-redis/v1/clusters' \
       --data "@body.json"
   

4. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Create a file named body.json and add the following contents to it:

   {
     "folder_id": "<folder_ID>",
     "name": "<cluster_name>",
     "environment": "<environment>",
     "config_spec": {
       "version": "<Valkey™_version>",
       "resources": {
         "resource_preset_id": "<host_class>",
         "disk_size": "<storage_size_in_bytes>",
         "disk_type_id": "<disk_type>"
       },
       "access": {
         "web_sql": <access_from_WebSQL>
       },
       "redis": {
         "password": "<user_password>"
       }
     },
     "host_specs": [
       {
         "zone_id": "<availability_zone>",
         "subnet_id": "<subnet_ID>",
         "shard_name": "<shard_name>",
         "replica_priority": "<host_priority>",
         "assign_public_ip": <public_access_to_cluster_host>
       },
       { <similar_configuration_for_host_2> },
       { ... },
       { <similar_configuration_for_host_N> }
     ],
     "network_id": "<network_ID>",
     "sharded": <cluster_sharding>,
     "security_group_ids": [
       "<security_group_1_ID>",
       "<security_group_2_ID>",
       ...
       "<security_group_N_ID>"
     ],
     "tls_enabled": <encrypted_TLS_connection_support>,
     "deletion_protection": <cluster_deletion_protection>,
     "announce_hostnames": <using_FQDNs_instead_of_IP_addresses>
   }
   

   Where:

   • folder_id: Folder ID. You can request it with the list of folders in the cloud.

   • name: Cluster name.

   • environment: Environment, PRESTABLE or PRODUCTION.

   • config_spec: Cluster settings:

     • version: Valkey™ version.

     • resources: Cluster resources:

       • resource_preset_id: Host class.
       • disk_size: Disk size in bytes.
       • disk_type_id: Disk type.

     • access.web_sql: Access to cluster databases from the Yandex Cloud management console through Yandex WebSQL, true or false.

     • redis.password: User password.

   • host_specs: Host parameters:

     • zone_id: Availability zone.
     • subnet_id: Subnet ID. Specify if two or more subnets are created in the selected availability zone.
     • shard_name: Shard name for the host. Only used if the sharded parameter is set to true.
     • replica_priority: Host priority for assignment as a master if the primary master fails.
     • assign_public_ip: Internet access to the host via a public IP address, true or false. You can enable public access only if the tls_enabled parameter is set to true.

   • network_id: ID of the network the cluster will be in.

   • sharded: Cluster sharding, true or false.

     Warning

     You cannot disable sharding in a cluster where it is already enabled. You can create a non-sharded cluster and enable sharding later, if required.

     If you are creating a sharded cluster with the local-ssd disk type, specify at least two hosts per shard, adding the appropriate number of host_specs blocks.

   • security_group_ids: Security group IDs.

   • tls_enabled: Support for encrypted TLS connections to the cluster, true or false.

     Warning

     You can only enable connection encryption when creating a new cluster. You cannot disable encryption for a cluster that it is enabled for.

   • deletion_protection: Cluster protection from accidental deletion, true or false.

     Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.

   • announce_hostnames: Using FQDNs instead of IP addresses, true or false.

     Note

     Some clients do not support this setting and will fail to connect to the cluster hosts. Such clients expect an IP address and will produce errors if you provide an FQDN instead.

4. Use the ClusterService.Create call and send the following request, e.g., via gRPCurl:

   grpcurl \
       -format json \
       -import-path ~/cloudapi/ \
       -import-path ~/cloudapi/third_party/googleapis/ \
       -proto ~/cloudapi/yandex/cloud/mdb/redis/v1/cluster_service.proto \
       -rpc-header "Authorization: Bearer $IAM_TOKEN" \
       -d @ \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.redis.v1.ClusterService.Create \
       < body.json
   

5. View the server response to make sure the request was successful.

Create a Yandex Managed Service for Valkey™ cluster and a network for it with the following test specifications:

• Name: myredis.
• Version: 7.2.
• Environment: PRODUCTION.
• Cloud ID: b1gq90dgh25bebiu75o.
• Folder ID: b1gia87mbaomkfvsleds.
• New mynet network.
• A single hm2.nano class host in the new subnet called mysubnet, ru-central1-a availability zone, with public access and a host priority of 50. Range for mysubnet: 10.5.0.0/24.
• New redis-sg security group allowing connections through the 6380 port from any addresses in mysubnet.
• SSL support: Enabled.
• Network SSD storage (network-ssd): 16 GB.
• Password: user1user1.
• Deletion protection: Enabled.

The configuration file for this cluster is as follows:

resource "yandex_mdb_redis_cluster" "myredis" {
  name                = "myredis"
  environment         = "PRODUCTION"
  network_id          = yandex_vpc_network.mynet.id
  security_group_ids  = [ yandex_vpc_security_group.redis-sg.id ]
  tls_enabled         = true
  deletion_protection = true

  config {
    password = "user1user1"
    version  = "7.2"
  }

  resources {
    resource_preset_id = "hm2.nano"
    disk_type_id       = "network-ssd"
    disk_size          = 16
  }

  host {
    zone             = "ru-central1-a"
    subnet_id        = yandex_vpc_subnet.mysubnet.id
    assign_public_ip = true
    replica_priority = 50
  }
}

resource "yandex_vpc_network" "mynet" { name = "mynet" }

resource "yandex_vpc_security_group" "redis-sg" {
  name       = "redis-sg"
  network_id = yandex_vpc_network.mynet.id

  ingress {
    description    = "Valkey™"
    port           = 6380
    protocol       = "TCP"
    v4_cidr_blocks = ["10.5.0.0/24"]
  }
}

resource "yandex_vpc_subnet" "mysubnet" {
  name           = "mysubnet"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.mynet.id
  v4_cidr_blocks = ["10.5.0.0/24"]
}

Create a sharded Yandex Managed Service for Valkey™ cluster and a network for it with the following test characteristics:

• Name: myredis.
• Version: 7.2.
• Environment: PRODUCTION.
• Sharding: Enabled.
• SSL support: Enabled.
• Deletion protection: Enabled.
• New network named mynet with a single subnet. Range for mysubnet: 10.5.0.0/24.
• New redis-sg security group allowing connections through the 6380 port from any addresses in mysubnet.
• Host class: hm2.nano.
• A single host in the shard called shard1, in the mysubnet subnet, ru-central1-a availability zone, with public access and a host priority of 50.
• Network SSD storage (network-ssd): 16 GB.
• Password: user1user1.

The configuration file for this cluster is as follows:

resource "yandex_mdb_redis_cluster" "myredis" {
  name                = "myredis"
  environment         = "PRODUCTION"
  sharded             = true
  tls_enabled         = true
  deletion_protection = true
  network_id          = yandex_vpc_network.mynet.id
  security_group_ids  = [yandex_vpc_security_group.redis-sg.id]

  config {
    version  = "7.2"
    password = "user1user1"
  }

  resources {
    resource_preset_id = "hm2.nano"
    disk_type_id       = "network-ssd"
    disk_size          = 16
  }

  host {
    shard_name = "shard1"
    subnet_id  = yandex_vpc_subnet.mysubnet.id
    zone       = "ru-central1-a"
    assign_public_ip = true
    replica_priority = 50
  }
}

resource "yandex_vpc_network" "mynet" { name = "mynet" }

resource "yandex_vpc_subnet" "mysubnet" {
  name           = "mysubnet"
  zone           = "ru-central1-a"
  network_id     = yandex_vpc_network.mynet.id
  v4_cidr_blocks = ["10.5.0.0/24"]
}

resource "yandex_vpc_security_group" "redis-sg" {
  name       = "redis-sg"
  network_id = yandex_vpc_network.mynet.id

  ingress {
    description    = "Valkey™"
    port           = 6380
    protocol       = "TCP"
    v4_cidr_blocks = ["10.5.0.0/24"]
  }
}