From 539957e8be632040af473041e7d3c374a0705a97 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Tue, 22 Sep 2026 19:04:53 +0300 Subject: [PATCH 1/6] docs: split the Russian guides out of the examples page The examples page mixed cluster-wide and namespaced scenarios, so neither audience could read it straight through. It is replaced by a guide per role: ADMIN_GUIDE.ru.md for the cluster-scoped kinds and USER_GUIDE.ru.md for the namespaced ones, each with tabbed CLI and web-interface instructions and a table of the statuses its resources can report. README.ru.md gains a diagram of the resource model and links every kind to its reference page. The English side is untouched, so the pair is diverged: EXAMPLE.md is gone while README.md still links to example.html, and no English guides exist yet. Signed-off-by: Ilya Drey --- docs/ADMIN_GUIDE.ru.md | 578 +++++++++++++++++++++++++++++++++++++++++ docs/EXAMPLE.md | 158 ----------- docs/EXAMPLE.ru.md | 158 ----------- docs/README.ru.md | 91 +++++-- docs/USER_GUIDE.ru.md | 520 ++++++++++++++++++++++++++++++++++++ 5 files changed, 1164 insertions(+), 341 deletions(-) create mode 100644 docs/ADMIN_GUIDE.ru.md delete mode 100644 docs/EXAMPLE.md delete mode 100644 docs/EXAMPLE.ru.md create mode 100644 docs/USER_GUIDE.ru.md diff --git a/docs/ADMIN_GUIDE.ru.md b/docs/ADMIN_GUIDE.ru.md new file mode 100644 index 0000000..27d3fd2 --- /dev/null +++ b/docs/ADMIN_GUIDE.ru.md @@ -0,0 +1,578 @@ +--- +title: "Руководство администратора" +description: "Deckhouse Kubernetes Platform — управление кластерными ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." +weight: 40 +--- + +Руководство описывает работу с кластерными ресурсами модуля: репозитории чартов, их каталоги и аддоны. Для работы с данными кастомными ресурсами необходимо иметь полномочия не ниже чем [`ClusterAdmin`](/modules/user-authz/#текущая-ролевая-модель). + +## Добавление репозитория аддонов + +Репозиторий — точка входа для всех остальных ресурсов: пока он не добавлен, выбирать чарт не из чего. + +Создайте ресурс [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository): + +{{< tabs name="create-addon-repository" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +{{< /alert >}} + +Модуль синхронизирует репозиторий и создаст по объекту [`HelmClusterAddonChart`](/modules/operator-helm/cr.html#helmclusteraddonchart) на каждый найденный чарт. Для просмотра чартов репозитория: + +{{< tabs name="list-addon-charts" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k get helmclusteraddoncharts -l repository=podinfo +``` + +Пример вывода: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo +``` + +Имя объекта каталога формируется из имени репозитория, имени чарта и хеша, поэтому выбирать чарт удобнее по лейблам `repository` и `chart`, а не по имени. + +Доступные версии чарта перечислены в его статусе. Выведите их: + +```shell +d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddonChart +metadata: + labels: + chart: podinfo + heritage: deckhouse + repository: podinfo + name: podinfo-chart-podinfo-dfbe83e63b0b +status: + versions: + - version: 6.11.0 + - version: 6.10.2 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Чарты аддонов». + +{{% /tab %}} +{{< /tabs >}} + +## Развёртывание аддона + +Создайте ресурс [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon), указав репозиторий, имя и версию чарта, а также неймспейс развёртывания: + +{{< tabs name="create-addon" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} +При необходимости вы можете скорректировать параметры Helm-чарта. Для получения параметров используемых по умолчанию, нажмите на ссылку «Показать значения по умолчанию» в форме создания аддона. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +Заданный чарт заданного репозитория может обслуживать только один ресурс `HelmClusterAddon`. При этом из одного репозитория одновременно могут разворачиваться разные чарты. +{{< /alert >}} + +### Проверка состояния репозитория + +Состояние репозитория отражают условия в его статусе. Для оценки состояния репозитория: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k get helmclusteraddonrepository podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddonRepository +metadata: + creationTimestamp: "2026-09-22T15:28:51Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 2 + name: podinfo + resourceVersion: "48926557" + uid: 0fbfec2f-6669-40ba-a7ef-0cd223aabfca +spec: + url: https://stefanprodan.github.io/podinfo +status: + chartCount: 1 + conditions: + - lastTransitionTime: "2026-09-22T15:28:52Z" + message: "" + observedGeneration: 2 + reason: Success + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T15:28:51Z" + message: "" + observedGeneration: 2 + reason: Success + status: "True" + type: Synced + lastSuccessfulSyncTime: "2026-09-22T15:28:51Z" + nextSyncTime: "2026-09-22T15:34:09Z" + observedGeneration: 2 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Репозитории». +1. Выберите нужный репозиторий и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Просмотр возможных состояний репозитория" >}} + +| Условие | Значение | Причина | Что это значит | +| --- | --- | --- | --- | +| `Ready` | `True` | `Success` | Репозиторий доступен, каталог чартов построен. Можно выбирать чарт для аддона. | +| `Ready` | `Unknown` | `AwaitingInitialSync` | Репозиторий только создан, первое чтение ещё не завершилось. Дождитесь окончания синхронизации. | +| `Ready` | `False` | `AuxiliaryResourcesFailed` | Не удалось создать служебный секрет с учётными данными репозитория. Проверьте свои полномочия в неймспейсе. | +| `Synced` | `True` | `Success` | Каталог чартов соответствует содержимому репозитория. | +| `Synced` | `False` | `SyncFailed` | Репозиторий не удалось прочитать. Проверьте URL и доступность реестра из кластера. | +| `Synced` | `False` | `CatalogUpdateFailed` | Репозиторий прочитан, но записать каталог чартов в кластер не удалось. Попытка повторится автоматически. | +| `Synced` | `False` | `PartialSync` | При первом чтении часть версий разобрать не удалось. Остальные уже доступны, пропущенные подтянутся при следующей синхронизации. | +| `Reconciling` | `True` | `Synchronization` | Идёт плановая синхронизация с репозиторием. | +| `Reconciling` | `True` | `ForceReconcile` | Идёт синхронизация, запрошенная вручную. | +| `Reconciling` | `True` | `ProgressingWithRetry` | Предыдущая попытка не удалась, запланирован повтор. | +| `Stalled` | `True` | `UnsupportedRepositoryType` | Схема в URL не поддерживается. Допустимы только `http(s)://` и `oci://`. | +| `Stalled` | `True` | `InvalidRepositoryURL` | URL не удалось разобрать. Проверьте адрес репозитория. | +| `Stalled` | `True` | `AuthenticationFailed` | Реестр отклонил учётные данные. Проверьте логин и пароль в спецификации репозитория. | +| `Stalled` | `True` | `SourceNotFound` | По указанному URL репозиторий не найден. | +| `Stalled` | `True` | `SourceRejectedRequest` | Реестр отклонил запрос. Обратитесь к владельцу реестра. | +| `Stalled` | `True` | `RetriesExceeded` | Попытки чтения исчерпаны. Устраните причину и запросите принудительную реконсиляцию. | + +{{< alert level="info" >}} + +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. + +{{< /alert >}} + +{{< /details >}} + +### Проверка состояния аддона + +Состояние аддона отражают условия в его статусе. Для оценки состояния аддона: + +{{< tabs name="check-addon-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k get helmclusteraddon podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddon +metadata: + creationTimestamp: "2026-09-22T09:50:34Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 5 + name: podinfo + resourceVersion: "48927375" + uid: 5365281f-0f8c-4d3d-b174-5096d6bf255d +spec: + chart: + helmClusterAddonChart: podinfo + helmClusterAddonRepository: podinfo-helm-repository + version: 6.15.0 + maintenance: "" + namespace: default +status: + conditions: + - lastTransitionTime: "2026-09-22T15:29:56Z" + message: Helm upgrade succeeded for release default/podinfo.v2 with chart podinfo@6.15.0 + observedGeneration: 5 + reason: UpgradeSucceeded + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T09:50:41Z" + message: Helm install succeeded for release default/podinfo.v1 with chart podinfo@6.15.0 + observedGeneration: 1 + reason: InstallSucceeded + status: "True" + type: Installed + - lastTransitionTime: "2026-09-22T10:30:50Z" + message: Maintenance mode disabled + observedGeneration: 5 + reason: MaintenanceModeInactive + status: "True" + type: Managed + lastAppliedChart: + helmClusterAddonChart: podinfo + helmClusterAddonRepository: podinfo-helm-repository + version: 6.15.0 + lastForceReconcileTime: "2026-09-22T10:53:51Z" + observedGeneration: 5 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Аддоны». +1. Выберите нужный аддон и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Просмотр возможных состояний аддона" >}} + +| Условие | Значение | Причина | Что это значит | +| --- | --- | --- | --- | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | Релиз развёрнут и соответствует спецификации. Причину в этом случае подставляет Helm. | +| `Ready` | `Unknown` | `Reconciling` | Работа идёт: чарт загружается или релиз раскатывается. | +| `Ready` | `False` | `ReleaseFailed` | Helm не смог установить или обновить релиз. Текст ошибки приведён в поле `message`. | +| `Ready` | `False` | `TestFailed` | Тесты чарта завершились неудачно. | +| `Ready` | `False` | `Remediated` | Выполнен откат к предыдущему состоянию релиза. | +| `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | Чарт не удалось загрузить из репозитория или сохранить в кластере. | +| `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | Не удалось получить или проверить чарт из OCI-реестра. | +| `Ready` | `False` | `ChartVersionRemoved` | Указанная версия чарта больше не публикуется репозиторием. Выберите другую версию. | +| `Ready` | `False` | `ChartClaimConflict` | Этот чарт репозитория уже развёрнут другим аддоном: одну пару «репозиторий — чарт» может обслуживать только один `HelmClusterAddon`. Занявший её ресурс указан в поле `message`. Состояние разрешится само в течение полуминуты после того, как тот аддон удалят или перенацелят на другой чарт. | +| `Ready` | `False` | `UnsupportedRepositoryType` | У репозитория, на который ссылается аддон, нечитаемый URL. Обратитесь к владельцу репозитория. | +| `Ready` | `False` | `Failed` | Прочие ошибки. Причина приведена в поле `message`. | +| `Installed` | как у `Ready` | та же, что у `Ready` | Результат первой установки релиза. | +| `UpdateInstalled` | как у `Ready` | та же, что у `Ready` | Результат обновления релиза. Появляется при смене версии чарта. | +| `ConfigurationApplied` | как у `Ready` | та же, что у `Ready` | Результат применения значений чарта. Появляется при изменении значений. | +| `Managed` | `True` | `MaintenanceModeInactive` | Аддон находится под управлением модуля. | +| `Managed` | `False` | `MaintenanceModeActive` | Включён режим обслуживания, реконсиляция приостановлена. | +| `Reconciling` | `True` | `Reconciling` | Идёт раскатка релиза. | +| `Reconciling` | `True` | `ProgressingWithRetry` | Произошёл сбой, запланирован повтор. | +| `Reconciling` | `True` | `ForceReconcile` | Идёт реконсиляция, запрошенная вручную. | +| `Stalled` | `True` | причина того сбоя, который его вызвал | Повтор не поможет: нужно исправить спецификацию аддона, дождаться изменений в репозитории или убрать мешающий объект. Пока причина не устранена, попытки прекращены. | + +{{< alert level="info" >}} + +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как аддон проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Добавление репозитория с чартами приложений + +С помощью создания [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) администратор платформы может централизованно предоставить администраторам неймспейсов доступ к Helm-чартам. Helm-чарты данного репозитория будут доступны администраторам всех неймспейсов для развёртывания [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication). + +Создайте ресурс [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository): + +{{< tabs name="create-cluster-application-repository" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +{{< /alert >}} + +Каталог такого репозитория публикуется в ресурсах [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). Выведите его: + +{{< tabs name="list-cluster-application-charts" >}} +{{% tab name="В командной строке" %}} + +```shell +d8 k get helmclusterapplicationcharts -l repository=podinfo-shared +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Репозитории приложений». +1. Выберите интересующий вас репозиторий из списка и нажмите на его имя. +1. В открывшейся форме во вкладке «Чарты» вы увидите список доступных Helm-чартов. + +{{% /tab %}} +{{< /tabs >}} + +Дальнейшая работа с чартами из этого репозитория описана в [руководстве пользователя](user_guide.html). + +## Подключение приватного репозитория + +Учётные данные и параметры TLS задаются в спецификации репозитория. Пример настройки репозитория с аутентификацией и самоподписанным сертификатом: + +{{< tabs name="connect-private-repository" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} + +{{< alert level="warning" >}} +Учётные данные хранятся в ресурсе открытым текстом. Право на чтение репозитория — это право на чтение его учётных данных. +{{< /alert >}} + +## Принудительный запуск реконсиляции + +При работе с аддонами и репозиториями может возникнуть необходимость принудительного запуска реконсиляции. В штатном режиме работы запуск реконсиляции происходит автоматически в случае внесения изменений в ресурсы либо изменения состояния их зависимостей. + +В случае с аддонами принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек аддона возникла терминальная ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. + +При работе с репозиториями запуск принудительной реконсиляции позволяет выполнить синхронизацию репозитория, не дожидаясь очередного запуска по расписанию. + +{{< tabs name="force-reconcile-addon" >}} +{{% tab name="В командной строке" %}} + +Для принудительной реконсиляции [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) выполните команду: + +```shell +d8 k annotate helmclusteraddon podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +Для принудительной реконсиляции [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) выполните команду: + +```shell +d8 k annotate helmclusteraddonrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +{{< alert level="info" >}} +Модуль проверяет только наличие аннотации, её содержимое он не читает. Временная метка в примерах нужна лишь для того, чтобы повторный запрос отличался от предыдущего. +{{< /alert >}} + +{{< alert level="info" >}} +Завершение принудительной реконсиляции можно отследить по полю [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmclusteraddon-v1alpha1-status-lastforcereconciletime) ресурса. Например: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +Для принудительной реконсиляции аддона: + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Аддоны». +1. Выберите нужный аддон и нажмите на иконку «Принудительная реконсиляция». + +Результат принудительной реконсиляции будет отражён в столбце «Статус». + +Для принудительной реконсиляции репозитория аддонов: + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Репозитории аддонов». +1. Выберите нужный репозиторий и нажмите на иконку «Принудительная реконсиляция». + +Результат принудительной реконсиляции будет отражён в столбце «Статус». + +{{< alert level="info" >}} +Реконсиляция может происходить очень быстро, поэтому в веб-интерфейсе может не успеть отобразиться изменение статуса. Убедиться в том, что принудительная синхронизация выполнена, можно по значению поля `.status.lastForceReconcileTime` ресурса. Для этого нажмите на имя интересующего ресурса и перейдите на вкладку «YAML» в открывшейся форме. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +## Режим обслуживания + +Режим обслуживания приостанавливает реконсиляцию аддона, что позволяет вмешаться в релиз вручную, корректируя параметры ранее развёрнутых ресурсов (изменять количество реплик, менять параметры и другое). + +{{< tabs name="enable-addon-maintenance" >}} +{{% tab name="В командной строке" %}} + +Для включения режима обслуживания выполните команду: + +```shell +d8 k patch helmclusteraddon podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' +``` + +Проверить, что режим обслуживания включён, можно командой: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Пример успешного вывода: + +```text +MaintenanceModeActive +``` + +Для выключения режима обслуживания выполните команду: + +```shell +d8 k patch helmclusteraddon podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' +``` + +Проверить, что режим обслуживания выключен, можно командой: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Пример успешного вывода: + +```text +MaintenanceModeInactive +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +Для управления режимом обслуживания аддона: + +1. Перейдите на вкладку «Система». +1. Перейдите в раздел «Helm-оператор» → «Аддоны». +1. Выберите нужный аддон и нажмите на его имя. +1. В открывшейся форме будет доступна опция «Режим обслуживания». + +У аддона, находящегося в режиме обслуживания, будет установлен статус «Обслуживание». + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +Аддон в режиме обслуживания не поддерживает принудительную реконсиляцию и не может быть удалён. +{{< /alert >}} diff --git a/docs/EXAMPLE.md b/docs/EXAMPLE.md deleted file mode 100644 index e111916..0000000 --- a/docs/EXAMPLE.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Examples" -description: "Deckhouse Kubernetes Platform — usage examples for the operator-helm module." -weight: 30 ---- - -## Adding a Helm repository - -To add a repository, create a HelmClusterAddonRepository resource: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddonRepository -metadata: - name: podinfo -spec: - url: https://stefanprodan.github.io/podinfo -``` - -After creating the repository, view the available Helm charts: - -```shell -d8 k get helmclusteraddoncharts.helm.deckhouse.io -l repository=podinfo -``` - -Example output: - -```text -NAME AGE LABELS -podinfo-chart-podinfo 11d chart=podinfo,heritage=deckhouse,repository=podinfo -``` - -To view the list of versions available for a specific chart: - -```shell -d8 k get helmclusteraddonchart podinfo-podinfo -o yaml -``` - -Example output: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddonChart -metadata: - labels: - chart: podinfo - heritage: deckhouse - repository: podinfo - name: podinfo-podinfo -status: - versions: - - version: 6.11.0 - - version: 6.10.2 -``` - -## Deploying an application - -To deploy an application, create a HelmClusterAddon resource specifying the repository name, chart name and version, and the target namespace: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddon -metadata: - name: podinfo -spec: - namespace: test - chart: - helmClusterAddonChart: podinfo - helmClusterAddonRepository: podinfo - version: 6.10.2 -``` - -{{< alert level="warning" >}} -Only one instance of HelmClusterAddon using a specific Helm chart from a specific repository can be deployed at a time. Different Helm charts from the same repository can be deployed simultaneously. -{{< /alert >}} - -{{< alert level="info" >}} -The `.spec.chart.version` parameter is optional. If omitted, the latest available version of the chart will be installed. -{{< /alert >}} - -## Deploying a namespaced application - -A namespace owner can deploy a chart into their own namespace without cluster-wide rights, using HelmApplicationRepository and HelmApplication instead of the cluster-scoped resources above. - -To add a repository, create a HelmApplicationRepository resource in the target namespace: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmApplicationRepository -metadata: - name: podinfo - namespace: test -spec: - url: https://stefanprodan.github.io/podinfo -``` - -To deploy a chart from it, create a HelmApplication resource in the same namespace, specifying the chart name, version, and the repository to take it from: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmApplication -metadata: - name: podinfo - namespace: test -spec: - chart: - name: podinfo - repository: podinfo - version: 6.10.2 -``` - -The release is always deployed into the namespace of the HelmApplication resource itself, so there is no separate namespace field to set. A chart may also be taken from a cluster-wide HelmClusterApplicationRepository by setting `.spec.chart.clusterRepository` instead of `.spec.chart.repository`. - -{{< alert level="warning" >}} -Creating a HelmApplication grants it administrator-level rights inside its namespace — see the module documentation's Limitations section for details. -{{< /alert >}} - -## Triggering a manual reconciliation - -To trigger an immediate reconciliation of a resource without waiting for the next scheduled sync, annotate it with `reconcile.helm.deckhouse.io/force`. The controller will detect the annotation, run a full reconciliation cycle, and remove the annotation automatically once processing is complete. - -To trigger reconciliation of a HelmClusterAddon: - -```shell -d8 k annotate helmclusteraddon podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite -``` - -To trigger reconciliation of a HelmClusterAddonRepository: - -```shell -d8 k annotate helmclusteraddonrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite -``` - -{{< alert level="info" >}} -The annotation value is not significant — only its presence on the resource matters. The controller removes the annotation after the reconciliation is complete. -{{< /alert >}} - -### Observing a forced reconciliation - -While a forced pass is running, the resource carries the `Reconciling` condition with the reason `ForceReconcile`: - -```shell -d8 k get helmclusteraddonrepository podinfo -o jsonpath='{.status.conditions[?(@.type=="Reconciling")]}' -``` - -A synchronization that runs on the ordinary schedule raises the same condition with the reason `Synchronization`, so the reason tells the two apart. - -Once the pass finishes, that condition is removed and `.status.lastForceReconcileTime` records when the request was processed: - -```shell -d8 k get helmclusteraddonrepository podinfo -o jsonpath='{.status.lastForceReconcileTime}' -``` - -The timestamp records that the request was acted on, not that it succeeded — the outcome is reported by the `Ready` and `Synced` conditions. - -{{< alert level="warning" >}} -A HelmClusterAddon in maintenance mode (`.spec.maintenance: NoResourceReconciliation`) is not reconciled at all, so a force request on it cannot be honoured. The controller discards the annotation instead of holding it until maintenance is lifted, and `.status.lastForceReconcileTime` is left untouched. Lift maintenance first, then request the reconciliation. -{{< /alert >}} diff --git a/docs/EXAMPLE.ru.md b/docs/EXAMPLE.ru.md deleted file mode 100644 index 5116879..0000000 --- a/docs/EXAMPLE.ru.md +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Примеры" -description: "Deckhouse Kubernetes Platform — примеры использования модуля operator-helm." -weight: 30 ---- - -## Добавление Helm-репозитория - -Для добавления репозитория создайте ресурс HelmClusterAddonRepository: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddonRepository -metadata: - name: podinfo -spec: - url: https://stefanprodan.github.io/podinfo -``` - -После создания репозитория можно просмотреть доступные в нём Helm-чарты: - -```shell -d8 k get helmclusteraddoncharts.helm.deckhouse.io -l repository=podinfo -``` - -Пример вывода: - -```text -NAME AGE LABELS -podinfo-chart-podinfo 11d chart=podinfo,heritage=deckhouse,repository=podinfo -``` - -Для просмотра списка версий, доступных для заданного чарта: - -```shell -d8 k get helmclusteraddonchart podinfo-podinfo -o yaml -``` - -Пример вывода: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddonChart -metadata: - labels: - chart: podinfo - heritage: deckhouse - repository: podinfo - name: podinfo-podinfo -status: - versions: - - version: 6.11.0 - - version: 6.10.2 -``` - -## Развёртывание приложения - -Для развёртывания приложения создайте ресурс HelmClusterAddon, указав имя репозитория, имя и версию чарта, а также целевое пространство имён: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmClusterAddon -metadata: - name: podinfo -spec: - namespace: test - chart: - helmClusterAddonChart: podinfo - helmClusterAddonRepository: podinfo - version: 6.10.2 -``` - -{{< alert level="warning" >}} -Одновременно допускается развёртывание только одного экземпляра HelmClusterAddon, использующего заданный Helm-чарт из заданного репозитория. При этом из одного репозитория одновременно могут быть развёрнуты разные Helm-чарты. -{{< /alert >}} - -{{< alert level="info" >}} -Параметр `.spec.chart.version` является необязательным. Если он не указан, будет установлена последняя доступная версия чарта. -{{< /alert >}} - -## Развёртывание приложения в пространстве имён - -Владелец namespace может развернуть чарт в собственном namespace без прав на весь кластер, используя HelmApplicationRepository и HelmApplication вместо кластерных ресурсов, описанных выше. - -Для добавления репозитория создайте ресурс HelmApplicationRepository в целевом namespace: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmApplicationRepository -metadata: - name: podinfo - namespace: test -spec: - url: https://stefanprodan.github.io/podinfo -``` - -Для развёртывания чарта из него создайте ресурс HelmApplication в том же namespace, указав имя и версию чарта, а также репозиторий, из которого его нужно взять: - -```yaml -apiVersion: helm.deckhouse.io/v1alpha1 -kind: HelmApplication -metadata: - name: podinfo - namespace: test -spec: - chart: - name: podinfo - repository: podinfo - version: 6.10.2 -``` - -Релиз всегда разворачивается в namespace самого ресурса HelmApplication, поэтому отдельного поля для имени namespace здесь нет. Чарт также можно взять из кластерного HelmClusterApplicationRepository, указав вместо `.spec.chart.repository` поле `.spec.chart.clusterRepository`. - -{{< alert level="warning" >}} -Создание HelmApplication даёт ему права уровня администратора внутри его namespace — подробнее см. раздел «Ограничения» документации модуля. -{{< /alert >}} - -## Ручной запуск реконсиляции - -Чтобы запустить немедленную реконсиляцию ресурса, не дожидаясь следующей запланированной синхронизации, добавьте к нему аннотацию `reconcile.helm.deckhouse.io/force`. Контроллер обнаружит аннотацию, выполнит полный цикл реконсиляции и автоматически удалит аннотацию после завершения обработки. - -Запуск реконсиляции для HelmClusterAddon: - -```shell -d8 k annotate helmclusteraddon podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite -``` - -Запуск реконсиляции для HelmClusterAddonRepository: - -```shell -d8 k annotate helmclusteraddonrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite -``` - -{{< alert level="info" >}} -Значение аннотации не имеет значения — контроллер проверяет только её наличие на ресурсе. После завершения реконсиляции аннотация удаляется автоматически. -{{< /alert >}} - -### Наблюдение за принудительной реконсиляцией - -Пока принудительный проход выполняется, на ресурсе присутствует условие `Reconciling` с причиной `ForceReconcile`: - -```shell -d8 k get helmclusteraddonrepository podinfo -o jsonpath='{.status.conditions[?(@.type=="Reconciling")]}' -``` - -Синхронизация по обычному расписанию выставляет то же условие с причиной `Synchronization`, поэтому причина позволяет различить эти два случая. - -После завершения прохода это условие снимается, а в `.status.lastForceReconcileTime` записывается время обработки запроса: - -```shell -d8 k get helmclusteraddonrepository podinfo -o jsonpath='{.status.lastForceReconcileTime}' -``` - -Отметка времени фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражают условия `Ready` и `Synced`. - -{{< alert level="warning" >}} -HelmClusterAddon в режиме обслуживания (`.spec.maintenance: NoResourceReconciliation`) не согласовывается вовсе, поэтому запрос принудительной реконсиляции для него невыполним. Контроллер удаляет аннотацию, а не удерживает её до выхода из режима обслуживания; `.status.lastForceReconcileTime` при этом не меняется. Сначала выйдите из режима обслуживания, затем запрашивайте реконсиляцию. -{{< /alert >}} diff --git a/docs/README.ru.md b/docs/README.ru.md index 2e1cc80..9d8fe10 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -4,40 +4,81 @@ description: "Deckhouse Kubernetes Platform — модуль operator-helm дл weight: 10 --- -Модуль `operator-helm` позволяет декларативно управлять развёртыванием Helm-чартов в кластере. Он автоматизирует установку чартов с помощью кастомных ресурсов и охватывает два уровня: кластерное семейство аддонов для администраторов кластеров и DevOps-инженеров и пространственное (namespaced) семейство приложений, которое позволяет владельцу namespace устанавливать чарты в собственном namespace без прав на весь кластер. +Модуль `operator-helm` декларативно разворачивает Helm-чарты и рассчитан на две аудитории: администраторов платформы и администраторов неймспейсов. Чарты он делит на аддоны и приложения — по тому, какие объекты они создают. -Контроллер модуля отслеживает состояние ресурсов HelmClusterAddon и HelmApplication и автоматически приводит Helm-релизы в кластере в соответствие с заданными параметрами. +**Аддоны** ([`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon)) могут содержать CRD и другие кластерные объекты, поэтому их разворачивает администратор платформы. Такой Helm-чарт может влиять на состояние кластера, и управление им остаётся на уровне кластера. + +**Приложения** ([`HelmApplication`](/modules/operator-helm/cr.html#helmapplication)) состоят только из объектов, относящихся к конкретному неймспейсу. Их разворачивает администратор неймспейса. ## Основные возможности -- Развёртывание Helm-чартов из классических HTTP/HTTPS-репозиториев и OCI-репозиториев через единый декларативный API. -- Автоматическое обнаружение и отслеживание версий чартов через ресурсы HelmClusterAddonChart, HelmApplicationChart и HelmClusterApplicationChart. -- Настройка параметров чартов через ресурсы HelmClusterAddon и HelmApplication. -- Установка чартов в отдельном namespace через HelmApplication в дополнение к установке на уровне кластера через HelmClusterAddon. -- Режим обслуживания для приостановки согласования и ручного вмешательства в управляемые релизы. -- Поддержка проверки TLS-сертификатов и аутентификации для приватных OCI и Helm репозиториев. -- Управление через CLI (`d8 k`) или веб-интерфейс Deckhouse. +Модуль предоставляет следующие возможности: + +- декларативное управление развёртыванием Helm-чартов; +- установка чартов из HTTP(S)- и OCI-репозиториев через один и тот же API; +- автоматическая синхронизация репозитория для просмотра и поиска доступных Helm-чартов и их версий; +- установка чартов администратором неймспейса без выдачи ему прав на кластер; +- поддержка общих репозиториев приложений, доступных во всех неймспейсах; +- автоматическое устранение дрейфа конфигурации; +- режим обслуживания, который приостанавливает реконсиляцию для ручного вмешательства в релиз; +- поддержка приватных репозиториев с использованием корпоративного PKI; +- управление через `d8 k` или веб-интерфейс Deckhouse Kubernetes Platform. ## Кастомные ресурсы -Для управления Helm-чартами в модуле используются следующие кастомные ресурсы: +Ресурсы модуля делятся на две группы по области видимости. Кластерными ресурсами управляет администратор платформы, а ресурсами в заданном неймспейсе — администратор неймспейса. -- **HelmClusterAddonRepository** — репозиторий Helm или OCI, содержащий Helm-чарты для последующей установки в кластере. -- **HelmClusterAddon** — декларативное описание конкретного релиза Helm-чарта. Ресурс содержит целевую версию чарта, имя пространства имён для развёртывания и пользовательские значения параметров. -- **HelmApplicationRepository** — репозиторий Helm или OCI, на Helm-чарты которого могут ссылаться ресурсы HelmApplication из того же namespace. -- **HelmClusterApplicationRepository** — репозиторий Helm или OCI, на Helm-чарты которого могут ссылаться ресурсы HelmApplication из любого namespace. -- **HelmApplication** — декларативное описание установки Helm-чарта в пределах одного namespace. Релиз всегда развёртывается в namespace самого ресурса; ресурс содержит целевую версию чарта, ссылку либо на HelmApplicationRepository из того же namespace, либо на кластерный HelmClusterApplicationRepository, а также пользовательские значения параметров. +```mermaid +flowchart TB + classDef actor fill:#ffffff,stroke:#000000,color:#000000,stroke-width:3px; + classDef cluster fill:#e0e7ff,stroke:#1a237e,color:#000000,stroke-width:2px; + classDef ns fill:#f0fdfa,stroke:#004d40,color:#000000,stroke-width:2px; -Каждый репозиторий дополнительно публикует каталог предлагаемых им чартов — HelmClusterAddonChart, HelmApplicationChart и HelmClusterApplicationChart. Контроллер создаёт и обновляет их при синхронизации репозиториев; эти ресурсы доступны только для чтения и вручную не редактируются. + ADM(["fa:fa-user
Администратор
платформы"]):::actor + USR(["fa:fa-user
Администратор
неймспейса"]):::actor -## Ограничения + HCA["HelmClusterAddon"]:::cluster + HCAR["HelmClusterAddonRepository"]:::cluster + HCApR["HelmClusterApplicationRepository"]:::cluster + + HA["HelmApplication"]:::ns + HAR["HelmApplicationRepository"]:::ns + + HCAC["HelmClusterAddonChart"]:::cluster + HCApC["HelmClusterApplicationChart"]:::cluster + HAC["HelmApplicationChart"]:::ns + + ADM -->|Управляет| HCA + ADM -->|Управляет| HCAR + ADM -->|Управляет| HCApR + HCA -->|Использует| HCAC + HCAR -->|Обслуживает| HCAC + + USR -->|Управляет| HA + USR -->|Управляет| HAR + HA -->|Использует| HAC + HA -->|Использует| HCApC + HAR -->|Обслуживает| HAC + + HCApR -->|Обслуживает| HCApC +``` -- Семейство аддонов (HelmClusterAddon, HelmClusterAddonChart, HelmClusterAddonRepository) полностью кластерное, поэтому для управления им требуется роль `ClusterAdmin`. -- Семейство приложений является namespaced: владелец namespace с ролью `Admin` может создавать HelmApplication и HelmApplicationRepository в своём namespace и управлять ими без прав на весь кластер. HelmClusterApplicationRepository — кластерный ресурс, поэтому для его создания нужна роль `ClusterAdmin`, но любой HelmApplication может ссылаться на уже существующий из своего namespace. -- Создание HelmApplication фактически равносильно правам администратора внутри его namespace: контроллер создаёт в namespace объект Role с неограниченными правами (`apiGroups: ["*"]`, `resources: ["*"]`, `verbs: ["*"]`) и привязывает его к ServiceAccount приложения. Оба объекта принадлежат модулю и реконсилируются: контроллер следит за ними и восстанавливает свои правила, subjects и метки, поэтому сузить или удалить любой из них на срок дольше одного прохода не получится. Принадлежность определяется меткой `helm.deckhouse.io/managed-by: operator-helm`: объект, занявший одно из этих имён без этой метки — созданный кем-то заранее или лишившийся метки позже, — никогда не присваивается, не патчится и не удаляется, а приложение сообщает `Stalled` с причиной `ForeignAccessObject` и ничего не устанавливает. Возврат метки поднимает приложение сам; удаление объекта, который метки никогда не нёс, — нет, потому что за ним никто не следит, поэтому после удаления запросите реконсиляцию аннотацией `reconcile.helm.deckhouse.io/force`. Поскольку выдаваемые права предоставляет модуль, а не исходные права создателя, право на создание HelmApplication без прочих прав в namespace даёт через устанавливаемый чарт тот же уровень доступа, что и права администратора namespace. -- HelmApplication нельзя создать в системном namespace (`kube-system`, `kube-public`, `kube-node-lease`, а также в любом namespace, имя которого начинается с `d8-`, включая собственный namespace модуля `d8-operator-helm`); admission-контроллер отклоняет такую попытку. -- HelmApplicationRepository и HelmClusterApplicationRepository хранят учётные данные реестра в открытом виде (`spec.auth.username` и `spec.auth.password`; альтернативы через `secretRef` нет), поэтому любое право на чтение ресурса-репозитория — это право на чтение его пароля. В том числе поэтому репозитории доступны не ниже уровня `Admin`. -- К модулю обращаются две роли Deckhouse, и уровни накапливаются снизу вверх. `Admin` может делать что угодно с HelmApplication и HelmApplicationRepository и получает чтение обоих каталогов, из которых приложение выбирает чарт: HelmApplicationChart и HelmClusterApplicationChart. `ClusterAdmin` покрывает кластерные виды: полные права на HelmClusterAddon, HelmClusterAddonRepository и HelmClusterApplicationRepository, а также чтение HelmClusterAddonChart. Стоит понимать, что означает первое: установка приложения равносильна правам администратора namespace, как описано выше, поэтому `Admin` — самый низкий уровень, которому модуль вообще доступен. Записывать каталог чартов не может ни один уровень — его единственный автор контроллер. -- Ресурс HelmClusterAddon, ссылающийся на заданный HelmClusterAddonChart, может быть создан в кластере только в единственном экземпляре. Это обусловлено тем, что Helm-чарты могут содержать определения кастомных ресурсов (CRD), повторная установка которых на уровне кластера недопустима. +Синей заливкой отмечены кластерные ресурсы, бирюзовой — ресурсы внутри неймспейса. Каталоги чартов модуль обслуживает сам, вручную они не редактируются. + +Администратор платформы работает с кластерными ресурсами: + +- [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) — репозиторий Helm или OCI с чартами для установки на уровне кластера; +- [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) — описание релиза: целевая версия чарта, неймспейс развёртывания и расширенные параметры установки (при необходимости); +- [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — репозиторий, чарты которого доступны ресурсам `HelmApplication` из любого неймспейса. + +Администратор неймспейса работает с ресурсами своего неймспейса: + +- [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) — репозиторий, чарты которого доступны ресурсам `HelmApplication` того же неймспейса; +- [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) — описание релиза в собственном неймспейсе: целевая версия чарта, ссылка на `HelmApplicationRepository` или `HelmClusterApplicationRepository` и расширенные параметры установки (при необходимости). + +Примеры настройки вышеописанных ресурсов приведены в [руководстве администратора](admin_guide.html) и [руководстве пользователя](user_guide.html). + +## Ограничения -Примеры использования приведены в разделе [примеры использования](example.html). +- Ресурс [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon), ссылающийся на заданный [`HelmClusterAddonChart`](/modules/operator-helm/cr.html#helmclusteraddonchart), может быть создан только в единственном экземпляре. Helm-чарты, используемые в аддоне, могут содержать определения кастомных ресурсов (Custom Resource Definition, CRD), а их повторная установка на уровне кластера может привести к перебоям в работе сервисов; +- Создание [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) требует наличия полномочий не ниже чем `Admin`, так как деплой приложений выполняется с использованием `ServiceAccount`, обладающего аналогичными привилегиями. diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md new file mode 100644 index 0000000..a59874e --- /dev/null +++ b/docs/USER_GUIDE.ru.md @@ -0,0 +1,520 @@ +--- +title: "Руководство пользователя" +description: "Deckhouse Kubernetes Platform — установка Helm-чартов в своём неймспейсе с помощью модуля operator-helm." +weight: 50 +--- + +Руководство описывает работу с ресурсами модуля в пределах неймспейса: репозиториями чартов, их каталогами и приложениями. Для работы с данными кастомными ресурсами необходимо иметь полномочия не ниже чем [`Admin`](/modules/user-authz/#текущая-ролевая-модель) в своём неймспейсе. + +## Добавление репозитория приложений + +Репозиторий — точка входа для всех остальных ресурсов: пока он не добавлен, выбирать чарт не из чего. + +Создайте ресурс [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) в своём неймспейсе: + +{{< tabs name="create-application-repository" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +{{< /alert >}} + +Модуль синхронизирует репозиторий и создаст по объекту [`HelmApplicationChart`](/modules/operator-helm/cr.html#helmapplicationchart) на каждый найденный чарт. Для просмотра чартов репозитория: + +{{< tabs name="list-application-charts" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k -n test get helmapplicationcharts -l repository=podinfo +``` + +Пример вывода: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo +``` + +Имя объекта каталога формируется из имени репозитория, имени чарта и хеша, поэтому выбирать чарт удобнее по лейблам `repository` и `chart`, а не по имени. + +Доступные версии чарта перечислены в его статусе. Выведите их: + +```shell +d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplicationChart +metadata: + labels: + chart: podinfo + heritage: deckhouse + repository: podinfo + name: podinfo-chart-podinfo-dfbe83e63b0b + namespace: test +status: + versions: + - version: 6.11.0 + - version: 6.10.2 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Чарты». + +{{% /tab %}} +{{< /tabs >}} + +### Проверка состояния репозитория + +Состояние репозитория отражают условия в его статусе. Для оценки состояния репозитория: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k -n test get helmapplicationrepository podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplicationRepository +metadata: + creationTimestamp: "2026-09-22T13:41:25Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 1 + name: podinfo + namespace: test + resourceVersion: "48844673" + uid: f081a6d7-610a-4996-a10c-3d663928f027 +spec: + url: https://stefanprodan.github.io/podinfo +status: + chartCount: 1 + conditions: + - lastTransitionTime: "2026-09-22T13:41:26Z" + message: "" + observedGeneration: 1 + reason: Success + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T13:41:25Z" + message: "" + observedGeneration: 1 + reason: Success + status: "True" + type: Synced + lastSuccessfulSyncTime: "2026-09-22T13:41:25Z" + nextSyncTime: "2026-09-22T13:46:10Z" + observedGeneration: 1 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Репозитории». +1. Выберите нужный репозиторий и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Просмотр возможных состояний репозитория" >}} + +| Условие | Значение | Причина | Что это значит | +| --- | --- | --- | --- | +| `Ready` | `True` | `Success` | Репозиторий доступен, каталог чартов построен. Можно выбирать чарт для приложения. | +| `Ready` | `Unknown` | `AwaitingInitialSync` | Репозиторий только создан, первое чтение ещё не завершилось. Дождитесь окончания синхронизации. | +| `Ready` | `False` | `AuxiliaryResourcesFailed` | Не удалось создать служебный секрет с учётными данными репозитория. Проверьте свои полномочия в неймспейсе. | +| `Synced` | `True` | `Success` | Каталог чартов соответствует содержимому репозитория. | +| `Synced` | `False` | `SyncFailed` | Репозиторий не удалось прочитать. Проверьте URL и доступность реестра из кластера. | +| `Synced` | `False` | `CatalogUpdateFailed` | Репозиторий прочитан, но записать каталог чартов в кластер не удалось. Попытка повторится автоматически. | +| `Synced` | `False` | `PartialSync` | При первом чтении часть версий разобрать не удалось. Остальные уже доступны, пропущенные подтянутся при следующей синхронизации. | +| `Reconciling` | `True` | `Synchronization` | Идёт плановая синхронизация с репозиторием. | +| `Reconciling` | `True` | `ForceReconcile` | Идёт синхронизация, запрошенная вручную. | +| `Reconciling` | `True` | `ProgressingWithRetry` | Предыдущая попытка не удалась, запланирован повтор. | +| `Stalled` | `True` | `UnsupportedRepositoryType` | Схема в URL не поддерживается. Допустимы только `http(s)://` и `oci://`. | +| `Stalled` | `True` | `InvalidRepositoryURL` | URL не удалось разобрать. Проверьте адрес репозитория. | +| `Stalled` | `True` | `AuthenticationFailed` | Реестр отклонил учётные данные. Проверьте логин и пароль в спецификации репозитория. | +| `Stalled` | `True` | `SourceNotFound` | По указанному URL репозиторий не найден. | +| `Stalled` | `True` | `SourceRejectedRequest` | Реестр отклонил запрос. Обратитесь к владельцу реестра. | +| `Stalled` | `True` | `RetriesExceeded` | Попытки чтения исчерпаны. Устраните причину и запросите принудительную реконсиляцию. | + +{{< alert level="info" >}} + +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. + +{{< /alert >}} + +{{< /details >}} + +## Развёртывание приложения + +Создайте ресурс [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) в том же неймспейсе, указав репозиторий, имя и версию чарта: + +{{< tabs name="create-application" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} +Приложения могут разворачиваться не только из Helm-чартов локального для неймспейса репозитория, но и из общего репозитория, который завёл администратор платформы. Общие репозитории описываются с помощью ресурса [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository), а их каталог — ресурсами [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). + +У любого пользователя в неймспейсе есть доступ на чтение [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). + +Для использования чарта из общего репозитория при описании ресурса `HelmApplication` укажите поле [`spec.chart.clusterRepository`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-spec-chart-clusterrepository) вместо [`spec.chart.repository`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-spec-chart-repository). + +{{< details summary="Просмотр доступных общих Helm-чартов приложений" >}} + +Для просмотра общих Helm-чартов выполните команду: + +```shell +d8 k get helmclusterapplicationcharts --show-labels +``` + +Пример вывода: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo-shared +``` + +{{< /details >}} + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Приложения». +1. Нажмите кнопку «Создать». +1. В открывшейся форме в поле «Имя» введите произвольное имя ресурса. +1. В поле «Репозиторий» выберите репозиторий с Helm-чартами приложений или общий репозиторий приложений, созданный администратором. +1. В поле «Чарт» выберите Helm-чарт. +1. В поле «Версия» выберите версию Helm-чарта. +1. Нажмите кнопку «Создать». + +{{< alert level="info" >}} +В списке репозиториев у некоторых может быть постфикс «(cluster)» — это значит, что репозиторий общий ([`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository)) и его создал администратор платформы. +{{< /alert >}} + +{{< alert level="info" >}} +При необходимости вы можете скорректировать параметры Helm-чарта. Для получения параметров, используемых по умолчанию, нажмите на ссылку «Показать значения по умолчанию» в форме создания приложения. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +Развёртывание [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) выполняется с полными привилегиями в рамках неймспейса. + +{{< details summary="Правила роли, используемой при развёртывании приложения" >}} + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + labels: + helm.deckhouse.io/managed-by: operator-helm + name: operator-helm-application + namespace: test +rules: +- apiGroups: + - '*' + resources: + - '*' + verbs: + - '*' +``` + +{{< /details >}} + +{{< /alert >}} + +### Проверка состояния приложения + +Состояние приложения отражают условия в его статусе. Для оценки состояния приложения: + +{{< tabs name="check-application-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k -n test get helmapplication podinfo -o yaml +``` + +Пример вывода: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplication +metadata: + creationTimestamp: "2026-09-18T08:19:55Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 1 + name: podinfo + namespace: test + resourceVersion: "48926122" + uid: f4059036-a6c9-401a-be8d-67d8f2410c6f +spec: + chart: + repository: podinfo + name: podinfo + version: 6.15.0 +status: + conditions: + - lastTransitionTime: "2026-09-22T15:28:11Z" + message: Helm upgrade succeeded for release test/hap-podinfo-3fb7b289386f.v2 + with chart podinfo@6.15.0 + observedGeneration: 1 + reason: UpgradeSucceeded + status: "True" + type: Ready + - lastTransitionTime: "2026-09-18T08:20:03Z" + message: Helm install succeeded for release test/hap-podinfo-3fb7b289386f.v1 + with chart podinfo@6.15.0 + observedGeneration: 1 + reason: InstallSucceeded + status: "True" + type: Installed + lastAppliedChart: + repository: podinfo + name: podinfo + version: 6.15.0 + observedGeneration: 1 +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Приложения». +1. Выберите нужное приложение и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Просмотр возможных состояний приложения" >}} + +| Условие | Значение | Причина | Что это значит | +| --- | --- | --- | --- | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | Релиз развёрнут и соответствует спецификации. Причину в этом случае подставляет Helm. | +| `Ready` | `Unknown` | `Reconciling` | Работа идёт: чарт загружается или релиз раскатывается. | +| `Ready` | `False` | `ReleaseFailed` | Helm не смог установить или обновить релиз. Текст ошибки приведён в поле `message`. | +| `Ready` | `False` | `TestFailed` | Тесты чарта завершились неудачно. | +| `Ready` | `False` | `Remediated` | Выполнен откат к предыдущему состоянию релиза. | +| `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | Чарт не удалось загрузить из репозитория или сохранить в кластере. | +| `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | Не удалось получить или проверить чарт из OCI-реестра. | +| `Ready` | `False` | `ChartVersionRemoved` | Указанная версия чарта больше не публикуется репозиторием. Выберите другую версию. | +| `Ready` | `False` | `AccessSetupFailed` | Не удалось подготовить `ServiceAccount`, `Role` или `RoleBinding`, от имени которых устанавливается чарт. Попытка повторится автоматически. | +| `Ready` | `False` | `ForeignAccessObject` | Занято имя `Role` или `RoleBinding`, которые модуль создаёт для приложения. `Role` всегда называется `operator-helm-application`, имя `RoleBinding` совпадает с именем `ServiceAccount` приложения и приведено в поле `message`. Объект с таким именем создан не модулем, поэтому модуль его не трогает. Удалите чужой объект и запросите принудительную реконсиляцию. | +| `Ready` | `False` | `UnsupportedRepositoryType` | У репозитория, на который ссылается приложение, нечитаемый URL. Обратитесь к владельцу репозитория. | +| `Ready` | `False` | `Failed` | Прочие ошибки. Причина приведена в поле `message`. | +| `Installed` | как у `Ready` | та же, что у `Ready` | Результат первой установки релиза. | +| `UpdateInstalled` | как у `Ready` | та же, что у `Ready` | Результат обновления релиза. Появляется при смене версии чарта. | +| `ConfigurationApplied` | как у `Ready` | та же, что у `Ready` | Результат применения значений чарта. Появляется при изменении значений. | +| `Managed` | `True` | `MaintenanceModeInactive` | Приложение находится под управлением модуля. | +| `Managed` | `False` | `MaintenanceModeActive` | Включён режим обслуживания, реконсиляция приостановлена. | +| `Reconciling` | `True` | `Reconciling` | Идёт раскатка релиза. | +| `Reconciling` | `True` | `ProgressingWithRetry` | Произошёл сбой, запланирован повтор. | +| `Reconciling` | `True` | `ForceReconcile` | Идёт реконсиляция, запрошенная вручную. | +| `Stalled` | `True` | причина того сбоя, который его вызвал | Повтор не поможет: нужно исправить спецификацию приложения, дождаться изменений в репозитории или убрать мешающий объект. Пока причина не устранена, попытки прекращены. | + +{{< alert level="info" >}} + +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как приложение проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Принудительный запуск реконсиляции + +При работе с приложениями и репозиториями может возникнуть необходимость принудительного запуска реконсиляции. В штатном режиме работы запуск реконсиляции происходит автоматически в случае внесения изменений в ресурсы либо изменения состояния их зависимостей. + +В случае с приложениями принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек приложения возникла терминальная ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. + +При работе с репозиториями запуск принудительной реконсиляции позволяет выполнить синхронизацию репозитория, не дожидаясь очередного запуска по расписанию. + +{{< tabs name="force-reconcile-application" >}} +{{% tab name="В командной строке" %}} + +Для принудительной реконсиляции [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) выполните команду: + +```shell +d8 k -n test annotate helmapplication podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +Для принудительной реконсиляции [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) выполните команду: + +```shell +d8 k -n test annotate helmapplicationrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +{{< alert level="info" >}} +Модуль проверяет только наличие аннотации, её содержимое он не читает. Временная метка в примерах нужна лишь для того, чтобы повторный запрос отличался от предыдущего. +{{< /alert >}} + +{{< alert level="info" >}} +Завершение принудительной реконсиляции можно отследить по полю [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-status-lastforcereconciletime) ресурса. Например: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +Для принудительной реконсиляции приложения: + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Приложения». +1. Выберите нужное приложение и нажмите на иконку «Принудительная реконсиляция». + +Результат принудительной реконсиляции будет отражён в столбце «Статус». + +Для принудительной реконсиляции репозитория приложений: + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Репозитории». +1. Выберите нужный репозиторий и нажмите на иконку «Принудительная реконсиляция». + +Результат принудительной реконсиляции будет отражён в столбце «Статус». + +{{< alert level="info" >}} + +Реконсиляция может происходить очень быстро, поэтому в веб-интерфейсе может не успеть отобразиться изменение статуса. Убедиться в том, что принудительная синхронизация выполнена, можно по значению поля `.status.lastForceReconcileTime` ресурса. Для этого нажмите на имя интересующего ресурса и перейдите на вкладку «YAML» в открывшейся форме. + +{{< /alert >}} + +{{% /tab %}} + +{{< /tabs >}} + +## Режим обслуживания + +Режим обслуживания приостанавливает реконсиляцию приложения, что позволяет вмешаться в релиз вручную, корректируя параметры ранее развёрнутых ресурсов (изменять количество реплик, менять параметры и другое). + +{{< tabs name="enable-application-maintenance" >}} +{{% tab name="В командной строке" %}} + +Для включения режима обслуживания выполните команду: + +```shell +d8 k -n test patch helmapplication podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' +``` + +Проверить, что режим обслуживания включён, можно командой: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Пример успешного вывода: + +```text +MaintenanceModeActive +``` + +Для выключения режима обслуживания выполните команду: + +```shell +d8 k -n test patch helmapplication podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' +``` + +Проверить, что режим обслуживания выключен, можно командой: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Пример успешного вывода: + +```text +MaintenanceModeInactive +``` + +{{% /tab %}} + +{{% tab name="В веб-интерфейсе" %}} + +Для управления режимом обслуживания приложения: + +1. Перейдите на вкладку «Проекты» и выберите нужный проект. +1. Перейдите в раздел «Helm-оператор» → «Приложения». +1. Выберите нужное приложение и нажмите на его имя. +1. В открывшейся форме будет доступна опция «Режим обслуживания». + +У приложения, находящегося в режиме обслуживания, будет установлен статус «Обслуживание». + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +Приложение в режиме обслуживания не поддерживает принудительную реконсиляцию и не может быть удалено. +{{< /alert >}} From 69a65a3d0cca154cb552190e24ba39cd0e5b26c5 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:08:37 +0300 Subject: [PATCH 2/6] docs: translate the module guides into English The English side had fallen behind: EXAMPLE.md was deleted with the Russian rework while README.md still linked to example.html, and neither guide existed. Both guides and the overview are now translated from their Russian originals, so the two languages carry the same structure, diagram and status tables. The web-interface labels are translated literally: the console strings in the checkout do not match the UI the Russian text describes, so they could not be verified against it. Signed-off-by: Ilya Drey --- docs/ADMIN_GUIDE.md | 578 ++++++++++++++++++++++++++++++++++++++++++++ docs/README.md | 96 +++++--- docs/USER_GUIDE.md | 520 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 1166 insertions(+), 28 deletions(-) create mode 100644 docs/ADMIN_GUIDE.md create mode 100644 docs/USER_GUIDE.md diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md new file mode 100644 index 0000000..8f8dcae --- /dev/null +++ b/docs/ADMIN_GUIDE.md @@ -0,0 +1,578 @@ +--- +title: "Administrator guide" +description: "Deckhouse Platform — managing the cluster-scoped resources of the operator-helm module: repositories, chart catalogs and addons." +weight: 40 +--- + +This guide describes how to work with the cluster-scoped resources of the module: chart repositories, their catalogs and addons. Working with these custom resources requires permissions no lower than [`ClusterAdmin`](/modules/user-authz/#current-role-based-model). + +## Adding an addon repository + +A repository is the entry point for every other resource: until one is added, there is no chart to pick. + +Create a [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) resource: + +{{< tabs name="create-addon-repository" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +Two schemes can be used in a repository URL: `http(s)://` (a Helm repository that publishes an `index.yaml` file listing the available Helm charts) and `oci://` (a container registry that supports storing Helm charts). +{{< /alert >}} + +The module synchronizes the repository and creates one [`HelmClusterAddonChart`](/modules/operator-helm/cr.html#helmclusteraddonchart) object per chart found. To view the charts of a repository: + +{{< tabs name="list-addon-charts" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k get helmclusteraddoncharts -l repository=podinfo +``` + +Example output: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo +``` + +The name of a catalog object is composed of the repository name, the chart name and a hash, so it is more convenient to select a chart by the `repository` and `chart` labels than by name. + +The available chart versions are listed in its status. To print them: + +```shell +d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddonChart +metadata: + labels: + chart: podinfo + heritage: deckhouse + repository: podinfo + name: podinfo-chart-podinfo-dfbe83e63b0b +status: + versions: + - version: 6.11.0 + - version: 6.10.2 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addon charts". + +{{% /tab %}} +{{< /tabs >}} + +## Deploying an addon + +Create a [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) resource, specifying the repository, the chart name and version, and the namespace to deploy into: + +{{< tabs name="create-addon" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} +You can adjust the Helm chart parameters if needed. To see the parameters used by default, click the "Show default values" link in the addon creation form. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +A given chart of a given repository can be served by only one `HelmClusterAddon` resource. Different charts from the same repository can still be deployed at the same time. +{{< /alert >}} + +### Checking the repository state + +The state of a repository is reflected by the conditions in its status. To assess the state of a repository: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k get helmclusteraddonrepository podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddonRepository +metadata: + creationTimestamp: "2026-09-22T15:28:51Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 2 + name: podinfo + resourceVersion: "48926557" + uid: 0fbfec2f-6669-40ba-a7ef-0cd223aabfca +spec: + url: https://stefanprodan.github.io/podinfo +status: + chartCount: 1 + conditions: + - lastTransitionTime: "2026-09-22T15:28:52Z" + message: "" + observedGeneration: 2 + reason: Success + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T15:28:51Z" + message: "" + observedGeneration: 2 + reason: Success + status: "True" + type: Synced + lastSuccessfulSyncTime: "2026-09-22T15:28:51Z" + nextSyncTime: "2026-09-22T15:34:09Z" + observedGeneration: 2 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Repositories". +1. Select the repository you need and hover the mouse over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible repository states" >}} + +| Condition | Value | Reason | What it means | +| --- | --- | --- | --- | +| `Ready` | `True` | `Success` | The repository is reachable and the chart catalog is built. You can select a chart for an addon. | +| `Ready` | `Unknown` | `AwaitingInitialSync` | The repository has just been created and the first read has not finished yet. Wait for the synchronization to complete. | +| `Ready` | `False` | `AuxiliaryResourcesFailed` | The auxiliary secret holding the repository credentials could not be created. Check your permissions in the namespace. | +| `Synced` | `True` | `Success` | The chart catalog matches the contents of the repository. | +| `Synced` | `False` | `SyncFailed` | The repository could not be read. Check the URL and that the registry is reachable from the cluster. | +| `Synced` | `False` | `CatalogUpdateFailed` | The repository was read, but the chart catalog could not be written to the cluster. The attempt will be repeated automatically. | +| `Synced` | `False` | `PartialSync` | Some versions could not be parsed during the first read. The rest are already available, and the skipped ones will be picked up at the next synchronization. | +| `Reconciling` | `True` | `Synchronization` | A scheduled synchronization with the repository is in progress. | +| `Reconciling` | `True` | `ForceReconcile` | A manually requested synchronization is in progress. | +| `Reconciling` | `True` | `ProgressingWithRetry` | The previous attempt failed and a retry is scheduled. | +| `Stalled` | `True` | `UnsupportedRepositoryType` | The scheme in the URL is not supported. Only `http(s)://` and `oci://` are allowed. | +| `Stalled` | `True` | `InvalidRepositoryURL` | The URL could not be parsed. Check the repository address. | +| `Stalled` | `True` | `AuthenticationFailed` | The registry rejected the credentials. Check the username and the password in the repository spec. | +| `Stalled` | `True` | `SourceNotFound` | No repository was found at the given URL. | +| `Stalled` | `True` | `SourceRejectedRequest` | The registry rejected the request. Contact the registry owner. | +| `Stalled` | `True` | `RetriesExceeded` | The read attempts are exhausted. Fix the cause and request a forced reconciliation. | + +{{< alert level="info" >}} + +The `Reconciling` and `Stalled` conditions are present only while they apply: the first until the work is finished, the second until the cause of the failure is fixed. + +{{< /alert >}} + +{{< /details >}} + +### Checking the addon state + +The state of an addon is reflected by the conditions in its status. To assess the state of an addon: + +{{< tabs name="check-addon-conditions" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k get helmclusteraddon podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmClusterAddon +metadata: + creationTimestamp: "2026-09-22T09:50:34Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 5 + name: podinfo + resourceVersion: "48927375" + uid: 5365281f-0f8c-4d3d-b174-5096d6bf255d +spec: + chart: + helmClusterAddonChart: podinfo + helmClusterAddonRepository: podinfo-helm-repository + version: 6.15.0 + maintenance: "" + namespace: default +status: + conditions: + - lastTransitionTime: "2026-09-22T15:29:56Z" + message: Helm upgrade succeeded for release default/podinfo.v2 with chart podinfo@6.15.0 + observedGeneration: 5 + reason: UpgradeSucceeded + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T09:50:41Z" + message: Helm install succeeded for release default/podinfo.v1 with chart podinfo@6.15.0 + observedGeneration: 1 + reason: InstallSucceeded + status: "True" + type: Installed + - lastTransitionTime: "2026-09-22T10:30:50Z" + message: Maintenance mode disabled + observedGeneration: 5 + reason: MaintenanceModeInactive + status: "True" + type: Managed + lastAppliedChart: + helmClusterAddonChart: podinfo + helmClusterAddonRepository: podinfo-helm-repository + version: 6.15.0 + lastForceReconcileTime: "2026-09-22T10:53:51Z" + observedGeneration: 5 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addons". +1. Select the addon you need and hover the mouse over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible addon states" >}} + +| Condition | Value | Reason | What it means | +| --- | --- | --- | --- | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | The release is deployed and matches the spec. The reason here is supplied by Helm. | +| `Ready` | `Unknown` | `Reconciling` | Work is in progress: the chart is being downloaded or the release is being rolled out. | +| `Ready` | `False` | `ReleaseFailed` | Helm could not install or upgrade the release. The error text is given in the `message` field. | +| `Ready` | `False` | `TestFailed` | The chart tests failed. | +| `Ready` | `False` | `Remediated` | The release was rolled back to its previous state. | +| `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | The chart could not be downloaded from the repository or stored in the cluster. | +| `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | The chart could not be retrieved from the OCI registry or verified. | +| `Ready` | `False` | `ChartVersionRemoved` | The specified chart version is no longer published by the repository. Select another version. | +| `Ready` | `False` | `ChartClaimConflict` | This chart of this repository is already deployed by another addon: a single repository–chart pair can be served by only one `HelmClusterAddon`. The resource holding it is named in the `message` field. The state resolves on its own within half a minute after that addon is deleted or pointed at another chart. | +| `Ready` | `False` | `UnsupportedRepositoryType` | The repository the addon refers to has an unreadable URL. Contact the repository owner. | +| `Ready` | `False` | `Failed` | Other errors. The cause is given in the `message` field. | +| `Installed` | same as `Ready` | same as for `Ready` | The outcome of the first installation of the release. | +| `UpdateInstalled` | same as `Ready` | same as for `Ready` | The outcome of a release upgrade. Appears when the chart version changes. | +| `ConfigurationApplied` | same as `Ready` | same as for `Ready` | The outcome of applying the chart values. Appears when the values change. | +| `Managed` | `True` | `MaintenanceModeInactive` | The addon is managed by the module. | +| `Managed` | `False` | `MaintenanceModeActive` | Maintenance mode is on, reconciliation is paused. | +| `Reconciling` | `True` | `Reconciling` | The release is being rolled out. | +| `Reconciling` | `True` | `ProgressingWithRetry` | A failure occurred and a retry is scheduled. | +| `Reconciling` | `True` | `ForceReconcile` | A manually requested reconciliation is in progress. | +| `Stalled` | `True` | the reason for the failure that caused it | Retrying will not help: you have to fix the addon spec, wait for the repository to change, or remove the object standing in the way. Attempts stop until the cause is resolved. | + +{{< alert level="info" >}} + +The `Reconciling` and `Stalled` conditions are present only while they apply: the first until the work is finished, the second until the cause of the failure is fixed. `Installed`, `UpdateInstalled` and `ConfigurationApplied` appear as the addon passes the corresponding stages and carry the same verdict as `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Adding a repository with application charts + +By creating a [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository), a platform administrator can give namespace administrators centralized access to Helm charts. The Helm charts of such a repository become available to the administrators of every namespace for deploying [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication). + +Create a [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) resource: + +{{< tabs name="create-cluster-application-repository" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +Two schemes can be used in a repository URL: `http(s)://` (a Helm repository that publishes an `index.yaml` file listing the available Helm charts) and `oci://` (a container registry that supports storing Helm charts). +{{< /alert >}} + +The catalog of such a repository is published in [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart) resources. To print it: + +{{< tabs name="list-cluster-application-charts" >}} +{{% tab name="Command line" %}} + +```shell +d8 k get helmclusterapplicationcharts -l repository=podinfo-shared +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Application repositories". +1. Select the repository you are interested in from the list and click its name. +1. In the form that opens, the "Charts" tab shows the list of the available Helm charts. + +{{% /tab %}} +{{< /tabs >}} + +Further work with the charts of this repository is described in the [user guide](user_guide.html). + +## Connecting a private repository + +The credentials and the TLS parameters are set in the repository spec. An example of configuring a repository with authentication and a self-signed certificate: + +{{< tabs name="connect-private-repository" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="warning" >}} +The credentials are stored in the resource in plaintext. The right to read a repository is the right to read its credentials. +{{< /alert >}} + +## Forcing reconciliation + +While working with addons and repositories, you may need to force a reconciliation. In normal operation, reconciliation starts automatically whenever the resources are changed or the state of their dependencies changes. + +For addons, a forced reconciliation can be useful if a terminal error occurred while deploying the addon or changing its settings. Without manual intervention, the module's controllers make no further reconciliation attempts. + +For repositories, a forced reconciliation lets you synchronize the repository without waiting for the next scheduled run. + +{{< tabs name="force-reconcile-addon" >}} +{{% tab name="Command line" %}} + +To force the reconciliation of a [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon), run the following command: + +```shell +d8 k annotate helmclusteraddon podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +To force the reconciliation of a [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository), run the following command: + +```shell +d8 k annotate helmclusteraddonrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +{{< alert level="info" >}} +The module only checks that the annotation is present; it does not read its contents. The timestamp in the examples is there only to make a repeated request differ from the previous one. +{{< /alert >}} + +{{< alert level="info" >}} +The completion of a forced reconciliation can be tracked through the [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmclusteraddon-v1alpha1-status-lastforcereconciletime) field of the resource. For example: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +To force the reconciliation of an addon: + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addons". +1. Select the addon you need and click the "Force reconciliation" icon. + +The outcome of the forced reconciliation is shown in the "Status" column. + +To force the reconciliation of an addon repository: + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addon repositories". +1. Select the repository you need and click the "Force reconciliation" icon. + +The outcome of the forced reconciliation is shown in the "Status" column. + +{{< alert level="info" >}} +Reconciliation can be very fast, so the web interface may not have time to show the status change. To make sure that the forced synchronization has been carried out, check the value of the `.status.lastForceReconcileTime` field of the resource. To do this, click the name of the resource you are interested in and switch to the "YAML" tab in the form that opens. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +## Maintenance mode + +Maintenance mode pauses the reconciliation of an addon, which lets you modify the release manually by adjusting the parameters of the previously deployed resources (changing the number of replicas, changing parameters and so on). + +{{< tabs name="enable-addon-maintenance" >}} +{{% tab name="Command line" %}} + +To turn maintenance mode on, run the following command: + +```shell +d8 k patch helmclusteraddon podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' +``` + +To check that maintenance mode is on, run the following command: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Example of successful output: + +```text +MaintenanceModeActive +``` + +To turn maintenance mode off, run the following command: + +```shell +d8 k patch helmclusteraddon podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' +``` + +To check that maintenance mode is off, run the following command: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Example of successful output: + +```text +MaintenanceModeInactive +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +To manage the maintenance mode of an addon: + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addons". +1. Select the addon you need and click its name. +1. The "Maintenance mode" option is available in the form that opens. + +An addon that is in maintenance mode gets the "Maintenance" status. + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +An addon in maintenance mode does not support forced reconciliation and cannot be deleted. +{{< /alert >}} diff --git a/docs/README.md b/docs/README.md index 1f5bf88..737e52b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,44 +1,84 @@ --- title: "Module operator-helm" -description: "Deckhouse Kubernetes Platform — the operator-helm module for declarative Helm chart management." +description: "Deckhouse Platform — the operator-helm module for declarative Helm chart management." weight: 10 --- -The `operator-helm` module allows you to declaratively manage Helm chart deployments in the cluster. It automates chart installation using custom resources and covers two scopes: a cluster-scoped addon family for cluster administrators and DevOps engineers, and a namespaced application family that lets a namespace owner install charts into their own namespace without cluster-wide privileges. +The `operator-helm` module deploys Helm charts declaratively and targets two audiences: platform administrators and namespace administrators. It divides charts into addons and applications according to the objects they create. -The module controller monitors the state of HelmClusterAddon and HelmApplication resources and automatically reconciles Helm releases in the cluster with the specified parameters. +**Addons** ([`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon)) may contain CRDs and other cluster-scoped objects, so a platform administrator deploys them. Such a Helm chart can affect the state of the cluster, so managing it stays at the cluster level. -## Main Features +**Applications** ([`HelmApplication`](/modules/operator-helm/cr.html#helmapplication)) consist solely of objects that belong to a single namespace. A namespace administrator deploys them. -- Deploying Helm charts from classic HTTP/HTTPS repositories and OCI registries through a unified declarative API. -- Automatic chart version discovery and tracking via HelmClusterAddonChart, HelmApplicationChart and HelmClusterApplicationChart resources. -- Configurable chart values through HelmClusterAddon and HelmApplication resources. -- Namespace-scoped chart installation through HelmApplication, in addition to cluster-wide installation through HelmClusterAddon. -- Maintenance mode to pause reconciliation on managed releases. -- TLS verification and authentication support for private Helm and OCI repositories. -- Management through CLI (`d8 k`) or the Deckhouse web interface. +## Key features +The module provides the following capabilities: -## Custom Resources +- declarative management of Helm chart deployment; +- installing charts from HTTP(S) and OCI repositories through the same API; +- automatic repository synchronization for browsing and searching the available Helm charts and their versions; +- chart installation by a namespace administrator without granting them cluster-wide rights; +- support for shared application repositories available in every namespace; +- automatic correction of configuration drift; +- maintenance mode that pauses reconciliation so that a release can be modified manually; +- support for private repositories that use a corporate PKI; +- management via `d8 k` or the Deckhouse Platform web interface. -The following custom resources are used to manage Helm charts in the module: +## Custom resources -- **HelmClusterAddonRepository** — a Helm or OCI registry containing Helm charts for deployment in the cluster. -- **HelmClusterAddon** — a declarative description of a specific Helm chart release. The resource contains the target chart version, the namespace name for deployment, and custom values. -- **HelmApplicationRepository** — a Helm or OCI registry containing Helm charts that can be referenced by HelmApplication resources from the same namespace. -- **HelmClusterApplicationRepository** — a Helm or OCI registry containing Helm charts that can be referenced by HelmApplication resources from any namespace. -- **HelmApplication** — a declarative description of a Helm chart installation inside a single namespace. The release is always deployed into the namespace of the resource itself; the resource contains the target chart version, a reference to either a same-namespace HelmApplicationRepository or a cluster-wide HelmClusterApplicationRepository, and custom values. +The module's resources fall into two groups by scope. Cluster-scoped resources are managed by a platform administrator, and the resources of a given namespace by a namespace administrator. -Each repository also publishes a catalog of the charts it offers — HelmClusterAddonChart, HelmApplicationChart and HelmClusterApplicationChart. The controller creates and updates them during repository synchronization; they are read-only and are not edited by hand. +```mermaid +flowchart TB + classDef actor fill:#ffffff,stroke:#000000,color:#000000,stroke-width:3px; + classDef cluster fill:#e0e7ff,stroke:#1a237e,color:#000000,stroke-width:2px; + classDef ns fill:#f0fdfa,stroke:#004d40,color:#000000,stroke-width:2px; -## Limitations + ADM(["fa:fa-user
Platform
administrator"]):::actor + USR(["fa:fa-user
Namespace
administrator"]):::actor + + HCA["HelmClusterAddon"]:::cluster + HCAR["HelmClusterAddonRepository"]:::cluster + HCApR["HelmClusterApplicationRepository"]:::cluster + + HA["HelmApplication"]:::ns + HAR["HelmApplicationRepository"]:::ns + + HCAC["HelmClusterAddonChart"]:::cluster + HCApC["HelmClusterApplicationChart"]:::cluster + HAC["HelmApplicationChart"]:::ns + + ADM -->|Manages| HCA + ADM -->|Manages| HCAR + ADM -->|Manages| HCApR + HCA -->|Uses| HCAC + HCAR -->|Maintains| HCAC + + USR -->|Manages| HA + USR -->|Manages| HAR + HA -->|Uses| HAC + HA -->|Uses| HCApC + HAR -->|Maintains| HAC + + HCApR -->|Maintains| HCApC +``` -- The addon family (HelmClusterAddon, HelmClusterAddonChart, HelmClusterAddonRepository) is entirely cluster-scoped, so managing it requires the `ClusterAdmin` role. -- The application family is namespaced: a namespace owner can create and manage HelmApplication and HelmApplicationRepository in their own namespace without cluster-wide rights, with the `Admin` role. HelmClusterApplicationRepository is cluster-scoped, so creating one requires the `ClusterAdmin` role, but any HelmApplication may reference an existing one from its own namespace. -- Creating a HelmApplication is effectively equivalent to having administrator rights inside its namespace: the controller creates a Role there with unrestricted rights over the namespace (`apiGroups: ["*"]`, `resources: ["*"]`, `verbs: ["*"]`) and binds it to the application's ServiceAccount. Both objects are owned by the module and reconciled: the controller watches them and restores its own rules, subjects and labels, so narrowing or deleting either does not outlast the application that needs it. Ownership is decided by the `helm.deckhouse.io/managed-by: operator-helm` label: an object occupying one of these names without that label — pre-created by someone else, or stripped of the label afterwards — is never adopted, patched or deleted, and the application reports `Stalled` with the reason `ForeignAccessObject` and installs nothing. Restoring the label resumes the application on its own; removing an object that never carried the label does not, because nothing watches it, so ask for a reconciliation with the `reconcile.helm.deckhouse.io/force` annotation afterwards. Because the granted rights come from the module rather than from the creator's own rights, granting someone only the right to create a HelmApplication — without other rights in the namespace — hands them the same namespace-admin-level access through the installed chart. -- A HelmApplication cannot be created in a system namespace (`kube-system`, `kube-public`, `kube-node-lease`, or any namespace whose name starts with `d8-`, including the module's own `d8-operator-helm`); the admission webhook rejects it. -- `HelmApplicationRepository` and `HelmClusterApplicationRepository` store their registry credentials in plaintext (`spec.auth.username` and `spec.auth.password`; there is no `secretRef` alternative), so any right to read a repository resource is a right to read its password. That is one reason repositories are reachable no lower than `Admin`. -- Two Deckhouse roles reach this module, and the levels accumulate upwards. `Admin` may do anything with HelmApplication and HelmApplicationRepository, and may read both catalogs an application can pick a chart from: HelmApplicationChart and HelmClusterApplicationChart. `ClusterAdmin` covers the cluster-scoped kinds: full rights over HelmClusterAddon, HelmClusterAddonRepository and HelmClusterApplicationRepository, and a read of HelmClusterAddonChart. Note what the first of these means: installing an application is equivalent to namespace-admin rights, as explained above, so `Admin` is the lowest level that reaches this module at all. No level may write a chart catalog of any kind — the controller is its only author. -- A HelmClusterAddon resource referencing a specific HelmClusterAddonChart can only be created as a single instance in the cluster. This is because Helm charts can contain custom resource definitions (CRDs), and installing them multiple times at the cluster level is not allowed. +Blue fill marks cluster-scoped resources; turquoise marks the resources inside a namespace. The module maintains the chart catalogs itself; they are not edited by hand. + +A platform administrator works with the cluster-scoped resources: + +- [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) — a Helm or OCI repository with charts to be installed at the cluster level; +- [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) — a release description: the target chart version, the namespace to deploy into and, where required, extended installation parameters; +- [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — a repository whose charts are available to [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) resources from any namespace. + +A namespace administrator works with the resources of their own namespace: + +- [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) — a repository whose charts are available to [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) resources of the same namespace; +- [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) — a release description in the administrator's own namespace: the target chart version, a reference to a [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) or a [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) and, where required, extended installation parameters. + +Configuration examples for the resources described above are given in the [administrator guide](admin_guide.html) and the [user guide](user_guide.html). + +## Limitations -See [usage examples](example.html) for practical scenarios. +- A [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) resource referring to a given [`HelmClusterAddonChart`](/modules/operator-helm/cr.html#helmclusteraddonchart) can only be created as a single instance. Helm charts used in an addon may contain custom resource definitions (CRDs), and installing them again at the cluster level can disrupt running services; +- Creating a [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) requires permissions no lower than `Admin`, because applications are deployed using a `ServiceAccount` that holds equivalent privileges. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md new file mode 100644 index 0000000..7c7d360 --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,520 @@ +--- +title: "User guide" +description: "Deckhouse Platform — installing Helm charts in your own namespace with the operator-helm module." +weight: 50 +--- + +This guide describes how to work with the resources of the module within a namespace: chart repositories, their catalogs and applications. Working with these custom resources requires permissions no lower than [`Admin`](/modules/user-authz/#current-role-based-model) in your namespace. + +## Adding an application repository + +A repository is the entry point for every other resource: until one is added, there is no chart to pick. + +Create a [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) resource in your namespace: + +{{< tabs name="create-application-repository" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +Two schemes can be used in a repository URL: `http(s)://` (a Helm repository that publishes an `index.yaml` file listing the available Helm charts) and `oci://` (a container registry that supports storing Helm charts). +{{< /alert >}} + +The module synchronizes the repository and creates one [`HelmApplicationChart`](/modules/operator-helm/cr.html#helmapplicationchart) object per chart found. To view the charts of a repository: + +{{< tabs name="list-application-charts" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k -n test get helmapplicationcharts -l repository=podinfo +``` + +Example output: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo +``` + +The name of a catalog object is composed of the repository name, the chart name and a hash, so it is more convenient to select a chart by the `repository` and `chart` labels than by name. + +The available chart versions are listed in its status. To print them: + +```shell +d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplicationChart +metadata: + labels: + chart: podinfo + heritage: deckhouse + repository: podinfo + name: podinfo-chart-podinfo-dfbe83e63b0b + namespace: test +status: + versions: + - version: 6.11.0 + - version: 6.10.2 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Charts". + +{{% /tab %}} +{{< /tabs >}} + +### Checking the repository state + +The state of a repository is reflected by the conditions in its status. To assess the state of a repository: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k -n test get helmapplicationrepository podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplicationRepository +metadata: + creationTimestamp: "2026-09-22T13:41:25Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 1 + name: podinfo + namespace: test + resourceVersion: "48844673" + uid: f081a6d7-610a-4996-a10c-3d663928f027 +spec: + url: https://stefanprodan.github.io/podinfo +status: + chartCount: 1 + conditions: + - lastTransitionTime: "2026-09-22T13:41:26Z" + message: "" + observedGeneration: 1 + reason: Success + status: "True" + type: Ready + - lastTransitionTime: "2026-09-22T13:41:25Z" + message: "" + observedGeneration: 1 + reason: Success + status: "True" + type: Synced + lastSuccessfulSyncTime: "2026-09-22T13:41:25Z" + nextSyncTime: "2026-09-22T13:46:10Z" + observedGeneration: 1 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Repositories". +1. Select the repository you need and hover the mouse over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible repository states" >}} + +| Condition | Value | Reason | What it means | +| --- | --- | --- | --- | +| `Ready` | `True` | `Success` | The repository is reachable and the chart catalog is built. You can select a chart for an application. | +| `Ready` | `Unknown` | `AwaitingInitialSync` | The repository has just been created and the first read has not finished yet. Wait for the synchronization to complete. | +| `Ready` | `False` | `AuxiliaryResourcesFailed` | The auxiliary secret holding the repository credentials could not be created. Check your permissions in the namespace. | +| `Synced` | `True` | `Success` | The chart catalog matches the contents of the repository. | +| `Synced` | `False` | `SyncFailed` | The repository could not be read. Check the URL and that the registry is reachable from the cluster. | +| `Synced` | `False` | `CatalogUpdateFailed` | The repository was read, but the chart catalog could not be written to the cluster. The attempt will be repeated automatically. | +| `Synced` | `False` | `PartialSync` | Some versions could not be parsed during the first read. The rest are already available, and the skipped ones will be picked up at the next synchronization. | +| `Reconciling` | `True` | `Synchronization` | A scheduled synchronization with the repository is in progress. | +| `Reconciling` | `True` | `ForceReconcile` | A manually requested synchronization is in progress. | +| `Reconciling` | `True` | `ProgressingWithRetry` | The previous attempt failed and a retry is scheduled. | +| `Stalled` | `True` | `UnsupportedRepositoryType` | The scheme in the URL is not supported. Only `http(s)://` and `oci://` are allowed. | +| `Stalled` | `True` | `InvalidRepositoryURL` | The URL could not be parsed. Check the repository address. | +| `Stalled` | `True` | `AuthenticationFailed` | The registry rejected the credentials. Check the username and the password in the repository spec. | +| `Stalled` | `True` | `SourceNotFound` | No repository was found at the given URL. | +| `Stalled` | `True` | `SourceRejectedRequest` | The registry rejected the request. Contact the registry owner. | +| `Stalled` | `True` | `RetriesExceeded` | The read attempts are exhausted. Fix the cause and request a forced reconciliation. | + +{{< alert level="info" >}} + +The `Reconciling` and `Stalled` conditions are present only while they apply: the first until the work is finished, the second until the cause of the failure is fixed. + +{{< /alert >}} + +{{< /details >}} + +## Deploying an application + +Create a [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) resource in the same namespace, specifying the repository and the chart name and version: + +{{< tabs name="create-application" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} +Applications can be deployed not only from the Helm charts of a repository local to the namespace, but also from a shared repository set up by a platform administrator. Shared repositories are described with the [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) resource, and their catalog with [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart) resources. + +Every user in a namespace has read access to [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). + +To use a chart from a shared repository, specify the [`spec.chart.clusterRepository`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-spec-chart-clusterrepository) field instead of [`spec.chart.repository`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-spec-chart-repository) when describing the `HelmApplication` resource. + +{{< details summary="Viewing the available shared application Helm charts" >}} + +To view the shared Helm charts, run the following command: + +```shell +d8 k get helmclusterapplicationcharts --show-labels +``` + +Example output: + +```text +NAME AGE LABELS +podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repository=podinfo-shared +``` + +{{< /details >}} + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Applications". +1. Click the "Create" button. +1. In the form that opens, enter an arbitrary resource name in the "Name" field. +1. In the "Repository" field, select the repository holding the application Helm charts, or a shared application repository created by an administrator. +1. In the "Chart" field, select the Helm chart. +1. In the "Version" field, select the Helm chart version. +1. Click the "Create" button. + +{{< alert level="info" >}} +Some repositories in the list may carry the "(cluster)" suffix. This means that the repository is shared ([`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository)) and was created by a platform administrator. +{{< /alert >}} + +{{< alert level="info" >}} +You can adjust the Helm chart parameters if needed. To see the parameters used by default, click the "Show default values" link in the application creation form. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +A [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) is deployed with full privileges within the namespace. + +{{< details summary="The rules of the role used when deploying an application" >}} + +```yaml +apiVersion: rbac.authorization.k8s.io/v1 +kind: Role +metadata: + labels: + helm.deckhouse.io/managed-by: operator-helm + name: operator-helm-application + namespace: test +rules: +- apiGroups: + - '*' + resources: + - '*' + verbs: + - '*' +``` + +{{< /details >}} + +{{< /alert >}} + +### Checking the application state + +The state of an application is reflected by the conditions in its status. To assess the state of an application: + +{{< tabs name="check-application-conditions" >}} +{{% tab name="Command line" %}} + +Run the following command: + +```shell +d8 k -n test get helmapplication podinfo -o yaml +``` + +Example output: + +```yaml +apiVersion: helm.deckhouse.io/v1alpha1 +kind: HelmApplication +metadata: + creationTimestamp: "2026-09-18T08:19:55Z" + finalizers: + - helm.deckhouse.io/cleanup + generation: 1 + name: podinfo + namespace: test + resourceVersion: "48926122" + uid: f4059036-a6c9-401a-be8d-67d8f2410c6f +spec: + chart: + repository: podinfo + name: podinfo + version: 6.15.0 +status: + conditions: + - lastTransitionTime: "2026-09-22T15:28:11Z" + message: Helm upgrade succeeded for release test/hap-podinfo-3fb7b289386f.v2 + with chart podinfo@6.15.0 + observedGeneration: 1 + reason: UpgradeSucceeded + status: "True" + type: Ready + - lastTransitionTime: "2026-09-18T08:20:03Z" + message: Helm install succeeded for release test/hap-podinfo-3fb7b289386f.v1 + with chart podinfo@6.15.0 + observedGeneration: 1 + reason: InstallSucceeded + status: "True" + type: Installed + lastAppliedChart: + repository: podinfo + name: podinfo + version: 6.15.0 + observedGeneration: 1 +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Applications". +1. Select the application you need and hover the mouse over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible application states" >}} + +| Condition | Value | Reason | What it means | +| --- | --- | --- | --- | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | The release is deployed and matches the spec. The reason here is supplied by Helm. | +| `Ready` | `Unknown` | `Reconciling` | Work is in progress: the chart is being downloaded or the release is being rolled out. | +| `Ready` | `False` | `ReleaseFailed` | Helm could not install or upgrade the release. The error text is given in the `message` field. | +| `Ready` | `False` | `TestFailed` | The chart tests failed. | +| `Ready` | `False` | `Remediated` | The release was rolled back to its previous state. | +| `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | The chart could not be downloaded from the repository or stored in the cluster. | +| `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | The chart could not be retrieved from the OCI registry or verified. | +| `Ready` | `False` | `ChartVersionRemoved` | The specified chart version is no longer published by the repository. Select another version. | +| `Ready` | `False` | `AccessSetupFailed` | The `ServiceAccount`, `Role` or `RoleBinding` used to install the chart could not be prepared. The attempt will be repeated automatically. | +| `Ready` | `False` | `ForeignAccessObject` | The name of the `Role` or the `RoleBinding` that the module creates for the application is taken. The `Role` is always named `operator-helm-application`, and the name of the `RoleBinding` matches the name of the application's `ServiceAccount` and is given in the `message` field. An object with such a name was not created by the module, so the module does not touch it. Delete the foreign object and request a forced reconciliation. | +| `Ready` | `False` | `UnsupportedRepositoryType` | The repository the application refers to has an unreadable URL. Contact the repository owner. | +| `Ready` | `False` | `Failed` | Other errors. The cause is given in the `message` field. | +| `Installed` | same as `Ready` | same as for `Ready` | The outcome of the first installation of the release. | +| `UpdateInstalled` | same as `Ready` | same as for `Ready` | The outcome of a release upgrade. Appears when the chart version changes. | +| `ConfigurationApplied` | same as `Ready` | same as for `Ready` | The outcome of applying the chart values. Appears when the values change. | +| `Managed` | `True` | `MaintenanceModeInactive` | The application is managed by the module. | +| `Managed` | `False` | `MaintenanceModeActive` | Maintenance mode is on, reconciliation is paused. | +| `Reconciling` | `True` | `Reconciling` | The release is being rolled out. | +| `Reconciling` | `True` | `ProgressingWithRetry` | A failure occurred and a retry is scheduled. | +| `Reconciling` | `True` | `ForceReconcile` | A manually requested reconciliation is in progress. | +| `Stalled` | `True` | the reason for the failure that caused it | Retrying will not help: you have to fix the application spec, wait for the repository to change, or remove the object standing in the way. Attempts stop until the cause is resolved. | + +{{< alert level="info" >}} + +The `Reconciling` and `Stalled` conditions are present only while they apply: the first until the work is finished, the second until the cause of the failure is fixed. `Installed`, `UpdateInstalled` and `ConfigurationApplied` appear as the application passes the corresponding stages and carry the same verdict as `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Forcing reconciliation + +While working with applications and repositories, you may need to force a reconciliation. In normal operation, reconciliation starts automatically whenever the resources are changed or the state of their dependencies changes. + +For applications, a forced reconciliation can be useful if a terminal error occurred while deploying the application or changing its settings. Without manual intervention, the module's controllers make no further reconciliation attempts. + +For repositories, a forced reconciliation lets you synchronize the repository without waiting for the next scheduled run. + +{{< tabs name="force-reconcile-application" >}} +{{% tab name="Command line" %}} + +To force the reconciliation of a [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication), run the following command: + +```shell +d8 k -n test annotate helmapplication podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +To force the reconciliation of a [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository), run the following command: + +```shell +d8 k -n test annotate helmapplicationrepository podinfo reconcile.helm.deckhouse.io/force="$(date -u +%Y-%m-%dT%H:%M:%SZ)" --overwrite +``` + +{{< alert level="info" >}} +The module only checks that the annotation is present; it does not read its contents. The timestamp in the examples is there only to make a repeated request differ from the previous one. +{{< /alert >}} + +{{< alert level="info" >}} +The completion of a forced reconciliation can be tracked through the [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-status-lastforcereconciletime) field of the resource. For example: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{< /alert >}} + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +To force the reconciliation of an application: + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Applications". +1. Select the application you need and click the "Force reconciliation" icon. + +The outcome of the forced reconciliation is shown in the "Status" column. + +To force the reconciliation of an application repository: + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Repositories". +1. Select the repository you need and click the "Force reconciliation" icon. + +The outcome of the forced reconciliation is shown in the "Status" column. + +{{< alert level="info" >}} + +Reconciliation can be very fast, so the web interface may not have time to show the status change. To make sure that the forced synchronization has been carried out, check the value of the `.status.lastForceReconcileTime` field of the resource. To do this, click the name of the resource you are interested in and switch to the "YAML" tab in the form that opens. + +{{< /alert >}} + +{{% /tab %}} + +{{< /tabs >}} + +## Maintenance mode + +Maintenance mode pauses the reconciliation of an application, which lets you modify the release manually by adjusting the parameters of the previously deployed resources (changing the number of replicas, changing parameters and so on). + +{{< tabs name="enable-application-maintenance" >}} +{{% tab name="Command line" %}} + +To turn maintenance mode on, run the following command: + +```shell +d8 k -n test patch helmapplication podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' +``` + +To check that maintenance mode is on, run the following command: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Example of successful output: + +```text +MaintenanceModeActive +``` + +To turn maintenance mode off, run the following command: + +```shell +d8 k -n test patch helmapplication podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' +``` + +To check that maintenance mode is off, run the following command: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.type=="Managed")].reason}' +``` + +Example of successful output: + +```text +MaintenanceModeInactive +``` + +{{% /tab %}} + +{{% tab name="Web interface" %}} + +To manage the maintenance mode of an application: + +1. Go to the "Projects" tab and select the project you need. +1. Go to "Helm operator" → "Applications". +1. Select the application you need and click its name. +1. The "Maintenance mode" option is available in the form that opens. + +An application that is in maintenance mode gets the "Maintenance" status. + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +An application in maintenance mode does not support forced reconciliation and cannot be deleted. +{{< /alert >}} From aff8221145de0ff7a3c3d2032f18655cecdb3125 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:00 +0300 Subject: [PATCH 3/6] docs: link every CRD mention on the overview page to its reference Four mentions inside the resource lists were left as bare code spans while the first mention of each kind was already a link. Signed-off-by: Ilya Drey --- docs/README.ru.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/README.ru.md b/docs/README.ru.md index 9d8fe10..14abcfb 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -69,12 +69,12 @@ flowchart TB - [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) — репозиторий Helm или OCI с чартами для установки на уровне кластера; - [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) — описание релиза: целевая версия чарта, неймспейс развёртывания и расширенные параметры установки (при необходимости); -- [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — репозиторий, чарты которого доступны ресурсам `HelmApplication` из любого неймспейса. +- [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — репозиторий, чарты которого доступны ресурсам [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) из любого неймспейса. Администратор неймспейса работает с ресурсами своего неймспейса: -- [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) — репозиторий, чарты которого доступны ресурсам `HelmApplication` того же неймспейса; -- [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) — описание релиза в собственном неймспейсе: целевая версия чарта, ссылка на `HelmApplicationRepository` или `HelmClusterApplicationRepository` и расширенные параметры установки (при необходимости). +- [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) — репозиторий, чарты которого доступны ресурсам [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) того же неймспейса; +- [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) — описание релиза в собственном неймспейсе: целевая версия чарта, ссылка на [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) или [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) и расширенные параметры установки (при необходимости). Примеры настройки вышеописанных ресурсов приведены в [руководстве администратора](admin_guide.html) и [руководстве пользователя](user_guide.html). From 2e5063443b6138679f80e630db43013745be47f6 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:08 +0300 Subject: [PATCH 4/6] docs: call the product Deckhouse Platform Deckhouse Kubernetes Platform is not the name the product goes by. Signed-off-by: Ilya Drey --- docs/ADMIN_GUIDE.ru.md | 2 +- docs/CONFIGURATION.md | 2 +- docs/CONFIGURATION.ru.md | 2 +- docs/CR.md | 2 +- docs/CR.ru.md | 2 +- docs/README.ru.md | 4 ++-- docs/USER_GUIDE.ru.md | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/ADMIN_GUIDE.ru.md b/docs/ADMIN_GUIDE.ru.md index 27d3fd2..2ceb5ff 100644 --- a/docs/ADMIN_GUIDE.ru.md +++ b/docs/ADMIN_GUIDE.ru.md @@ -1,6 +1,6 @@ --- title: "Руководство администратора" -description: "Deckhouse Kubernetes Platform — управление кластерными ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." +description: "Deckhouse Platform — управление кластерными ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." weight: 40 --- diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 80620c1..0face1e 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,5 +1,5 @@ --- title: "Configuration" -description: "Deckhouse Kubernetes Platform — configuration parameters of the operator-helm module." +description: "Deckhouse Platform — configuration parameters of the operator-helm module." weight: 20 --- diff --git a/docs/CONFIGURATION.ru.md b/docs/CONFIGURATION.ru.md index 7ceffe5..e63e268 100644 --- a/docs/CONFIGURATION.ru.md +++ b/docs/CONFIGURATION.ru.md @@ -1,5 +1,5 @@ --- title: "Настройки" -description: "Deckhouse Kubernetes Platform, параметры конфигурации модуля operator-helm." +description: "Deckhouse Platform, параметры конфигурации модуля operator-helm." weight: 20 --- diff --git a/docs/CR.md b/docs/CR.md index ea293af..7ca2812 100644 --- a/docs/CR.md +++ b/docs/CR.md @@ -1,5 +1,5 @@ --- title: "Custom Resources" -description: "Deckhouse Kubernetes Platform — Custom resources of the operator-helm module." +description: "Deckhouse Platform — Custom resources of the operator-helm module." weight: 60 --- diff --git a/docs/CR.ru.md b/docs/CR.ru.md index e22d7ed..9b7e457 100644 --- a/docs/CR.ru.md +++ b/docs/CR.ru.md @@ -1,5 +1,5 @@ --- title: "Кастомные ресурсы" -description: "Deckhouse Kubernetes Platform, кастомные ресурсы (custom resources) модуля operator-helm." +description: "Deckhouse Platform, кастомные ресурсы (custom resources) модуля operator-helm." weight: 60 --- diff --git a/docs/README.ru.md b/docs/README.ru.md index 14abcfb..2e92044 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -1,6 +1,6 @@ --- title: "Модуль operator-helm" -description: "Deckhouse Kubernetes Platform — модуль operator-helm для декларативного управления Helm-чартами." +description: "Deckhouse Platform — модуль operator-helm для декларативного управления Helm-чартами." weight: 10 --- @@ -22,7 +22,7 @@ weight: 10 - автоматическое устранение дрейфа конфигурации; - режим обслуживания, который приостанавливает реконсиляцию для ручного вмешательства в релиз; - поддержка приватных репозиториев с использованием корпоративного PKI; -- управление через `d8 k` или веб-интерфейс Deckhouse Kubernetes Platform. +- управление через `d8 k` или веб-интерфейс Deckhouse Platform. ## Кастомные ресурсы diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index a59874e..d9506b6 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -1,6 +1,6 @@ --- title: "Руководство пользователя" -description: "Deckhouse Kubernetes Platform — установка Helm-чартов в своём неймспейсе с помощью модуля operator-helm." +description: "Deckhouse Platform — установка Helm-чартов в своём неймспейсе с помощью модуля operator-helm." weight: 50 --- From da4aa2a2bd7961a799d7c1b37db8dcc72e5d28fb Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:28 +0300 Subject: [PATCH 5/6] docs: tidy the release notes Fix four typos and the Russian entries of v0.1.0, which were the only ones left in the imperative; the wording lives in CHANGELOG, so it is fixed there too. Capitalizing the bullets is applied to the generated pages alone: chlog.py emits the changelog strings as they are, so the change does not survive the next run until the generator itself capitalizes them. Signed-off-by: Ilya Drey --- CHANGELOG/v0.0.2.yaml | 2 +- CHANGELOG/v0.0.3.yaml | 2 +- CHANGELOG/v0.0.6.yaml | 2 +- CHANGELOG/v0.1.0.ru.yaml | 6 +++--- CHANGELOG/v0.1.0.yaml | 2 +- docs/RELEASE_NOTES.md | 38 +++++++++++++++++++------------------- docs/RELEASE_NOTES.ru.md | 38 +++++++++++++++++++------------------- 7 files changed, 45 insertions(+), 45 deletions(-) diff --git a/CHANGELOG/v0.0.2.yaml b/CHANGELOG/v0.0.2.yaml index 7b55dca..176ab19 100644 --- a/CHANGELOG/v0.0.2.yaml +++ b/CHANGELOG/v0.0.2.yaml @@ -1,5 +1,5 @@ features: - - apply deckhouse runtime time review recommendations + - apply deckhouse runtime review recommendations fixes: [] security: [] chore: [] diff --git a/CHANGELOG/v0.0.3.yaml b/CHANGELOG/v0.0.3.yaml index 959e82b..3c1e2eb 100644 --- a/CHANGELOG/v0.0.3.yaml +++ b/CHANGELOG/v0.0.3.yaml @@ -1,5 +1,5 @@ features: - - the first public alpha release with HelmClusterAddon, HelmClusterAddonChart, and HelmClusterAddonRepository CRDs supoort + - the first public alpha release with HelmClusterAddon, HelmClusterAddonChart, and HelmClusterAddonRepository CRDs support fixes: [] security: [] chore: [] diff --git a/CHANGELOG/v0.0.6.yaml b/CHANGELOG/v0.0.6.yaml index dbed862..e8d5f3d 100644 --- a/CHANGELOG/v0.0.6.yaml +++ b/CHANGELOG/v0.0.6.yaml @@ -1,5 +1,5 @@ features: - - do not mark possible status conditions as intitialized on reconcile + - do not mark possible status conditions as initialized on reconcile fixes: [] security: [] chore: diff --git a/CHANGELOG/v0.1.0.ru.yaml b/CHANGELOG/v0.1.0.ru.yaml index c8cd524..4fa6c6c 100644 --- a/CHANGELOG/v0.1.0.ru.yaml +++ b/CHANGELOG/v0.1.0.ru.yaml @@ -1,7 +1,7 @@ features: - - "внедрить ограниченный PSS" + - "внедрён ограниченный PSS" fixes: - - "запретить использование системных пространств имен" + - "запрещено использование системных пространств имен" security: [] chore: - - "добавить генерацию журнала изменений и заметок о выпуске" + - "добавлена генерация журнала изменений и заметок о выпуске" diff --git a/CHANGELOG/v0.1.0.yaml b/CHANGELOG/v0.1.0.yaml index 56629c4..99ed2c0 100644 --- a/CHANGELOG/v0.1.0.yaml +++ b/CHANGELOG/v0.1.0.yaml @@ -1,5 +1,5 @@ features: - - "enforce restricted pss" + - "enforce restricted PSS" fixes: - "forbid to use system namespaces" security: [] diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index da74f8e..5e8122c 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -13,18 +13,18 @@ description: "Release notes for Deckhouse operator-helm." ### New Features -* reworked HelmClusterAddonRepository status semantics -* support legacy OCI chart media type with incremental indexing -* surface force reconcile progress and completion in status -* report scheduled repository synchronization in status +* Reworked HelmClusterAddonRepository status semantics +* Support legacy OCI chart media type with incremental indexing +* Surface force reconcile progress and completion in status +* Report scheduled repository synchronization in status ### Bug Fixes -* propagate force reconcile to internal sources +* Propagate force reconcile to internal sources ### Chore -* added dev registry cleanup job +* Added dev registry cleanup job ## v0.1.1 @@ -40,68 +40,68 @@ description: "Release notes for Deckhouse operator-helm." ### New Features -* enforced restricted pss +* Enforced restricted PSS ### Bug Fixes -* forbidden to use system namespaces +* Forbidden to use system namespaces ### Chore -* added changelog and release notes generation +* Added changelog and release notes generation ## v0.0.8 ### Bug Fixes -* resolved race on module disable which could lead to application disruption +* Resolved race on module disable which could lead to application disruption ### Chore -* watch shadow custom resources in module namespace only +* Watch shadow custom resources in module namespace only ## v0.0.7 ### New Features -* added ability to review chart default values in console during addon creation +* Added ability to review chart default values in console during addon creation ## v0.0.6 ### New Features -* do not mark possible status conditions as intitialized on reconcile +* Do not mark possible status conditions as initialized on reconcile ### Chore -* added weight annotations to validation webhook +* Added weight annotations to validation webhook ## v0.0.5 ### Chore -* minor documentation updates +* Minor documentation updates ## v0.0.4 ### Chore -* updated main documentation page alerts formatting +* Updated main documentation page alerts formatting ## v0.0.3 ### New Features -* the first public alpha release with HelmClusterAddon, HelmClusterAddonChart, and HelmClusterAddonRepository CRDs supoort +* The first public alpha release with HelmClusterAddon, HelmClusterAddonChart, and HelmClusterAddonRepository CRDs support ## v0.0.2 ### New Features -* applied deckhouse runtime time review recommendations +* Applied deckhouse runtime review recommendations ## v0.0.1 ### New Features -* initial release with basic capabilities +* Initial release with basic capabilities diff --git a/docs/RELEASE_NOTES.ru.md b/docs/RELEASE_NOTES.ru.md index d7ce3d2..4a97672 100644 --- a/docs/RELEASE_NOTES.ru.md +++ b/docs/RELEASE_NOTES.ru.md @@ -13,18 +13,18 @@ description: "Релизы Deckhouse operator-helm." ### Новые возможности -* переработана семантика статуса HelmClusterAddonRepository -* добавлена поддержка устаревшего типа медиаданных OCI chart с инкрементной индексацией -* добавлен прогресс и завершение принудительной синхронизации в статусе -* добавлено отображение запланированной синхронизации репозитория в статусе +* Переработана семантика статуса HelmClusterAddonRepository +* Добавлена поддержка устаревшего типа медиаданных OCI chart с инкрементной индексацией +* Добавлен прогресс и завершение принудительной синхронизации в статусе +* Добавлено отображение запланированной синхронизации репозитория в статусе ### Исправления -* исправлена передача принудительной синхронизации во внутренние источники +* Исправлена передача принудительной синхронизации во внутренние источники ### Прочее -* добавлена задача очистки dev registry +* Добавлена задача очистки dev registry ## v0.1.1 @@ -40,68 +40,68 @@ description: "Релизы Deckhouse operator-helm." ### Новые возможности -* внедрить ограниченный PSS +* Внедрён ограниченный PSS ### Исправления -* запретить использование системных пространств имен +* Запрещено использование системных пространств имен ### Прочее -* добавить генерацию журнала изменений и заметок о выпуске +* Добавлена генерация журнала изменений и заметок о выпуске ## v0.0.8 ### Исправления -* устранена гонка при отключении модуля, которая могла привести к сбою приложения +* Устранена гонка при отключении модуля, которая могла привести к сбою приложения ### Прочее -* теневые пользовательские ресурсы теперь отслеживаются только в пространстве имен модуля +* Теневые пользовательские ресурсы теперь отслеживаются только в пространстве имен модуля ## v0.0.7 ### Новые возможности -* добавлена возможность просматривать значения чарта по умолчанию в консоли при создании дополнения +* Добавлена возможность просматривать значения чарта по умолчанию в консоли при создании дополнения ## v0.0.6 ### Новые возможности -* возможные условия статуса больше не отмечаются как инициализированные при согласовании +* Возможные условия статуса больше не отмечаются как инициализированные при согласовании ### Прочее -* добавлены аннотации веса в веб-хук валидации +* Добавлены аннотации веса в веб-хук валидации ## v0.0.5 ### Прочее -* внесены незначительные обновления документации +* Внесены незначительные обновления документации ## v0.0.4 ### Прочее -* обновлено форматирование уведомлений на главной странице документации +* Обновлено форматирование уведомлений на главной странице документации ## v0.0.3 ### Новые возможности -* выпущен первый публичный альфа-релиз с поддержкой CRD HelmClusterAddon, HelmClusterAddonChart и HelmClusterAddonRepository +* Выпущен первый публичный альфа-релиз с поддержкой CRD HelmClusterAddon, HelmClusterAddonChart и HelmClusterAddonRepository ## v0.0.2 ### Новые возможности -* применены рекомендации по результатам ревью deckhouse runtime +* Применены рекомендации по результатам ревью deckhouse runtime ## v0.0.1 ### Новые возможности -* выпущена первоначальная версия с базовыми возможностями +* Выпущена первоначальная версия с базовыми возможностями From cdcea16ff7667a85b851d311e3d93830387b44c0 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:31:35 +0300 Subject: [PATCH 6/6] docs: rename the RBAC condition reasons The reasons a release reports for its identity are now RBACSetupFailed and ForeignRBACObject. The code change is on feat/ns-scoped-applications; the guides these rows live in exist only on this branch, so the two halves cannot share a commit. Signed-off-by: Ilya Drey --- docs/USER_GUIDE.md | 4 ++-- docs/USER_GUIDE.ru.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index 7c7d360..d82e7d6 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -368,8 +368,8 @@ status: | `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | The chart could not be downloaded from the repository or stored in the cluster. | | `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | The chart could not be retrieved from the OCI registry or verified. | | `Ready` | `False` | `ChartVersionRemoved` | The specified chart version is no longer published by the repository. Select another version. | -| `Ready` | `False` | `AccessSetupFailed` | The `ServiceAccount`, `Role` or `RoleBinding` used to install the chart could not be prepared. The attempt will be repeated automatically. | -| `Ready` | `False` | `ForeignAccessObject` | The name of the `Role` or the `RoleBinding` that the module creates for the application is taken. The `Role` is always named `operator-helm-application`, and the name of the `RoleBinding` matches the name of the application's `ServiceAccount` and is given in the `message` field. An object with such a name was not created by the module, so the module does not touch it. Delete the foreign object and request a forced reconciliation. | +| `Ready` | `False` | `RBACSetupFailed` | The `ServiceAccount`, `Role` or `RoleBinding` used to install the chart could not be prepared. The attempt will be repeated automatically. | +| `Ready` | `False` | `ForeignRBACObject` | The name of the `Role` or the `RoleBinding` that the module creates for the application is taken. The `Role` is always named `operator-helm-application`, and the name of the `RoleBinding` matches the name of the application's `ServiceAccount` and is given in the `message` field. An object with such a name was not created by the module, so the module does not touch it. Delete the foreign object and request a forced reconciliation. | | `Ready` | `False` | `UnsupportedRepositoryType` | The repository the application refers to has an unreadable URL. Contact the repository owner. | | `Ready` | `False` | `Failed` | Other errors. The cause is given in the `message` field. | | `Installed` | same as `Ready` | same as for `Ready` | The outcome of the first installation of the release. | diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index d9506b6..fa00fb6 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -368,8 +368,8 @@ status: | `Ready` | `False` | `ChartFetchFailed`, `ChartStorageFailed` | Чарт не удалось загрузить из репозитория или сохранить в кластере. | | `Ready` | `False` | `OCIFetchFailed`, `OCIIncludeUnavailable`, `OCIStorageFailed`, `OCIVerificationFailed` | Не удалось получить или проверить чарт из OCI-реестра. | | `Ready` | `False` | `ChartVersionRemoved` | Указанная версия чарта больше не публикуется репозиторием. Выберите другую версию. | -| `Ready` | `False` | `AccessSetupFailed` | Не удалось подготовить `ServiceAccount`, `Role` или `RoleBinding`, от имени которых устанавливается чарт. Попытка повторится автоматически. | -| `Ready` | `False` | `ForeignAccessObject` | Занято имя `Role` или `RoleBinding`, которые модуль создаёт для приложения. `Role` всегда называется `operator-helm-application`, имя `RoleBinding` совпадает с именем `ServiceAccount` приложения и приведено в поле `message`. Объект с таким именем создан не модулем, поэтому модуль его не трогает. Удалите чужой объект и запросите принудительную реконсиляцию. | +| `Ready` | `False` | `RBACSetupFailed` | Не удалось подготовить `ServiceAccount`, `Role` или `RoleBinding`, от имени которых устанавливается чарт. Попытка повторится автоматически. | +| `Ready` | `False` | `ForeignRBACObject` | Занято имя `Role` или `RoleBinding`, которые модуль создаёт для приложения. `Role` всегда называется `operator-helm-application`, имя `RoleBinding` совпадает с именем `ServiceAccount` приложения и приведено в поле `message`. Объект с таким именем создан не модулем, поэтому модуль его не трогает. Удалите чужой объект и запросите принудительную реконсиляцию. | | `Ready` | `False` | `UnsupportedRepositoryType` | У репозитория, на который ссылается приложение, нечитаемый URL. Обратитесь к владельцу репозитория. | | `Ready` | `False` | `Failed` | Прочие ошибки. Причина приведена в поле `message`. | | `Installed` | как у `Ready` | та же, что у `Ready` | Результат первой установки релиза. |