Руководство администратора

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

Основной инструмент администратора — ресурс MemcachedClass. Этот cluster-scoped Custom Resource определяет, какие конфигурации Memcached могут быть развернуты пользователями, устанавливает политики ресурсов, ограничения и правила валидации. Все пользовательские инстансы Memcached создаются на основе классов, которые вы определяете как администратор.

Содержание

Описание

MemcachedClass — это cluster-scoped Custom Resource, который определяет политики и ограничения для создаваемых пользователями ресурсов Memcached.

По сути, MemcachedClass является конструктором для managed-service Memcached — он задает набор правил и значений по умолчанию, на основе которых будут создаваться конкретные инстансы Memcached. Каждый ресурс Memcached, созданный пользователем, обязан ссылаться на один из существующих классов через поле memcachedClassName.

Администратор кластера создает и управляет классами, чтобы контролировать, какие конфигурации Memcached могут быть развернуты в кластере.

Назначение MemcachedClass

Ресурс MemcachedClass позволяет администратору:

  • Определить допустимые диапазоны CPU и памяти для инстансов Memcached
  • Задать конфигурацию Memcached по умолчанию
  • Ограничить параметры, которые пользователи могут переопределять
  • Настроить правила размещения подов (node affinity, tolerations, node selector)
  • Определить политики топологии для обеспечения высокой доступности
  • Установить кастомные правила валидации с использованием CEL (Common Expression Language)

Структура ресурса MemcachedClass

Базовый пример (default класс из модуля)

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: MemcachedClass
metadata:
  name: default
spec:
  topology:
    allowedTopologies:
      - Zonal
      - TransZonal
      - Ignored
    defaultTopology: "Ignored"
  overridableConfiguration:
    - maxItemSize
    - slabMinSize
  validations:
    - message: "max item size must be smaller than 1/2 memory size"
      rule: "configuration.maxItemSize <= (instance.memory.size / 2)"
    - message: "maxItemSize must be greater than 512k"
      rule: "configuration.maxItemSize >= (1024 * 512)"
    - message: "maxItemSize must divisible by slabChunkMax (default 524288 bytes 512kB)"
      rule: "(configuration.maxItemSize % (1024 * 512)) == 0"
  configuration:
    threads: 5
    maxConnections: 2000
    maxItemSize: "4Mi"
    slabMinSize: "Short"
    lockMemory: false
  sizingPolicies:
    - cores:
        min: 1
        max: 4
      memory:
        min: 100Mi
        max: 1Gi
        step: 1Mi
      coreFraction:
        - "1%"
        - "5%"
        - "10%"
    - cores:
        min: 5
        max: 10
      memory:
        min: 400Mi
        max: 10Gi
      coreFraction:
        - "5%"
        - "10%"
        - "15%"

Поля спецификации

1. sizingPolicies (обязательное)

Определяет допустимые комбинации CPU и памяти. Пользовательский Memcached ресурс должен попадать в один из определенных sizing policies.

sizingPolicies:
  - cores:
      min: 1          # Минимальное количество ядер
      max: 4          # Максимальное количество ядер
    memory:
      min: 256Mi      # Минимальный объем памяти
      max: 8Gi        # Максимальный объем памяти
      step: 256Mi     # Шаг изменения памяти (опционально)
    coreFraction:     # Допустимые значения coreFraction (опционально)
      - "5%"
      - "10%"
      - "25%"

Правила валидации:

  • CPU и память пользовательского инстанса должны попадать в диапазон одного из sizing policies
  • Если указан coreFraction, значение пользователя должно быть в списке
  • Если указан step, размер памяти пользователя должен быть кратен этому шагу
  • Диапазоны CPU разных sizing policies не должны пересекаться

Пример ошибки:

Если пользователь создает Memcached с 3 cores и 16Gi памяти при указанном выше sizing policy:

haven't found matching size policy in class default

2. configuration (опционально)

Конфигурация Memcached по умолчанию. Эти значения используются, если пользователь не указывает свои или если пользователю запрещено указывать свои через overridableConfiguration

configuration:
  threads: 4                    # Количество рабочих потоков Memcached (только для администратора)
  maxConnections: 1024          # Максимальное количество одновременных подключений (только для администратора)
  maxItemSize: "4Mi"           # Максимальный размер элемента в кеше
  slabMinSize: "Medium"        # Размер slab (Short: 50 bytes, Medium: 100 bytes, Long: 200 bytes)
  lockMemory: false            # Блокировка памяти (mlockall)

Важно: Параметры threads и maxConnections доступны только для администратора и не могут быть добавлены в overridableConfiguration. Пользователи не могут переопределять эти параметры.

Параметры:

Параметр Тип Описание Значения Доступность
threads integer Количество рабочих потоков сервера Memcached Положительное число Только администратор
maxConnections integer Максимальное количество одновременных подключений Положительное число Только администратор
maxItemSize Quantity Максимальный размер элемента в кеше Например: “512k”, “1Mi”, “4Mi” Может быть в overridableConfiguration
slabMinSize string Минимальный размер slab-страницы “Short” (50 bytes), “Medium” (100 bytes), “Long” (200 bytes) Может быть в overridableConfiguration
lockMemory boolean Блокировать память (использовать mlockall) true/false Может быть в overridableConfiguration

3. overridableConfiguration (опционально)

Список параметров конфигурации, которые пользователь может переопределить в своем Memcached ресурсе.

overridableConfiguration:
  - maxItemSize
  - slabMinSize
  - lockMemory

Допустимые значения:

  • lockMemory
  • slabMinSize
  • maxItemSize

Важно: Если пользователь попытается переопределить параметр, не указанный в overridableConfiguration, валидация завершится с ошибкой:

ValidationError: configuration field [<field_name>] is not allowed to be overridden by user

4. validations (опционально)

Кастомные правила валидации на основе CEL (Common Expression Language).

Важно: В дефолтном классе default уже созданы CEL-правила, которые предотвращают запуск невалидных конфигураций Memcached (например, когда maxItemSize слишком большой или не кратен требуемому значению). Эти правила основаны на ограничениях самого сервера Memcached и помогают избежать ошибок конфигурации.

Рекомендация: При создании собственных классов настоятельно рекомендуется копировать эти правила валидации из дефолтного класса в ваши кастомные классы. Это обеспечит базовую проверку корректности конфигурации и предотвратит создание инстансов с некорректными параметрами.

validations:
  - message: "max item size must be smaller than 1/2 memory size"
    rule: "configuration.maxItemSize <= (instance.memory.size / 2)"
  - message: "maxItemSize must be greater than 512k"
    rule: "configuration.maxItemSize >= (1024 * 512)"
  - message: "maxItemSize must be divisible by 512k"
    rule: "(configuration.maxItemSize % (1024 * 512)) == 0"

Доступные переменные в CEL:

Переменная Тип Описание
instance.memory.size int Размер памяти в байтах
instance.cpu.cores int Количество ядер CPU
configuration.maxItemSize int Максимальный размер элемента в байтах
configuration.lockMemory bool Флаг блокировки памяти
configuration.cpu.coreFraction int Доля ядра CPU (1-100)
configuration.slabMinSize string Размер slab (“Short”, “Medium”, “Long”)
configuration.maxConnections int Максимальное количество подключений
configuration.threads int Количество потоков

Примеры правил:

# Проверка, что maxItemSize не превышает половину памяти
- message: "maxItemSize too large"
  rule: "configuration.maxItemSize <= (instance.memory.size / 2)"

# Проверка соотношения потоков и ядер
- message: "threads should not exceed cores * 2"
  rule: "configuration.threads <= (instance.cpu.cores * 2)"

5. topology (обязательное)

Определяет политики топологии для высокой доступности.

topology:
  allowedTopologies:
    - Zonal
    - TransZonal
    - Ignored
  defaultTopology: "TransZonal"
  allowedZones:
    - zone-a
    - zone-b
    - zone-c

Параметры:

  • allowedTopologies — список разрешенных топологий:

    • Zonal: все поды кластера размещаются в одной зоне (требует ровно 1 зону в allowedZones)
    • TransZonal: поды кластера размещаются в разных зонах (требует минимум 2 зоны)
    • Ignored: поды размещаются без учета зон, используются стандартные правила k8s

  • defaultTopology — топология по умолчанию (если пользователь не указал)

  • allowedZones — список разрешенных зон доступности (опционально)

Правила валидации:

  1. Для TransZonal:

    • Требуется минимум 2 зоны в allowedZones
    • Размер группы (group.size) не должен превышать количество зон

  2. Для Zonal:

    • Требуется ровно 1 зона в allowedZones

  3. defaultTopology должна быть в списке allowedTopologies

Примеры ошибок:

ValidationError: topology TransZonal not allowed by class default
TransZonal Topology can't be used with less than 2 AllowedZones in selected memcachedClass
You need to have at least 3 allowed zones in memcached class default. You have only 2

6. Правила размещения подов

Важно о мердже правил размещения:

Правила размещения подов из класса (affinity, tolerations, topologySpreadConstraints, nodeSelector и т.д. и параметры topology) объединяются с правилами из пользовательского ресурса Memcached:

  • Стандартное поведение: Применяются одновременно и правила из класса (заданные администратором), и правила из пользовательского ресурса. Это позволяет администратору установить базовые требования к размещению, которые пользователь может дополнить своими специфичными требованиями.

  • Особый случай (Ignored topology): Если пользователь явно указывает топологию Ignored в своем ресурсе, и это разрешено в allowedTopologies класса, то для размещения будут применены только правила администратора из класса (affinity, tolerations, topologySpreadConstraints), без автоматического распределения по зонам.

nodeSelector (опционально)

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

nodeSelector:
  node-role.kubernetes.io/memcached: ""
  disktype: ssd

affinity (опционально)

Настройка node affinity для более гибкого управления размещением.

affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
        - matchExpressions:
            - key: node.deckhouse.io/group
              operator: In
              values:
                - memcached

tolerations (опционально)

Позволяет подам размещаться на узлах с taint’ами.

tolerations:
  - key: "memcached"
    operator: "Equal"
    value: "true"
    effect: "NoSchedule"
  - key: "high-memory"
    operator: "Exists"
    effect: "NoSchedule"

Как MemcachedClass ограничивает пользовательские ресурсы

Важное замечание о несуществующих классах

Важно: Если пользователь указал в memcachedClassName класс, которого не существует в кластере, ресурс Memcached будет успешно создан, но сервис не будет развернут до тех пор, пока указанный класс не появится в кластере.

Когда администратор создаст требуемый класс:

  1. Автоматически запустятся все валидации пользовательского ресурса
  2. Если будут обнаружены ошибки валидации, они будут записаны в status.conditions ресурса Memcached
  3. Пользователь сможет увидеть эти ошибки через kubectl describe memcached <name> или проверив conditions в статусе

Это позволяет пользователям заранее создавать ресурсы в ожидании появления нужного класса, но администратору следует информировать пользователей о создании новых классов.

Процесс валидации

Когда пользователь создает или обновляет ресурс Memcached, оператор выполняет следующие проверки:

  1. Валидация Sizing Policy

    • Проверяет, что CPU и память попадают в один из sizingPolicies
    • Проверяет coreFraction, если указан в policy
    • Проверяет step памяти, если указан в policy

  2. Валидация пользовательской конфигурации

    • Проверяет, что пользователь переопределяет только поля из overridableConfiguration

  3. Валидация топологии

    • Проверяет, что выбранная топология есть в allowedTopologies
    • Проверяет соответствие количества зон требованиям топологии

  4. CEL валидации

    • Выполняет все правила из validations

Примеры валидации

Пример 1: Несоответствие sizing policy

MemcachedClass:

sizingPolicies:
  - cores:
      min: 1
      max: 4
    memory:
      min: 256Mi
      max: 8Gi

Memcached (ошибка):

spec:
  instance:
    cpu:
      cores: 8        # Превышает max: 4
    memory:
      size: 16Gi

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

Пример 2: Попытка переопределить запрещенный параметр

MemcachedClass:

configuration:
  threads: 4
  maxItemSize: "4Mi"
overridableConfiguration:
  - maxItemSize

Memcached (ошибка):

spec:
  configuration:
    maxItemSize: "2Mi"  # OK - в списке overridableConfiguration
    lockMemory: true    # ERROR - не в списке overridableConfiguration

Ошибка: configuration field [lockMemory] is not allowed to be overridden by user

Пример 3: Нарушение CEL правила

MemcachedClass:

validations:
  - message: "maxItemSize must be less than half of memory"
    rule: "configuration.maxItemSize <= (instance.memory.size / 2)"

Memcached (ошибка):

spec:
  instance:
    memory:
      size: 1Gi
  configuration:
    maxItemSize: "600Mi"  # Больше чем 512Mi (половина от 1Gi)

Ошибка: ValidationError: maxItemSize must be less than half of memory

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

Пример 1: Класс для development окружения

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: MemcachedClass
metadata:
  name: dev
spec:
  sizingPolicies:
    - cores:
        min: 1
        max: 2
      memory:
        min: 128Mi
        max: 2Gi
      coreFraction:
        - "5%"
        - "10%"
  
  configuration:
    threads: 2
    maxConnections: 500
    maxItemSize: "1Mi"
    slabMinSize: "Short"
    lockMemory: false
  
  overridableConfiguration:
    - maxItemSize
    - slabMinSize
  
  topology:
    allowedTopologies:
      - Ignored
    defaultTopology: "Ignored"
  
  validations:
    - message: "maxItemSize must be smaller than 1/2 memory size"
      rule: "configuration.maxItemSize <= (instance.memory.size / 2)"

Пример 2: Класс для production окружения

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: MemcachedClass
metadata:
  name: production
spec:
  sizingPolicies:
    - cores:
        min: 4
        max: 16
      memory:
        min: 4Gi
        max: 64Gi
        step: 4Gi
      coreFraction:
        - "50%"
        - "100%"
  
  configuration:
    threads: 8
    maxConnections: 4096
    maxItemSize: "8Mi"
    slabMinSize: "Medium"
    lockMemory: true
  
  overridableConfiguration:
    - maxItemSize
    - slabMinSize
  
  nodeSelector:
    node-role.kubernetes.io/memcached: ""
  
  tolerations:
    - key: "memcached"
      operator: "Equal"
      value: "true"
      effect: "NoSchedule"
  
  topology:
    allowedTopologies:
      - TransZonal
    defaultTopology: "TransZonal"
    allowedZones:
      - zone-a
      - zone-b
      - zone-c
  
  validations:
    - message: "maxItemSize must be smaller than 1/2 memory size"
      rule: "configuration.maxItemSize <= (instance.memory.size / 2)"
    - message: "maxItemSize must be greater than 1Mi"
      rule: "configuration.maxItemSize >= (1024 * 1024)"
    - message: "maxItemSize must be divisible by 512k"
      rule: "(configuration.maxItemSize % (1024 * 512)) == 0"
    - message: "production requires minimum 4 cores"
      rule: "instance.cpu.cores >= 4"

Пример 3: Класс с несколькими sizing policies

apiVersion: managed-services.deckhouse.io/v1alpha2
kind: MemcachedClass
metadata:
  name: flexible
spec:
  sizingPolicies:
    # Политика для малых инстансов
    - cores:
        min: 1
        max: 4
      memory:
        min: 256Mi
        max: 4Gi
        step: 256Mi
      coreFraction:
        - "5%"
        - "10%"
        - "25%"
    
    # Политика для средних инстансов
    - cores:
        min: 5
        max: 8
      memory:
        min: 4Gi
        max: 16Gi
        step: 1Gi
      coreFraction:
        - "25%"
        - "50%"
    
    # Политика для больших инстансов
    - cores:
        min: 9
        max: 16
      memory:
        min: 16Gi
        max: 64Gi
        step: 4Gi
      coreFraction:
        - "50%"
        - "100%"
  
  configuration:
    threads: 4
    maxConnections: 2048
    maxItemSize: "4Mi"
    slabMinSize: "Medium"
    lockMemory: false
  
  overridableConfiguration:
    - maxItemSize
    - slabMinSize
    - lockMemory
  
  topology:
    allowedTopologies:
      - Zonal
      - TransZonal
      - Ignored
    defaultTopology: "TransZonal"
    allowedZones:
      - zone-a
      - zone-b
      - zone-c
  
  validations:
    - message: "maxItemSize must be smaller than 1/2 memory size"
      rule: "configuration.maxItemSize <= (instance.memory.size / 2)"
    - message: "maxItemSize must be at least 512k"
      rule: "configuration.maxItemSize >= (1024 * 512)"

Управление классами

Создание класса

kubectl apply -f memcached-class.yaml

Просмотр классов

kubectl get memcachedclass
kubectl get memcachedclass default -o yaml

Обновление класса

Важно: Поле spec в MemcachedClass является immutable (неизменяемым). Это означает, что после создания класса изменить его спецификацию нельзя.

Если нужно изменить класс:

  1. Создайте новый класс с другим именем
  2. Переключите пользовательские ресурсы на новый класс
  3. Удалите старый класс

Удаление класса

kubectl delete memcachedclass <name>

Внимание: Перед удалением класса убедитесь, что нет активных ресурсов Memcached, использующих этот класс.

Рекомендации

Для production окружения

  1. Используйте строгие sizing policies

    • Определите четкие диапазоны CPU и памяти
    • Используйте step для контроля гранулярности
    • Ограничьте coreFraction разумными значениями

  2. Минимизируйте overridableConfiguration

    • Позволяйте переопределять только критически важные параметры
    • Держите под контролем threads и maxConnections

  3. Используйте CEL валидации

    • Добавьте правила для проверки соотношений параметров
    • Предотвращайте некорректные конфигурации

  4. Настройте topology

    • Для критичных сервисов используйте TransZonal
    • Указывайте конкретные allowedZones

  5. Используйте node placement

    • Изолируйте Memcached на выделенных узлах
    • Используйте nodeSelector и tolerations

Для development окружения

  1. Используйте гибкие sizing policies

    • Широкие диапазоны CPU и памяти
    • Не ограничивайте coreFraction

  2. Разрешайте больше overridableConfiguration

    • Позволяйте разработчикам экспериментировать с настройками

  3. Простая topology

    • Используйте Ignored для упрощения

  4. Минимум валидаций

    • Только базовые проверки безопасности

Диагностика

Проверка валидации

Если пользовательский Memcached не создается, проверьте события:

kubectl describe memcached <name> -n <namespace>

Ищите условие ConfigurationValid:

status:
  conditions:
    - type: ConfigurationValid
      status: "False"
      message: "ValidationError: max item size must be smaller than 1/2 memory size"