Данная статья содержит описание аннотаций, которые меняют поведение механизма отслеживания ресурсов в процессе выката с помощью werf. Все аннотации должны быть объявлены в шаблонах чарта.

  • werf.io/weight — задает вес ресурса, который определяет порядок развертывания ресурсов.

  • werf.io/deploy-dependency-ANY_NAME — задать зависимость от другого ресурса, что повлияет на порядок развертывания ресурсов.

  • werf.io/ownership — определяет, как обрабатывается удаление ресурса и управление аннотациями релиза.
  • werf.io/deploy-on — определяет, когда рендерить ресурс для выката и на каких стадиях он должен быть задеплоен.
  • werf.io/delete-policy — управляет удалением ресурса во время его выката.
  • werf.io/resource-policy — определяет, какие операции werf может выполнять с ресурсом: создание, обновление, пересоздание, удаление.
  • werf.io/delete-propagation — определяет политику удаления дочерних ресурсов.
  • werf.io/delete-dependency-ANY_NAME — задать зависимость от другого ресурса, что повлияет на порядок удаления ресурсов.
  • werf.io/replicas-on-creation — задаёт количество реплик, которое должно быть установлено при первичном создании ресурса (полезно при использовании HPA).
  • werf.io/track-termination-mode — определяет условие при котором werf остановит отслеживание ресурса.
  • werf.io/fail-mode — определяет как werf обработает ресурс в состоянии ошибки. Ресурс в свою очередь перейдет в состояние ошибки после превышения порога допустимых ошибок, обнаруженных при отслеживании этого ресурса в процессе выката.
  • werf.io/failures-allowed-per-replica — определяет порог ошибок, обнаруживаемых при отслеживании этого ресурса в процессе выката, после превышения которого ресурс перейдет в состояние ошибки. werf обработает это состояние в соответствии с настройкой fail mode.
  • werf.io/ignore-readiness-probe-fails-for-CONTAINER_NAME — переопределить высчитываемый автоматически период, в течение которого неуспешные readiness-пробы будут игнорироваться и не будут переводить ресурс в состояние ошибки.
  • werf.io/no-activity-timeout — переопределить период неактивности, по истечении которого ресурс перейдет в состояние ошибки.
  • werf.io/log-regex — показывать в логах только те строки вывода ресурса, которые подходят под указанный шаблон.
  • werf.io/log-regex-for-CONTAINER_NAME — показывать в логах только те строки вывода для указанного контейнера, которые подходят под указанный шаблон.
  • werf.io/log-regex-skip — не показывать строки логов, которые подходят под указанный шаблон.
  • werf.io/log-regex-skip-for-CONTAINER_NAME — не показывать строки логов, которые подходят под указанный шаблон, но только для указанного контейнера.
  • werf.io/skip-logs — выключить логирование вывода для ресурса.
  • werf.io/skip-logs-for-containers — выключить логирование вывода для указанного контейнера.
  • werf.io/show-logs-only-for-number-of-replicas — включить логирование вывода только для указанного числа реплик ресурса.
  • werf.io/show-logs-only-for-containers — включить логирование вывода только для указанных контейнеров ресурса.
  • werf.io/show-service-messages — включить вывод сервисных сообщений и событий Kubernetes для данного ресурса.
  • werf.io/sensitive — скрывать значения data.* и stringData.* ресурса в диффах werf plan.
  • werf.io/sensitive-paths — задать JSONPath полей, значения которых нужно скрывать в диффах werf plan.

Больше информации о том, что такое чарт, шаблоны и пр. доступно в главе про Helm.

Вес ресурса

werf.io/weight: "NUM"

Пример:
werf.io/weight: "10"
werf.io/weight: "-10"

Может быть положительным числом, отрицательным числом или нулем. Значение передается в виде строки. По умолчанию weight имеет значение 0. Работает только для ресурсов, не относящихся к хукам. Для хуков используйте helm.sh/hook-weight, логика работы которого почти такая же.

Этот параметр задает вес ресурсов, определяя порядок их развертывания. Сначала werf группирует ресурсы в соответствии с их весом, а затем последовательно развертывает их, начиная с группы с наименьшим весом. В этом случае werf не будет приступать к развертыванию следующей группы ресурсов, пока развертывание предыдущей не завершено успешно.

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

Зависимости ресурса

werf.io/deploy-dependency-ANY_NAME: state=STATE[,name=NAME][,namespace=NAMESPACE][,kind=KIND][,group=GROUP][,version=VERSION][,external=auto|true|false]

Пример:
werf.io/deploy-dependency-db: state=ready,kind=StatefulSet,name=postgres
werf.io/deploy-dependency-app: state=present,kind=Deployment,group=apps,version=v1,name=app,namespace=app
werf.io/deploy-dependency-secret: state=ready,kind=Secret,version=v1,name=my-vault-secret,external=true

Обязательные параметры:

  • state: ready или present. Если present, то дождаться, пока ресурс не будет создан/обновлен, если ready, то дождаться, пока ресурс не будет создан/обновлен и приведен в готовность.

Как минимум один из этих параметров требуется указать:

  • name: имя ресурса, от которого будет зависеть текущий ресурс.
  • namespace: namespace ресурса, от которого будет зависеть текущий ресурс.
  • kind: kind ресурса, от которого будет зависеть текущий ресурс.
  • group: api group ресурса, от которого будет зависеть текущий ресурс.
  • version: api version ресурса, от которого будет зависеть текущий ресурс.

Необязательные параметры:

  • external: auto (по умолчанию), true или false. Определяет, является ли зависимость ресурсом релиза или внешним ресурсом кластера. При auto, если среди ресурсов релиза не найден подходящий ресурс, зависимость автоматически считается внешней и werf ожидает её в кластере. При true — всегда внешняя. При false — всегда внутренняя (ресурс релиза). Для внешней зависимости необходимо указать name, kind и version.

Больше информации: порядок развертывания

Право владения ресурсом

werf.io/ownership: release|anyone

Определяет, как обрабатывается удаление ресурса и управление аннотациями релиза. Допустимые значения:

  • release: ресурс удаляется, если он удалён из чарта или при удалении релиза, а аннотации релиза применяются/проверяются во время выката.
  • anyone: поведение, обратное от release — ресурс никогда не удаляется при удалении релиза или удалении из чарта, а аннотации релиза не применяются/не проверяются во время выката.

Обычные ресурсы по умолчанию имеют владельцем release, а хуки и CRD из директории crds — anyone.

Условный деплой ресурса

werf.io/deploy-on: pre-install|install|post-install|pre-upgrade|upgrade|post-upgrade|pre-rollback|rollback|post-rollback|pre-delete|delete|post-delete

Определяет, когда рендерить ресурс для выката и на каких стадиях он должен быть задеплоен. Возможные значения:

  • pre-install, install, post-install — рендерить только при установке релиза
  • pre-upgrade, upgrade, post-upgrade — рендерить только при обновлении релиза
  • pre-rollback, rollback, post-rollback — рендерить только при откате релиза
  • pre-delete, delete, post-delete — рендерить только при удалении релиза

По умолчанию для обычных ресурсов используется значение install,upgrade,rollback, для хуков — значения из helm.sh/hook.

Политика удаления ресурса

werf.io/delete-policy: before-creation|before-creation-if-immutable|succeeded|failed

Аннотация werf.io/delete-policy управляет удалением ресурса во время его выката и вдохновлена аннотацией helm.sh/hook-delete-policy. Допустимые значения:

  • before-creation: ресурс всегда пересоздаётся
  • before-creation-if-immutable: ресурс пересоздаётся только если при обновлении ресурса мы получили ошибку field is immutable
  • succeeded: ресурс удаляется после успешной проверки готовности
  • failed: ресурс удаляется, если проверка готовности завершилась неудачно

По умолчанию для обычных ресурсов политика удаления не задана, а для хуков значения берутся из helm.sh/hook-delete-policy и преобразуются в значения в werf.io/delete-policy.

Политика ресурса

werf.io/resource-policy: skip-create|skip-update|skip-recreate|skip-delete|keep

Аннотация werf.io/resource-policy ограничивает, какие операции werf разрешено выполнять с ресурсом при выкате. Допустимые значения:

  • skip-create: никогда не создавать ресурс, выкатывать его только если он уже есть в кластере
  • skip-update: никогда не обновлять ресурс после его создания
  • skip-recreate: никогда не пересоздавать ресурс — он остаётся как есть, даже если изменилось immutable-поле
  • skip-delete: никогда не удалять ресурс — ни при удалении из чарта, ни при удалении релиза
  • keep: псевдоним для skip-delete, совместимый с helm.sh/resource-policy: keep

Можно указать несколько значений одновременно, и они имеют приоритет над werf.io/delete-policy. skip-delete учитывается и в том случае, если аннотация задана на ресурсе в кластере, остальные значения — только в чарте.

По умолчанию политика ресурса не задана, кроме Namespace релиза — для него всегда действует skip-delete. Аннотация helm.sh/resource-policy: keep равнозначна werf.io/resource-policy: skip-delete, но игнорируется, если задана werf.io/resource-policy.

Распространение удаления

werf.io/delete-propagation: Foreground|Background|Orphan

Аннотация werf.io/delete-propagation определяет политику удаления дочерних ресурсов. Foreground означает удаление ресурса после удаления всех его зависимостей, Background означает немедленное удаление ресурса и удаление всех его зависимостей в фоновом режиме, а Orphan означает удаление ресурса, но без удаления его зависимостей.

Значением по умолчанию является Foreground.

Зависимости при удалении

werf.io/delete-dependency-ANY_NAME: state=STATE[,name=NAME][,namespace=NAMESPACE][,kind=KIND][,group=GROUP][,version=VERSION][,external=auto|true|false]

Пример:
werf.io/delete-dependency-db: state=absent,kind=StatefulSet,name=postgres
werf.io/delete-dependency-app: state=absent,kind=Deployment,group=apps,version=v1,name=app,namespace=app
werf.io/delete-dependency-secret: state=absent,kind=Secret,version=v1,name=my-vault-secret,external=true

Обязательные параметры:

  • state: absent. Дождаться, пока ресурс будет удален.

Как минимум один из этих параметров требуется указать:

  • name: имя ресурса, от которого будет зависеть текущий ресурс.
  • namespace: namespace ресурса, от которого будет зависеть текущий ресурс.
  • kind: kind ресурса, от которого будет зависеть текущий ресурс.
  • group: api group ресурса, от которого будет зависеть текущий ресурс.
  • version: api version ресурса, от которого будет зависеть текущий ресурс.

Необязательные параметры:

  • external: auto (по умолчанию), true или false. Определяет, является ли зависимость ресурсом релиза или внешним ресурсом кластера. При auto, если среди ресурсов релиза не найден подходящий ресурс, зависимость автоматически считается внешней и werf ожидает её удаления из кластера. При true — всегда внешняя. При false — всегда внутренняя (ресурс релиза). Для внешней зависимости необходимо указать name, kind и version.

Больше информации: порядок развертывания

Количество реплик при создании

Когда для ресурса включён HPA, использование spec.replicas может привести к непредсказуемому поведению, потому что каждый раз когда происходит converge для werf chart через CI/CD количество реплик ресурса будет сброшено к статически заданному в шаблонах чарта значению spec.replicas, даже если это значение изменил HPA в рантайме.

Одно из рекомендованных решений — совсем удалить spec.replicas из шаблонов чарта. Однако если необходимо установить начальное значение реплик при создании ресурса, можно воспользоваться аннотацией "werf.io/replicas-on-creation".

"werf.io/replicas-on-creation": "NUM"

Задаёт число реплик, которые должны быть установлены для ресурса при его первичном создании.

ЗАМЕЧАНИЕ "NUM" должно быть указано строкой (в двойных кавычках), потому что аннотации не поддерживают передачу других типов данных кроме строк, аннотации с другим типом данных будут проигнорированы.

Режим остановки отслеживания

"werf.io/track-termination-mode": WaitUntilResourceReady|NonBlocking

Определяет условие остановки отслеживания ресурса в процессе деплоя:

  • WaitUntilResourceReady (по умолчанию) — весь процесс деплоя будет отслеживать и ожидать готовности ресурса с данной аннотацией. Т.к. данный режим включен по умолчанию, то, по умолчанию, процесс деплоя ждет готовности всех ресурсов.
  • NonBlocking — ресурс с данной аннотацией отслеживается только пока есть другие ресурсы, готовности которых ожидает процесс деплоя.

СОВЕТ Используйте аннотации — "werf.io/track-termination-mode": NonBlocking и "werf.io/fail-mode": IgnoreAndContinueDeployProcess, когда описываете в релизе объект Job, который должен быть запущен в фоне и не влияет на процесс деплоя.

СОВЕТ Используйте аннотацию "werf.io/track-termination-mode": NonBlocking, когда описываете в релизе объект StatefulSet с ручной стратегией выката (параметр OnDelete) и не хотите блокировать весь процесс деплоя из-за этого объекта, дожидаясь его обновления.

Режим обработки ошибок

"werf.io/fail-mode": FailWholeDeployProcessImmediately|HopeUntilEndOfDeployProcess|IgnoreAndContinueDeployProcess

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

  • FailWholeDeployProcessImmediately (по умолчанию) — в случае ошибки при деплое ресурса с данной аннотацией, весь процесс деплоя будет завершен с ошибкой.
  • HopeUntilEndOfDeployProcess — в случае ошибки при деплое ресурса с данной аннотацией его отслеживание будет продолжаться, пока есть другие ресурсы, готовности которых ожидает процесс деплоя, либо все оставшиеся ресурсы имеют такую-же аннотацию. Если с ошибкой остался только этот ресурс или несколько ресурсов с такой-же аннотацией, то в случае сохранения ошибки весь процесс деплоя завершается с ошибкой.
  • IgnoreAndContinueDeployProcess — ошибка при деплое ресурса с данной аннотацией не влияет на весь процесс деплоя.

Допустимое количество ошибок на реплику

"werf.io/failures-allowed-per-replica": "NUMBER"

По умолчанию, при отслеживании статуса ресурса допускается срабатывание ошибки 1 раз, прежде чем весь процесс деплоя считается ошибочным. Этот параметр влияет на поведение настройки Fail mode: определяет порог срабатывания, после которого начинает работать режим реакции на ошибки.

Игнорирование неудачных readiness-проб контейнера

"werf.io/ignore-readiness-probe-fails-for-CONTAINER_NAME": "TIME"

Эта аннотация позволяет переопределить высчитываемый автоматически период, в течение которого неуспешные readiness-пробы не станут переводить ресурс в состояние ошибки, т. е. будут проигнорированы. По умолчанию период игнорирования неудачных readiness-проб автоматически вычисляется на основе конфигурации readiness-пробы. Заметим, что если в конфигурации readiness-пробы указано failureThreshold: 1, тогда первая же неудачная readiness-проба переведет ресурс в состояние ошибки, независимо от периода игнорирования.

Формат записи значения описан здесь.

Пример: "werf.io/ignore-readiness-probe-fails-for-backend": "20s"

Таймаут отсутствия активности

werf.io/no-activity-timeout: "TIME"

По умолчанию: 4m

Пример:
werf.io/no-activity-timeout: "8m30s"
werf.io/no-activity-timeout: "90s"

При отсутствии новых событий и обновлений ресурса в течение TIME ресурс перейдет в состояние ошибки.

Формат записи значения описан здесь.

Шаблон для включения логов

"werf.io/log-regex": RE2_REGEX

Определяет Re2 regex шаблон, применяемый ко всем логам всех контейнеров всех подов ресурса с этой аннотацией. werf будет выводить только те строки лога, которые удовлетворяют regex-шаблону. По умолчанию werf выводит все строки лога.

Шаблон для включения логов контейнера

"werf.io/log-regex-for-CONTAINER_NAME": RE2_REGEX

Определяет Re2 regex шаблон, применяемый к логам контейнера с именем CONTAINER_NAME всех подов с данной аннотацией. werf будет выводить только те строки лога, которые удовлетворяют regex-шаблону. По умолчанию werf выводит все строки лога.

Шаблон для исключения логов

"werf.io/log-regex-skip": RE2_REGEX

Определяет Re2 regex шаблон, применяемый ко всем логам всех контейнеров всех подов ресурса с этой аннотацией. werf не будет выводить те строки лога, которые удовлетворяют regex-шаблону. По умолчанию werf выводит все строки лога.

Шаблон для исключения логов контейнера

"werf.io/log-regex-skip-for-CONTAINER_NAME": RE2_REGEX

Определяет Re2 regex шаблон, применяемый к логам контейнера с именем CONTAINER_NAME всех подов с данной аннотацией. werf будет скрывать те строки лога, которые удовлетворяют regex-шаблону. По умолчанию werf выводит все строки лога.

Отключение логов

"werf.io/skip-logs": "true"|"false"

Если установлена в "true", то логи всех контейнеров пода с данной аннотацией не выводятся при отслеживании. Отключено по умолчанию.

Отключение логов для контейнеров

"werf.io/skip-logs-for-containers": CONTAINER_NAME1,CONTAINER_NAME2,CONTAINER_NAME3...

Список (через запятую) контейнеров пода с данной аннотацией, для которых логи не выводятся при отслеживании.

Логи для указанного числа реплик

"werf.io/show-logs-only-for-number-of-replicas": "NUMBER"

Отобразить логи только для указанного числа реплик ресурса в процессе трекинга. Мы отображаем логи только для одной реплики по умолчанию, чтобы избежать избыточного вывода логов и оптимизировать утилизацию ресурсов.

Логи для указанных контейнеров

"werf.io/show-logs-only-for-containers": CONTAINER_NAME1,CONTAINER_NAME2,CONTAINER_NAME3...

Список (через запятую) контейнеров пода с данной аннотацией, для которых выводятся логи при отслеживании. Для контейнеров, чьи имена отсутствуют в списке, логи не выводятся. По умолчанию выводятся логи для всех контейнеров всех подов ресурса.

Отображение служебных сообщений

"werf.io/show-service-messages": "true"|"false"

Если установлена в "true", то при отслеживании для ресурсов будет выводиться дополнительная отладочная информация, такая как события Kubernetes. По умолчанию, werf выводит такую отладочную информацию только в случае если ошибка ресурса приводит к ошибке всего процесса деплоя.

Пометка полей ресурса как чувствительных

"werf.io/sensitive-paths": "JSONPath,JSONPath,..."

Например:
"werf.io/sensitive-paths": "$.spec.template.spec.containers[*].env[*].value,$.data.*,$.stringData.*"

Скрывать значения полей, соответствующих указанным JSONPath, в диффах. Вместо значения выводится его длина (или количество элементов) и хеш, поэтому изменение скрытого значения остаётся заметным. Поля вне выбранных путей остаются видимыми. Путь к целому объекту или списку скрывает его содержимое целиком.

Непустой список путей имеет приоритет над werf.io/sensitive, включая "false", и заменяет, а не дополняет стандартные пути. Чтобы сохранить скрытие данных Secret при добавлении собственных путей, включите $.data.* и $.stringData.*, как в примере. Пустая или состоящая только из пробелов строка не задаёт переопределение: применяется werf.io/sensitive или поведение по умолчанию.

Проверьте пути до вывода диффов в общедоступные логи. Чувствительные значения вне указанных путей остаются видимыми; --show-sensitive-diffs или WERF_SHOW_SENSITIVE_DIFFS=true отключает скрытие значений в диффах werf plan и werf bundle plan.

Пометка ресурса как чувствительного

"werf.io/sensitive": "true"|"false"

Если установлена в "true", werf скрывает в диффах только значения data.* и stringData.*, а не весь ресурс. Значения заменяются длиной (или количеством элементов) и хешем; метаданные, имена ключей и остальные поля остаются видимыми. По умолчанию это поведение включено для v1/Secret и выключено для остальных ресурсов.

Значение "false" отключает это автоматическое скрытие, в том числе для Secret. Непустой werf.io/sensitive-paths имеет приоритет над обоими значениями аннотации.

Для чувствительных данных в других полях, например spec.token, одного werf.io/sensitive: "true" недостаточно. Задайте их явно через werf.io/sensitive-paths, например "$.spec.token". Эти аннотации управляют только скрытием в диффах, а не шифрованием ресурсов или секретных файлов.