Creating a Valkey™ cluster
A Valkey™ cluster consists of one or more database hosts, with the option to configure replication between them. Replication is enabled by default in any cluster with more than one host: the master host accepts write requests and propagates the changes to its replicas.
For more information on the Yandex Managed Service for Valkey™ cluster structure, see Resource relationships.
Note
- The number of hosts you can create together with a Valkey™ cluster depends on the selected disk type and host class, as well as on whether sharding is used.
- The available disk types depend on the selected host class.
Cluster DB connections are managed by Connection Manager. Creating a cluster automatically creates:
-
Connection Manager connection with information about the database connection.
-
Yandex Lockbox secret that stores the DB owner's user password. Storing passwords in Yandex Lockbox ensures their security.
The connection and secret will be created for each new database user. To view all connections, select the Connections tab on the cluster page.
You need the connection-manager.viewer role to view connection info. You can use Connection Manager to configure access to connections.
You can use Connection Manager and secrets you create there free of charge.
Creating a cluster
To create a Yandex Managed Service for Valkey™ cluster, you need the vpc.user role and the managed-redis.editor role or higher. For more information on assigning roles, see this Identity and Access Management guide.
Note
The following restrictions apply when creating sharded clusters:
- You can create a single-shard cluster using the CLI, Terraform, or API.
- You cannot create a cluster with two shards, but you can add a shard to an existing single-shard cluster.
- You can create a cluster with three or more shards using the management console, CLI, Terraform, or API.
There are no restrictions for non-sharded clusters.
To create a Yandex Managed Service for Valkey™ cluster:
-
In the management console
, go to the folder where you want to create your database cluster. -
Navigate to the Yandex Managed Service for Valkey™ service.
-
Click Create cluster.
-
Under Basic parameters:
-
Enter a name for the cluster in the Cluster name field. The cluster name must be unique within the folder.
-
Optionally, add a cluster description.
-
Select your cluster environment. Note that you cannot change the environment once the cluster is created:
PRODUCTION: For stable versions of your applications.PRESTABLE: For testing purposes. The prestable environment is similar to the production environment and is also covered by an SLA. However, it receives new features, improvements, and bug fixes earlier. In the prestable environment, you can test new versions for compatibility with your application.
-
Select the DBMS version.
-
Optionally, add labels.
-
Enable cluster sharding, if required.
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.
-
Enable encrypted TLS connections to your cluster, if required.
Warning
You can enable encrypted connections only when creating a new cluster. You cannot disable encryption for an existing cluster.
-
Optionally, enable using FQDNs instead of IP addresses.
Note
Some clients do not support this setting and will fail to connect to the cluster hosts. They expect an IP address and will produce errors if you provide an FQDN instead.
-
Select the data persistence mode.
-
-
Under Resources:
-
Select a platform in the Platform field.
-
Specify the Type of virtual machine where you want to deploy the hosts.
-
Select Host class.
-
Select the disk type:
- Either the more flexible network SSD (
network-ssd) or non-replicated SSD (network-ssd-nonreplicated) storage - Or the faster local SSD (
local-ssd) storage
The type you select determines the increments for changing the disk size:
- Network SSD storage: In increments of 1 GB.
- Local SSD storage:
- For Intel Broadwell and Intel Cascade Lake: In increments of 100 GB.
- For Intel Ice Lake: In increments of 368 GB.
- Non-replicated SSD storage: In increments of 93 GB.
- Either the more flexible network SSD (
-
Select the storage size. The available storage size is capped by quotas and limits.
-
In the Increase size field, set the conditions for the actions below:
-
Storage expansion during the next maintenance window if and when the specified storage space utilization percentage is exceeded. If you set this condition, configure the maintenance schedule.
-
Storage expansion immediately if and when the specified storage space utilization percentage is exceeded.
Warning
If you set both conditions, make sure the immediate expansion threshold is higher than the scheduled one.
-
-
In the Maximum storage size field, specify the maximum storage size that can be set during autoscaling.
Warning
- You cannot reduce the storage size.
- During storage resizing, cluster hosts will be stopped and updated one at a time.
-
Optionally, select Encrypted disk to encrypt the disk with a custom KMS key.
-
To create a new key, click Create.
-
To use a previously created key, select it in the KMS key field.
To learn more about disk encryption, see Storage.
-
-
-
Under Network settings, select:
- Cloud network for cluster deployment.
- Security groups for cluster network traffic. You may need to additionally set up security groups to be able connect to the cluster.
-
Under Hosts, configure the hosts:
-
To change the settings of a host, click
next to the host name.-
Availability zone: Select the availability zone.
-
Subnet: Specify the subnet in the selected availability zone.
-
Public access: Enables access to the host from the internet if you enabled TLS support for the cluster.
-
Master priority: Host priority for promotion to master if the primary master fails.
-
Shard name: Enables you to change the shard name for the host. This field is only available if you enabled Cluster sharding for the cluster.
-
-
To add hosts to your cluster, click Add host.
If you enabled cluster sharding and selected the local-ssd disk type, add at least two hosts per shard.
-
-
Under DBMS settings:
-
In the Password field, enter the user password.
The password must be from 8 to 128 characters long and match the
[a-zA-Z0-9@=+?*.,!&#$^<>_-]*regular expression. -
Configure the DBMS settings, if required.
-
-
Under Service settings, configure the additional cluster settings as follows:
-
Backup start time (UTC): Cluster backup start time (UTC, 24-hour format). If you leave the time unset, the backup will start at 22:00 UTC.
-
Maintenance window: Maintenance window settings:
- To enable maintenance at any time, select arbitrary (default).
- To specify the preferred maintenance start time, select by schedule and specify the desired day of the week and UTC hour. For example, you can choose a time when the cluster is least loaded.
Maintenance operations are carried out both on enabled and disabled clusters. They may include updating the DBMS, applying patches, and so on.
-
Deletion protection: Manages cluster protection against accidental deletion.
Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.
-
WebSQL access: This option enables you to run SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL.
-
-
Click Create cluster.
If you do not have the Yandex Cloud CLI installed yet, install and initialize it.
By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.
To create a Yandex Managed Service for Valkey™ cluster:
-
Verify that your folder has subnets for cluster host placement:
yc vpc subnet listIf your folder contains no subnets, create them in VPC.
-
View the description of the CLI command for creating a cluster:
yc managed-redis cluster create --help -
When creating a cluster with the CLI, you cannot explicitly specify the host type and RAM size. Select the appropriate host class instead. To view the available host classes, run the following command:
yc managed-redis resource-preset list -
Run this command, providing the cluster settings (our example lists only some flags):
yc managed-redis cluster create \ --name <cluster_name> \ --environment <environment> \ --redis-version <Valkey™_version> \ --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 \ --persistence-mode <persistence_mode> \ --resource-preset <host_class> \ --disk-size <storage_size_in_GB> \ --disk-size-autoscaling disk-size-limit=<maximum_storage_size_in_GB>,` `planned-usage-threshold=<scheduled_expansion_percentage>,` `emergency-usage-threshold=<immediate_expansion_percentage> \ --disk-type-id <network-ssd|network-ssd-nonreplicated|local-ssd> \ --password=<user_password> \ --backup-window-start <time> \ --disk-encryption-key-id <KMS_key_ID> \ --deletion-protection \ --announce-hostnames <using_FQDNs_instead_of_IP_addresses> \ --valkey-modules enable-valkey-search=<enable_Valkey-Search_module>,` `valkey-search-reader-threads=<number_of_request_processing_threads>,` `valkey-search-writer-threads=<number_of_indexing_threads>,` `enable-valkey-json=<enable_Valkey-JSON_module>,` `enable-valkey-bloom=<enable_Valkey-Bloom_module>Where:
-
--environment: Environment,prestableorproduction. -
--redis-version: Valkey™ version,7.2-valkey,8.0-valkey,8.1-valkey, or9.0-valkey. -
--host: Host settings:zone-id: Availability zone.subnet-id: Subnet ID. Specify it if the selected availability zone has two or more subnets.assign-public-ip: Controls whether the host is accessible via a public IP address,trueorfalse.replica-priority: Host priority for promotion to master if the primary master fails.
-
--disk-type-id: Disk type. -
--websql-access: Enables running SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value isfalse. -
--disk-size-autoscaling: Automatic storage expansion settings:-
planned-usage-threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.If you set this condition, configure the maintenance schedule.
-
emergency-usage-threshold: Storage usage percentage to trigger an immediate storage expansion.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.Warning
If you specify both thresholds,
emergency-usage-thresholdmust not be less thanplanned-usage-threshold. -
disk-size-limit: Maximum storage size after expansion, in GB.
Warning
- You cannot reduce the storage size.
- During storage resizing, cluster hosts will be stopped and updated one at a time.
-
-
--persistence-mode: Data persistence mode.The possible values are:
ON: Enable persistence.OFF: Disable persistence.ON_REPLICAS: Enable persistence on replicas only.
-
--backup-window-start: Backup start time inHH:MM:SSformat. -
--deletion-protection: Cluster protection from accidental deletion,trueorfalse.Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.
-
--disk-encryption-key-id: Disk encryption with a custom KMS key.To learn more about disk encryption, see Storage.
-
--announce-hostnames: Use of FQDNs instead of IP addresses,trueorfalse.Note
Some clients do not support this setting and will fail to connect to the cluster hosts. They expect an IP address and will produce errors if you provide an FQDN instead.
-
--valkey-modules: Valkey™ module parameters:enable-valkey-search: Enable theValkey-Searchmodule,trueorfalse.valkey-search-reader-threads: Number of request processing threads in theValkey-Searchmodule.valkey-search-writer-threads: Number of indexing threads in theValkey-Searchmodule.enable-valkey-json: Enable theValkey-JSONmodule,trueorfalse.enable-valkey-bloom: Enable theValkey-Bloommodule,trueorfalse.
Warning
You cannot disable modules once enabled.
You must specify the
subnet-idif the selected availability zone has more than one subnet.The password must be from 8 to 128 characters long and match 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
The default maintenance mode for new clusters is
anytime. You can set a specific maintenance period when updating the cluster settings. -
With Terraform
Terraform is distributed under the Business Source License
For more information about the provider resources, see the relevant documentation on the Terraform
If you do not have Terraform yet, install it and configure the Yandex Cloud provider.
To create a Yandex Managed Service for Valkey™ cluster:
-
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 required.
-
Network: Description of the cloud network to host the cluster. If you already have a network in place, you do not need to describe it again.
-
Subnets: Description of the subnets to connect the cluster hosts to. If you already have subnets in place, you do not need to describe them again.
Here is an example structure of a configuration file for creating a non-sharded cluster with SSL support:
resource "yandex_mdb_redis_cluster_v2" "<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> persistence_mode = "<persistence_mode>" disk_size_autoscaling { planned_usage_threshold = "<scheduled_expansion_percentage>" emergency_usage_threshold = "<immediate_expansion_percentage>" disk_size_limit = "<maximum_storage_size_in_GiB>" } 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,PRESTABLEorPRODUCTION. -
deletion_protection: Cluster deletion protection,trueorfalse.Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.
-
disk_size_autoscaling: Automatic storage expansion settings:-
planned_usage_threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.If you set this condition, configure the maintenance schedule in the
maintenance_windowsection. -
emergency_usage_threshold: Storage usage percentage to trigger an immediate storage expansion.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.Warning
If you specify both thresholds,
emergency_usage_thresholdmust not be less thanplanned_usage_threshold. -
disk_size_limit: Maximum storage size after the increase, in gibibytes.
Warning
- You cannot reduce the storage size.
- During storage resizing, cluster hosts will be stopped and updated one at a time.
-
-
announce_hostnames: Use of FQDNs instead of IP addresses,trueorfalse.Note
Some clients do not support this setting and will fail to connect to the cluster hosts. They expect an IP address and will produce errors if you provide an FQDN instead.
-
persistence_mode: Data persistence mode.The possible values are:
ON: Enable persistence.OFF: Disable persistence.ON_REPLICAS: Enable persistence on replicas only.
-
version: Valkey™ version,7.2-valkey,8.0-valkey,8.1-valkey, or9.0-valkey. -
host: Host settings:zone_id: Availability zone.subnet_id: ID of the subnet in the selected availability zone.assign_public_ip: Public access to the host,trueorfalse.replica_priority: Host priority for promotion to master if the primary master fails.
The password must be from 8 to 128 characters long and match 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 that will also apply to stopped clusters, add the
maintenance_windowsection to the cluster description:resource "yandex_mdb_redis_cluster_v2" "<cluster_name>" { ... maintenance_window { type = <maintenance_type> day = <day_of_week> hour = <hour> } ... }Where:
type: Maintenance type. The possible values include:ANYTIME: AnytimeWEEKLY: On a schedule
day: Day of week for theWEEKLYtype, i.e.,MON,TUE,WED,THU,FRI,SAT, orSUN.hour: UTC hour for theWEEKLYtype, from1to24.
To encrypt the disk with a custom KMS key, add the
disk_encryption_key_idargument:resource "yandex_mdb_redis_cluster_v2" "<cluster_name>" { ... disk_encryption_key_id = <KMS_key_ID> ... }To learn more about disk encryption, see Storage.
To learn more about resources you can create with Terraform, see this provider guide.
-
-
Validate your configuration.
-
In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
-
Run this command:
terraform validateTerraform will show any errors found in your configuration files.
-
-
Create the cluster.
-
Run this command to view the planned changes:
terraform planIf 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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply -
Confirm updating the resources.
-
Wait for the operation to complete.
-
This will create all the resources you need in the specified folder, and the terminal will display the FQDNs of the cluster hosts. You can check the new resources and their configuration using the management console
.Timeouts
The Terraform provider sets the following timeouts for Yandex Managed Service for Valkey™ cluster operations:
- Creating a cluster, including by restoring it from a backup: 15 minutes.
- Editing a cluster: 60 minutes.
- Deleting a cluster: 15 minutes.
Operations exceeding the timeout are aborted.
How do I change these limits?
Add the
timeoutssection to your cluster description, such as the following:resource "yandex_mdb_redis_cluster_v2" "<cluster_name>" { ... timeouts { create = "1h30m" # 1 hour 30 minutes update = "2h" # 2 hours delete = "30m" # 30 minutes } } -
-
Get an IAM token for API authentication and place it in an environment variable:
export IAM_TOKEN="<IAM_token>" -
Create a file named
body.jsonand paste the following code into 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>" }, "diskSizeAutoscaling": { "plannedUsageThreshold": "<scheduled_expansion_percentage>", "emergencyUsageThreshold": "<immediate_expansion_percentage>", "diskSizeLimit": "<maximum_storage_size_in_bytes>" }, "access": { "webSql": <access_from_WebSQL> }, "redis": { "password": "<user_password>" }, "modules": { "valkeySearch": { "enabled": "<enable_Valkey-Search_module>", "readerThreads": "<number_of_request_processing_threads>", "writerThreads": "<number_of_indexing_threads>" }, "valkeyJson": { "enabled": "<enable_Valkey-JSON_module>" }, "valkeyBloom": { "enabled": "<enable_Valkey-Bloom_module>" } } }, "hostSpecs": [ { "zoneId": "<availability_zone>", "subnetId": "<subnet_ID>", "shardName": "<shard_name>", "replicaPriority": "<host_priority>", "assignPublicIp": <public_access_to_cluster_host> }, { <similar_settings_for_host_2> }, { ... }, { <similar_settings_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>, "persistenceMode": "<persistence_mode>" }Where:
-
folderId: Folder ID. You can get it from the list of your cloud folders. -
name: Cluster name. -
environment: Environment,PRESTABLEorPRODUCTION. -
configSpec: Cluster settings:-
version: Valkey™ version,7.2-valkey,8.0-valkey,8.1-valkey, or9.0-valkey. -
resources: Cluster resources:resourcePresetId: Host class.diskSize: Disk size, in bytes.diskTypeId: Disk type.
-
diskSizeAutoscaling: Automatic storage expansion settings:-
plannedUsageThreshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.If you set this condition, configure the
maintenanceWindow. -
emergencyUsageThreshold: Storage usage percentage to trigger an immediate storage expansion.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.Warning
If you specify both thresholds,
emergencyUsageThresholdmust not be less thanplannedUsageThreshold. -
diskSizeLimit: Maximum storage size after expansion, in bytes.
Warning
- You cannot reduce the storage size.
- During storage resizing, cluster hosts will be stopped and updated one at a time.
-
-
access.webSql: Access to cluster databases from the Yandex Cloud management console using Yandex WebSQL,trueorfalse. -
redis.password: Password. -
modules: Valkey™ module parameters:valkeySearch.enabled: Enable theValkey-Searchmodule,trueorfalse. What you can set up for the module:valkeySearch.readerThreads: Number of request processing threads.valkeySearch.writerThreads: Number of indexing threads.
valkeyJson.enabled: Enable theValkey-JSONmodule,trueorfalse.valkeyBloom.enabled: Enable theValkey-Bloommodule,trueorfalse.
Warning
You cannot disable modules once enabled.
-
-
hostSpecs: Host settings:zoneId: Availability zone.subnetId: Subnet ID. You must specify this setting if the selected availability zone has more than one subnet.shardName: Shard name for the host. This setting only applies whenshardedis set totrue.replicaPriority: Host priority for promotion to master if the primary master fails.assignPublicIp: Internet access to the host via a public IP address,trueorfalse. You can enable public access only iftlsEnabledis set totrue.
-
networkId: ID of the network where the cluster will be deployed. -
sharded: Cluster sharding,trueorfalse.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-ssddisk type, specify at least two hosts per shard, adding the appropriate number ofhostSpecssections. -
securityGroupIds: Security group IDs. -
tlsEnabled: Support for encrypted TLS connections to the cluster,trueorfalse.Warning
You can enable encrypted connections only when creating a new cluster. You cannot disable encryption for an existing cluster.
-
deletionProtection: Cluster deletion protection,trueorfalse.Even with deletion protection enabled, one can still connect to the cluster manually and delete the data.
-
announceHostnames: Using FQDNs instead of IP addresses,trueorfalse.Note
Some clients do not support this setting and will fail to connect to the cluster hosts. They expect an IP address and will produce errors if you provide an FQDN instead.
-
persistenceMode: Data persistence mode.The possible values are:
ON: Enable persistence.OFF: Disable persistence.ON_REPLICAS: Enable persistence on replicas only.
-
-
Call the Cluster.Create method, e.g., via the following cURL
request: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" -
Check the server response to make sure your request was successful.
-
Get an IAM token for API authentication and place it in an environment variable:
export IAM_TOKEN="<IAM_token>" -
Clone the cloudapi
repository:cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapiBelow, we assume that the repository contents reside in the
~/cloudapi/directory. -
Create a file named
body.jsonand paste the following code into 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>" }, "disk_size_autoscaling": { "planned_usage_threshold": "<scheduled_expansion_percentage>", "emergency_usage_threshold": "<immediate_expansion_percentage>", "disk_size_limit": "<maximum_storage_size_in_bytes>" }, "access": { "web_sql": <access_from_WebSQL> }, "redis": { "password": "<user_password>" }, "modules": { "valkey_search": { "enabled": "<enable_Valkey-Search_module>", "reader_threads": "<number_of_request_processing_threads>", "writer_threads": "<number_of_indexing_threads>" }, "valkey_json": { "enabled": "<enable_Valkey-JSON_module>" }, "valkey_bloom": { "enabled": "<enable_Valkey-Bloom_module>" } } }, "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_settings_for_host_2> }, { ... }, { <similar_settings_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>, "persistence_mode": "<persistence_mode>" }Where:
-
folder_id: Folder ID. You can get it with the list of folders in the cloud. -
name: Cluster name. -
environment: Environment,PRESTABLEorPRODUCTION. -
config_spec: Cluster settings:-
version: Valkey™ version,7.2-valkey,8.0-valkey,8.1-valkey, or9.0-valkey. -
resources: Cluster resources:resource_preset_id: Host class.disk_size: Disk size, in bytes.disk_type_id: Disk type.
-
disk_size_autoscaling: Automatic storage expansion settings:-
planned_usage_threshold: Storage usage percentage to trigger a storage expansion during the next maintenance window.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.If you set this condition, configure the
maintenance_window. -
emergency_usage_threshold: Storage usage percentage to trigger an immediate storage expansion.Use a value between
0and100%. The default value is0, i.e., automatic expansion is disabled.Warning
If you specify both thresholds,
emergency_usage_thresholdmust not be less thanplanned_usage_threshold. -
disk_size_limit: Maximum storage size after expansion, in bytes.
Warning
- You cannot reduce the storage size.
- During storage resizing, cluster hosts will be stopped and updated one at a time.
-
-
access.web_sql: Access to cluster databases from the Yandex Cloud management console using Yandex WebSQL,trueorfalse. -
redis.password: Password. -
modules: Valkey™ module parameters:valkey_search.enabled: Enable theValkey-Searchmodule,trueorfalse. What you can set up for the module:valkey_search.reader_threads: Number of request processing threads.valkey_search.writer_threads: Number of indexing threads.
valkey_json.enabled: Enable theValkey-JSONmodule,trueorfalse.valkey_bloom.enabled: Enable theValkey-Bloommodule,trueorfalse.
Warning
You cannot disable modules once enabled.
-
-
host_specs: Host settings:zone_id: Availability zone.subnet_id: Subnet ID. You must specify this setting if the selected availability zone has more than one subnet.shard_name: Shard name for the host. This setting only applies whenshardedis set totrue.replica_priority: Host priority for master promotion during failover.assign_public_ip: Internet access to the host via a public IP address,trueorfalse. You can enable public access only iftls_enabledis set totrue.
-
network_id: ID of the network where the cluster will be deployed. -
sharded: Cluster sharding,trueorfalse.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-ssddisk type, specify at least two hosts per shard, adding the appropriate number ofhost_specssections. -
security_group_ids: Security group IDs. -
tls_enabled: Support for encrypted TLS connections to the cluster,trueorfalse.Warning
You can enable encrypted connections only when creating a new cluster. You cannot disable encryption for an existing cluster.
-
deletion_protection: Cluster deletion protection,trueorfalse.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,trueorfalse.Note
Some clients do not support this setting and will fail to connect to the cluster hosts. They expect an IP address and will produce errors if you provide an FQDN instead.
-
persistence_mode: Data persistence mode.The possible values are:
ON: Enable persistence.OFF: Disable persistence.ON_REPLICAS: Enable persistence on replicas only.
-
-
Call the ClusterService.Create method, e.g., via the following gRPCurl
request: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 -
Check the server response to make sure your request was successful.
Warning
If you specified security group IDs when creating a cluster, you may need to additionally configure them to enable cluster access.
Creating a cluster copy
You can create a Valkey™ cluster with the settings of another one created earlier. Do this by importing the original Valkey™ cluster configuration into Terraform. Then you can either create an identical copy or use the imported configuration as the baseline and modify it as needed. The import feature is handy when the original Valkey™ cluster has a lot of settings and you need to create a similar one.
To create a Valkey™ cluster copy:
-
If you do not have Terraform yet, install it.
-
Get the authentication credentials. You can add them to environment variables or specify them later in the provider configuration file.
-
Configure and initialize a provider. There is no need to create a provider configuration file manually, you can download it
. -
Place the configuration file in a separate working directory and specify the parameter values. If you did not add the authentication credentials to environment variables, specify them in the configuration file.
-
In your current working directory, create a
.tffile with the following contents:resource "yandex_mdb_redis_cluster_v2" "old" { } -
Save the ID of the original Valkey™ cluster to an environment variable:
export REDIS_CLUSTER_ID=<cluster_ID>You can get the ID with the list of clusters in the folder.
-
Import the original Valkey™ cluster configuration into Terraform:
terraform import yandex_mdb_redis_cluster_v2.old ${REDIS_CLUSTER_ID} -
Get the imported configuration:
terraform show -
Copy it from the terminal and paste it into the
.tffile. -
Move the file to the new
imported-clusterdirectory. -
Modify the copied configuration to prepare it for creating a new cluster:
- Specify the new cluster name in the
resourcestring and thenameparameter. - Delete
created_at,health,id, andstatus. - Add the
passwordparameter to theconfigsection. - If you have
notify_keyspace_events = "\"\""in theconfigsection, delete this parameter. - If
sharded = false, delete theshard_nameparameters from thehostsections. - If the
maintenance_windowsection containstype = "ANYTIME", delete thehoursetting. - Optionally, make further changes if you need a customized configuration.
- Specify the new cluster name in the
-
Navigate to the
imported-clusterdirectory and get the authentication credentials. -
In the same directory, configure and initialize the provider. Instead of manually creating the provider configuration file, you can download it
. -
Move the configuration file to the
imported-clusterdirectory and specify its settings. If you have not set the authentication credentials as environment variables, specify them in the configuration file. -
Validate your Terraform configuration:
terraform validateTerraform will display any configuration errors detected in your files.
-
Create the required infrastructure:
-
Run this command to view the planned changes:
terraform planIf 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.
-
If everything looks correct, apply the changes:
-
Run this command:
terraform apply -
Confirm updating the resources.
-
Wait for the operation to complete.
-
All the required resources will be created in the specified folder. You can check resource availability and their settings in the management console
. -
Timeouts
The Terraform provider sets the following timeouts for Yandex Managed Service for Valkey™ cluster operations:
- Creating a cluster, including by restoring it from a backup: 15 minutes.
- Editing a cluster: 60 minutes.
- Deleting a cluster: 15 minutes.
Operations exceeding the timeout are aborted.
How do I change these limits?
Add the timeouts section to your cluster description, such as the following:
resource "yandex_mdb_redis_cluster_v2" "<cluster_name>" {
...
timeouts {
create = "1h30m" # 1 hour 30 minutes
update = "2h" # 2 hours
delete = "30m" # 30 minutes
}
}
Examples
Creating a single-host cluster
To create a single-host cluster, provide one --host parameter.
Create a Yandex Managed Service for Valkey™ cluster with the following test specifications:
- Name:
myredis. - Version: `9.0-valkey``.
- Environment:
production. - Network:
default. - A single
hm2.nanohost in theb0rcctk2rvtr********subnet,ru-central1-aavailability zone and security group with theenp6saqnq4ie244g67sbID, with public access and a host priority of50. - SSL support: Enabled.
- Network SSD storage (
network-ssd): 16 GB. - Password:
user1user1. - Deletion protection: Enabled.
Run this command:
yc managed-redis cluster create \
--name myredis \
--redis-version 9.0-valkey` \
--environment production \
--network-name default \
--resource-preset hm2.nano \
--host zone-id=ru-central1-a,subnet-id=b0rcctk2rvtr********,assign-public-ip=true,replica-priority=50 \
--security-group-ids enp6saqnq4ie244g67sb \
--enable-tls \
--disk-type-id network-ssd \
--disk-size 16 \
--password=user1user1 \
--deletion-protection
Create a Yandex Managed Service for Valkey™ cluster and its network with the following test specifications:
- Name:
myredis. - Version: `9.0-valkey``.
- Environment:
PRODUCTION. - Cloud ID:
b1gq90dgh25bebiu75o. - Folder ID:
b1gia87mbaomkfvsleds. - Network:
mynet(new). - A single
hm2.nanoclass host in the new subnet calledmysubnet,ru-central1-aavailability zone, with public access and a host priority of50.mysubnetCIDR range:10.5.0.0/24. - Security group:
redis-sg(new), allowing connections on port6380from any addresses inmysubnet. - 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_v2" "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 = "9.0-valkey`"
}
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"]
}
Creating a sharded cluster with a single shard
Create a sharded Yandex Managed Service for Valkey™ cluster with the following test specifications:
- Name:
myredis. - Version: `9.0-valkey``.
- Environment:
production. - Sharding: Enabled.
- SSL support: Enabled.
- Deletion protection: Enabled.
- Network:
default. - Security group ID:
enp6saqnq4ie244g67sb. - Host class:
hm2.nano. - A single host in the shard called
shard1, in theb0rcctk2rvtr********subnet,ru-central1-aavailability zone, with public access and a host priority of50. - Network SSD storage (
network-ssd): 16 GB. - Password:
user1user1.
Run this command:
yc managed-redis cluster create \
--name myredis \
--redis-version 9.0-valkey` \
--environment production \
--sharded \
--enable-tls \
--deletion-protection \
--network-name default \
--security-group-ids enp6saqnq4ie244g67sb \
--resource-preset hm2.nano \
--host shard-name=shard1,subnet-id=b0rcctk2rvtr********,zone-id=ru-central1-a,assign-public-ip=true,replica-priority=50 \
--disk-type-id network-ssd \
--disk-size 16 \
--password user1user1
Create a sharded Yandex Managed Service for Valkey™ cluster and a network for it with the following test specifications:
- Name:
myredis. - Version: `9.0-valkey``.
- Environment:
PRODUCTION. - Sharding: Enabled.
- SSL support: Enabled.
- Deletion protection: Enabled.
- Network:
mynet(new) with a single subnet:mysubnet. CIDR range formysubnet:10.5.0.0/24. - Security group:
redis-sg(new), allowing connections on port6380from any addresses inmysubnet. - Host class:
hm2.nano. - A single host in the shard called
shard1, in themysubnetsubnet,ru-central1-aavailability zone, with public access and a host priority of50. - Network SSD storage (
network-ssd): 16 GB. - Password:
user1user1.
The configuration file for this cluster is as follows:
resource "yandex_mdb_redis_cluster_v2" "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 = "9.0-valkey`"
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"]
}
}
Creating a sharded cluster with three shards
Create a sharded Yandex Managed Service for Valkey™ cluster with the following test specifications:
- Name:
myredis. - Version: `9.0-valkey``.
- Environment:
PRODUCTION. - Cloud ID:
b1gq90dgh25bebiu75o. - Folder ID:
b1gia87mbaomkfvsleds. - Network:
mynet(new). - Three subnets in the
mynetnetwork, one in each availability zone:subnet-awith the10.1.0.0/24rangesubnet-bwith the10.2.0.0/24rangesubnet-dwith the10.3.0.0/24range
- Three
hm2.nanoclass hosts, one in each subnet. - New
redis-sgsecurity group allowing connections via ports6379and26379(Valkey™ Sentinel) from any subnet addresses. - 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_v2" "myredis" {
name = "myredis"
environment = "PRODUCTION"
network_id = yandex_vpc_network.mynet.id
security_group_ids = [yandex_vpc_security_group.redis-sg.id]
sharded = true
deletion_protection = true
config {
password = "user1user1"
version = "9.0-valkey`"
}
resources {
resource_preset_id = "hm2.nano"
disk_type_id = "network-ssd"
disk_size = 16
}
host {
zone = "ru-central1-a"
subnet_id = yandex_vpc_subnet.subnet-a.id
shard_name = "shard1"
}
host {
zone = "ru-central1-b"
subnet_id = yandex_vpc_subnet.subnet-b.id
shard_name = "shard2"
}
host {
zone = "ru-central1-d"
subnet_id = yandex_vpc_subnet.subnet-d.id
shard_name = "shard3"
}
}
resource "yandex_vpc_network" "mynet" { name = "mynet" }
resource "yandex_vpc_subnet" "subnet-a" {
name = "subnet-a"
zone = "ru-central1-a"
network_id = yandex_vpc_network.mynet.id
v4_cidr_blocks = ["10.1.0.0/24"]
}
resource "yandex_vpc_subnet" "subnet-b" {
name = "subnet-b"
zone = "ru-central1-b"
network_id = yandex_vpc_network.mynet.id
v4_cidr_blocks = ["10.2.0.0/24"]
}
resource "yandex_vpc_subnet" "subnet-d" {
name = "subnet-d"
zone = "ru-central1-d"
network_id = yandex_vpc_network.mynet.id
v4_cidr_blocks = ["10.3.0.0/24"]
}
resource "yandex_vpc_security_group" "redis-sg" {
name = "redis-sg"
network_id = yandex_vpc_network.mynet.id
ingress {
description = "Valkey™"
port = 6379
protocol = "TCP"
v4_cidr_blocks = [
"10.1.0.0/24",
"10.2.0.0/24",
"10.3.0.0/24"
]
}
ingress {
description = "Valkey™ Sentinel"
port = 26379
protocol = "TCP"
v4_cidr_blocks = [
"10.1.0.0/24",
"10.2.0.0/24",
"10.3.0.0/24"
]
}
}