Работа с модулями Valkey™

Статья создана

Улучшена

Обновлена 24 февраля 2026 г.

Подключение модулей
Изменение настроек модулей

В Yandex Managed Service for Valkey™ доступно подключение модулей — расширений ядра Valkey™. Модули предоставляют функциональность для решения современных задач с помощью высоконагруженных сервисов и AI-платформ — векторный поиск, эффективное хранение JSON-структур данных и масштабируемые вероятностные фильтры.

Вы можете подключить модули к новому или существующему кластеру, а также изменить настройки модуля.

Подключение модулей

Важно

После подключения модули невозможно отключить.

Консоль управления

CLI

Terraform

REST API

gRPC API

В консоли управления перейдите в каталог с нужным кластером.
Перейдите в сервис Yandex Managed Service for Valkey™.
Выберите нужный кластер.
В верхней части страницы нажмите кнопку Редактировать.
В блоке Модули подключите необходимые модули Valkey™.

Для модуля Search настройте параметры Количество потоков чтения и Количество потоков записи.
Нажмите кнопку Сохранить изменения.

Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

Чтобы подключить модули:

Посмотрите описание команды CLI для обновления кластера:
```
yc managed-redis cluster update --help
```
Выполните команду подключения модулей:
```
yc managed-redis cluster update \
  --cluster-name=<имя_кластера> \
  --valkey-modules enable-valkey-search=<включить_модуль_Valkey-Search>,`
                   `valkey-search-reader-threads=<количество_потоков_обработки_запросов>,`
                   `valkey-search-writer-threads=<количество_потоков_индексации>,`
                   `enable-valkey-json=<включить_модуль_Valkey-JSON>,`
                   `enable-valkey-bloom=<включить_модуль_Valkey-Bloom>
```
Где:
- --cluster-name — имя кластера Yandex Managed Service for Valkey™. Его можно запросить со списком кластеров в каталоге.
- --valkey-modules — параметры модулей Valkey™:
  - enable-valkey-search — подключить модуль Valkey-Search: true или false.
  - valkey-search-reader-threads — количество потоков обработки запросов в модуле Valkey-Search.
  - valkey-search-writer-threads — количество потоков индексации в модуле Valkey-Search.
  - enable-valkey-json — подключить модуль Valkey-JSON: true или false.
  - enable-valkey-bloom — подключить модуль Valkey-Bloom: true или false.

Откройте актуальный конфигурационный файл Terraform с планом инфраструктуры.

О том, как создать такой файл, см. в разделе Создание кластера.
Добавьте в описание кластера Yandex Managed Service for Valkey™ блок modules:
```
resource "yandex_mdb_redis_cluster_v2" "<имя_кластера>" {
  ...
  modules = {
    valkey_bloom = {
      enabled = <включить_модуль_Valkey-Bloom>
    }
    valkey_json = {
      enabled = <включить_модуль_Valkey-JSON>
    }
    valkey_search = {
      enabled        = <включить_модуль_Valkey-Search>
      reader_threads = <количество_потоков_обработки_запросов>
      writer_threads = <количество_потоков_индексации>
    }
  }
}
```
Где:
- valkey_bloom.enabled — подключить модуль Valkey-Bloom: true или false.
- valkey_json.enabled — подключить модуль Valkey-JSON: true или false.
- valkey_search.enabled — подключить модуль Valkey-Search: true или false.
- valkey_search.reader_threads — количество потоков обработки запросов в модуле Valkey-Search.
- valkey_search.writer_threads — количество потоков индексации в модуле Valkey-Search.
Проверьте корректность настроек.
1. В командной строке перейдите в каталог, в котором расположены актуальные конфигурационные файлы Terraform с планом инфраструктуры.
2. Выполните команду:
```
terraform validate
```
  Если в файлах конфигурации есть ошибки, Terraform на них укажет.
Подтвердите изменение ресурсов.
1. Выполните команду для просмотра планируемых изменений:
```
terraform plan
```
  Если конфигурации ресурсов описаны верно, в терминале отобразится список изменяемых ресурсов и их параметров. Это проверочный этап: ресурсы не будут изменены.
2. Если вас устраивают планируемые изменения, внесите их:
  1. Выполните команду:
```
terraform apply
```
  2. Подтвердите изменение ресурсов.
  3. Дождитесь завершения операции.

Подробнее см. в документации провайдера Terraform.

Ограничения по времени

Провайдер Terraform ограничивает время на выполнение операций с кластером Yandex Managed Service for Valkey™:

создание, в т. ч. путем восстановления из резервной копии, — 15 минут;
изменение — 60 минут;
удаление — 15 минут.

Операции, длящиеся дольше указанного времени, прерываются.

Как изменить эти ограничения?

Добавьте к описанию кластера блок timeouts, например:

resource "yandex_mdb_redis_cluster_v2" "<имя_кластера>" {
  ...
  timeouts {
    create = "1h30m" # Полтора часа
    update = "2h"    # 2 часа
    delete = "30m"   # 30 минут
  }
}

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Воспользуйтесь методом Cluster.Update и выполните запрос, например с помощью cURL:

Важно

Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре updateMask (одной строкой через запятую).
```
curl \
    --request PATCH \
    --header "Authorization: Bearer $IAM_TOKEN" \
    --header "Content-Type: application/json" \
    --url 'https://mdb.api.cloud.yandex.net/managed-redis/v1/clusters/<идентификатор_кластера>' \
    --data '{
              "updateMask": "configSpec.modules.valkeySearch.enabled,configSpec.modules.valkeySearch.readerThreads,configSpec.modules.valkeySearch.writerThreads,configSpec.valkeyJson.enabled,configSpec.valkeyBloom.enabled",
              "configSpec": {
                "modules": {
                  "valkeySearch": {
                    "enabled": "<включить_модуль_Valkey-Search>",
                    "readerThreads": "<количество_потоков_обработки_запросов>",
                    "writerThreads": "<количество_потоков_индексации>"
                  },
                  "valkeyJson": {
                    "enabled": "<включить_модуль_Valkey-JSON>"
                  },
                  "valkeyBloom": {
                    "enabled": "<включить_модуль_Valkey-Bloom>"
                  }
                }
              }
            }'
```
Где:
- updateMask — перечень изменяемых параметров в одну строку через запятую.
- configSpec.modules — параметры модулей Valkey™:
  - valkeySearch.enabled — подключить модуль Valkey-Search: true или false. Для модуля доступна настройка параметров:
    - valkeySearch.readerThreads — количество потоков обработки запросов.
    - valkeySearch.writerThreads — количество потоков индексации.
  - valkeyJson.enabled — подключить модуль Valkey-JSON: true или false.
  - valkeyBloom.enabled — подключить модуль Valkey-Bloom: true или false.
Идентификатор кластера можно запросить со списком кластеров в каталоге.
Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Получите IAM-токен для аутентификации в API и поместите токен в переменную среды окружения:
```
export IAM_TOKEN="<IAM-токен>"
```
Клонируйте репозиторий cloudapi:
```
cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
```
Далее предполагается, что содержимое репозитория находится в директории ~/cloudapi/.

Воспользуйтесь вызовом ClusterService.Update и выполните запрос, например с помощью gRPCurl:

Важно

Метод API переопределит все параметры изменяемого объекта, которые не были явно переданы в запросе, на значения по умолчанию. Чтобы избежать этого, перечислите настройки, которые вы хотите изменить, в параметре update_mask (в виде массива строк paths[]).

Формат перечисления настроек

"update_mask": {
    "paths": [
        "<настройка_1>",
        "<настройка_2>",
        ...
        "<настройка_N>"
    ]
}

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 '{
          "cluster_id": "<идентификатор_кластера>",
          "update_mask": {
            "paths": [
              "config_spec.modules.valkey_search.enabled",
              "config_spec.modules.valkey_search.reader_threads",
              "config_spec.modules.valkey_search.writer_threads",
              "config_spec.valkey_json.enabled",
              "config_spec.valkey_bloom.enabled"
            ]
          },
          "config_spec": {
            "modules": {
              "valkey_search": {
                "enabled": "<включить_модуль_Valkey-Search>",
                "reader_threads": "<количество_потоков_обработки_запросов>",
                "writer_threads": "<количество_потоков_индексации>"
              },
              "valkey_json": {
                "enabled": "<включить_модуль_Valkey-JSON>"
              },
              "valkey_bloom": {
                "enabled": "<включить_модуль_Valkey-Bloom>"
              }
            }
          }
        }' \
    mdb.api.cloud.yandex.net:443 \
    yandex.cloud.mdb.redis.v1.ClusterService.Update

Где:

update_mask — перечень изменяемых параметров в виде массива строк paths[].
config_spec.modules — параметры модулей Valkey™:
- valkey_search.enabled — подключить модуль Valkey-Search: true или false. Для модуля доступна настройка параметров:
  - valkey_search.reader_threads — количество потоков обработки запросов.
  - valkey_search.writer_threads — количество потоков индексации.
- valkey_json.enabled — подключить модуль Valkey-JSON: true или false.
- valkey_bloom.enabled — подключить модуль Valkey-Bloom: true или false.

Идентификатор кластера можно запросить со списком кластеров в каталоге.

Убедитесь, что запрос был выполнен успешно, изучив ответ сервера.

Изменение настроек модулей