Оператор Memcached - Руководство пользователя

Это руководство предназначено для пользователей кластера Deckhouse Kubernetes Platform, которые хотят развернуть и использовать Memcached для своих приложений.

Основной инструмент пользователя — ресурс Memcached. Этот Custom Resource позволяет вам создавать и управлять инстансами Memcached в своих namespace. Все инстансы создаются на основе классов (MemcachedClass), которые определяет администратор кластера. Классы задают доступные конфигурации, ограничения ресурсов и правила размещения.

Версия API: Модуль в настоящее время использует версию API v1alpha2. Предыдущая версия v1alpha1 по-прежнему поддерживается через автоматические webhook-конверсии. Существующие ресурсы, созданные с v1alpha1, продолжат работать без изменений, и оператор автоматически конвертирует их при необходимости. Для новых ресурсов рекомендуется использовать v1alpha2.

Содержание

Быстрый старт

После установки оператора вы можете сразу начать создавать инстансы Memcached. Модуль поставляется с готовым к использованию дефолтным классом default, который включает разумные настройки по умолчанию и правила валидации. Этот класс готов к использованию в production и подходит для большинства типичных сценариев.

Вы можете использовать этот дефолтный класс сразу или попросить администратора кластера создать кастомные классы для специфических требований.

1. Проверьте доступные классы

Сначала проверьте, какие MemcachedClass доступны (созданы администратором кластера):

# Список доступных классов
kubectl get memcachedclass

# Просмотр деталей класса
kubectl get memcachedclass default -o yaml

Класс определяет лимиты ресурсов, разрешенные конфигурации и правила валидации. Ваш администратор кластера может создать дополнительные классы для разных окружений (dev, staging, production).

Важно: Если вы укажете имя класса, которого не существует в кластере, ваш ресурс Memcached будет создан, но сервис не будет развернут до тех пор, пока класс не появится. Когда администратор создаст класс, все валидации выполнятся автоматически, и любые ошибки появятся в status.conditions. Вы можете проверить их с помощью:

kubectl describe memcached <name>
kubectl get memcached <name> -o yaml | grep -A 10 conditions

2. Создайте инстанс Memcached

Создайте простой standalone инстанс Memcached, используя класс default:

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: Memcached
metadata:
  name: my-memcached
  namespace: default
spec:
  memcachedClassName: default  # Используем класс default
  type: Standalone
  instance:
    memory:
      size: "256Mi"
    cpu:
      cores: 1
      coreFraction: "5%"

Примените конфигурацию:

kubectl apply -f memcached.yaml

3. Проверьте статус

Отслеживайте статус развертывания:

# Проверьте инстанс Memcached
kubectl get memcached my-memcached

# Получите подробный статус
kubectl describe memcached my-memcached

# Просмотрите полную конфигурацию
kubectl get memcached my-memcached -o yaml

Дождитесь, пока условие Available станет True.

4. Получите строку подключения

Оператор создает Headless Service для подключения вашего приложения к Memcached. Формат DNS-имени: d8ms-mc-<имя>-<индекс>.<namespace>.svc.cluster.local

Для Standalone инстансов:

d8ms-mc-my-memcached-0.default.svc.cluster.local:11211

Для Group инстансов (например, 3 реплики):

d8ms-mc-my-memcached-0.default.svc.cluster.local:11211
d8ms-mc-my-memcached-1.default.svc.cluster.local:11211
d8ms-mc-my-memcached-2.default.svc.cluster.local:11211

Ваше приложение должно подключаться ко всем инстансам для распределенного кэширования.

Конфигурация инстанса

Базовая конфигурация

Каждому инстансу Memcached требуется следующая базовая конфигурация:

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: Memcached
metadata:
  name: my-memcached
  namespace: default
spec:
  memcachedClassName: default  # Обязательно: ссылка на MemcachedClass
  type: Standalone             # Обязательно: Standalone или Group
  instance:                    # Обязательно: выделение ресурсов
    memory:
      size: "1Gi"
    cpu:
      cores: 2
      coreFraction: "10%"

Ключевые поля:

  • memcachedClassName: Имя MemcachedClass для использования (узнайте у администратора кластера)
  • type: Тип развертывания - Standalone (один инстанс) или Group (несколько инстансов)
  • instance: Выделение ресурсов (должно соответствовать sizing policies класса)

Standalone vs Group

Standalone

Один инстанс, подходит для разработки или некритичных нагрузок:

spec:
  type: Standalone
  instance:
    memory:
      size: "512Mi"
    cpu:
      cores: 1
      coreFraction: "5%"

Group

Несколько инстансов для высокой доступности и распределения нагрузки:

spec:
  type: Group
  group:
    size: 3              # Количество инстансов
    topology: TransZonal # Zonal, TransZonal или Ignored
  instance:
    memory:
      size: "1Gi"
    cpu:
      cores: 2
      coreFraction: "10%"

Варианты топологии:

  • Zonal: Все инстансы в одной зоне доступности
  • TransZonal: Инстансы распределены по разным зонам
  • Ignored: Позволить планировщику Kubernetes решать

Примечание: Доступные топологии определяются MemcachedClass. Уточните у администратора кластера.

Конфигурация ресурсов

Память и CPU

Ресурсы должны попадать в диапазоны, определенные sizing policies класса:

instance:
  memory:
    size: "512Mi"    # Должен быть в пределах класса и соответствовать step, если определен
  cpu:
    cores: 2         # Должен быть в пределах класса
    coreFraction: "10%" # Должен быть в разрешенном списке, если определен

Типичные значения coreFraction:

  • "5%": 5% ядра CPU (минимальная нагрузка)
  • "10%": 10% ядра CPU (легкая нагрузка)
  • "25%": 25% ядра CPU (умеренная нагрузка)
  • "50%": 50% ядра CPU (высокая нагрузка)
  • "100%": 100% ядра CPU (максимальная производительность)

Если ваша конфигурация не соответствует политикам класса, вы получите ошибку валидации:

haven't found matching size policy in class

Обратитесь к администратору для настройки класса или выберите корректные значения.

Кастомная конфигурация

Вы можете переопределить определенные параметры конфигурации Memcached, если класс это позволяет (проверьте overridableConfiguration в классе):

spec:
  configuration:
    maxItemSize: "2Mi"      # Максимальный размер кешируемого элемента
    slabMinSize: "Medium"   # Размер slab-страницы: Short, Medium или Long
    lockMemory: false       # Блокировать память для предотвращения свопинга

Параметры конфигурации:

Параметр Описание Значения Типичное использование
maxItemSize Максимальный размер одного кешируемого элемента например, “512k”, “1Mi”, “4Mi” Устанавливается на основе самых больших объектов
slabMinSize Минимальный размер slab-страницы Short (50 байт)
Medium (100 байт)
Long (200 байт)		 Соответствует типичным размерам объектов
lockMemory Использовать mlockall() для блокировки памяти true, false Включайте для production для предотвращения свопинга

Примечание: Можно изменять только параметры, указанные в overridableConfiguration класса. Попытка переопределить другие параметры приведет к ошибке валидации.

Примеры

Пример 1: Development инстанс

Небольшой standalone инстанс для разработки:

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: Memcached
metadata:
  name: dev-cache
  namespace: development
spec:
  memcachedClassName: default
  type: Standalone
  instance:
    memory:
      size: "256Mi"
    cpu:
      cores: 1
      coreFraction: "5%"

Пример 2: Production Group

Высокодоступная группа с кастомной конфигурацией:

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: Memcached
metadata:
  name: prod-cache
  namespace: production
spec:
  memcachedClassName: production  # Используем production-класс
  type: Group
  group:
    size: 3
    topology: TransZonal
  instance:
    memory:
      size: "2Gi"
    cpu:
      cores: 2
      coreFraction: "5%"0
  configuration:
    maxItemSize: "4Mi"
    slabMinSize: "Medium"

Пример 3: Большой Standalone инстанс

Один инстанс с большими ресурсами:

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: Memcached
metadata:
  name: large-cache
  namespace: default
spec:
  memcachedClassName: default
  type: Standalone
  instance:
    memory:
      size: "4Gi"
    cpu:
      cores: 4
      coreFraction: "25%"
  configuration:
    maxItemSize: "8Mi"

Для дополнительных примеров и сценариев использования см. документ Примеры.

Поиск и устранение неисправностей

Частые ошибки

1. MemcachedClass не найден

Ошибка: MemcachedClass <name> not found

Решение: Проверьте доступные классы и используйте корректное имя:

kubectl get memcachedclass

Обратитесь к администратору кластера, если вам нужен конкретный класс.

2. Ошибка валидации конфигурации

Ошибка: Configuration validation failed: <детали>

Решение: Проверьте сообщение об ошибке валидации в статусе:

kubectl describe memcached <name>
kubectl get memcached <name> -o yaml | grep -A 10 conditions

Распространенные ошибки валидации:

  • Параметр конфигурации не в overridableConfiguration
  • Не выполнено CEL-правило валидации (например, maxItemSize слишком большой)
  • Недопустимое значение параметра

3. Несоответствие Sizing Policy

Ошибка: haven't found matching size policy in class

Решение: Ваша конфигурация CPU/памяти не соответствует ни одной sizing policy в классе:

# Проверьте sizing policies класса
kubectl get memcachedclass <class-name> -o yaml | grep -A 20 sizingPolicies

Скорректируйте конфигурацию в соответствии с одной из политик или обратитесь к администратору.

4. Топология не разрешена

Ошибка: topology <type> not allowed by class

Решение: Запрошенная топология отсутствует в разрешенных топологиях класса:

# Проверьте разрешенные топологии
kubectl get memcachedclass <class-name> -o jsonpath='{.spec.topology.allowedTopologies}'

Выберите разрешенную топологию или не указывайте поле topology для использования значения по умолчанию.

Описание статусов

Отслеживайте эти условия в status.conditions:

kubectl get memcached <name> -o jsonpath='{.status.conditions[*]}' | jq

Условия:

Условие Описание Значение
ConfigurationValid Статус валидации конфигурации True: конфигурация валидна
False: валидация не прошла
Available Доступность сервиса True: сервис доступен (>50% подов готовы)
False: сервис недоступен
LastValidConfigurationApplied Последняя валидная конфигурация применена True: конфигурация успешно применена ко всем инстансам
ScaledToLastValidConfiguration Статус масштабирования True: все инстансы работают с текущей конфигурацией

Команды для отладки

# Получить статус инстанса
kubectl get memcached <name>
kubectl describe memcached <name>

Лучшие практики

Планирование ресурсов

  1. Выделение памяти

    • Выделяйте 70-80% памяти инстанса под данные Memcached
    • Учитывайте накладные расходы на соединения и метаданные
    • Используйте мониторинг памяти для правильного подбора размера инстансов

  2. Выделение CPU

    • Начните с меньших значений coreFraction и увеличивайте при необходимости
    • Отслеживайте использование CPU для оптимизации coreFraction
    • Используйте более высокие значения coreFraction для write-intensive нагрузок

  3. Размер инстанса

    • Начинайте с малого и масштабируйте на основе мониторинга
    • Несколько меньших инстансов (Group) часто лучше, чем один большой
    • Учитывайте пропускную способность сети при выборе размера

Конфигурация

  1. maxItemSize

    • Устанавливайте на основе самых больших кешируемых объектов
    • Типичные значения: 1Mi для малых объектов, 4Mi для средних, 8Mi+ для больших
    • Помните: должен быть меньше половины памяти инстанса

  2. slabMinSize

    • Short (50 байт): Большинство объектов < 50 байт
    • Medium (100 байт): Большинство объектов < 100 байт
    • Long (200 байт): Более крупные объекты
    • Выбирайте на основе наибольшего используемого ключа

  3. lockMemory

    • true: Рекомендуется для production (предотвращает свопинг)
    • false: Допустимо для development/testing
    • Требует настройки ОС

Высокая доступность

  1. Используйте тип Group

    • Всегда используйте Group для production нагрузок
    • Минимум 3 инстанса для отказоустойчивости

  2. Выбор топологии

    • TransZonal: Лучше всего для production (распределение по зонам)
    • Zonal: Используйте, когда весь трафик в одной зоне
    • Ignored: Только для development/testing

  3. Настройка клиента

    • Настройте клиенты для подключения ко всем инстансам
    • Реализуйте распределенное кэширование в вашем приложении
    • Корректно обрабатывайте сбои инстансов

  4. Мониторинг

    • Отслеживайте соотношение попаданий/промахов (hit/miss ratio)
    • Следите за использованием памяти и вытеснениями (evictions)
    • Настройте алерты на перезапуски подов
    • Отслеживайте время отклика

Для более продвинутых тем и информации для администраторов см. Руководство администратора.