Creating a Valkey™ cluster

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

The folder specified in the CLI profile is used by default. 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 create cluster CLI command:

   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 (only some of the supported flags are given 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: Priority for assigning the host as a master if the primary master fails.

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

     Warning

     You cannot change disk type after you create a cluster.

   • --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 deletion protection.

   • --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.

   Enabled deletion protection will not prevent a manual connection with the purpose to delete database contents.

   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 don't have Terraform, install it and configure the Yandex Cloud provider.

To create a Yandex Managed Service for Valkey™ cluster:

1. In the configuration file, describe the parameters of 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 = <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 deletion protection, true or false.

   • 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, 6.2 or 7.0.

   • 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: Priority for assigning the host 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.

   Enabled deletion protection will not prevent a manual connection with the purpose to delete database contents.

   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.

   For more information about the resources you can create with Terraform, see the provider documentation.

2. Make sure the settings are correct.

   1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

3. Create a cluster.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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 a 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: Priority for assigning the host 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 deletion protection, true or false.

     With deletion protection enabled, you will still be able to manually connect to the cluster and delete it.

   • 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 make a 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 a 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: Priority for assigning the host 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 deletion protection, true or false.

     With deletion protection enabled, you will still be able to manually connect to the cluster and delete it.

   • 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 make a 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.0.
• 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.
• Protection against accidental cluster deletion.

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.0"
  }

  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.0.
• Environment: PRODUCTION.
• Sharding: Enabled.
• SSL support: Enabled.
• Protection against accidental cluster deletion.
• 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.0"
    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    = "Redis"
    port           = 6380
    protocol       = "TCP"
    v4_cidr_blocks = ["10.5.0.0/24"]
  }
}