Как управлять CustomValues сервисов

Обзор #

CustomValues — это параметры (values) в формате YAML, которые передаются в Helm при установке и обновлении сервиса. Они позволяют переопределить настройки чарта: порты, лимиты ресурсов, флаги, адреса хранилищ и т.д.

Приоритетный способ изменения customvalues — ресурс ShturvalServicePatch (SSP): патчи накладываются поверх базового ShturvalServiceConfig (SSC) и удобны для версионирования, нескольких слоёв настроек и обновлений платформы (см. преимущества). Правка customvalues напрямую в интерфейсе сервиса или в манифесте SSC не рекомендуется — такие способы приведены в разделе «Другие способы (не рекомендуется)».

Описание всех специфических кастомных ресурсов платформы, включая ShturvalServiceConfig и ShturvalServicePatch, приведено на странице «Кастомные ресурсы в платформе».

ShturvalServicePatch — рекомендуемый способ #

ShturvalServicePatch — кастомный ресурс-патч: он ссылается на сервис (SSC) по имени и задаёт для него дополнительные или переопределяющие customvalues. Контроллер shturval-services объединяет базовую конфигурацию SSC и все применённые к нему SSP и передаёт результат в Helm.

Где и как управлять SSP:

Просмотр:

• Страница сервиса: Сервисы и репозитории → Установленные сервисы → Управлять сервисом → вкладка Примененные ShturvalServicePatch. По нажатию на строку с патчем открывается просмотр и редактирование YAML манифеста SSP.

Создание и редактирование:

• Кастомные ресурсы: Администрирование → Кастомные ресурсы → ops.shturval.tech → ShturvalServicePatch. Можно редактировать или удалять существующие через манифесты.

В манифесте SSP обязательно укажите spec.shturvalServiceConfigName — имя ресурса ShturvalServiceConfig (сервиса), к которому применяется патч. Параметры задаются в spec.customvalues в формате YAML.

apiVersion: ops.shturval.tech/v1beta2
kind: ShturvalServicePatch
metadata:
  name: <имя ресурса>
spec:
  shturvalServiceConfigName: shturval-auth
  customvalues:
    ingress_auth:
      annotations:
        nginx.ingress.kubernetes.io/proxy-read-timeout: "<ваше значение параметра>"

Через консоль (kubectl) #

Создайте файл с манифестом ShturvalServicePatch (как в примере выше) и примените его:

kubectl apply -f ssp-nfs-csi.yaml

Просмотр и редактирование существующего патча:

# Список всех SSP в кластере
kubectl get shturvalservicepatch -A

# Детали патча
kubectl get shturvalservicepatch <имя> -n shturval-services -o yaml

# Редактирование в консоли
kubectl edit shturvalservicepatch <имя> -n shturval-services

Создание секрета с учётными данными и передача в SSP выполняется отдельно (например, через Secret в неймспейсе сервиса и ссылку на него в customvalues по документации чарта).

# Файл ssp-backup-retention.yaml
apiVersion: ops.shturval.tech/v1beta1
kind: ShturvalServicePatch
metadata:
  name: shturval-backup-retention
  namespace: shturval-services
spec:
  shturvalServiceConfigName: shturval-backup
  customvalues: |
    configuration:
      defaultVolumesToRestic: true
    schedule: "0 2 * * *"    

После применения SSP контроллер shturval-services пересчитает конфигурацию сервиса и при необходимости обновит Helm-релиз. Проверить применение можно на странице Установленные сервисы → Управлять сервисом → вкладки Сервис и Примененные ShturvalServicePatch.

Преимущества ShturvalServicePatch #

Использование ShturvalServicePatch вместо правки spec.customvalues непосредственно в ShturvalServiceConfig (SSC) даёт:

1. Разделение базовой и кастомной конфигурации — исходный SSC остаётся «как из платформы»; все переопределения собраны в отдельных ресурсах SSP. При обновлении платформы или чарта проще понять, что было добавлено вами.
2. Несколько патчей на один сервис — к одному SSC можно применить несколько SSP (например, один — общие настройки, другой — под конкретное окружение). Контроллер объединяет их с учётом порядка (при необходимости используется patchOrder).
3. Удобный откат — чтобы отменить кастомизацию, достаточно удалить или отредактировать SSP, не трогая сам SSC.
4. Версионирование и GitOps — манифесты SSP можно хранить в репозитории, применять через CI/CD или импорт манифестов и отслеживать изменения в Git.
5. Повторное использование — один и тот же манифест SSP можно применить в другом кластере (например, из ClusterProfile при создании кластера), не редактируя GUI.

Особенности работы ShturvalServicePatch #

Ниже — правила слияния конфигурации и работы патчей в интерфейсе и в API.

1. Для одного сервиса (одного SSC) можно создать неограниченное число ресурсов ShturvalServicePatch.
2. Через SSP можно добавить или переопределить значения в итоговых customvalues сервиса. Удалить уже заданные в SSC ключи и их значения через патч нельзя — для этого приходится править ShturvalServiceConfig или блок «Спецификация сервиса» в GUI; эти способы не рекомендуются.
3. Если у нескольких SSP задан patchOrder, итоговая конфигурация собирается с учётом приоритета: большее число в patchOrder означает более высокий приоритет. Если приоритет не задан, порядок применения не гарантируется.
4. Значение параметра в SSP приоритетнее, чем значение того же параметра в spec.customvalues самого SSC: при совпадении ключа в патче и в SSC в Helm уйдёт значение из патча, а поле в SSC для этого ключа фактически игнорируется.
5. Если несколько SSP задают один и тот же параметр, побеждает значение из ShturvalServicePatch с более высоким приоритетом (см. п. 3). При конфликте без patchOrder выбор непредсказуем — задавайте patchOrder явно.
6. Дата создания SSP проставляется автоматически.
7. SSP можно применять, когда сервис в режиме Авто. Если сервис в режиме Ручной, переведите его в Авто или укажите в манифесте SSP поле spec.mode: auto, иначе патч может не примениться ожидаемо.

Системно созданные ShturvalServicePatch #

При развёртывании и обновлении кластера автоматически создаются системные ShturvalServicePatch, необходимые для корректной работы сервисов. В metadata.labels таких ShturvalServicePatch задан лейбл generated-by со значением cluster-manager или shturval-update. Для системных SSP используется patchOrder: 10000.

При просмотре манифеста такого ShturvalServicePatch в интерфейсе: вкладка Примененные ShturvalServicePatch на странице сервиса или Администрирование → Кастомные ресурсы, отображается уведомление, что просматриваемый объект создан системно. В GUI недоступно редактирование и удаление такого ShturvalServicePatch.

Обратите внимание! системные ShturvalServicePatch не предназначены для изменения или удаления — это может нарушить работу сервиса. При необходимости внесения изменений создайте новый ShturvalServicePatch с более высоким приоритетом: задайте patchOrder меньше 10000.

Состояние сервиса после применения ShturvalServicePatch #

После применения хотя бы одного SSP у сервиса в интерфейсе отображаются состояние Patch и статус Patched. Список применённых патчей — на странице Установленные сервисы → Управлять → вкладка Примененные ShturvalServicePatch.

Удалить SSP можно:

• на вкладке Примененные ShturvalServicePatch — действие удаления в строке патча;
• на странице просмотра манифеста соответствующего ShturvalServicePatch.

Импорт нового ShturvalServicePatch — Импорт манифестов.

Другие способы (не рекомендуется) #

Ниже перечислены способы изменить customvalues без отдельного ресурса ShturvalServicePatch. Они меняют базовый SSC или эквивалентную запись в GUI и не рекомендуются как основной подход: при обновлениях платформы сложнее отслеживать отличия от поставки, выше риск конфликтов с механизмом патчей. Для постоянных и переносимых настроек используйте ShturvalServicePatch.

Обратите внимание! если значения customvalues уже были изменены напрямую в ShturvalServiceConfig, перенесите такие изменения в отдельный ShturvalServicePatch с явно заданным более высоким приоритетом: у системных SSP используется patchOrder: 10000, поэтому задайте значение больше 10000. Иначе при обновлении платформы или появлении системных SSP эти значения могут быть переопределены.

Напрямую в блоке «Спецификация сервиса» в интерфейсе сервиса (не рекомендуется) #

Где: выберите кластер → Сервисы и репозитории → Установленные сервисы → нажмите Управлять у нужного сервиса. На странице управления сервисом найдите блок Спецификация сервиса (customvalues).

В левой части блока отображается и редактируется YAML со значениями, передаваемыми в Helm. Справа — доступные параметры чарта (только для просмотра, с поиском по названию). Внесите изменения и нажмите Сохранить.

Подходит разве что для разовой диагностики; для регулярной кастомизации предпочтительнее ShturvalServicePatch.

Через интерфейс «Кастомные ресурсы» — манифест ShturvalServiceConfig (SSC) (не рекомендуется) #

Где: выберите кластер → Администрирование → Кастомные ресурсы → API-группа ops.shturval.tech → ShturvalServiceConfig (SSC).

Выберите нужный сервис (например, shturval-nfs-csi), откройте вкладку Манифест. В поле spec.customvalues можно отредактировать YAML values напрямую в манифесте ресурса ShturvalServiceConfig. Сохраните манифест.

Так вы меняете исходную конфигурацию сервиса (SSC). Для разделения поставки платформы и ваших переопределений используйте ShturvalServicePatch.