From 2f6e5a6faefb10aa4dff889443c32d7376cd39d1 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Tue, 22 Sep 2026 19:04:53 +0300 Subject: [PATCH 01/10] 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 00000000..27d3fd27 --- /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 e1119167..00000000 --- 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 51168795..00000000 --- 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 2e1cc807..9d8fe102 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 00000000..a59874e1 --- /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 fcde3ecbe937f506cf79712586287c1c02dd48d8 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:08:37 +0300 Subject: [PATCH 02/10] 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 00000000..8f8dcae2 --- /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 1f5bf889..737e52b4 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 00000000..7c7d360d --- /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 66c2a25b05ffed8494b23aebe6c8ca922b590abd Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:00 +0300 Subject: [PATCH 03/10] 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 9d8fe102..14abcfb2 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 4694ebfad19bd39dce9b34be9bf930087af06c3f Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:08 +0300 Subject: [PATCH 04/10] 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 27d3fd27..2ceb5ffc 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 80620c13..0face1ec 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 7ceffe57..e63e2686 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 ea293afd..7ca28121 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 e22d7ed5..9b7e457c 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 14abcfb2..2e92044b 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 a59874e1..d9506b61 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 38b32a8fbd0bb7bbeca59d2136e157a5130ad8d3 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:09:28 +0300 Subject: [PATCH 05/10] 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 7b55dca2..176ab199 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 959e82bd..3c1e2eb0 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 dbed862e..e8d5f3d6 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 c8cd5249..4fa6c6cd 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 56629c4e..99ed2c00 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 da74f8e4..5e8122c3 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 d7ce3d27..4a976722 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 3fa3414d2e910590db2516dd34dcc04f9f5b765d Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 23 Sep 2026 11:31:35 +0300 Subject: [PATCH 06/10] 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 7c7d360d..d82e7d6f 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 d9506b61..fa00fb67 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` | Результат первой установки релиза. | From 63bc7a00943ebb6efab3c0926a8894d1d63bf3ee Mon Sep 17 00:00:00 2001 From: Max Chervov Date: Wed, 30 Sep 2026 13:38:31 +0300 Subject: [PATCH 07/10] Edits Signed-off-by: Max Chervov --- docs/ADMIN_GUIDE.md | 279 ++++++++++++++++++++------------------- docs/ADMIN_GUIDE.ru.md | 256 +++++++++++++++++------------------ docs/CONFIGURATION.md | 2 +- docs/CONFIGURATION.ru.md | 2 +- docs/CR.md | 2 +- docs/CR.ru.md | 2 +- docs/README.md | 55 ++++---- docs/README.ru.md | 45 ++++--- docs/RELEASE_NOTES.md | 44 +++--- docs/RELEASE_NOTES.ru.md | 44 +++--- docs/USER_GUIDE.md | 173 ++++++++++++------------ docs/USER_GUIDE.ru.md | 153 ++++++++++----------- 12 files changed, 538 insertions(+), 519 deletions(-) diff --git a/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md index 8f8dcae2..dc183168 100644 --- a/docs/ADMIN_GUIDE.md +++ b/docs/ADMIN_GUIDE.md @@ -1,19 +1,19 @@ --- title: "Administrator guide" -description: "Deckhouse Platform — managing the cluster-scoped resources of the operator-helm module: repositories, chart catalogs and addons." +description: "Managing the cluster-wide 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). +This guide describes how to work with the `operator-helm` module using cluster-wide resources. Working with these custom resources requires permissions no lower than the [`ClusterAdmin`](/modules/user-authz/#current-role-based-model) role. ## Adding an addon repository -A repository is the entry point for every other resource: until one is added, there is no chart to pick. +A Helm repository is the entry point for every other resource. It contains Helm charts for a following installation in the cluster. -Create a [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) resource: +To add a new Helm addon repository, create a [HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository) resource: {{< tabs name="create-addon-repository" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -30,7 +30,7 @@ EOF {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "System" tab. 1. Go to "Helm operator" → "Addon repositories". @@ -43,13 +43,16 @@ EOF {{< /tabs >}} {{< 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). +Use one of the two schemes in the repository URL: + +- `http(s)://`: Helm repository that publishes an `index.yaml` file listing the available Helm charts. +- `oci://`: 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: +After the HelmClusterAddonRepository resource is created, the module synchronizes the repository and creates a separate [HelmClusterAddonChart](/modules/operator-helm/cr.html#helmclusteraddonchart) object for each chart in the repository. To view the charts in a repository: {{< tabs name="list-addon-charts" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -66,7 +69,7 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo 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: +The available chart versions are listed in its status. To see a list of versions, run the following command: ```shell d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml @@ -74,7 +77,7 @@ d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddonChart metadata: @@ -91,7 +94,7 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "System" tab. 1. Go to "Helm operator" → "Addon charts". @@ -99,61 +102,12 @@ status: {{% /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: +The state of a repository is reflected by the conditions in its status ([`status.conditions`](cr.html#helmclusteraddonrepository-v1alpha1-status-conditions)). To assess the state of a repository: {{< tabs name="check-repository-conditions" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -163,7 +117,7 @@ d8 k get helmclusteraddonrepository podinfo -o yaml Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddonRepository metadata: @@ -198,50 +152,99 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via 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. +1. Select the repository you need and hover 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 | +| Condition | Value | Reason | Description | | --- | --- | --- | --- | -| `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. | +| `Ready` | `True` | `Success` | The repository is reachable and the chart catalog has been 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 repository is reachable from the cluster | +| `Synced` | `False` | `CatalogUpdateFailed` | The repository has been 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 versions are already available, and the skipped ones will be picked up at the next synchronization | +| `Reconciling` | `True` | `Synchronization` | A scheduled reconciliation is in progress | +| `Reconciling` | `True` | `ForceReconcile` | A forced reconciliation is in progress | +| `Reconciling` | `True` | `ProgressingWithRetry` | The previous reconciliation attempt has 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 repository rejected the credentials. Check the username and the password in the repository specification | +| `Stalled` | `True` | `SourceNotFound` | No repository was found at the given URL | +| `Stalled` | `True` | `SourceRejectedRequest` | The repository rejected the request. Contact the repository owner | +| `Stalled` | `True` | `RetriesExceeded` | The number of read attempts has been exceeded. 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. +The `Reconciling` and `Stalled` conditions are present only while they apply. The `Reconciling` condition is present until the work is finished, the `Stalled` condition is present until the cause of the failure is fixed. {{< /alert >}} {{< /details >}} +## Deploying an addon + +To deploy 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="Via 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 "Show default values" in the addon creation form. +{{< /alert >}} + +{{% /tab %}} +{{< /tabs >}} + +{{< alert level="warning" >}} +Only one HelmClusterAddon instance using a given Helm chart from a given repository can be deployed at a time. However, different Helm charts from the same repository can be deployed simultaneously. +{{< /alert >}} + ### Checking the addon state -The state of an addon is reflected by the conditions in its status. To assess the state of an addon: +The state of an addon is reflected by the conditions in its status ([`status.conditions`](cr.html#helmclusteraddon-v1alpha1-status-conditions)). To assess the state of an addon: {{< tabs name="check-addon-conditions" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -251,7 +254,7 @@ d8 k get helmclusteraddon podinfo -o yaml Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddon metadata: @@ -299,43 +302,43 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via 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. +1. Select the addon you need and hover 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 | +| Condition | Value | Reason | Description | | --- | --- | --- | --- | -| `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. | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | The release has been deployed and matches the specification. The reason is provided by Helm | +| `Ready` | `Unknown` | `Reconciling` | 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 failure cause | Fix the addon specification, wait for the repository to change, or remove the object standing in the way. Attempts are stopped 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`. +The `Reconciling` and `Stalled` conditions are present only while they apply: `Reconciling` is present until the work is finished, `Stalled` is present until the cause of the failure is fixed. The `Installed`, `UpdateInstalled` and `ConfigurationApplied` conditions appear as the addon passes the corresponding stages and carry the same verdict as `Ready`. {{< /alert >}} @@ -343,12 +346,12 @@ The `Reconciling` and `Stalled` conditions are present only while they apply: th ## 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). +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: +To add an application chart repository, create a [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository) resource: {{< tabs name="create-cluster-application-repository" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -365,7 +368,7 @@ EOF {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "System" tab. 1. Go to "Helm operator" → "Application repositories". @@ -378,13 +381,18 @@ EOF {{< /tabs >}} {{< 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). +Use one of the two schemes in the repository URL: + +- `http(s)://`: Helm repository that publishes an `index.yaml` file listing the available Helm charts. +- `oci://`: 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: +The catalog of such a repository is published in [HelmClusterApplicationChart](/modules/operator-helm/cr.html#helmclusterapplicationchart) resources. To list all Helm charts available in a repository: {{< tabs name="list-cluster-application-charts" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} + +Run the following command: ```shell d8 k get helmclusterapplicationcharts -l repository=podinfo-shared @@ -392,7 +400,7 @@ d8 k get helmclusterapplicationcharts -l repository=podinfo-shared {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "System" tab. 1. Go to "Helm operator" → "Application repositories". @@ -402,14 +410,14 @@ d8 k get helmclusterapplicationcharts -l repository=podinfo-shared {{% /tab %}} {{< /tabs >}} -Further work with the charts of this repository is described in the [user guide](user_guide.html). +For details on working with the charts in this repository, refer to the ["User guide"](user_guide.html) page. ## 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: +To connect a private repository, specify the credentials and the TLS parameters in the repository specification. An example of configuring a repository with authentication and a self-signed certificate: {{< tabs name="connect-private-repository" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -433,7 +441,7 @@ EOF {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "System" tab. 1. Go to "Helm operator" → "Addon repositories". @@ -448,7 +456,7 @@ EOF {{< /tabs >}} {{< 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. +The credentials are stored in the resource in plain text. A user that has a read-level access to a repository can view its credentials as well. {{< /alert >}} ## Forcing reconciliation @@ -460,36 +468,33 @@ For addons, a forced reconciliation can be useful if a terminal error occurred w 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" %}} +{{% tab name="Via command line" %}} -To force the reconciliation of a [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon), run the following command: +To force the reconciliation of a [HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon), add the annotation `reconcile.helm.deckhouse.io/force` to it by running 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: +To force the reconciliation of a [HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository), add the annotation `reconcile.helm.deckhouse.io/force` to it by running 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. +The annotation value is ignored. The module only checks that the annotation is present on the resource. The time stamp in the examples in only to make one request differ from another. {{< /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" %}} +{{% tab name="Via web interface" %}} To force the reconciliation of an addon: @@ -516,12 +521,12 @@ Reconciliation can be very fast, so the web interface may not have time to show ## 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). +Maintenance mode pauses the reconciliation of an addon, which lets you modify the release manually by adjusting the parameters of the previously deployed resources (such as the number of replicas and other parameters). {{< tabs name="enable-addon-maintenance" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} -To turn maintenance mode on, run the following command: +To enable maintenance mode, run the following command: ```shell d8 k patch helmclusteraddon podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' @@ -539,7 +544,7 @@ Example of successful output: MaintenanceModeActive ``` -To turn maintenance mode off, run the following command: +To disable maintenance mode, run the following command: ```shell d8 k patch helmclusteraddon podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' @@ -559,7 +564,7 @@ MaintenanceModeInactive {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} To manage the maintenance mode of an addon: diff --git a/docs/ADMIN_GUIDE.ru.md b/docs/ADMIN_GUIDE.ru.md index 2ceb5ffc..3423b68f 100644 --- a/docs/ADMIN_GUIDE.ru.md +++ b/docs/ADMIN_GUIDE.ru.md @@ -1,16 +1,17 @@ --- title: "Руководство администратора" -description: "Deckhouse Platform — управление кластерными ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." +description: "Управление cluster-wide-ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." weight: 40 --- -Руководство описывает работу с кластерными ресурсами модуля: репозитории чартов, их каталоги и аддоны. Для работы с данными кастомными ресурсами необходимо иметь полномочия не ниже чем [`ClusterAdmin`](/modules/user-authz/#текущая-ролевая-модель). +Руководство описывает порядок работы с модулем `operator-helm` через cluster-wide-ресурсы. Для работы с данными кастомными ресурсами необходимы права не ниже уровня [роли `ClusterAdmin`](/modules/user-authz/#текущая-ролевая-модель). ## Добавление репозитория аддонов -Репозиторий — точка входа для всех остальных ресурсов: пока он не добавлен, выбирать чарт не из чего. +Helm-репозиторий аддонов — это точка входа для всех остальных ресурсов. +Он содержит Helm-чарты для последующей установки в кластере. -Создайте ресурс [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository): +Чтобы добавить новый Helm-репозиторий аддонов, создайте [ресурс HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository): {{< tabs name="create-addon-repository" >}} {{% tab name="В командной строке" %}} @@ -36,17 +37,20 @@ EOF 1. Перейдите в раздел «Helm-оператор» → «Репозитории аддонов». 1. Нажмите кнопку «Создать». 1. В открывшейся форме в поле «Имя» введите произвольное имя репозитория. -1. В поле «URL» введите URL репозитория с чартами. +1. В поле «URL» введите URL-адрес репозитория с чартами. 1. Нажмите кнопку «Применить». {{% /tab %}} {{< /tabs >}} {{< alert level="info" >}} -При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +В URL-адресе репозитория используйте одну из двух схем: + +- `http(s)://` — Helm-репозиторий, содержащий файл `index.yaml` с перечнем доступных Helm-чартов; +- `oci://` — хранилище образов контейнеров, поддерживающее хранение Helm-чартов. {{< /alert >}} -Модуль синхронизирует репозиторий и создаст по объекту [`HelmClusterAddonChart`](/modules/operator-helm/cr.html#helmclusteraddonchart) на каждый найденный чарт. Для просмотра чартов репозитория: +После создания ресурса HelmClusterAddonRepository модуль синхронизирует репозиторий и создаст отдельный [объект HelmClusterAddonChart](/modules/operator-helm/cr.html#helmclusteraddonchart) для каждого чарта в репозитории. Для просмотра чартов репозитория: {{< tabs name="list-addon-charts" >}} {{% tab name="В командной строке" %}} @@ -66,7 +70,7 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo Имя объекта каталога формируется из имени репозитория, имени чарта и хеша, поэтому выбирать чарт удобнее по лейблам `repository` и `chart`, а не по имени. -Доступные версии чарта перечислены в его статусе. Выведите их: +Доступные версии чарта перечислены в его статусе. Для просмотра списка версий используйте следующую команду: ```shell d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml @@ -74,7 +78,7 @@ d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddonChart metadata: @@ -99,58 +103,9 @@ status: {{% /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 >}} - ### Проверка состояния репозитория -Состояние репозитория отражают условия в его статусе. Для оценки состояния репозитория: +Состояние репозитория отражают условия в его статусе ([`status.conditions`](cr.html#helmclusteraddonrepository-v1alpha1-status-conditions)). Для оценки состояния репозитория: {{< tabs name="check-repository-conditions" >}} {{% tab name="В командной строке" %}} @@ -163,7 +118,7 @@ d8 k get helmclusteraddonrepository podinfo -o yaml Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddonRepository metadata: @@ -202,43 +157,92 @@ status: 1. Перейдите на вкладку «Проекты» и выберите нужный проект. 1. Перейдите в раздел «Helm-оператор» → «Репозитории». -1. Выберите нужный репозиторий и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. +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` | Попытки чтения исчерпаны. Устраните причину и запросите принудительную реконсиляцию. | +| `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` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. +Условия `Reconciling` и `Stalled` присутствуют только пока они применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. {{< /alert >}} {{< /details >}} +## Развёртывание аддона + +Чтобы развернуть аддон, создайте [ресурс 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, использующего заданный Helm-чарт из заданного репозитория. При этом из одного репозитория одновременно могут быть развёрнуты разные Helm-чарты. +{{< /alert >}} + ### Проверка состояния аддона -Состояние аддона отражают условия в его статусе. Для оценки состояния аддона: +Состояние аддона отражают условия в его статусе ([`status.conditions`](cr.html#helmclusteraddon-v1alpha1-status-conditions)). Для оценки состояния аддона: {{< tabs name="check-addon-conditions" >}} {{% tab name="В командной строке" %}} @@ -251,7 +255,7 @@ d8 k get helmclusteraddon podinfo -o yaml Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmClusterAddon metadata: @@ -303,39 +307,39 @@ status: 1. Перейдите на вкладку «Система». 1. Перейдите в раздел «Helm-оператор» → «Аддоны». -1. Выберите нужный аддон и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. +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` | причина того сбоя, который его вызвал | Повтор не поможет: нужно исправить спецификацию аддона, дождаться изменений в репозитории или убрать мешающий объект. Пока причина не устранена, попытки прекращены. | +| `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`. +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. Условия `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как аддон проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. {{< /alert >}} @@ -343,9 +347,9 @@ status: ## Добавление репозитория с чартами приложений -С помощью создания [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) администратор платформы может централизованно предоставить администраторам неймспейсов доступ к Helm-чартам. Helm-чарты данного репозитория будут доступны администраторам всех неймспейсов для развёртывания [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication). +С помощью создания [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository) администратор Deckhouse Platform может централизованно предоставить администраторам неймспейсов доступ к Helm-чартам. Helm-чарты данного репозитория будут доступны администраторам всех неймспейсов для развёртывания [HelmApplication](/modules/operator-helm/cr.html#helmapplication). -Создайте ресурс [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository): +Чтобы добавить репозиторий с чартами приложений, создайте [ресурс HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository): {{< tabs name="create-cluster-application-repository" >}} {{% tab name="В командной строке" %}} @@ -371,21 +375,26 @@ EOF 1. Перейдите в раздел «Helm-оператор» → «Репозитории приложений». 1. Нажмите кнопку «Создать». 1. В открывшейся форме в поле «Имя» введите произвольное имя репозитория. -1. В поле «URL» введите URL репозитория с чартами. +1. В поле «URL» введите URL-адрес репозитория с чартами. 1. Нажмите кнопку «Применить». {{% /tab %}} {{< /tabs >}} {{< alert level="info" >}} -При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +В URL-адресе репозитория используйте одну из двух схем: + +- `http(s)://` — Helm-репозиторий, содержащий файл `index.yaml` с перечнем доступных Helm-чартов; +- `oci://` — хранилище образов контейнеров, поддерживающее хранение Helm-чартов. {{< /alert >}} -Каталог такого репозитория публикуется в ресурсах [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). Выведите его: +Каталог такого репозитория публикуется в ресурсах [HelmClusterApplicationChart](/modules/operator-helm/cr.html#helmclusterapplicationchart). Чтобы вывести список доступных в репозитории Helm-чартов: {{< tabs name="list-cluster-application-charts" >}} {{% tab name="В командной строке" %}} +Выполните команду: + ```shell d8 k get helmclusterapplicationcharts -l repository=podinfo-shared ``` @@ -402,11 +411,11 @@ d8 k get helmclusterapplicationcharts -l repository=podinfo-shared {{% /tab %}} {{< /tabs >}} -Дальнейшая работа с чартами из этого репозитория описана в [руководстве пользователя](user_guide.html). +Дальнейшая работа с чартами из этого репозитория описана в [«Руководстве пользователя»](user_guide.html). ## Подключение приватного репозитория -Учётные данные и параметры TLS задаются в спецификации репозитория. Пример настройки репозитория с аутентификацией и самоподписанным сертификатом: +Чтобы подключить приватный репозиторий, укажите учётные данные и параметры TLS в спецификации репозитория. Пример настройки репозитория с аутентификацией и самоподписанным сертификатом: {{< tabs name="connect-private-repository" >}} {{% tab name="В командной строке" %}} @@ -439,7 +448,7 @@ EOF 1. Перейдите в раздел «Helm-оператор» → «Репозитории аддонов». 1. Нажмите кнопку «Создать». 1. В открывшейся форме в поле «Имя» введите произвольное имя репозитория. -1. В поле «URL» введите URL репозитория с чартами. +1. В поле «URL» введите URL-адрес репозитория с чартами. 1. В разделе «Аутентификация» укажите учётные данные для доступа к репозиторию. 1. В разделе «CA-сертификат» укажите CA-сертификат в формате PEM, либо воспользуйтесь формой загрузки сертификата, нажав на ссылку «нажмите, чтобы загрузить». 1. Нажмите кнопку «Применить». @@ -448,45 +457,42 @@ EOF {{< /tabs >}} {{< alert level="warning" >}} -Учётные данные хранятся в ресурсе открытым текстом. Право на чтение репозитория — это право на чтение его учётных данных. +Учётные данные хранятся в ресурсе в открытом виде. Пользователь с правами на чтение репозитория сможет просмотреть учётные данные. {{< /alert >}} ## Принудительный запуск реконсиляции При работе с аддонами и репозиториями может возникнуть необходимость принудительного запуска реконсиляции. В штатном режиме работы запуск реконсиляции происходит автоматически в случае внесения изменений в ресурсы либо изменения состояния их зависимостей. -В случае с аддонами принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек аддона возникла терминальная ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. +В случае с аддонами принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек аддона возникла критическая ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. При работе с репозиториями запуск принудительной реконсиляции позволяет выполнить синхронизацию репозитория, не дожидаясь очередного запуска по расписанию. {{< tabs name="force-reconcile-addon" >}} {{% tab name="В командной строке" %}} -Для принудительной реконсиляции [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) выполните команду: +Для принудительной реконсиляции [ресурса HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon) добавьте к нему аннотацию `reconcile.helm.deckhouse.io/force`, выполнив следующую команду: ```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) выполните команду: +Для принудительной реконсиляции [ресурса HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository) добавьте к нему аннотацию `reconcile.helm.deckhouse.io/force`, выполнив следующую команду: ```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="В веб-интерфейсе" %}} @@ -516,18 +522,18 @@ d8 k get helmclusteraddon podinfo -o jsonpath='{.status.lastForceReconcileTime}' ## Режим обслуживания -Режим обслуживания приостанавливает реконсиляцию аддона, что позволяет вмешаться в релиз вручную, корректируя параметры ранее развёрнутых ресурсов (изменять количество реплик, менять параметры и другое). +Режим обслуживания приостанавливает реконсиляцию аддона, что позволяет скорректировать релиз вручную, изменив параметры ранее развёрнутых ресурсов (количество реплик и другие параметры). {{< 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}' @@ -539,13 +545,13 @@ d8 k get helmclusteraddon podinfo -o jsonpath='{.status.conditions[?(@.type=="Ma 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}' diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 0face1ec..670ff985 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,5 +1,5 @@ --- title: "Configuration" -description: "Deckhouse Platform — configuration parameters of the operator-helm module." +description: "Configuration parameters of the operator-helm module." weight: 20 --- diff --git a/docs/CONFIGURATION.ru.md b/docs/CONFIGURATION.ru.md index e63e2686..f78d7012 100644 --- a/docs/CONFIGURATION.ru.md +++ b/docs/CONFIGURATION.ru.md @@ -1,5 +1,5 @@ --- title: "Настройки" -description: "Deckhouse Platform, параметры конфигурации модуля operator-helm." +description: "Параметры конфигурации модуля operator-helm." weight: 20 --- diff --git a/docs/CR.md b/docs/CR.md index 7ca28121..bf1803d6 100644 --- a/docs/CR.md +++ b/docs/CR.md @@ -1,5 +1,5 @@ --- title: "Custom Resources" -description: "Deckhouse Platform — Custom resources of the operator-helm module." +description: "Custom resources of the operator-helm module." weight: 60 --- diff --git a/docs/CR.ru.md b/docs/CR.ru.md index 9b7e457c..7361d4d9 100644 --- a/docs/CR.ru.md +++ b/docs/CR.ru.md @@ -1,5 +1,5 @@ --- title: "Кастомные ресурсы" -description: "Deckhouse Platform, кастомные ресурсы (custom resources) модуля operator-helm." +description: "Кастомные ресурсы модуля operator-helm." weight: 60 --- diff --git a/docs/README.md b/docs/README.md index 737e52b4..8536add2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,32 +1,35 @@ --- title: "Module operator-helm" -description: "Deckhouse Platform — the operator-helm module for declarative Helm chart management." +description: "Operator-helm module for declarative Helm chart management in Deckhouse Platform." weight: 10 --- -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 `operator-helm` module lets you control declaratively the Helm chart deployment in the Deckhouse Platform (DP) cluster. -**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. +Depending on the scope of created resources, Helm charts are divided in addons and applications: -**Applications** ([`HelmApplication`](/modules/operator-helm/cr.html#helmapplication)) consist solely of objects that belong to a single namespace. A namespace administrator deploys them. +- **Addons** ([HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon)) may create custom and other cluster-wide resources. A DP administrator deploys and controls them. +- **Applications** ([HelmApplication](/modules/operator-helm/cr.html#helmapplication)) create only namespaced resources. A namespace administrator can deploy applications and control them within a designated namespace. + +To enable the module, use one of the methods described on the ["Configuration"](configuration.html) page. ## Key features The module provides the following capabilities: -- 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. +- 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 the [`d8`](/products/kubernetes-platform/documentation/v1/cli/d8/) CLI tool or the DP web interface. ## Custom resources -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. +The module's resources fall into two groups by scope: cluster-wide resources that are managed by a DP administrator, and the namespaced resources managed by a namespace administrator. ```mermaid flowchart TB @@ -34,7 +37,7 @@ flowchart TB classDef cluster fill:#e0e7ff,stroke:#1a237e,color:#000000,stroke-width:2px; classDef ns fill:#f0fdfa,stroke:#004d40,color:#000000,stroke-width:2px; - ADM(["fa:fa-user
Platform
administrator"]):::actor + ADM(["fa:fa-user
DP
administrator"]):::actor USR(["fa:fa-user
Namespace
administrator"]):::actor HCA["HelmClusterAddon"]:::cluster @@ -63,22 +66,22 @@ flowchart TB HCApR -->|Maintains| HCApC ``` -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. +Blue fill marks cluster-wide resources; turquoise marks the namespaced resources. The module maintains the HelmClusterAddonChart, HelmClusterApplicationChart and HelmApplicationChart resources on its own. They should not be edited manually. -A platform administrator works with the cluster-scoped resources: +A DP administrator works with the following cluster-wide 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. +- [HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository): Defines a Helm or OCI repository with charts to be installed at the cluster level. +- [HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon): Defines a Helm release, including the target chart version, the namespace to deploy into and, where required, extended installation parameters. +- [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository): Defines an application 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: +A namespace administrator manages the following resources in the designated 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. +- [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository): Defines an application 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): Defines a Helm release, including the target chart version, a repository and installation parameters. You can use a [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) or [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository) as the chart source. -Configuration examples for the resources described above are given in the [administrator guide](admin_guide.html) and the [user guide](user_guide.html). +For configuration examples for the resources described above, refer to the ["Administrator guide"](admin_guide.html) and ["User guide"](user_guide.html) pages. ## Limitations -- 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. +- For a single [HelmClusterAddonChart](/modules/operator-helm/cr.html#helmclusteraddonchart) resource, only one referring [HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon) resource can be created. Helm charts used in an addon may contain custom resource definitions (CRDs) and other cluster-wide resources, which, if installed repeatedly, may cause service failures. +- Creating a [HelmApplication](/modules/operator-helm/cr.html#helmapplication) requires permissions of no lower than the [`Admin`](/modules/user-authz/#current-role-based-model) role, because applications are deployed using a ServiceAccount that holds equivalent privileges. diff --git a/docs/README.ru.md b/docs/README.ru.md index 2e92044b..a6519ffe 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -1,32 +1,35 @@ --- title: "Модуль operator-helm" -description: "Deckhouse Platform — модуль operator-helm для декларативного управления Helm-чартами." +description: "Модуль operator-helm для декларативного управления Helm-чартами в Deckhouse Platform." weight: 10 --- -Модуль `operator-helm` декларативно разворачивает Helm-чарты и рассчитан на две аудитории: администраторов платформы и администраторов неймспейсов. Чарты он делит на аддоны и приложения — по тому, какие объекты они создают. +Модуль `operator-helm` позволяет декларативно управлять развёртыванием Helm-чартов в кластере Deckhouse Platform (DP). -**Аддоны** ([`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon)) могут содержать CRD и другие кластерные объекты, поэтому их разворачивает администратор платформы. Такой Helm-чарт может влиять на состояние кластера, и управление им остаётся на уровне кластера. +В зависимости от области видимости создаваемых ресурсов Helm-чарты разделяются на аддоны и приложения: -**Приложения** ([`HelmApplication`](/modules/operator-helm/cr.html#helmapplication)) состоят только из объектов, относящихся к конкретному неймспейсу. Их разворачивает администратор неймспейса. +- **Аддоны** ([HelmClusterAddon](cr.html#helmclusteraddon)) могут создавать кастомные и другие cluster-wide-ресурсы. Установкой аддонов и управлением ими занимается администратор DP. +- **Приложения** ([HelmApplication](cr.html#helmapplication)) создают только namespaced-ресурсы. Администратор неймспейса может устанавливать приложения и управлять ими в пределах своего неймспейса. + +Чтобы включить модуль, воспользуйтесь одним из способов, описанных [в разделе «Настройки»](configuration.html). ## Основные возможности Модуль предоставляет следующие возможности: - декларативное управление развёртыванием Helm-чартов; -- установка чартов из HTTP(S)- и OCI-репозиториев через один и тот же API; +- установка чартов из HTTP(S)- и OCI-репозиториев через единый API; - автоматическая синхронизация репозитория для просмотра и поиска доступных Helm-чартов и их версий; -- установка чартов администратором неймспейса без выдачи ему прав на кластер; +- установка чартов администратором неймспейса без предоставления прав на cluster-wide-ресурсы; - поддержка общих репозиториев приложений, доступных во всех неймспейсах; -- автоматическое устранение дрейфа конфигурации; +- устранение отклонений от заданной конфигурации; - режим обслуживания, который приостанавливает реконсиляцию для ручного вмешательства в релиз; - поддержка приватных репозиториев с использованием корпоративного PKI; -- управление через `d8 k` или веб-интерфейс Deckhouse Platform. +- управление через [CLI-утилиту `d8`](/products/kubernetes-platform/documentation/v1/cli/d8/) или веб-интерфейс DP. ## Кастомные ресурсы -Ресурсы модуля делятся на две группы по области видимости. Кластерными ресурсами управляет администратор платформы, а ресурсами в заданном неймспейсе — администратор неймспейса. +Кастомные ресурсы модуля разделяются по области видимости на cluster-wide-ресурсы, которыми управляет администратор DP, и namespaced-ресурсы, которыми управляет администратор соответствующего неймспейса. ```mermaid flowchart TB @@ -34,7 +37,7 @@ flowchart TB classDef cluster fill:#e0e7ff,stroke:#1a237e,color:#000000,stroke-width:2px; classDef ns fill:#f0fdfa,stroke:#004d40,color:#000000,stroke-width:2px; - ADM(["fa:fa-user
Администратор
платформы"]):::actor + ADM(["fa:fa-user
Администратор
DP"]):::actor USR(["fa:fa-user
Администратор
неймспейса"]):::actor HCA["HelmClusterAddon"]:::cluster @@ -63,22 +66,22 @@ flowchart TB HCApR -->|Обслуживает| HCApC ``` -Синей заливкой отмечены кластерные ресурсы, бирюзовой — ресурсы внутри неймспейса. Каталоги чартов модуль обслуживает сам, вручную они не редактируются. +Синей заливкой на схеме обозначены cluster-wide-ресурсы, бирюзовой — namespaced-ресурсы. Ресурсы HelmClusterAddonChart, HelmClusterApplicationChart и HelmApplicationChart модуль обслуживает сам. Они не предназначены для изменения вручную. -Администратор платформы работает с кластерными ресурсами: +Администратор DP управляет следующими cluster-wide-ресурсами: -- [`HelmClusterAddonRepository`](/modules/operator-helm/cr.html#helmclusteraddonrepository) — репозиторий Helm или OCI с чартами для установки на уровне кластера; -- [`HelmClusterAddon`](/modules/operator-helm/cr.html#helmclusteraddon) — описание релиза: целевая версия чарта, неймспейс развёртывания и расширенные параметры установки (при необходимости); -- [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — репозиторий, чарты которого доступны ресурсам [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) из любого неймспейса. +- [HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository) — описывает репозиторий Helm или OCI с чартами для установки на уровне кластера; +- [HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon) — описывает Helm-релиз, включая целевую версию чарта, неймспейс развёртывания и расширенные параметры установки (при необходимости); +- [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository) — описывает репозиторий приложений, чарты которого доступны ресурсам [HelmApplication](/modules/operator-helm/cr.html#helmapplication) из любого неймспейса. -Администратор неймспейса работает с ресурсами своего неймспейса: +Администратор неймспейса управляет следующими ресурсами в своём неймспейсе: -- [`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) и расширенные параметры установки (при необходимости). +- [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) — описывает репозиторий приложений, чарты которого доступны ресурсам [HelmApplication](/modules/operator-helm/cr.html#helmapplication) того же неймспейса; +- [HelmApplication](/modules/operator-helm/cr.html#helmapplication) — описывает Helm-релиз приложения, включая целевую версию чарта, репозиторий и параметры установки. В качестве источника чарта можно использовать [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) из того же неймспейса или [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository). -Примеры настройки вышеописанных ресурсов приведены в [руководстве администратора](admin_guide.html) и [руководстве пользователя](user_guide.html). +Примеры настройки вышеописанных ресурсов приведены в [«Руководстве администратора»](admin_guide.html) и [«Руководстве пользователя»](user_guide.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`, обладающего аналогичными привилегиями. +- Для одного ресурса [HelmClusterAddonChart](/modules/operator-helm/cr.html#helmclusteraddonchart) может существовать только один ссылающийся на него ресурс [HelmClusterAddon](/modules/operator-helm/cr.html#helmclusteraddon). Helm-чарты, используемые в аддоне, могут содержать определения кастомных ресурсов (Custom Resource Definition, CRD) и другие cluster-wide-ресурсы, повторная установка которых может привести к перебоям в работе сервисов. +- Для создания [HelmApplication](/modules/operator-helm/cr.html#helmapplication) требуются права уровня [роли `Admin`](/modules/user-authz/#текущая-ролевая-модель), поскольку приложение развёртывается с использованием ServiceAccount, обладающего аналогичными правами. diff --git a/docs/RELEASE_NOTES.md b/docs/RELEASE_NOTES.md index 5e8122c3..5e2f0260 100644 --- a/docs/RELEASE_NOTES.md +++ b/docs/RELEASE_NOTES.md @@ -7,101 +7,101 @@ description: "Release notes for Deckhouse operator-helm." ### New Features -* Added Helm repositories support where chart urls have OCI schemas +* Added Helm repositories support where chart URLs have OCI schemas. ## v0.2.0 ### 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 ### Bug Fixes -* Fixed authentication issue when working with a private OCI repository +* Fixed authentication issue when working with a private OCI repository. ### Chore -* Documentation is now available to the AI agent built into the platform +* Documentation is now available to the AI agent built into the platform. ## v0.1.0 ### 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 initialized 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 support +* The first public alpha release with HelmClusterAddon, HelmClusterAddonChart, and HelmClusterAddonRepository CRDs support. ## v0.0.2 ### New Features -* Applied deckhouse runtime 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 4a976722..b802f167 100644 --- a/docs/RELEASE_NOTES.ru.md +++ b/docs/RELEASE_NOTES.ru.md @@ -7,101 +7,101 @@ description: "Релизы Deckhouse operator-helm." ### Новые возможности -* Добавлена поддержка репозиториев Helm, где URL-адреса чартов имеют схемы OCI +* Добавлена поддержка репозиториев Helm, где URL-адреса чартов имеют схемы OCI. ## v0.2.0 ### Новые возможности -* Переработана семантика статуса HelmClusterAddonRepository -* Добавлена поддержка устаревшего типа медиаданных OCI chart с инкрементной индексацией -* Добавлен прогресс и завершение принудительной синхронизации в статусе -* Добавлено отображение запланированной синхронизации репозитория в статусе +* Переработана семантика статуса HelmClusterAddonRepository. +* Добавлена поддержка устаревшего типа медиаданных OCI chart с инкрементной индексацией. +* Добавлен прогресс и завершение принудительной синхронизации в статусе. +* Добавлено отображение запланированной синхронизации репозитория в статусе. ### Исправления -* Исправлена передача принудительной синхронизации во внутренние источники +* Исправлена передача принудительной синхронизации во внутренние источники. ### Прочее -* Добавлена задача очистки dev registry +* Добавлена задача очистки dev registry. ## v0.1.1 ### Исправления -* Исправлена проблема аутентификации при работе с частным OCI репозиторием +* Исправлена проблема аутентификации при работе с частным OCI репозиторием. ### Прочее -* Документация теперь доступна встроенному в платформу AI агенту +* Документация теперь доступна встроенному в платформу AI-агенту. ## v0.1.0 ### Новые возможности -* Внедрён ограниченный 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 ### Новые возможности -* Выпущена первоначальная версия с базовыми возможностями +* Выпущена первоначальная версия с базовыми возможностями. diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index d82e7d6f..0b319fbc 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -1,19 +1,20 @@ --- title: "User guide" -description: "Deckhouse Platform — installing Helm charts in your own namespace with the operator-helm module." +description: "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. +This guide describes how to work with the namespaced resources of the module, including chart repositories, their catalogs and applications. Working with these custom resources requires permissions of no lower than [`Admin`](/modules/user-authz/#current-role-based-model) role in a designated 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. +A Helm application repository is the entry point for every other resource. +It contains Helm charts for a following installation within a designated namespace. -Create a [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) resource in your namespace: +To add a new Helm application repository, create a [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) resource in the target namespace: {{< tabs name="create-application-repository" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -31,7 +32,7 @@ EOF {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "Projects" tab and select the project you need. 1. Go to "Helm operator" → "Repositories". @@ -44,13 +45,16 @@ EOF {{< /tabs >}} {{< 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). +Use one of the two schemes in the repository URL: + +- `http(s)://`: Helm repository that publishes an `index.yaml` file listing the available Helm charts. +- `oci://`: 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: +After the HelmApplicationRepository resource is created, the module synchronizes the repository and creates a separate [HelmApplicationChart](/modules/operator-helm/cr.html#helmapplicationchart) object for each chart in the repository. To view the charts in a repository: {{< tabs name="list-application-charts" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -67,7 +71,7 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo 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: +The available chart versions are listed in its status. To see a list of versions, run the following command: ```shell d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yaml @@ -75,7 +79,7 @@ d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yam Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplicationChart metadata: @@ -93,7 +97,7 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "Projects" tab and select the project you need. 1. Go to "Helm operator" → "Charts". @@ -103,10 +107,10 @@ status: ### Checking the repository state -The state of a repository is reflected by the conditions in its status. To assess the state of a repository: +The state of a repository is reflected by the conditions in its status ([`status.conditions`](cr.html#helmapplicationrepository-v1alpha1-status-conditions)). To assess the state of a repository: {{< tabs name="check-repository-conditions" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -116,7 +120,7 @@ d8 k -n test get helmapplicationrepository podinfo -o yaml Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplicationRepository metadata: @@ -152,39 +156,39 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via 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. +1. Select the repository you need and hover 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 | +| Condition | Value | Reason | Description | | --- | --- | --- | --- | -| `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. | +| `Ready` | `True` | `Success` | The repository is reachable and the chart catalog has been 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 repository 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 reconciliation is in progress | +| `Reconciling` | `True` | `ForceReconcile` | A forced reconciliation 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 repository rejected the credentials. Check the username and the password in the repository specification | +| `Stalled` | `True` | `SourceNotFound` | No repository was found at the given URL | +| `Stalled` | `True` | `SourceRejectedRequest` | The repository rejected the request. Contact the repository owner. | +| `Stalled` | `True` | `RetriesExceeded` | The number of read attempts has been exceeded. 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. +The `Reconciling` and `Stalled` conditions are present only while they apply: `Reconciling` is present until the work is finished, `Stalled` is present until the cause of the failure is fixed. {{< /alert >}} @@ -192,10 +196,10 @@ The `Reconciling` and `Stalled` conditions are present only while they apply: th ## 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: +To deploy an application, create a [HelmApplication](/modules/operator-helm/cr.html#helmapplication) resource in the same namespace, specifying the repository, chart name and version: {{< tabs name="create-application" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -215,15 +219,15 @@ EOF ``` {{< alert level="info" >}} -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. +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 Deckhouse 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). +Every user in a namespace has read-level 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. +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: +To view a list of shared Helm charts, run the following command: ```shell d8 k get helmclusterapplicationcharts --show-labels @@ -242,7 +246,7 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} 1. Go to the "Projects" tab and select the project you need. 1. Go to "Helm operator" → "Applications". @@ -254,18 +258,18 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo 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. +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 Deckhouse 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. +You can adjust the Helm chart parameters if needed. To see the parameters used by default, click "Show default values" 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. +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" >}} @@ -292,10 +296,10 @@ rules: ### Checking the application state -The state of an application is reflected by the conditions in its status. To assess the state of an application: +The state of an application is reflected by the conditions in its status ([`status.conditions`](cr.html#helmapplication-v1alpha1-status-conditions)). To assess the state of an application: {{< tabs name="check-application-conditions" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} Run the following command: @@ -305,7 +309,7 @@ d8 k -n test get helmapplication podinfo -o yaml Example output: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplication metadata: @@ -347,44 +351,44 @@ status: {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via 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. +1. Select the application you need and hover 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 | +| Condition | Value | Reason | Description | | --- | --- | --- | --- | -| `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` | `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. | -| `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. | +| `Ready` | `True` | `InstallSucceeded`, `UpgradeSucceeded` | The release has been deployed and matches the specification. The reason is provided by Helm | +| `Ready` | `Unknown` | `Reconciling` | 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` | `RBACSetupFailed` | The ServiceAccount, Role or RoleBinding resource 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 resource that the module creates for the application is already 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 modify 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 forced reconciliation is in progress | +| `Stalled` | `True` | The failure cause | Fix the application specification, wait for the repository to change, or remove the object standing in the way. Attempts are stopped 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`. +The `Reconciling` and `Stalled` conditions are present only while they apply: `Reconciling` is present until the work is finished, `Stalled` is present until the cause of the failure is fixed. The `Installed`, `UpdateInstalled` and `ConfigurationApplied` conditions appear as the application passes the corresponding stages and carry the same verdict as `Ready`. {{< /alert >}} @@ -399,36 +403,33 @@ For applications, a forced reconciliation can be useful if a terminal error occu 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" %}} +{{% tab name="Via command line" %}} -To force the reconciliation of a [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication), run the following command: +To force the reconciliation of a [HelmApplication](/modules/operator-helm/cr.html#helmapplication) resource, add the annotation `reconcile.helm.deckhouse.io/force` to it by running 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: +To force the reconciliation of a [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository), add the annotation `reconcile.helm.deckhouse.io/force` to it by running 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. +The annotation value is ignored. The module only checks that the annotation is present on the resource. The time stamp in the examples in only to make one request differ from another. {{< /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" %}} +{{% tab name="Via web interface" %}} To force the reconciliation of an application: @@ -458,12 +459,12 @@ Reconciliation can be very fast, so the web interface may not have time to show ## 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). +Maintenance mode pauses the reconciliation of an application, which lets you modify the release manually by adjusting the parameters of the previously deployed resources (such as the number of replicas and other parameters). {{< tabs name="enable-application-maintenance" >}} -{{% tab name="Command line" %}} +{{% tab name="Via command line" %}} -To turn maintenance mode on, run the following command: +To enable maintenance mode, run the following command: ```shell d8 k -n test patch helmapplication podinfo --type=merge -p '{"spec":{"maintenance":"NoResourceReconciliation"}}' @@ -481,7 +482,7 @@ Example of successful output: MaintenanceModeActive ``` -To turn maintenance mode off, run the following command: +To disable maintenance mode, run the following command: ```shell d8 k -n test patch helmapplication podinfo --type=json -p '[{"op":"remove","path":"/spec/maintenance"}]' @@ -501,7 +502,7 @@ MaintenanceModeInactive {{% /tab %}} -{{% tab name="Web interface" %}} +{{% tab name="Via web interface" %}} To manage the maintenance mode of an application: diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md index fa00fb67..b8834412 100644 --- a/docs/USER_GUIDE.ru.md +++ b/docs/USER_GUIDE.ru.md @@ -1,16 +1,17 @@ --- title: "Руководство пользователя" -description: "Deckhouse Platform — установка Helm-чартов в своём неймспейсе с помощью модуля operator-helm." +description: "Установка Helm-чартов в собственном неймспейсе с помощью модуля operator-helm." weight: 50 --- -Руководство описывает работу с ресурсами модуля в пределах неймспейса: репозиториями чартов, их каталогами и приложениями. Для работы с данными кастомными ресурсами необходимо иметь полномочия не ниже чем [`Admin`](/modules/user-authz/#текущая-ролевая-модель) в своём неймспейсе. +Руководство описывает порядок работы с namespaced-ресурсами модуля, включая репозитории чартов, их каталоги и приложения. Для работы с данными кастомными ресурсами необходимы права не ниже уровня [роли `Admin`](/modules/user-authz/#текущая-ролевая-модель) в соответствующем неймспейсе. ## Добавление репозитория приложений -Репозиторий — точка входа для всех остальных ресурсов: пока он не добавлен, выбирать чарт не из чего. +Helm-репозиторий приложений — это точка входа для всех остальных ресурсов. +Он содержит Helm-чарты для последующей установки в рамках выбранного неймспейса. -Создайте ресурс [`HelmApplicationRepository`](/modules/operator-helm/cr.html#helmapplicationrepository) в своём неймспейсе: +Чтобы добавить новый Helm-репозиторий приложений, создайте ресурс [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) в необходимом неймспейсе: {{< tabs name="create-application-repository" >}} {{% tab name="В командной строке" %}} @@ -37,17 +38,20 @@ EOF 1. Перейдите в раздел «Helm-оператор» → «Репозитории». 1. Нажмите кнопку «Создать». 1. В открывшейся форме в поле «Имя» введите произвольное имя репозитория. -1. В поле «URL» введите URL репозитория с чартами. +1. В поле «URL» введите URL-адрес репозитория с чартами. 1. Нажмите кнопку «Применить». {{% /tab %}} {{< /tabs >}} {{< alert level="info" >}} -При задании URL репозитория могут использоваться две схемы: `http(s)://` (Helm-репозиторий, презентующий файл `index.yaml` с перечнем доступных Helm-чартов) и `oci://` (реестр контейнеров, поддерживающий хранение Helm-чартов). +В URL-адресе репозитория используйте одну из двух схем: + +- `http(s)://` — Helm-репозиторий, содержащий файл `index.yaml` с перечнем доступных Helm-чартов; +- `oci://` — хранилище образов контейнеров, поддерживающее хранение Helm-чартов. {{< /alert >}} -Модуль синхронизирует репозиторий и создаст по объекту [`HelmApplicationChart`](/modules/operator-helm/cr.html#helmapplicationchart) на каждый найденный чарт. Для просмотра чартов репозитория: +После создания ресурса HelmApplicationRepository модуль синхронизирует репозиторий и создаст отдельный [объект HelmApplicationChart](/modules/operator-helm/cr.html#helmapplicationchart) для каждого чарта в репозитории. Для просмотра чартов репозитория: {{< tabs name="list-application-charts" >}} {{% tab name="В командной строке" %}} @@ -67,7 +71,7 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo Имя объекта каталога формируется из имени репозитория, имени чарта и хеша, поэтому выбирать чарт удобнее по лейблам `repository` и `chart`, а не по имени. -Доступные версии чарта перечислены в его статусе. Выведите их: +Доступные версии чарта перечислены в его статусе. Для просмотра списка версий используйте следующую команду: ```shell d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yaml @@ -75,7 +79,7 @@ d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yam Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplicationChart metadata: @@ -103,7 +107,7 @@ status: ### Проверка состояния репозитория -Состояние репозитория отражают условия в его статусе. Для оценки состояния репозитория: +Состояние репозитория отражают условия в его статусе ([`status.conditions`](cr.html#helmapplicationrepository-v1alpha1-status-conditions)). Для оценки состояния репозитория: {{< tabs name="check-repository-conditions" >}} {{% tab name="В командной строке" %}} @@ -116,7 +120,7 @@ d8 k -n test get helmapplicationrepository podinfo -o yaml Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplicationRepository metadata: @@ -156,35 +160,35 @@ status: 1. Перейдите на вкладку «Проекты» и выберите нужный проект. 1. Перейдите в раздел «Helm-оператор» → «Репозитории». -1. Выберите нужный репозиторий и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. +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` | Попытки чтения исчерпаны. Устраните причину и запросите принудительную реконсиляцию. | +| `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` присутствуют, только пока применимы: первое — пока работа не завершена, второе — пока причина сбоя не устранена. +Условия `Reconciling` и `Stalled` присутствуют только пока они применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. {{< /alert >}} @@ -192,7 +196,7 @@ status: ## Развёртывание приложения -Создайте ресурс [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) в том же неймспейсе, указав репозиторий, имя и версию чарта: +Чтобы развернуть приложение, создайте [ресурс HelmApplication](/modules/operator-helm/cr.html#helmapplication) в том же неймспейсе, указав репозиторий, имя и версию чарта: {{< tabs name="create-application" >}} {{% tab name="В командной строке" %}} @@ -215,15 +219,15 @@ EOF ``` {{< alert level="info" >}} -Приложения могут разворачиваться не только из Helm-чартов локального для неймспейса репозитория, но и из общего репозитория, который завёл администратор платформы. Общие репозитории описываются с помощью ресурса [`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository), а их каталог — ресурсами [`HelmClusterApplicationChart`](/modules/operator-helm/cr.html#helmclusterapplicationchart). +Приложения могут разворачиваться не только из Helm-чартов локального для неймспейса репозитория, но и из общего репозитория, который завёл администратор Deckhouse Platform. Общие репозитории описываются с помощью [ресурса HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository), а их каталог — [ресурсами HelmClusterApplicationChart](/modules/operator-helm/cr.html#helmclusterapplicationchart). -У любого пользователя в неймспейсе есть доступ на чтение [`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). +Для использования чарта из общего репозитория при описании ресурса 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-чартов выполните команду: +Для просмотра списка общих Helm-чартов выполните следующую команду: ```shell d8 k get helmclusterapplicationcharts --show-labels @@ -254,18 +258,18 @@ podinfo-chart-podinfo-dfbe83e63b0b 11d chart=podinfo,heritage=deckhouse,repo 1. Нажмите кнопку «Создать». {{< alert level="info" >}} -В списке репозиториев у некоторых может быть постфикс «(cluster)» — это значит, что репозиторий общий ([`HelmClusterApplicationRepository`](/modules/operator-helm/cr.html#helmclusterapplicationrepository)) и его создал администратор платформы. +В списке репозиториев у некоторых может быть указан постфикс «(cluster)». Это означает, что данный репозиторий — общий ([HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository)) и его создал администратор Deckhouse Platform. {{< /alert >}} {{< alert level="info" >}} -При необходимости вы можете скорректировать параметры Helm-чарта. Для получения параметров, используемых по умолчанию, нажмите на ссылку «Показать значения по умолчанию» в форме создания приложения. +При необходимости вы можете скорректировать параметры Helm-чарта. Для получения параметров, используемых по умолчанию, нажмите «Показать значения по умолчанию» в форме создания приложения. {{< /alert >}} {{% /tab %}} {{< /tabs >}} {{< alert level="warning" >}} -Развёртывание [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) выполняется с полными привилегиями в рамках неймспейса. +Развёртывание [HelmApplication](/modules/operator-helm/cr.html#helmapplication) выполняется с полными привилегиями в рамках неймспейса. {{< details summary="Правила роли, используемой при развёртывании приложения" >}} @@ -292,7 +296,7 @@ rules: ### Проверка состояния приложения -Состояние приложения отражают условия в его статусе. Для оценки состояния приложения: +Состояние приложения отражают условия в его статусе ([`status.conditions`](cr.html#helmapplication-v1alpha1-status-conditions)). Для оценки состояния приложения: {{< tabs name="check-application-conditions" >}} {{% tab name="В командной строке" %}} @@ -305,7 +309,7 @@ d8 k -n test get helmapplication podinfo -o yaml Пример вывода: -```yaml +```text apiVersion: helm.deckhouse.io/v1alpha1 kind: HelmApplication metadata: @@ -351,40 +355,40 @@ status: 1. Перейдите на вкладку «Проекты» и выберите нужный проект. 1. Перейдите в раздел «Helm-оператор» → «Приложения». -1. Выберите нужное приложение и наведите мышкой на его статус. Во всплывающем окне будет приведена информация о его состоянии. +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` | `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` | Результат первой установки релиза. | -| `UpdateInstalled` | как у `Ready` | та же, что у `Ready` | Результат обновления релиза. Появляется при смене версии чарта. | -| `ConfigurationApplied` | как у `Ready` | та же, что у `Ready` | Результат применения значений чарта. Появляется при изменении значений. | -| `Managed` | `True` | `MaintenanceModeInactive` | Приложение находится под управлением модуля. | -| `Managed` | `False` | `MaintenanceModeActive` | Включён режим обслуживания, реконсиляция приостановлена. | -| `Reconciling` | `True` | `Reconciling` | Идёт раскатка релиза. | -| `Reconciling` | `True` | `ProgressingWithRetry` | Произошёл сбой, запланирован повтор. | -| `Reconciling` | `True` | `ForceReconcile` | Идёт реконсиляция, запрошенная вручную. | -| `Stalled` | `True` | причина того сбоя, который его вызвал | Повтор не поможет: нужно исправить спецификацию приложения, дождаться изменений в репозитории или убрать мешающий объект. Пока причина не устранена, попытки прекращены. | +| `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` | `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` | Результат первой установки релиза | +| `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`. +Условия `Reconciling` и `Stalled` присутствуют, только пока применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. Условия `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как приложение проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. {{< /alert >}} @@ -394,38 +398,35 @@ status: При работе с приложениями и репозиториями может возникнуть необходимость принудительного запуска реконсиляции. В штатном режиме работы запуск реконсиляции происходит автоматически в случае внесения изменений в ресурсы либо изменения состояния их зависимостей. -В случае с приложениями принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек приложения возникла терминальная ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. +В случае с приложениями принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек приложения возникла критическая ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. При работе с репозиториями запуск принудительной реконсиляции позволяет выполнить синхронизацию репозитория, не дожидаясь очередного запуска по расписанию. {{< tabs name="force-reconcile-application" >}} {{% tab name="В командной строке" %}} -Для принудительной реконсиляции [`HelmApplication`](/modules/operator-helm/cr.html#helmapplication) выполните команду: +Для принудительной реконсиляции [ресурса HelmApplication](/modules/operator-helm/cr.html#helmapplication) добавьте к нему аннотацию `reconcile.helm.deckhouse.io/force`, выполнив следующую команду: ```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) выполните команду: +Для принудительной реконсиляции [ресурса HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) добавьте к нему аннотацию `reconcile.helm.deckhouse.io/force`, выполнив следующую команду: ```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="В веб-интерфейсе" %}} @@ -458,18 +459,18 @@ d8 k -n test get helmapplication podinfo -o jsonpath='{.status.lastForceReconcil ## Режим обслуживания -Режим обслуживания приостанавливает реконсиляцию приложения, что позволяет вмешаться в релиз вручную, корректируя параметры ранее развёрнутых ресурсов (изменять количество реплик, менять параметры и другое). +Режим обслуживания приостанавливает реконсиляцию приложения, что позволяет скорректировать релиз вручную, изменив параметры ранее развёрнутых ресурсов (количество реплик и другие параметры). {{< 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}' @@ -481,13 +482,13 @@ d8 k -n test get helmapplication podinfo -o jsonpath='{.status.conditions[?(@.ty 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}' From 750cc756937be9837ee3f44d6af58fa11e709a0f Mon Sep 17 00:00:00 2001 From: Max Chervov Date: Wed, 30 Sep 2026 17:12:05 +0300 Subject: [PATCH 08/10] Edit CRD descriptions Signed-off-by: Max Chervov --- crds/doc-ru-helmapplicationcharts.yaml | 57 +++++++++-- crds/doc-ru-helmapplicationrepositories.yaml | 51 +++++++--- crds/doc-ru-helmapplications.yaml | 68 +++++++++---- crds/doc-ru-helmclusteraddoncharts.yaml | 57 +++++++++-- crds/doc-ru-helmclusteraddonrepositories.yaml | 50 +++++++--- crds/doc-ru-helmclusteraddons.yaml | 55 ++++++++--- crds/doc-ru-helmclusterapplicationcharts.yaml | 57 +++++++++-- ...ru-helmclusterapplicationrepositories.yaml | 50 +++++++--- crds/helmapplicationcharts.yaml | 76 +++++++-------- crds/helmapplicationrepositories.yaml | 70 ++++++------- crds/helmapplications.yaml | 97 ++++++++----------- crds/helmclusteraddoncharts.yaml | 72 +++++++------- crds/helmclusteraddonrepositories.yaml | 70 ++++++------- crds/helmclusteraddons.yaml | 80 +++++++-------- crds/helmclusterapplicationcharts.yaml | 76 +++++++-------- crds/helmclusterapplicationrepositories.yaml | 69 ++++++------- 16 files changed, 629 insertions(+), 426 deletions(-) diff --git a/crds/doc-ru-helmapplicationcharts.yaml b/crds/doc-ru-helmapplicationcharts.yaml index 1af34170..ba51148c 100644 --- a/crds/doc-ru-helmapplicationcharts.yaml +++ b/crds/doc-ru-helmapplicationcharts.yaml @@ -8,27 +8,66 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationChart представляет собой Helm-чарт, обнаруженный в HelmApplicationRepository. Эти ресурсы создаются автоматически во время синхронизации репозитория и защищены от изменений. + description: |- + HelmApplicationChart описывает Helm-чарт, обнаруженный в HelmApplicationRepository. + + Ресурсы HelmApplicationChart создаются и обновляются контроллером автоматически во время синхронизации репозитория и не предназначены для изменения вручную. properties: status: properties: iconURL: - description: URL-адрес иконки Helm-чарта. Применимо только для чартов из Helm-репозиториев. + description: |- + URL-адрес иконки Helm-чарта. + + Применимо только для чартов из Helm-репозиториев. conditions: - description: Условия отражают последние наблюдения за состоянием чарта. + description: Условия, отражающие текущее состояние Helm-чарта. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. versions: - description: Список всех версий Helm-чарта, изученных контроллером. Версия пригодна к использованию, если у неё нет unavailableReason; для OCI-репозитория у пригодной версии также заполнен media type слоя, который её содержит. + description: |- + Список обнаруженных версий Helm-чарта. + + Версия доступна для установки, если поле `unavailableReason` не заполнено. + Для версий из OCI-репозитория также должен быть указан поддерживаемый media type слоя. items: properties: version: description: Версия Helm-чарта. ociRef: - description: "OCI-ссылка, по которой опубликована эта версия, записанная из индекса репозитория. Заполняется только для версии helm-репозитория, чья запись в индексе указывает на OCI-репозиторий вместо архива чарта: такая версия раскатывается через внутренний OCIRepository, хотя её репозиторий — helm." + description: |- + OCI-ссылка на опубликованную версию Helm-чарта. + + Заполняется только для версии из Helm-репозитория, если соответствующая запись в индексе репозитория ссылается на OCI-репозиторий вместо архива чарта. + Такая версия устанавливается с помощью внутреннего OCIRepository. mediaType: - description: "OCI media type слоя, содержащего эту версию чарта. Заполняется только для версии oci://-репозитория и только когда слой поддерживается: пустое значение там означает, что версию нельзя задеплоить." + description: |- + OCI media type слоя, содержащего версию Helm-чарта. + + Заполняется только для версий из OCI-репозитория (`oci://`) с поддерживаемым типом слоя. + Если поле не заполнено, версия недоступна для установки. unavailableReason: - description: Причина, по которой версию нельзя задеплоить. Отсутствие поля означает, что версия пригодна. + description: |- + Причина, по которой версия Helm-чарта недоступна для установки. + + Если поле не заполнено, версия доступна. unavailableMessage: - description: Человекочитаемые подробности к unavailableReason. + description: Подробное описание причины, указанной в `unavailableReason`. diff --git a/crds/doc-ru-helmapplicationrepositories.yaml b/crds/doc-ru-helmapplicationrepositories.yaml index 2c5c5c51..44f9d8b6 100644 --- a/crds/doc-ru-helmapplicationrepositories.yaml +++ b/crds/doc-ru-helmapplicationrepositories.yaml @@ -8,7 +8,8 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationRepository представляет собой Helm- или OCI-совместимый репозиторий, содержащий Helm-чарты, на которые могут ссылаться ресурсы HelmApplication из того же пространства имён. + description: |- + HelmApplicationRepository описывает Helm- или OCI-совместимый репозиторий с Helm-чартами, на которые могут ссылаться ресурсы HelmApplication из того же неймспейса. properties: spec: properties: @@ -20,29 +21,55 @@ spec: username: description: Имя пользователя для аутентификации в репозитории. caCertificate: - description: CA-сертификат в формате PEM для проверки TLS. + description: CA-сертификат в формате PEM для проверки TLS-сертификата репозитория. insecureSkipVerify: - description: Выключить проверку TLS-сертификата. + description: Отключает проверку TLS-сертификата репозитория. url: description: | - URL Helm-репозитория. + URL-адрес Helm- или OCI-совместимого репозитория. - Поддерживаются протоколы `http(s)://` и `oci://`. + Поддерживаются схемы `http(s)://` и `oci://`. status: properties: conditions: - description: Условия отражают последние наблюдения за состоянием репозитория. + description: Условия, отражающие текущее состояние репозитория. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. lastSuccessfulSyncTime: - description: Время последнего успешного приведения каталога чартов в актуальное состояние. + description: Время последней успешной синхронизации репозитория. nextSyncTime: - description: Запланированное время следующей попытки синхронизации. + description: Запланированное время следующей попытки синхронизации репозитория. lastForceReconcileTime: description: | - Время обработки последнего запроса принудительной реконсиляции. Фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражают `Ready` и `Synced`. + Время обработки последнего запроса на принудительную реконсиляцию. + + Значение поля указывает на то, что запрос был обработан, но не свидетельствует об успешном завершении реконсиляции. + Результат реконсиляции отображается в условиях `Ready` и `Synced`. consecutiveFetchFailures: - description: Число подряд идущих неудачных обращений к репозиторию. Определяет задержку повтора и обнуляется при первом успехе. + description: |- + Количество последовательных неудачных обращений к репозиторию. + + Используется для определения задержки перед следующей попыткой и сбрасывается после успешного обращения. chartCount: description: | - Число чартов, которые репозиторий предлагал при последнем успешном чтении. Отсутствует, пока успешного чтения не было, поэтому репозиторий, который ещё не читали, отличим от репозитория без чартов. + Количество чартов, обнаруженных при последней успешной синхронизации репозитория. + + Поле не заполняется до первой успешной синхронизации, что позволяет отличить ещё не синхронизированный репозиторий от репозитория, в котором нет чартов. diff --git a/crds/doc-ru-helmapplications.yaml b/crds/doc-ru-helmapplications.yaml index 308b5986..cface966 100644 --- a/crds/doc-ru-helmapplications.yaml +++ b/crds/doc-ru-helmapplications.yaml @@ -8,7 +8,14 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplication представляет собой установку Helm-чарта в пределах одного пространства имён. Релиз развёртывается в том же пространстве имён, где создан ресурс. Чарт применяется от имени ServiceAccount, связанного с Role, дающей все права внутри этого пространства имён, поэтому право создавать HelmApplication эквивалентно правам администратора пространства имён; Role и RoleBinding принадлежат модулю и реконсилируются, поэтому правка любого из них не переживает приложение, которому он нужен. + description: |- + HelmApplication описывает Helm-релиз в пределах одного неймспейса. + + Релиз развёртывается в том же неймспейсе, в котором создан ресурс HelmApplication. + + Для развёртывания чарта используется ServiceAccount с правами на выполнение любых операций со всеми ресурсами в этом неймспейсе. Поэтому для создания HelmApplication требуются права администратора неймспейса. + + Связанные с ServiceAccount ресурсы Role и RoleBinding управляются модулем и автоматически приводятся к заданному состоянию при реконсиляции. Изменения, внесённые в эти ресурсы вручную, будут перезаписаны. properties: spec: properties: @@ -16,42 +23,67 @@ spec: properties: name: description: | - Имя Helm-чарта для установки из указанного репозитория (например, «nginx» или «redis»). + Имя Helm-чарта для установки из указанного репозитория (например, `nginx` или `redis`). repository: description: | - Имя ресурса HelmApplicationRepository в том же пространстве имён, содержащего параметры подключения и учётные данные для доступа к репозиторию, в котором расположен чарт. + Имя ресурса HelmApplicationRepository в том же неймспейсе. + + Указанный репозиторий используется как источник Helm-чарта. clusterRepository: description: | - Имя кластерного ресурса HelmClusterApplicationRepository, содержащего параметры подключения и учётные данные для доступа к репозиторию, в котором расположен чарт. + Имя ресурса HelmClusterApplicationRepository. + + Указанный репозиторий используется как источник Helm-чарта. version: - description: Версия Helm-чарта для HelmApplication. + description: Версия Helm-чарта для установки. maintenance: description: | - Стратегия согласования ресурса. + Режим согласования ресурса. - При значении `NoResourceReconciliation` контроллер прекращает обновление управляемых ресурсов, что позволяет выполнять ручное вмешательство или обслуживание без перезаписи изменений оператором. - При пустом значении (`""`) используется стандартное согласование. + При значении `NoResourceReconciliation` контроллер приостанавливает согласование управляемых ресурсов, что позволяет изменять их вручную без перезаписи изменений контроллером. + При пустом значении (`""`) используется стандартный режим согласования. values: - description: Пользовательские значения для релиза HelmApplication. + description: Пользовательские значения Helm-чарта. status: properties: conditions: - description: Условия отражают последние наблюдения за состоянием ресурса. + description: Условия, отражающие текущее состояние ресурса. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. lastAppliedChart: - description: Последний применённый чарт, инициировавший установку или обновление приложения. + description: Helm-чарт, использованный при последней установке или обновлении приложения. properties: name: - description: Имя Helm-чарта, из которого последний раз развёртывался релиз. + description: Имя Helm-чарта, использованного при последней установке или обновлении приложения. repository: - description: Имя ресурса HelmApplicationRepository, из которого последний раз был взят чарт. + description: Имя ресурса HelmApplicationRepository, использованного при последней установке или обновлении приложения. clusterRepository: - description: Имя ресурса HelmClusterApplicationRepository, из которого последний раз был взят чарт. + description: Имя ресурса HelmClusterApplicationRepository, использованного при последней установке или обновлении приложения. version: - description: Версия Helm-чарта, из которой последний раз развёртывался релиз. + description: Версия Helm-чарта, использованная при последней установке или обновлении приложения. lastAppliedValues: - description: Последние применённые значения, инициировавшие установку или обновление приложения. + description: Пользовательские значения Helm-чарта, использованные при последней установке или обновлении приложения. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. lastForceReconcileTime: description: | - Время обработки последнего запроса принудительной реконсиляции. Фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражает `Ready`. + Время обработки последнего запроса на принудительную реконсиляцию. + + Значение поля указывает на то, что запрос был обработан, но не свидетельствует об успешном завершении реконсиляции. + Результат реконсиляции отображается в условии `Ready`. diff --git a/crds/doc-ru-helmclusteraddoncharts.yaml b/crds/doc-ru-helmclusteraddoncharts.yaml index ab763f74..bf5d2086 100644 --- a/crds/doc-ru-helmclusteraddoncharts.yaml +++ b/crds/doc-ru-helmclusteraddoncharts.yaml @@ -8,27 +8,66 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonChart представляет собой Helm-чарт, обнаруженный в HelmClusterAddonRepository. Эти ресурсы создаются автоматически во время синхронизации репозитория и защищены от изменений. + description: |- + HelmClusterAddonChart описывает Helm-чарт, обнаруженный в HelmClusterAddonRepository. + + Ресурсы HelmClusterAddonChart создаются и обновляются контроллером автоматически во время синхронизации репозитория и не предназначены для изменения вручную. properties: status: properties: iconURL: - description: URL-адрес иконки Helm-чарта. Применимо только для чартов из Helm-репозиториев. + description: |- + URL-адрес иконки Helm-чарта. + + Применимо только для чартов из Helm-репозиториев. conditions: - description: Условия отражают последние наблюдения за состоянием чарта. + description: Условия, отражающие текущее состояние Helm-чарта. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. versions: - description: Список всех версий Helm-чарта, изученных контроллером. Версия пригодна к использованию, если у неё нет unavailableReason; для OCI-репозитория у пригодной версии также заполнен media type слоя, который её содержит. + description: |- + Список обнаруженных версий Helm-чарта. + + Версия доступна для установки, если поле `unavailableReason` не заполнено. + Для версий из OCI-репозитория также должен быть указан поддерживаемый media type слоя. items: properties: version: description: Версия Helm-чарта. ociRef: - description: "OCI-ссылка, по которой опубликована эта версия, записанная из индекса репозитория. Заполняется только для версии helm-репозитория, чья запись в индексе указывает на OCI-репозиторий вместо архива чарта: такая версия раскатывается через внутренний OCIRepository, хотя её репозиторий — helm." + description: |- + OCI-ссылка на опубликованную версию Helm-чарта. + + Заполняется только для версии из Helm-репозитория, если соответствующая запись в индексе репозитория ссылается на OCI-репозиторий вместо архива чарта. + Такая версия устанавливается с помощью внутреннего OCIRepository. mediaType: - description: "OCI media type слоя, содержащего эту версию чарта. Заполняется только для версии oci://-репозитория и только когда слой поддерживается: пустое значение там означает, что версию нельзя задеплоить." + description: |- + OCI media type слоя, содержащего версию Helm-чарта. + + Заполняется только для версий из OCI-репозитория (`oci://`) с поддерживаемым типом слоя. + Если поле не заполнено, версия недоступна для установки. unavailableReason: - description: Причина, по которой версию нельзя задеплоить. Отсутствие поля означает, что версия пригодна. + description: |- + Причина, по которой версия Helm-чарта недоступна для установки. + + Если поле не заполнено, версия доступна. unavailableMessage: - description: Человекочитаемые подробности к unavailableReason. + description: Подробное описание причины, указанной в `unavailableReason`. diff --git a/crds/doc-ru-helmclusteraddonrepositories.yaml b/crds/doc-ru-helmclusteraddonrepositories.yaml index d0073763..352411d2 100644 --- a/crds/doc-ru-helmclusteraddonrepositories.yaml +++ b/crds/doc-ru-helmclusteraddonrepositories.yaml @@ -8,7 +8,7 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonRepository представляет собой Helm- или OCI-совместимый репозиторий, содержащий Helm-чарты, на которые могут ссылаться ресурсы HelmClusterAddon. + description: HelmClusterAddonRepository описывает Helm- или OCI-совместимый репозиторий с Helm-чартами, на которые могут ссылаться ресурсы HelmClusterAddon. properties: spec: properties: @@ -20,29 +20,55 @@ spec: username: description: Имя пользователя для аутентификации в репозитории. caCertificate: - description: CA-сертификат в формате PEM для проверки TLS. + description: CA-сертификат в формате PEM для проверки TLS-сертификата репозитория. insecureSkipVerify: - description: Выключить проверку TLS-сертификата. + description: Отключает проверку TLS-сертификата репозитория. url: description: | - URL Helm-репозитория. + URL-адрес Helm- или OCI-совместимого репозитория. - Поддерживаются протоколы `http(s)://` и `oci://`. + Поддерживаются схемы `http(s)://` и `oci://`. status: properties: conditions: - description: Условия отражают последние наблюдения за состоянием репозитория. + description: Условия, отражающие текущее состояние репозитория. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. lastSuccessfulSyncTime: - description: Время последнего успешного приведения каталога чартов в актуальное состояние. + description: Время последней успешной синхронизации репозитория. nextSyncTime: - description: Запланированное время следующей попытки синхронизации. + description: Запланированное время следующей попытки синхронизации репозитория. lastForceReconcileTime: description: | - Время обработки последнего запроса принудительной реконсиляции. Фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражают `Ready` и `Synced`. + Время обработки последнего запроса на принудительную реконсиляцию. + + Значение поля указывает на то, что запрос был обработан, но не свидетельствует об успешном завершении реконсиляции. + Результат реконсиляции отображается в условиях `Ready` и `Synced`. consecutiveFetchFailures: - description: Число подряд идущих неудачных обращений к репозиторию. Определяет задержку повтора и обнуляется при первом успехе. + description: |- + Количество последовательных неудачных обращений к репозиторию. + + Используется для определения задержки перед следующей попыткой и сбрасывается после успешного обращения. chartCount: description: | - Число чартов, которые репозиторий предлагал при последнем успешном чтении. Отсутствует, пока успешного чтения не было, поэтому репозиторий, который ещё не читали, отличим от репозитория без чартов. + Количество чартов, обнаруженных при последней успешной синхронизации репозитория. + + Поле не заполняется до первой успешной синхронизации, что позволяет отличить ещё не синхронизированный репозиторий от репозитория, в котором нет чартов. diff --git a/crds/doc-ru-helmclusteraddons.yaml b/crds/doc-ru-helmclusteraddons.yaml index e9ef696e..648ba79f 100644 --- a/crds/doc-ru-helmclusteraddons.yaml +++ b/crds/doc-ru-helmclusteraddons.yaml @@ -8,7 +8,11 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddon представляет собой единичный экземпляр установки Helm-чарта в масштабе всего кластера, который может включать в себя определения пользовательских ресурсов (CRD) и требует прав cluster-admin для развертывания. В каждый момент времени может быть установлен только один экземпляр конкретного чарта. + description: |- + HelmClusterAddon описывает Helm-релиз, управляемый на уровне кластера. + + Helm-чарт может содержать CRD и другие cluster-wide-ресурсы, поэтому для создания HelmClusterAddon требуются права `ClusterAdmin`. + Для одного Helm-чарта из определённого репозитория в кластере может существовать только один ресурс HelmClusterAddon. properties: spec: properties: @@ -16,28 +20,48 @@ spec: properties: helmClusterAddonChart: description: | - Имя Helm-чарта для установки из указанного репозитория (например, «ingress-nginx» или «redis»). + Имя Helm-чарта для установки из указанного репозитория (например, `ingress-nginx` или `redis`). helmClusterAddonRepository: description: | - Имя ресурса HelmClusterAddonRepository, содержащего параметры подключения и учётные данные для доступа к репозиторию, в котором расположен чарт. + Имя ресурса HelmClusterAddonRepository. + + Указанный репозиторий используется как источник Helm-чарта. version: - description: Версия Helm-чарта для HelmClusterAddon. + description: Версия Helm-чарта для установки. maintenance: description: | - Стратегия согласования ресурса. + Режим согласования ресурса. - При значении `NoResourceReconciliation` контроллер прекращает обновление управляемых ресурсов, что позволяет выполнять ручное вмешательство или обслуживание без перезаписи изменений оператором. - При пустом значении (`""`) используется стандартное согласование. + При значении `NoResourceReconciliation` контроллер приостанавливает согласование управляемых ресурсов, что позволяет изменять их вручную без перезаписи изменений контроллером. + При пустом значении (`""`) используется стандартный режим согласования. namespace: - description: Пространство имён для развёртывания релиза аддона. + description: Неймспейс для развёртывания релиза аддона. values: - description: Пользовательские значения для релиза HelmClusterAddon. + description: Пользовательские значения Helm-чарта. status: properties: conditions: - description: Условия отражают последние наблюдения за состоянием ресурса. + description: Условия, отражающие текущее состояние ресурса. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. lastAppliedChart: - description: Последний применённый чарт, инициировавший установку или обновление аддона. + description: Helm-чарт, использованный при последней установке или обновлении аддона. properties: helmClusterAddonChart: description: Имя Helm-чарта. @@ -46,9 +70,12 @@ spec: version: description: Версия Helm-чарта. lastAppliedValues: - description: Последние применённые значения, инициировавшие установку или обновление аддона. + description: Пользовательские значения Helm-чарта, использованные при последней установке или обновлении аддона. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. lastForceReconcileTime: description: | - Время обработки последнего запроса принудительной реконсиляции. Фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражает `Ready`. + Время обработки последнего запроса на принудительную реконсиляцию. + + Значение поля указывает на то, что запрос был обработан, но не свидетельствует об успешном завершении реконсиляции. + Результат реконсиляции отображается в условии `Ready`. diff --git a/crds/doc-ru-helmclusterapplicationcharts.yaml b/crds/doc-ru-helmclusterapplicationcharts.yaml index 4e616efd..59fb2787 100644 --- a/crds/doc-ru-helmclusterapplicationcharts.yaml +++ b/crds/doc-ru-helmclusterapplicationcharts.yaml @@ -8,27 +8,66 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationChart представляет собой Helm-чарт, обнаруженный в HelmClusterApplicationRepository. Эти ресурсы создаются автоматически во время синхронизации репозитория и защищены от изменений. + description: |- + HelmClusterApplicationChart описывает Helm-чарт, обнаруженный в HelmClusterApplicationRepository. + + Ресурсы HelmClusterApplicationChart создаются и обновляются контроллером автоматически во время синхронизации репозитория и не предназначены для изменения вручную. properties: status: properties: iconURL: - description: URL-адрес иконки Helm-чарта. Применимо только для чартов из Helm-репозиториев. + description: |- + URL-адрес иконки Helm-чарта. + + Применимо только для чартов из Helm-репозиториев. conditions: - description: Условия отражают последние наблюдения за состоянием чарта. + description: Условия, отражающие текущее состояние Helm-чарта. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. versions: - description: Список всех версий Helm-чарта, изученных контроллером. Версия пригодна к использованию, если у неё нет unavailableReason; для OCI-репозитория у пригодной версии также заполнен media type слоя, который её содержит. + description: |- + Список обнаруженных версий Helm-чарта. + + Версия доступна для установки, если поле `unavailableReason` не заполнено. + Для версий из OCI-репозитория также должен быть указан поддерживаемый media type слоя. items: properties: version: description: Версия Helm-чарта. ociRef: - description: "OCI-ссылка, по которой опубликована эта версия, записанная из индекса репозитория. Заполняется только для версии helm-репозитория, чья запись в индексе указывает на OCI-репозиторий вместо архива чарта: такая версия раскатывается через внутренний OCIRepository, хотя её репозиторий — helm." + description: |- + OCI-ссылка на опубликованную версию Helm-чарта. + + Заполняется только для версии из Helm-репозитория, если соответствующая запись в индексе репозитория ссылается на OCI-репозиторий вместо архива чарта. + Такая версия устанавливается с помощью внутреннего OCIRepository. mediaType: - description: "OCI media type слоя, содержащего эту версию чарта. Заполняется только для версии oci://-репозитория и только когда слой поддерживается: пустое значение там означает, что версию нельзя задеплоить." + description: |- + OCI media type слоя, содержащего версию Helm-чарта. + + Заполняется только для версий из OCI-репозитория (`oci://`) с поддерживаемым типом слоя. + Если поле не заполнено, версия недоступна для установки. unavailableReason: - description: Причина, по которой версию нельзя задеплоить. Отсутствие поля означает, что версия пригодна. + description: |- + Причина, по которой версия Helm-чарта недоступна для установки. + + Если поле не заполнено, версия доступна. unavailableMessage: - description: Человекочитаемые подробности к unavailableReason. + description: Подробное описание причины, указанной в `unavailableReason`. diff --git a/crds/doc-ru-helmclusterapplicationrepositories.yaml b/crds/doc-ru-helmclusterapplicationrepositories.yaml index 3fbaf1b5..24960768 100644 --- a/crds/doc-ru-helmclusterapplicationrepositories.yaml +++ b/crds/doc-ru-helmclusterapplicationrepositories.yaml @@ -8,7 +8,7 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationRepository представляет собой кластерный Helm- или OCI-совместимый репозиторий, содержащий Helm-чарты, на которые могут ссылаться ресурсы HelmApplication из любого пространства имён. + description: HelmClusterApplicationRepository описывает Helm- или OCI-совместимый репозиторий с Helm-чартами, на которые могут ссылаться ресурсы HelmApplication из любого неймспейса. properties: spec: properties: @@ -20,29 +20,55 @@ spec: username: description: Имя пользователя для аутентификации в репозитории. caCertificate: - description: CA-сертификат в формате PEM для проверки TLS. + description: CA-сертификат в формате PEM для проверки TLS-сертификата репозитория. insecureSkipVerify: - description: Выключить проверку TLS-сертификата. + description: Отключает проверку TLS-сертификата репозитория. url: description: | - URL Helm-репозитория. + URL-адрес Helm- или OCI-совместимого репозитория. - Поддерживаются протоколы `http(s)://` и `oci://`. + Поддерживаются схемы `http(s)://` и `oci://`. status: properties: conditions: - description: Условия отражают последние наблюдения за состоянием репозитория. + description: Условия, отражающие текущее состояние репозитория. + items: + properties: + lastTransitionTime: + description: |- + Время последнего изменения состояния условия. + message: + description: |- + Сообщение с дополнительной информацией о состоянии условия. + observedGeneration: + description: |- + Поколение ресурса, на основе которого сформировано состояние условия. + reason: + description: |- + Причина последнего изменения состояния условия. + status: + description: Состояние условия. + type: + description: Тип условия. observedGeneration: - description: Поколение ресурса, обработанное контроллером последним. + description: Последнее поколение ресурса, обработанное контроллером. lastSuccessfulSyncTime: - description: Время последнего успешного приведения каталога чартов в актуальное состояние. + description: Время последней успешной синхронизации репозитория. nextSyncTime: - description: Запланированное время следующей попытки синхронизации. + description: Запланированное время следующей попытки синхронизации репозитория. lastForceReconcileTime: description: | - Время обработки последнего запроса принудительной реконсиляции. Фиксирует, что запрос был обработан, а не что он завершился успешно — результат отражают `Ready` и `Synced`. + Время обработки последнего запроса на принудительную реконсиляцию. + + Значение поля указывает на то, что запрос был обработан, но не свидетельствует об успешном завершении реконсиляции. + Результат реконсиляции отображается в условиях `Ready` и `Synced`. consecutiveFetchFailures: - description: Число подряд идущих неудачных обращений к репозиторию. Определяет задержку повтора и обнуляется при первом успехе. + description: |- + Количество последовательных неудачных обращений к репозиторию. + + Используется для определения задержки перед следующей попыткой и сбрасывается после успешного обращения. chartCount: description: | - Число чартов, которые репозиторий предлагал при последнем успешном чтении. Отсутствует, пока успешного чтения не было, поэтому репозиторий, который ещё не читали, отличим от репозитория без чартов. + Количество чартов, обнаруженных при последней успешной синхронизации репозитория. + + Поле не заполняется до первой успешной синхронизации, что позволяет отличить ещё не синхронизированный репозиторий от репозитория, в котором нет чартов. diff --git a/crds/helmapplicationcharts.yaml b/crds/helmapplicationcharts.yaml index fc78c06f..ce9eaf6e 100644 --- a/crds/helmapplicationcharts.yaml +++ b/crds/helmapplicationcharts.yaml @@ -20,9 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationChart represents a specific Helm chart discovered - within a HelmApplicationRepository. These resources are automatically managed - during repository synchronization and are immutable to user modifications. + description: |- + HelmApplicationChart describes a Helm chart discovered in a HelmApplicationRepository. + + HelmApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -31,6 +32,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -39,57 +41,50 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -102,43 +97,46 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: |- + Detailed description of the reason specified in `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -146,7 +144,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmapplicationrepositories.yaml b/crds/helmapplicationrepositories.yaml index 13086c9d..cb5405bf 100644 --- a/crds/helmapplicationrepositories.yaml +++ b/crds/helmapplicationrepositories.yaml @@ -45,9 +45,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationRepository represents a Helm or OCI-compliant - repository containing Helm charts that can be referenced by HelmApplication - resources from the same namespace. + description: HelmApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from the same namespace. properties: apiVersion: description: |- @@ -56,6 +54,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -64,12 +63,14 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -84,15 +85,16 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -105,58 +107,49 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -170,31 +163,30 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization - attempt. + description: Scheduled time of the next repository synchronization attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmapplications.yaml b/crds/helmapplications.yaml index 923bd1d5..da2c8ebc 100644 --- a/crds/helmapplications.yaml +++ b/crds/helmapplications.yaml @@ -46,13 +46,14 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplication represents an installation of a Helm chart inside - a single namespace. The release is deployed into the namespace of the resource - itself. The chart is applied with a ServiceAccount bound to a Role that - grants every permission inside that namespace, so the right to create a - HelmApplication is equivalent to administrator rights in its namespace; - the Role and the binding belong to the module and are reconciled, so an - edit to either does not outlast the application that needs it. + description: |- + HelmApplication describes a Helm release within a single namespace. + + The release is deployed in the same namespace as the HelmApplication resource. + + The chart is deployed using a ServiceAccount with permissions to perform any operation on all resources in the namespace. Therefore, namespace administrator permissions are required to create a HelmApplication. + + The Role and RoleBinding associated with the ServiceAccount are managed by the module and automatically reconciled to their desired state. Any manual changes to these resources are overwritten. properties: apiVersion: description: |- @@ -61,6 +62,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -69,36 +71,37 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true spec: properties: chart: properties: clusterRepository: description: |- - Specifies the name of the cluster-wide HelmClusterApplicationRepository custom - resource that contains the connection details and credentials for the - repository where the chart is located. + Name of the HelmClusterApplicationRepository resource. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 3 type: string name: description: |- - Specifies the name of the Helm chart to be installed - from the referenced repository (e.g., "nginx" or "redis"). + Name of the Helm chart in the specified repository (for example, `nginx` or `redis`). minLength: 1 type: string repository: description: |- - Specifies the name of the HelmApplicationRepository custom resource in the same - namespace that contains the connection details and credentials for the - repository where the chart is located. + Name of the HelmApplicationRepository resource in the same namespace. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 3 type: string version: - description: Version holds the HelmApplication chart version. + description: Helm chart version to install. minLength: 1 type: string required: @@ -111,17 +114,16 @@ spec: rule: has(self.repository) != has(self.clusterRepository) maintenance: description: |- - Maintenance specifies the reconciliation strategy for the resource. - When set to "NoResourceReconciliation", the controller will stop updating the - underlying resources, allowing for manual intervention or maintenance - without the operator overwriting changes. - When empty (""), standard reconciliation is active. + Resource reconciliation mode. + + When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + When set to an empty value (`""`), the standard reconciliation mode is used. enum: - "" - NoResourceReconciliation type: string values: - description: Values holds the values for this HelmApplication release. + description: Custom Helm chart values. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -129,52 +131,43 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the application state. + description: Conditions reflecting the current state of the resource. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -187,42 +180,36 @@ spec: type: object type: array lastAppliedChart: - description: LastAppliedChart represents the latest chart that triggered - application install or update. + description: Helm chart used during the last application installation or upgrade. properties: clusterRepository: description: |- - Specifies the name of the HelmClusterApplicationRepository custom resource the - chart was last taken from. + Name of the HelmClusterApplicationRepository resource used during the last application installation or upgrade. type: string name: - description: Specifies the name of the Helm chart the release - was last deployed from. + description: Name of the Helm chart used during the last application installation or upgrade. type: string repository: description: |- - Specifies the name of the HelmApplicationRepository custom resource the chart - was last taken from. + Name of the HelmApplicationRepository resource used during the last application installation or upgrade. type: string version: - description: Version holds the chart version the release was last - deployed from. + description: Helm chart version used during the last application installation or upgrade. type: string type: object lastAppliedValues: - description: LastAppliedValues represents the latest values that triggered - application install or update. + description: Custom Helm chart values used during the last application installation or upgrade. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` condition. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddoncharts.yaml b/crds/helmclusteraddoncharts.yaml index 45c958f2..ca44bf87 100644 --- a/crds/helmclusteraddoncharts.yaml +++ b/crds/helmclusteraddoncharts.yaml @@ -20,9 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonChart represents a specific Helm chart discovered - within a HelmClusterAddonRepository. These resources are automatically managed - during repository synchronization and are immutable to user modifications. + description: |- + HelmClusterAddonChart describes a Helm chart discovered in a HelmClusterAddonRepository. + + HelmClusterAddonChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -31,6 +32,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -39,57 +41,50 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -102,8 +97,10 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: description: Generation represents resource generation that was last @@ -112,33 +109,34 @@ spec: type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: Detailed description of the reason specified in `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -146,7 +144,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmclusteraddonrepositories.yaml b/crds/helmclusteraddonrepositories.yaml index 18bb24dc..7115c005 100644 --- a/crds/helmclusteraddonrepositories.yaml +++ b/crds/helmclusteraddonrepositories.yaml @@ -45,9 +45,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonRepository represents a Helm or OCI-compliant - repository containing Helm charts that can be referenced by HelmClusterAddon - resources. + description: HelmClusterAddonRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources. properties: apiVersion: description: |- @@ -56,6 +54,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -64,12 +63,14 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -84,15 +85,16 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -105,58 +107,49 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -170,31 +163,30 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization - attempt. + description: Scheduled time of the next repository synchronization attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddons.yaml b/crds/helmclusteraddons.yaml index 6a31b1e8..3e33d509 100644 --- a/crds/helmclusteraddons.yaml +++ b/crds/helmclusteraddons.yaml @@ -33,6 +33,11 @@ spec: name: v1alpha1 schema: openAPIV3Schema: + description: |- + HelmClusterAddon describes a Helm release managed at the cluster level. + + The Helm chart may contain CRDs and other cluster-wide resources, so `ClusterAdmin` permissions are required to create a HelmClusterAddon. + Only one HelmClusterAddon resource can exist in the cluster for a given Helm chart from a specific repository. properties: apiVersion: description: |- @@ -41,6 +46,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -49,28 +55,29 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true spec: properties: chart: properties: helmClusterAddonChart: description: |- - Specifies the name of the Helm chart to be installed - from the defined repository (e.g., "ingress-nginx" or "redis"). + Name of the Helm chart in the specified repository (for example, `ingress-nginx` or `redis`). minLength: 1 type: string helmClusterAddonRepository: description: |- - Specifies the name of the HelmClusterAddonRepository custom resource that contains - the connection details and credentials for the repository where - the chart is located. + Name of the HelmClusterAddonRepository resource. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 1 type: string version: - description: Versions holds the HelmClusterAddon chart version. + description: Helm chart version to install. type: string required: - helmClusterAddonChart @@ -79,23 +86,22 @@ spec: type: object maintenance: description: |- - Maintenance specifies the reconciliation strategy for the resource. - When set to "NoResourceReconciliation", the controller will stop updating the - underlying resources, allowing for manual intervention or maintenance - without the operator overwriting changes. - When empty (""), standard reconciliation is active. + Resource reconciliation mode. + + When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + When set to an empty value (`""`), the standard reconciliation mode is used. enum: - "" - NoResourceReconciliation type: string namespace: default: default - description: Namespace to deploy cluster addon release + description: Namespace to deploy a cluster addon release into. maxLength: 63 minLength: 3 type: string values: - description: Values holds the values for this HelmClusterAddon release. + description: Custom Helm chart values. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -103,52 +109,43 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the addon state. + description: Conditions reflecting the current state of the resource. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -161,38 +158,33 @@ spec: type: object type: array lastAppliedChart: - description: LastAppliedChart represents the latest chart that triggered - addon install or update. + description: Helm chart used during the last addon installation or upgrade. properties: helmClusterAddonChart: description: |- - Specifies the name of the Helm chart to be installed - from the defined repository (e.g., "ingress-nginx" or "redis"). + Helm chart name. type: string helmClusterAddonRepository: description: |- - Specifies the name of the HelmClusterAddonRepository custom resource that contains - the connection details and credentials for the repository where - the chart is located. + Name of the HelmClusterAddonRepository resource. type: string version: - description: Versions holds the HelmClusterAddon chart version. + description: Helm chart version. type: string type: object lastAppliedValues: - description: LastAppliedValues represents the latest values that triggered - addon install or update. + description: Custom Helm chart values used during the last addon installation or upgrade. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` condition. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusterapplicationcharts.yaml b/crds/helmclusterapplicationcharts.yaml index 7a2e9283..60d3a086 100644 --- a/crds/helmclusterapplicationcharts.yaml +++ b/crds/helmclusterapplicationcharts.yaml @@ -20,10 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationChart represents a specific Helm chart - discovered within a HelmClusterApplicationRepository. These resources are - automatically managed during repository synchronization and are immutable - to user modifications. + description: |- + HelmClusterApplicationChart describes a Helm chart discovered in a HelmClusterApplicationRepository. + + HelmClusterApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -32,6 +32,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -40,57 +41,50 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -103,43 +97,45 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: Detailed description of the reason specified in `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -147,7 +143,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmclusterapplicationrepositories.yaml b/crds/helmclusterapplicationrepositories.yaml index cba2d039..9611642f 100644 --- a/crds/helmclusterapplicationrepositories.yaml +++ b/crds/helmclusterapplicationrepositories.yaml @@ -45,9 +45,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationRepository represents a cluster-wide Helm - or OCI-compliant repository containing Helm charts that can be referenced - by HelmApplication resources from any namespace. + description: HelmClusterApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from any namespace. properties: apiVersion: description: |- @@ -56,6 +54,7 @@ spec: may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources type: string + x-doc-skip: true kind: description: |- Kind is a string value representing the REST resource this object represents. @@ -64,12 +63,14 @@ spec: In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds type: string + x-doc-skip: true metadata: type: object + x-doc-skip: true spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -84,15 +85,16 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -105,58 +107,49 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: description: |- - lastTransitionTime is the last time the condition transitioned from one status to another. - This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + Time when the condition status last changed. format: date-time type: string message: description: |- - message is a human readable message indicating details about the transition. - This may be an empty string. + Message with additional information about the condition state. maxLength: 32768 type: string observedGeneration: description: |- - observedGeneration represents the .metadata.generation that the condition was set based upon. - For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date - with respect to the current state of the instance. + Resource generation on which the condition state is based. format: int64 minimum: 0 type: integer reason: description: |- - reason contains a programmatic identifier indicating the reason for the condition's last transition. - Producers of specific condition types may define expected values and meanings for this field, - and whether the values are considered a guaranteed API. - The value should be a CamelCase string. - This field may not be empty. + Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ type: string status: - description: status of the condition, one of True, False, Unknown. + description: Condition status. enum: - "True" - "False" - Unknown type: string type: - description: type of condition in CamelCase or in foo.example.com/CamelCase. + description: Condition type. maxLength: 316 pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string @@ -170,31 +163,31 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization + description: Scheduled time of the next repository synchronization attempt. attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object From 270502e0f475e681c02693a850490f10d356e879 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 7 Oct 2026 11:58:43 +0300 Subject: [PATCH 09/10] feat(tools): finish the generated CRDs for the documentation site controller-gen cannot mark apiVersion, kind and metadata with x-doc-skip, and takes the Condition field descriptions from apimachinery rather than from this module. crddoc rewrites both on the generator's output before it is copied into crds/, through the same JSON-then-yaml.v2 path, so nothing else changes. Signed-off-by: Ilya Drey --- Taskfile.yaml | 8 +- api/scripts/update-codegen.sh | 2 + crds/helmapplicationcharts.yaml | 67 ++-- crds/helmapplicationrepositories.yaml | 61 ++-- crds/helmapplications.yaml | 88 +++--- crds/helmclusteraddoncharts.yaml | 63 ++-- crds/helmclusteraddonrepositories.yaml | 61 ++-- crds/helmclusteraddons.yaml | 71 ++--- crds/helmclusterapplicationcharts.yaml | 67 ++-- crds/helmclusterapplicationrepositories.yaml | 60 ++-- tools/crddoc/.golangci.yaml | 109 +++++++ tools/crddoc/Taskfile.dist.yaml | 21 ++ tools/crddoc/go.mod | 7 + tools/crddoc/go.sum | 10 + tools/crddoc/main.go | 171 ++++++++++ tools/crddoc/main_test.go | 308 +++++++++++++++++++ 16 files changed, 902 insertions(+), 272 deletions(-) create mode 100644 tools/crddoc/.golangci.yaml create mode 100644 tools/crddoc/Taskfile.dist.yaml create mode 100644 tools/crddoc/go.mod create mode 100644 tools/crddoc/go.sum create mode 100644 tools/crddoc/main.go create mode 100644 tools/crddoc/main_test.go diff --git a/Taskfile.yaml b/Taskfile.yaml index 98d9ae61..d1266d61 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -8,7 +8,7 @@ vars: VALIDATION_FILES: "tools/validation/{main,messages,diff,doc_changes}.go" golangciLintVersion: "v2.13.2" -# Only the modules this repository authors are listed, including tools/internalcrds. +# Only the modules this repository authors are listed, including the tools under tools/. # images/kube-api-rewriter is a separate upstream module vendored in for the build, and # images/helm-controller and images/source-controller carry nothing but their werf # files, so none of them is ours to lint, format or test here. The one exception is @@ -33,6 +33,9 @@ includes: internalcrds: taskfile: ./tools/internalcrds/Taskfile.dist.yaml dir: ./tools/internalcrds + crddoc: + taskfile: ./tools/crddoc/Taskfile.dist.yaml + dir: ./tools/crddoc deps: taskfile: https://raw.githubusercontent.com/werf/common-ci/refs/heads/main/Taskfile.deps.yml @@ -140,6 +143,7 @@ tasks: - task: chart-values-controller:test:unit - task: e2e:test:unit - task: internalcrds:test:unit + - task: crddoc:test:unit - task: test:rewrite-rules # The rule table and the generated definitions are two halves of one @@ -217,6 +221,7 @@ tasks: - task: chart-values-controller:format - task: e2e:format - task: internalcrds:format + - task: crddoc:format lint: deps: @@ -228,6 +233,7 @@ tasks: - task: chart-values-controller:lint - task: e2e:lint - task: internalcrds:lint + - task: crddoc:lint - task: lint:doc-ru lint:doc-ru: diff --git a/api/scripts/update-codegen.sh b/api/scripts/update-codegen.sh index b894c7a8..e28ae19b 100755 --- a/api/scripts/update-codegen.sh +++ b/api/scripts/update-codegen.sh @@ -72,6 +72,8 @@ function generate::crds { go tool controller-gen crd paths="${API_ROOT}/v1alpha1/...;" output:crd:dir="${OUTPUT_BASE}" + (cd "${ROOT}/tools/crddoc" && go run . "${OUTPUT_BASE}"/*.yaml) + # shellcheck disable=SC2044 for file in $(find "${OUTPUT_BASE}"/* -type f -iname "*.yaml"); do cp "$file" "${ROOT}/crds/$(echo $file | awk -Fio_ '{print $2}')" diff --git a/crds/helmapplicationcharts.yaml b/crds/helmapplicationcharts.yaml index ce9eaf6e..437c084b 100644 --- a/crds/helmapplicationcharts.yaml +++ b/crds/helmapplicationcharts.yaml @@ -20,10 +20,9 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: |- - HelmApplicationChart describes a Helm chart discovered in a HelmApplicationRepository. - - HelmApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. + description: HelmApplicationChart represents a specific Helm chart discovered + within a HelmApplicationRepository. These resources are automatically managed + during repository synchronization and are immutable to user modifications. properties: apiVersion: description: |- @@ -48,30 +47,29 @@ spec: status: properties: conditions: - description: Conditions reflecting the current state of the Helm chart. + description: Conditions represent the latest available observations + of the chart state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -97,46 +95,43 @@ spec: type: object type: array iconURL: - description: |- - URL of the Helm chart icon. - - Applicable only to charts from Helm repositories. + description: IconURL is the URL to the Helm chart icon (applicable + to Helm Chart repository charts only). type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer versions: description: |- - List of discovered Helm chart versions. - - A version is available for installation if `unavailableReason` is not set. - For versions from an OCI repository, a supported layer media type must also be specified. + Versions lists every chart version the controller has examined. A version is + usable when it has no unavailableReason; for an OCI repository a usable version + also carries the media type of the layer that holds it. items: properties: mediaType: description: |- - OCI media type of the layer containing the Helm chart version. - - Populated only for versions from an OCI repository (`oci://`) with a supported layer type. - If the field is not set, the version is unavailable for installation. + MediaType is the OCI media type of the layer that holds this chart version. It + is set only for a version of an oci:// repository, and only when the layer is + supported: an empty value there means the version cannot be deployed. type: string ociRef: description: |- - OCI reference to the published Helm chart version. - - Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. - Such a version is installed using an internal OCIRepository. + OCIRef is the OCI reference this version is published at, as recorded from + the repository index. It is set only for a version of a helm repository whose + index entry points at a registry instead of a chart archive; such a version is + deployed through an internal OCIRepository even though its repository is a helm + one. type: string unavailableMessage: - description: |- - Detailed description of the reason specified in `unavailableReason`. + description: UnavailableMessage carries human readable detail + for UnavailableReason. type: string unavailableReason: description: |- - Reason why the Helm chart version is unavailable for installation. - - If the field is not set, the version is available. + UnavailableReason explains why this version cannot be deployed. Its absence means + the version is usable. enum: - RemovedFromRepository - UnsupportedMediaType @@ -144,7 +139,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version. + description: Helm chart version minLength: 1 type: string required: diff --git a/crds/helmapplicationrepositories.yaml b/crds/helmapplicationrepositories.yaml index cb5405bf..41b78859 100644 --- a/crds/helmapplicationrepositories.yaml +++ b/crds/helmapplicationrepositories.yaml @@ -45,7 +45,9 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from the same namespace. + description: HelmApplicationRepository represents a Helm or OCI-compliant + repository containing Helm charts that can be referenced by HelmApplication + resources from the same namespace. properties: apiVersion: description: |- @@ -70,7 +72,7 @@ spec: spec: properties: auth: - description: Credentials for repository authentication. + description: Auth contains authentication credentials for the repository. properties: password: description: Repository authentication password. @@ -85,16 +87,15 @@ spec: - username type: object caCertificate: - description: CA certificate in PEM format for verifying the repository TLS certificate. + description: CACertificate is the PEM encoded CA certificate for TLS + verification. type: string insecureSkipVerify: - description: Disables verification of the repository TLS certificate. + description: InsecureSkipVerify disable TLS certificate verification. type: boolean url: - description: |- - URL of the Helm or OCI repository. - - Supported schemes: `http(s)://` and `oci://`. + description: URL of the Helm repository. Supports http(s):// and oci:// + protocols. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -107,36 +108,35 @@ spec: properties: chartCount: description: |- - Number of charts discovered during the last successful repository synchronization. - - The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. + ChartCount is the number of charts the repository offered when it was last read + successfully. It is absent until the first successful read, so a repository that + has never been read is distinguishable from one that offers no charts. format: int32 type: integer conditions: - description: Conditions reflecting the current state of the repository. + description: Conditions represent the latest available observations + of the repository state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -163,30 +163,31 @@ spec: type: array consecutiveFetchFailures: description: |- - Number of consecutive failed attempts to access the repository. - - Used to determine the delay before the next attempt and reset after a successful attempt. + ConsecutiveFetchFailures counts consecutive failures to read from the repository. + It drives the retry backoff and resets on the first success. format: int32 type: integer lastForceReconcileTime: description: |- - Time when the last forced reconciliation request was processed. - - This value indicates that the request was processed but does not indicate that reconciliation completed successfully. - Reconciliation results are reflected in the `Ready` and `Synced` conditions. + LastForceReconcileTime is the time the most recent force reconcile request was + processed. It records that the request was acted on, not that it succeeded: + the outcome is reported by Ready and Synced. format: date-time type: string lastSuccessfulSyncTime: description: |- - Time of the last successful repository synchronization. + LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, + including creating and pruning chart resources. format: date-time type: string nextSyncTime: - description: Scheduled time of the next repository synchronization attempt. + description: NextSyncTime is the scheduled time of the next synchronization + attempt. format: date-time type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmapplications.yaml b/crds/helmapplications.yaml index da2c8ebc..965bd259 100644 --- a/crds/helmapplications.yaml +++ b/crds/helmapplications.yaml @@ -46,14 +46,13 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: |- - HelmApplication describes a Helm release within a single namespace. - - The release is deployed in the same namespace as the HelmApplication resource. - - The chart is deployed using a ServiceAccount with permissions to perform any operation on all resources in the namespace. Therefore, namespace administrator permissions are required to create a HelmApplication. - - The Role and RoleBinding associated with the ServiceAccount are managed by the module and automatically reconciled to their desired state. Any manual changes to these resources are overwritten. + description: HelmApplication represents an installation of a Helm chart inside + a single namespace. The release is deployed into the namespace of the resource + itself. The chart is applied with a ServiceAccount bound to a Role that + grants every permission inside that namespace, so the right to create a + HelmApplication is equivalent to administrator rights in its namespace; + the Role and the binding belong to the module and are reconciled, so an + edit to either does not outlast the application that needs it. properties: apiVersion: description: |- @@ -81,27 +80,28 @@ spec: properties: clusterRepository: description: |- - Name of the HelmClusterApplicationRepository resource. - - The specified repository is used as the Helm chart source. + Specifies the name of the cluster-wide HelmClusterApplicationRepository custom + resource that contains the connection details and credentials for the + repository where the chart is located. maxLength: 63 minLength: 3 type: string name: description: |- - Name of the Helm chart in the specified repository (for example, `nginx` or `redis`). + Specifies the name of the Helm chart to be installed + from the referenced repository (e.g., "nginx" or "redis"). minLength: 1 type: string repository: description: |- - Name of the HelmApplicationRepository resource in the same namespace. - - The specified repository is used as the Helm chart source. + Specifies the name of the HelmApplicationRepository custom resource in the same + namespace that contains the connection details and credentials for the + repository where the chart is located. maxLength: 63 minLength: 3 type: string version: - description: Helm chart version to install. + description: Version holds the HelmApplication chart version. minLength: 1 type: string required: @@ -114,16 +114,17 @@ spec: rule: has(self.repository) != has(self.clusterRepository) maintenance: description: |- - Resource reconciliation mode. - - When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. - When set to an empty value (`""`), the standard reconciliation mode is used. + Maintenance specifies the reconciliation strategy for the resource. + When set to "NoResourceReconciliation", the controller will stop updating the + underlying resources, allowing for manual intervention or maintenance + without the operator overwriting changes. + When empty (""), standard reconciliation is active. enum: - "" - NoResourceReconciliation type: string values: - description: Custom Helm chart values. + description: Values holds the values for this HelmApplication release. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -131,30 +132,29 @@ spec: status: properties: conditions: - description: Conditions reflecting the current state of the resource. + description: Conditions represent the latest available observations + of the application state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -180,36 +180,42 @@ spec: type: object type: array lastAppliedChart: - description: Helm chart used during the last application installation or upgrade. + description: LastAppliedChart represents the latest chart that triggered + application install or update. properties: clusterRepository: description: |- - Name of the HelmClusterApplicationRepository resource used during the last application installation or upgrade. + Specifies the name of the HelmClusterApplicationRepository custom resource the + chart was last taken from. type: string name: - description: Name of the Helm chart used during the last application installation or upgrade. + description: Specifies the name of the Helm chart the release + was last deployed from. type: string repository: description: |- - Name of the HelmApplicationRepository resource used during the last application installation or upgrade. + Specifies the name of the HelmApplicationRepository custom resource the chart + was last taken from. type: string version: - description: Helm chart version used during the last application installation or upgrade. + description: Version holds the chart version the release was last + deployed from. type: string type: object lastAppliedValues: - description: Custom Helm chart values used during the last application installation or upgrade. + description: LastAppliedValues represents the latest values that triggered + application install or update. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - Time when the last forced reconciliation request was processed. - - This value indicates that the request was processed but does not indicate that reconciliation completed successfully. - Reconciliation results are reflected in the `Ready` condition. + LastForceReconcileTime is the time the most recent force reconcile request was + processed. It records that the request was acted on, not that it succeeded: + the outcome is reported by Ready. format: date-time type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddoncharts.yaml b/crds/helmclusteraddoncharts.yaml index ca44bf87..7a96f230 100644 --- a/crds/helmclusteraddoncharts.yaml +++ b/crds/helmclusteraddoncharts.yaml @@ -20,10 +20,9 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: |- - HelmClusterAddonChart describes a Helm chart discovered in a HelmClusterAddonRepository. - - HelmClusterAddonChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. + description: HelmClusterAddonChart represents a specific Helm chart discovered + within a HelmClusterAddonRepository. These resources are automatically managed + during repository synchronization and are immutable to user modifications. properties: apiVersion: description: |- @@ -48,30 +47,29 @@ spec: status: properties: conditions: - description: Conditions reflecting the current state of the Helm chart. + description: Conditions represent the latest available observations + of the chart state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -97,10 +95,8 @@ spec: type: object type: array iconURL: - description: |- - URL of the Helm chart icon. - - Applicable only to charts from Helm repositories. + description: IconURL is the URL to the Helm chart icon (applicable + to Helm Chart repository charts only). type: string observedGeneration: description: Generation represents resource generation that was last @@ -109,34 +105,33 @@ spec: type: integer versions: description: |- - List of discovered Helm chart versions. - - A version is available for installation if `unavailableReason` is not set. - For versions from an OCI repository, a supported layer media type must also be specified. + Versions lists every chart version the controller has examined. A version is + usable when it has no unavailableReason; for an OCI repository a usable version + also carries the media type of the layer that holds it. items: properties: mediaType: description: |- - OCI media type of the layer containing the Helm chart version. - - Populated only for versions from an OCI repository (`oci://`) with a supported layer type. - If the field is not set, the version is unavailable for installation. + MediaType is the OCI media type of the layer that holds this chart version. It + is set only for a version of an oci:// repository, and only when the layer is + supported: an empty value there means the version cannot be deployed. type: string ociRef: description: |- - OCI reference to the published Helm chart version. - - Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. - Such a version is installed using an internal OCIRepository. + OCIRef is the OCI reference this version is published at, as recorded from + the repository index. It is set only for a version of a helm repository whose + index entry points at a registry instead of a chart archive; such a version is + deployed through an internal OCIRepository even though its repository is a helm + one. type: string unavailableMessage: - description: Detailed description of the reason specified in `unavailableReason`. + description: UnavailableMessage carries human readable detail + for UnavailableReason. type: string unavailableReason: description: |- - Reason why the Helm chart version is unavailable for installation. - - If the field is not set, the version is available. + UnavailableReason explains why this version cannot be deployed. Its absence means + the version is usable. enum: - RemovedFromRepository - UnsupportedMediaType @@ -144,7 +139,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version. + description: Helm chart version minLength: 1 type: string required: diff --git a/crds/helmclusteraddonrepositories.yaml b/crds/helmclusteraddonrepositories.yaml index 7115c005..cc364047 100644 --- a/crds/helmclusteraddonrepositories.yaml +++ b/crds/helmclusteraddonrepositories.yaml @@ -45,7 +45,9 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources. + description: HelmClusterAddonRepository represents a Helm or OCI-compliant + repository containing Helm charts that can be referenced by HelmClusterAddon + resources. properties: apiVersion: description: |- @@ -70,7 +72,7 @@ spec: spec: properties: auth: - description: Credentials for repository authentication. + description: Auth contains authentication credentials for the repository. properties: password: description: Repository authentication password. @@ -85,16 +87,15 @@ spec: - username type: object caCertificate: - description: CA certificate in PEM format for verifying the repository TLS certificate. + description: CACertificate is the PEM encoded CA certificate for TLS + verification. type: string insecureSkipVerify: - description: Disables verification of the repository TLS certificate. + description: InsecureSkipVerify disable TLS certificate verification. type: boolean url: - description: |- - URL of the Helm or OCI repository. - - Supported schemes: `http(s)://` and `oci://`. + description: URL of the Helm repository. Supports http(s):// and oci:// + protocols. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -107,36 +108,35 @@ spec: properties: chartCount: description: |- - Number of charts discovered during the last successful repository synchronization. - - The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. + ChartCount is the number of charts the repository offered when it was last read + successfully. It is absent until the first successful read, so a repository that + has never been read is distinguishable from one that offers no charts. format: int32 type: integer conditions: - description: Conditions reflecting the current state of the repository. + description: Conditions represent the latest available observations + of the repository state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -163,30 +163,31 @@ spec: type: array consecutiveFetchFailures: description: |- - Number of consecutive failed attempts to access the repository. - - Used to determine the delay before the next attempt and reset after a successful attempt. + ConsecutiveFetchFailures counts consecutive failures to read from the repository. + It drives the retry backoff and resets on the first success. format: int32 type: integer lastForceReconcileTime: description: |- - Time when the last forced reconciliation request was processed. - - This value indicates that the request was processed but does not indicate that reconciliation completed successfully. - Reconciliation results are reflected in the `Ready` and `Synced` conditions. + LastForceReconcileTime is the time the most recent force reconcile request was + processed. It records that the request was acted on, not that it succeeded: + the outcome is reported by Ready and Synced. format: date-time type: string lastSuccessfulSyncTime: description: |- - Time of the last successful repository synchronization. + LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, + including creating and pruning chart resources. format: date-time type: string nextSyncTime: - description: Scheduled time of the next repository synchronization attempt. + description: NextSyncTime is the scheduled time of the next synchronization + attempt. format: date-time type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddons.yaml b/crds/helmclusteraddons.yaml index 3e33d509..8b22eefd 100644 --- a/crds/helmclusteraddons.yaml +++ b/crds/helmclusteraddons.yaml @@ -33,11 +33,6 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: |- - HelmClusterAddon describes a Helm release managed at the cluster level. - - The Helm chart may contain CRDs and other cluster-wide resources, so `ClusterAdmin` permissions are required to create a HelmClusterAddon. - Only one HelmClusterAddon resource can exist in the cluster for a given Helm chart from a specific repository. properties: apiVersion: description: |- @@ -65,19 +60,20 @@ spec: properties: helmClusterAddonChart: description: |- - Name of the Helm chart in the specified repository (for example, `ingress-nginx` or `redis`). + Specifies the name of the Helm chart to be installed + from the defined repository (e.g., "ingress-nginx" or "redis"). minLength: 1 type: string helmClusterAddonRepository: description: |- - Name of the HelmClusterAddonRepository resource. - - The specified repository is used as the Helm chart source. + Specifies the name of the HelmClusterAddonRepository custom resource that contains + the connection details and credentials for the repository where + the chart is located. maxLength: 63 minLength: 1 type: string version: - description: Helm chart version to install. + description: Versions holds the HelmClusterAddon chart version. type: string required: - helmClusterAddonChart @@ -86,22 +82,23 @@ spec: type: object maintenance: description: |- - Resource reconciliation mode. - - When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. - When set to an empty value (`""`), the standard reconciliation mode is used. + Maintenance specifies the reconciliation strategy for the resource. + When set to "NoResourceReconciliation", the controller will stop updating the + underlying resources, allowing for manual intervention or maintenance + without the operator overwriting changes. + When empty (""), standard reconciliation is active. enum: - "" - NoResourceReconciliation type: string namespace: default: default - description: Namespace to deploy a cluster addon release into. + description: Namespace to deploy cluster addon release maxLength: 63 minLength: 3 type: string values: - description: Custom Helm chart values. + description: Values holds the values for this HelmClusterAddon release. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -109,30 +106,29 @@ spec: status: properties: conditions: - description: Conditions reflecting the current state of the resource. + description: Conditions represent the latest available observations + of the addon state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -158,33 +154,38 @@ spec: type: object type: array lastAppliedChart: - description: Helm chart used during the last addon installation or upgrade. + description: LastAppliedChart represents the latest chart that triggered + addon install or update. properties: helmClusterAddonChart: description: |- - Helm chart name. + Specifies the name of the Helm chart to be installed + from the defined repository (e.g., "ingress-nginx" or "redis"). type: string helmClusterAddonRepository: description: |- - Name of the HelmClusterAddonRepository resource. + Specifies the name of the HelmClusterAddonRepository custom resource that contains + the connection details and credentials for the repository where + the chart is located. type: string version: - description: Helm chart version. + description: Versions holds the HelmClusterAddon chart version. type: string type: object lastAppliedValues: - description: Custom Helm chart values used during the last addon installation or upgrade. + description: LastAppliedValues represents the latest values that triggered + addon install or update. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - Time when the last forced reconciliation request was processed. - - This value indicates that the request was processed but does not indicate that reconciliation completed successfully. - Reconciliation results are reflected in the `Ready` condition. + LastForceReconcileTime is the time the most recent force reconcile request was + processed. It records that the request was acted on, not that it succeeded: + the outcome is reported by Ready. format: date-time type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusterapplicationcharts.yaml b/crds/helmclusterapplicationcharts.yaml index 60d3a086..64c367ad 100644 --- a/crds/helmclusterapplicationcharts.yaml +++ b/crds/helmclusterapplicationcharts.yaml @@ -20,10 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: |- - HelmClusterApplicationChart describes a Helm chart discovered in a HelmClusterApplicationRepository. - - HelmClusterApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. + description: HelmClusterApplicationChart represents a specific Helm chart + discovered within a HelmClusterApplicationRepository. These resources are + automatically managed during repository synchronization and are immutable + to user modifications. properties: apiVersion: description: |- @@ -48,30 +48,29 @@ spec: status: properties: conditions: - description: Conditions reflecting the current state of the Helm chart. + description: Conditions represent the latest available observations + of the chart state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -97,45 +96,43 @@ spec: type: object type: array iconURL: - description: |- - URL of the Helm chart icon. - - Applicable only to charts from Helm repositories. + description: IconURL is the URL to the Helm chart icon (applicable + to Helm Chart repository charts only). type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer versions: description: |- - List of discovered Helm chart versions. - - A version is available for installation if `unavailableReason` is not set. - For versions from an OCI repository, a supported layer media type must also be specified. + Versions lists every chart version the controller has examined. A version is + usable when it has no unavailableReason; for an OCI repository a usable version + also carries the media type of the layer that holds it. items: properties: mediaType: description: |- - OCI media type of the layer containing the Helm chart version. - - Populated only for versions from an OCI repository (`oci://`) with a supported layer type. - If the field is not set, the version is unavailable for installation. + MediaType is the OCI media type of the layer that holds this chart version. It + is set only for a version of an oci:// repository, and only when the layer is + supported: an empty value there means the version cannot be deployed. type: string ociRef: description: |- - OCI reference to the published Helm chart version. - - Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. - Such a version is installed using an internal OCIRepository. + OCIRef is the OCI reference this version is published at, as recorded from + the repository index. It is set only for a version of a helm repository whose + index entry points at a registry instead of a chart archive; such a version is + deployed through an internal OCIRepository even though its repository is a helm + one. type: string unavailableMessage: - description: Detailed description of the reason specified in `unavailableReason`. + description: UnavailableMessage carries human readable detail + for UnavailableReason. type: string unavailableReason: description: |- - Reason why the Helm chart version is unavailable for installation. - - If the field is not set, the version is available. + UnavailableReason explains why this version cannot be deployed. Its absence means + the version is usable. enum: - RemovedFromRepository - UnsupportedMediaType @@ -143,7 +140,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version. + description: Helm chart version minLength: 1 type: string required: diff --git a/crds/helmclusterapplicationrepositories.yaml b/crds/helmclusterapplicationrepositories.yaml index 9611642f..1e11a5e4 100644 --- a/crds/helmclusterapplicationrepositories.yaml +++ b/crds/helmclusterapplicationrepositories.yaml @@ -45,7 +45,9 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from any namespace. + description: HelmClusterApplicationRepository represents a cluster-wide Helm + or OCI-compliant repository containing Helm charts that can be referenced + by HelmApplication resources from any namespace. properties: apiVersion: description: |- @@ -70,7 +72,7 @@ spec: spec: properties: auth: - description: Credentials for repository authentication. + description: Auth contains authentication credentials for the repository. properties: password: description: Repository authentication password. @@ -85,16 +87,15 @@ spec: - username type: object caCertificate: - description: CA certificate in PEM format for verifying the repository TLS certificate. + description: CACertificate is the PEM encoded CA certificate for TLS + verification. type: string insecureSkipVerify: - description: Disables verification of the repository TLS certificate. + description: InsecureSkipVerify disable TLS certificate verification. type: boolean url: - description: |- - URL of the Helm or OCI repository. - - Supported schemes: `http(s)://` and `oci://`. + description: URL of the Helm repository. Supports http(s):// and oci:// + protocols. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -107,36 +108,35 @@ spec: properties: chartCount: description: |- - Number of charts discovered during the last successful repository synchronization. - - The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. + ChartCount is the number of charts the repository offered when it was last read + successfully. It is absent until the first successful read, so a repository that + has never been read is distinguishable from one that offers no charts. format: int32 type: integer conditions: - description: Conditions reflecting the current state of the repository. + description: Conditions represent the latest available observations + of the repository state. items: description: Condition contains details for one aspect of the current state of this API Resource. properties: lastTransitionTime: - description: |- - Time when the condition status last changed. + description: Time when the condition status last changed. format: date-time type: string message: - description: |- - Message with additional information about the condition state. + description: Message with additional information about the condition + state. maxLength: 32768 type: string observedGeneration: - description: |- - Resource generation on which the condition state is based. + description: Resource generation on which the condition state + is based. format: int64 minimum: 0 type: integer reason: - description: |- - Reason for the last change in the condition state. + description: Reason for the last change in the condition state. maxLength: 1024 minLength: 1 pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ @@ -163,31 +163,31 @@ spec: type: array consecutiveFetchFailures: description: |- - Number of consecutive failed attempts to access the repository. - - Used to determine the delay before the next attempt and reset after a successful attempt. + ConsecutiveFetchFailures counts consecutive failures to read from the repository. + It drives the retry backoff and resets on the first success. format: int32 type: integer lastForceReconcileTime: description: |- - Time when the last forced reconciliation request was processed. - - This value indicates that the request was processed but does not indicate that reconciliation completed successfully. - Reconciliation results are reflected in the `Ready` and `Synced` conditions. + LastForceReconcileTime is the time the most recent force reconcile request was + processed. It records that the request was acted on, not that it succeeded: + the outcome is reported by Ready and Synced. format: date-time type: string lastSuccessfulSyncTime: description: |- - Time of the last successful repository synchronization. + LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, + including creating and pruning chart resources. format: date-time type: string nextSyncTime: - description: Scheduled time of the next repository synchronization attempt. + description: NextSyncTime is the scheduled time of the next synchronization attempt. format: date-time type: string observedGeneration: - description: Latest resource generation processed by the controller. + description: Generation represents resource generation that was last + processed by the controller. format: int64 type: integer type: object diff --git a/tools/crddoc/.golangci.yaml b/tools/crddoc/.golangci.yaml new file mode 100644 index 00000000..9e052264 --- /dev/null +++ b/tools/crddoc/.golangci.yaml @@ -0,0 +1,109 @@ +# https://golangci-lint.run/usage/configuration/ +version: "2" + +run: + concurrency: 4 + timeout: 10m + +issues: + # Show all errors. + max-issues-per-linter: 0 + max-same-issues: 0 + exclude: + - "don't use an underscore in package name" + +output: + sort-results: true + +exclusions: + paths: + - "^zz_generated.*" + +formatters: + enable: + - gci + - gofmt + - gofumpt + - goimports + settings: + gci: + sections: + - standard + - default + - prefix(github.com/deckhouse/) + gofumpt: + extra-rules: true + goimports: + local-prefixes: github.com/deckhouse/ + +linters: + default: none + enable: + - asciicheck # checks that your code does not contain non-ASCII identifiers + - bidichk # checks for dangerous unicode character sequences + - bodyclose # checks whether HTTP response body is closed successfully + - contextcheck # [maybe too many false positives] checks the function whether use a non-inherited context + - dogsled # checks assignments with too many blank identifiers (e.g. x, _, _, _, := f()) + - errcheck # checking for unchecked errors, these unchecked errors can be critical bugs in some cases + - errname # checks that sentinel errors are prefixed with the Err and error types are suffixed with the Error + - errorlint # finds code that will cause problems with the error wrapping scheme introduced in Go 1.13 + - copyloopvar # detects places where loop variables are copied (Go 1.22+) + - gocritic # provides diagnostics that check for bugs, performance and style issues + - govet # reports suspicious constructs, such as Printf calls whose arguments do not align with the format string + - ineffassign # detects when assignments to existing variables are not used + - misspell # finds commonly misspelled English words in comments + - nolintlint # reports ill-formed or insufficient nolint directives + - reassign # checks that package variables are not reassigned + - revive # fast, configurable, extensible, flexible, and beautiful linter for Go, drop-in replacement of golint + - staticcheck # is a go vet on steroids, applying a ton of static analysis checks + - testifylint # checks usage of github.com/stretchr/testify + - unconvert # removes unnecessary type conversions + - unparam # reports unused function parameters + - unused # checks for unused constants, variables, functions and types + - usetesting # reports uses of functions with replacement inside the testing package + - testableexamples # checks if examples are testable (have an expected output) + - thelper # detects golang test helpers without t.Helper() call and checks the consistency of test helpers + - tparallel # detects inappropriate usage of t.Parallel() method in your Go test codes + - whitespace # detects leading and trailing whitespace + - wastedassign # finds wasted assignment statements + - importas # checks import aliases against the configured convention + settings: + errcheck: + exclude-functions: + - "(*os.File).Close" + - "(*net.TCPConn).Close" + - "(io.ReadCloser).Close" + - "(net.Listener).Close" + - "(net.Conn).Close" + - "(net.Conn).Close" + - "(*golang.org/x/crypto/ssh.Session).Close" + - "(*github.com/fsnotify/fsnotify.Watcher).Close" + staticcheck: + dot-import-whitelist: + - github.com/onsi/ginkgo/v2 + - github.com/onsi/gomega + revive: + rules: + - name: dot-imports + disabled: true + - name: exported + disabled: true + - name: package-comments + disabled: true + nolintlint: + # Exclude following linters from requiring an explanation. + # Default: [] + allow-no-explanation: [funlen, gocognit, lll] + # Enable to require an explanation of nonzero length after each nolint directive. + # Default: false + require-explanation: true + # Enable to require nolint directives to mention the specific linter being suppressed. + # Default: false + require-specific: true + importas: + # Do not allow unaliased imports of aliased packages. + # Default: false + no-unaliased: true + # Do not allow non-required aliases. + # Default: false + no-extra-aliases: false diff --git a/tools/crddoc/Taskfile.dist.yaml b/tools/crddoc/Taskfile.dist.yaml new file mode 100644 index 00000000..7bf197ea --- /dev/null +++ b/tools/crddoc/Taskfile.dist.yaml @@ -0,0 +1,21 @@ +version: "3" + +silent: true + +includes: + artifact: + taskfile: https://raw.githubusercontent.com/werf/common-ci/refs/heads/main/Taskfile.format_lint.yml + flatten: true + vars: + gciPrefix: '{{.gciPrefix | default "github.com/deckhouse/"}}' + golangciConfigPath: '{{.golangciConfigPath | default "./.golangci.yaml"}}' + golangciLintBinDir: '{{.golangciLintBinDir | default "../../bin"}}' + golangciLintVersion: '{{.golangciLintVersion | default "v2.13.2"}}' + golangciPaths: '{{.golangciPaths | default "./..."}}' + paths: '{{.paths | default "."}}' + +tasks: + test:unit: + desc: "Run the unit tests of this module." + cmds: + - go test ./... diff --git a/tools/crddoc/go.mod b/tools/crddoc/go.mod new file mode 100644 index 00000000..4a898e3b --- /dev/null +++ b/tools/crddoc/go.mod @@ -0,0 +1,7 @@ +module github.com/deckhouse/operator-helm/tools/crddoc + +go 1.26.3 + +require sigs.k8s.io/yaml v1.6.0 + +require go.yaml.in/yaml/v2 v2.4.2 // indirect diff --git a/tools/crddoc/go.sum b/tools/crddoc/go.sum new file mode 100644 index 00000000..bdcf478e --- /dev/null +++ b/tools/crddoc/go.sum @@ -0,0 +1,10 @@ +github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38= +github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= +go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI= +go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU= +go.yaml.in/yaml/v3 v3.0.3 h1:bXOww4E/J3f66rav3pX3m8w6jDE4knZjGOw8b5Y6iNE= +go.yaml.in/yaml/v3 v3.0.3/go.mod h1:tBHosrYAkRZjRAOREWbDnBXUf08JOwYq++0QNwQiWzI= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= +gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs= +sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4= diff --git a/tools/crddoc/main.go b/tools/crddoc/main.go new file mode 100644 index 00000000..422ca079 --- /dev/null +++ b/tools/crddoc/main.go @@ -0,0 +1,171 @@ +/* +Copyright 2026 Flant JSC. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +// Command crddoc finishes the CustomResourceDefinitions controller-gen renders +// for the documentation site. Two things the site needs cannot be expressed as +// a kubebuilder marker: apiVersion, kind and metadata have to carry x-doc-skip, +// and the fields of metav1.Condition have to carry the module's own descriptions +// instead of the apimachinery ones. The tool rewrites each file in place through +// the same JSON-then-yaml.v2 path controller-gen renders with, so nothing but +// those additions changes. +// +// Usage: +// +// crddoc ... +package main + +import ( + "flag" + "fmt" + "os" + + "sigs.k8s.io/yaml" +) + +// docSkipped are the root properties every kind shares with the rest of the API +// and the documentation site must not list again for each of them. +var docSkipped = []string{"apiVersion", "kind", "metadata"} + +// conditionDescriptions replace the ones apimachinery declares on metav1.Condition. +var conditionDescriptions = map[string]string{ + "lastTransitionTime": "Time when the condition status last changed.", + "message": "Message with additional information about the condition state.", + "observedGeneration": "Resource generation on which the condition state is based.", + "reason": "Reason for the last change in the condition state.", + "status": "Condition status.", + "type": "Condition type.", +} + +func main() { + flag.Parse() + + if flag.NArg() == 0 { + fmt.Fprintln(os.Stderr, "usage: crddoc ...") + os.Exit(2) + } + + if err := run(flag.Args()); err != nil { + fmt.Fprintln(os.Stderr, err) + os.Exit(1) + } +} + +func run(paths []string) error { + for _, path := range paths { + raw, err := os.ReadFile(path) + if err != nil { + return err + } + + doc := map[string]any{} + if err := yaml.Unmarshal(raw, &doc); err != nil { + return fmt.Errorf("parsing %s: %w", path, err) + } + + if err := finish(doc); err != nil { + return fmt.Errorf("%s: %w", path, err) + } + + encoded, err := yaml.Marshal(doc) + if err != nil { + return fmt.Errorf("encoding %s: %w", path, err) + } + + if err := os.WriteFile(path, append([]byte("---\n"), encoded...), 0o644); err != nil { + return err + } + } + + return nil +} + +func finish(doc map[string]any) error { + spec, _ := doc["spec"].(map[string]any) + versions, _ := spec["versions"].([]any) + + if len(versions) == 0 { + return fmt.Errorf("the definition declares no versions") + } + + for _, item := range versions { + version, _ := item.(map[string]any) + schema, _ := version["schema"].(map[string]any) + root, _ := schema["openAPIV3Schema"].(map[string]any) + properties, _ := root["properties"].(map[string]any) + + for _, name := range docSkipped { + property, ok := properties[name].(map[string]any) + if !ok { + return fmt.Errorf("version %v declares no %s property", version["name"], name) + } + + property["x-doc-skip"] = true + } + + if describeConditions(root) == 0 { + return fmt.Errorf("version %v declares no conditions", version["name"]) + } + } + + return nil +} + +// describeConditions walks the schema, rewrites the field descriptions of every +// object shaped like metav1.Condition and reports how many it found. The shape, +// not the apimachinery description, identifies it: a rewording upstream must not +// silently bring the upstream text back. A field added upstream changes the +// shape instead, which the caller turns into a failure rather than a silent +// return to the upstream text. +func describeConditions(schema map[string]any) int { + properties, _ := schema["properties"].(map[string]any) + + if isCondition(properties) { + for name, description := range conditionDescriptions { + property, _ := properties[name].(map[string]any) + property["description"] = description + } + + return 1 + } + + found := 0 + + for _, property := range properties { + if nested, ok := property.(map[string]any); ok { + found += describeConditions(nested) + } + } + + if items, ok := schema["items"].(map[string]any); ok { + found += describeConditions(items) + } + + return found +} + +func isCondition(properties map[string]any) bool { + if len(properties) != len(conditionDescriptions) { + return false + } + + for name := range conditionDescriptions { + if _, ok := properties[name].(map[string]any); !ok { + return false + } + } + + return true +} diff --git a/tools/crddoc/main_test.go b/tools/crddoc/main_test.go new file mode 100644 index 00000000..a26138ef --- /dev/null +++ b/tools/crddoc/main_test.go @@ -0,0 +1,308 @@ +/* +Copyright 2026 Flant JSC. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +*/ + +package main + +import ( + "os" + "path/filepath" + "testing" +) + +// The input is spelled the way controller-gen renders it, and the expected output +// must keep that spelling: the tool rewrites the committed definitions in place, +// so any formatting of its own would show up as an unrelated diff. +const generated = `--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: helmapplications.helm.deckhouse.io +spec: + group: helm.deckhouse.io + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + description: HelmApplication describes a Helm release within a single namespace. + properties: + apiVersion: + description: APIVersion defines the versioned schema of this representation + of an object. + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + In CamelCase. + type: string + metadata: + type: object + status: + properties: + conditions: + description: Conditions reflecting the current state of the resource. + items: + description: Condition contains details for one aspect of the current + state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: observedGeneration represents the .metadata.generation + that the condition was set based upon. + format: int64 + minimum: 0 + type: integer + reason: + description: reason contains a programmatic identifier indicating + the reason for the condition's last transition. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + type: object + type: object + served: true + storage: true +` + +const finished = `--- +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: helmapplications.helm.deckhouse.io +spec: + group: helm.deckhouse.io + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + description: HelmApplication describes a Helm release within a single namespace. + properties: + apiVersion: + description: APIVersion defines the versioned schema of this representation + of an object. + type: string + x-doc-skip: true + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + In CamelCase. + type: string + x-doc-skip: true + metadata: + type: object + x-doc-skip: true + status: + properties: + conditions: + description: Conditions reflecting the current state of the resource. + items: + description: Condition contains details for one aspect of the current + state of this API Resource. + properties: + lastTransitionTime: + description: Time when the condition status last changed. + format: date-time + type: string + message: + description: Message with additional information about the condition + state. + maxLength: 32768 + type: string + observedGeneration: + description: Resource generation on which the condition state + is based. + format: int64 + minimum: 0 + type: integer + reason: + description: Reason for the last change in the condition state. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: Condition status. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: Condition type. + maxLength: 316 + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + type: array + type: object + type: object + served: true + storage: true +` + +func TestFinishMarksTypeMetaAndDescribesConditions(t *testing.T) { + path := filepath.Join(t.TempDir(), "helmapplications.yaml") + if err := os.WriteFile(path, []byte(generated), 0o644); err != nil { + t.Fatal(err) + } + + if err := run([]string{path}); err != nil { + t.Fatal(err) + } + + got, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + + if string(got) != finished { + t.Fatalf("finished definition differs from the expected one:\n--- got\n%s\n--- want\n%s", got, finished) + } +} + +func TestFinishIsIdempotent(t *testing.T) { + path := filepath.Join(t.TempDir(), "helmapplications.yaml") + if err := os.WriteFile(path, []byte(finished), 0o644); err != nil { + t.Fatal(err) + } + + if err := run([]string{path}); err != nil { + t.Fatal(err) + } + + got, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + + if string(got) != finished { + t.Fatalf("a second run changed the definition:\n--- got\n%s\n--- want\n%s", got, finished) + } +} + +func TestRunFailsWithoutConditions(t *testing.T) { + path := filepath.Join(t.TempDir(), "broken.yaml") + doc := ` +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: broken.helm.deckhouse.io +spec: + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + properties: + apiVersion: + type: string + kind: + type: string + metadata: + type: object + status: + properties: + conditions: + items: + properties: + message: + type: string + status: + type: string + type: + type: string + type: object + type: array + type: object + type: object +` + if err := os.WriteFile(path, []byte(doc), 0o644); err != nil { + t.Fatal(err) + } + + if err := run([]string{path}); err == nil { + t.Fatal("expected an error, got nil") + } +} + +func TestRunFailsWithoutTypeMeta(t *testing.T) { + path := filepath.Join(t.TempDir(), "broken.yaml") + doc := ` +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: broken.helm.deckhouse.io +spec: + versions: + - name: v1alpha1 + schema: + openAPIV3Schema: + properties: + spec: + type: object + type: object +` + if err := os.WriteFile(path, []byte(doc), 0o644); err != nil { + t.Fatal(err) + } + + if err := run([]string{path}); err == nil { + t.Fatal("expected an error, got nil") + } + + got, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + + if string(got) != doc { + t.Fatal("run must leave a definition it cannot finish untouched") + } +} From d7293c1a652f16102ffa2f38cfdcfd7c48bca8f8 Mon Sep 17 00:00:00 2001 From: Ilya Drey Date: Wed, 7 Oct 2026 11:58:45 +0300 Subject: [PATCH 10/10] docs(api): port the editor's CRD descriptions into the Go types The descriptions rewritten by hand in crds/ now live in the kubebuilder doc comments they are generated from. HelmClusterAddon gains its root description, which a blank line had been keeping out of the CRD. Three slips in the edited files are not carried over: the chart catalog status is one shared type, so every chart kind gets the new observedGeneration text, and a trailing-space and a duplicated "attempt." line are dropped. Signed-off-by: Ilya Drey --- api/v1alpha1/chart_catalog_types.go | 40 +++++---- api/v1alpha1/helm_application.go | 61 +++++++------- api/v1alpha1/helm_application_chart.go | 4 +- api/v1alpha1/helm_application_repository.go | 2 +- api/v1alpha1/helm_cluster_addon.go | 55 ++++++------ api/v1alpha1/helm_cluster_addon_chart.go | 4 +- api/v1alpha1/helm_cluster_addon_repository.go | 2 +- .../helm_cluster_application_chart.go | 4 +- .../helm_cluster_application_repository.go | 2 +- api/v1alpha1/repository_types.go | 40 ++++----- crds/helmapplicationcharts.yaml | 53 ++++++------ crds/helmapplicationrepositories.yaml | 50 +++++------ crds/helmapplications.yaml | 84 +++++++++---------- crds/helmclusteraddoncharts.yaml | 53 ++++++------ crds/helmclusteraddonrepositories.yaml | 46 +++++----- crds/helmclusteraddons.yaml | 63 +++++++------- crds/helmclusterapplicationcharts.yaml | 54 ++++++------ crds/helmclusterapplicationrepositories.yaml | 50 +++++------ 18 files changed, 341 insertions(+), 326 deletions(-) diff --git a/api/v1alpha1/chart_catalog_types.go b/api/v1alpha1/chart_catalog_types.go index ef82513d..92e650c5 100644 --- a/api/v1alpha1/chart_catalog_types.go +++ b/api/v1alpha1/chart_catalog_types.go @@ -30,42 +30,46 @@ import ( // becomes the description of the status field in the CRD. type ChartCatalogStatus struct { - // IconURL is the URL to the Helm chart icon (applicable to Helm Chart repository charts only). + // URL of the Helm chart icon. + // + // Applicable only to charts from Helm repositories. IconURL string `json:"iconURL,omitempty"` - // Conditions represent the latest available observations of the chart state. + // Conditions reflecting the current state of the Helm chart. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` - // Generation represents resource generation that was last processed by the controller. + // Latest resource generation processed by the controller. ObservedGeneration int64 `json:"observedGeneration,omitempty"` - // Versions lists every chart version the controller has examined. A version is - // usable when it has no unavailableReason; for an OCI repository a usable version - // also carries the media type of the layer that holds it. + // List of discovered Helm chart versions. + // + // A version is available for installation if `unavailableReason` is not set. + // For versions from an OCI repository, a supported layer media type must also be specified. // +optional Versions []ChartVersion `json:"versions"` } type ChartVersion struct { - // Helm chart version + // Helm chart version. // +kubebuilder:validation:MinLength=1 Version string `json:"version"` - // OCIRef is the OCI reference this version is published at, as recorded from - // the repository index. It is set only for a version of a helm repository whose - // index entry points at a registry instead of a chart archive; such a version is - // deployed through an internal OCIRepository even though its repository is a helm - // one. + // OCI reference to the published Helm chart version. + // + // Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + // Such a version is installed using an internal OCIRepository. // +optional OCIRef string `json:"ociRef,omitempty"` - // MediaType is the OCI media type of the layer that holds this chart version. It - // is set only for a version of an oci:// repository, and only when the layer is - // supported: an empty value there means the version cannot be deployed. + // OCI media type of the layer containing the Helm chart version. + // + // Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + // If the field is not set, the version is unavailable for installation. // +optional MediaType string `json:"mediaType,omitempty"` - // UnavailableReason explains why this version cannot be deployed. Its absence means - // the version is usable. + // Reason why the Helm chart version is unavailable for installation. + // + // If the field is not set, the version is available. // +optional // +kubebuilder:validation:Enum=RemovedFromRepository;UnsupportedMediaType;ResolvePending;InvalidChartReference UnavailableReason string `json:"unavailableReason,omitempty"` - // UnavailableMessage carries human readable detail for UnavailableReason. + // Detailed description of the reason specified in `unavailableReason`. // +optional UnavailableMessage string `json:"unavailableMessage,omitempty"` } diff --git a/api/v1alpha1/helm_application.go b/api/v1alpha1/helm_application.go index efc5d678..375a9e39 100644 --- a/api/v1alpha1/helm_application.go +++ b/api/v1alpha1/helm_application.go @@ -32,7 +32,13 @@ const ( HelmApplicationLabelSourceName = "helm.deckhouse.io/application" ) -// HelmApplication represents an installation of a Helm chart inside a single namespace. The release is deployed into the namespace of the resource itself. The chart is applied with a ServiceAccount bound to a Role that grants every permission inside that namespace, so the right to create a HelmApplication is equivalent to administrator rights in its namespace; the Role and the binding belong to the module and are reconciled, so an edit to either does not outlast the application that needs it. +// HelmApplication describes a Helm release within a single namespace. +// +// The release is deployed in the same namespace as the HelmApplication resource. +// +// The chart is deployed using a ServiceAccount with permissions to perform any operation on all resources in the namespace. Therefore, namespace administrator permissions are required to create a HelmApplication. +// +// The Role and RoleBinding associated with the ServiceAccount are managed by the module and automatically reconciled to their desired state. Any manual changes to these resources are overwritten. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status @@ -168,15 +174,14 @@ func (r *HelmApplication) ForceReconcileRequired() bool { type HelmApplicationSpec struct { Chart HelmApplicationChartRef `json:"chart"` - // Values holds the values for this HelmApplication release. + // Custom Helm chart values. // +kubebuilder:pruning:PreserveUnknownFields // +optional Values *apiextensionsv1.JSON `json:"values"` - // Maintenance specifies the reconciliation strategy for the resource. - // When set to "NoResourceReconciliation", the controller will stop updating the - // underlying resources, allowing for manual intervention or maintenance - // without the operator overwriting changes. - // When empty (""), standard reconciliation is active. + // Resource reconciliation mode. + // + // When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + // When set to an empty value (`""`), the standard reconciliation mode is used. // +kubebuilder:validation:Enum="";NoResourceReconciliation // +optional Maintenance string `json:"maintenance,omitempty"` @@ -188,44 +193,44 @@ type HelmApplicationSpec struct { // +kubebuilder:validation:XValidation:rule="has(self.repository) != has(self.clusterRepository)",message="exactly one of spec.chart.repository or spec.chart.clusterRepository must be set" type HelmApplicationChartRef struct { - // Specifies the name of the Helm chart to be installed - // from the referenced repository (e.g., "nginx" or "redis"). + // Name of the Helm chart in the specified repository (for example, `nginx` or `redis`). // +kubebuilder:validation:MinLength=1 Name string `json:"name"` - // Specifies the name of the HelmApplicationRepository custom resource in the same - // namespace that contains the connection details and credentials for the - // repository where the chart is located. + // Name of the HelmApplicationRepository resource in the same namespace. + // + // The specified repository is used as the Helm chart source. // +optional // +kubebuilder:validation:MinLength=3 // +kubebuilder:validation:MaxLength=63 Repository string `json:"repository,omitempty"` - // Specifies the name of the cluster-wide HelmClusterApplicationRepository custom - // resource that contains the connection details and credentials for the - // repository where the chart is located. + // Name of the HelmClusterApplicationRepository resource. + // + // The specified repository is used as the Helm chart source. // +optional // +kubebuilder:validation:MinLength=3 // +kubebuilder:validation:MaxLength=63 ClusterRepository string `json:"clusterRepository,omitempty"` - // Version holds the HelmApplication chart version. + // Helm chart version to install. // +kubebuilder:validation:MinLength=1 Version string `json:"version"` } type HelmApplicationStatus struct { - // LastAppliedChart represents the latest chart that triggered application install or update. + // Helm chart used during the last application installation or upgrade. // +optional LastAppliedChart *HelmApplicationLastAppliedChartRef `json:"lastAppliedChart,omitempty"` - // LastAppliedValues represents the latest values that triggered application install or update. + // Custom Helm chart values used during the last application installation or upgrade. // +optional LastAppliedValues *apiextensionsv1.JSON `json:"lastAppliedValues,omitempty"` - // Conditions represent the latest available observations of the application state. + // Conditions reflecting the current state of the resource. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` - // Generation represents resource generation that was last processed by the controller. + // Latest resource generation processed by the controller. ObservedGeneration int64 `json:"observedGeneration,omitempty"` - // LastForceReconcileTime is the time the most recent force reconcile request was - // processed. It records that the request was acted on, not that it succeeded: - // the outcome is reported by Ready. + // Time when the last forced reconciliation request was processed. + // + // This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + // Reconciliation results are reflected in the `Ready` condition. // +optional LastForceReconcileTime *metav1.Time `json:"lastForceReconcileTime,omitempty"` } @@ -241,18 +246,16 @@ type HelmApplicationStatus struct { // description in the CRD. type HelmApplicationLastAppliedChartRef struct { - // Specifies the name of the Helm chart the release was last deployed from. + // Name of the Helm chart used during the last application installation or upgrade. // +optional Name string `json:"name,omitempty"` - // Specifies the name of the HelmApplicationRepository custom resource the chart - // was last taken from. + // Name of the HelmApplicationRepository resource used during the last application installation or upgrade. // +optional Repository string `json:"repository,omitempty"` - // Specifies the name of the HelmClusterApplicationRepository custom resource the - // chart was last taken from. + // Name of the HelmClusterApplicationRepository resource used during the last application installation or upgrade. // +optional ClusterRepository string `json:"clusterRepository,omitempty"` - // Version holds the chart version the release was last deployed from. + // Helm chart version used during the last application installation or upgrade. // +optional Version string `json:"version,omitempty"` } diff --git a/api/v1alpha1/helm_application_chart.go b/api/v1alpha1/helm_application_chart.go index 142d7fa7..5e562681 100644 --- a/api/v1alpha1/helm_application_chart.go +++ b/api/v1alpha1/helm_application_chart.go @@ -27,7 +27,9 @@ const ( HelmApplicationChartLabelSourceName = "helm.deckhouse.io/application-chart" ) -// HelmApplicationChart represents a specific Helm chart discovered within a HelmApplicationRepository. These resources are automatically managed during repository synchronization and are immutable to user modifications. +// HelmApplicationChart describes a Helm chart discovered in a HelmApplicationRepository. +// +// HelmApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/helm_application_repository.go b/api/v1alpha1/helm_application_repository.go index 96978f5a..d6ec0dc8 100644 --- a/api/v1alpha1/helm_application_repository.go +++ b/api/v1alpha1/helm_application_repository.go @@ -28,7 +28,7 @@ const ( HelmApplicationRepositoryLabelSourceName = "helm.deckhouse.io/application-repository" ) -// HelmApplicationRepository represents a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from the same namespace. +// HelmApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from the same namespace. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/helm_cluster_addon.go b/api/v1alpha1/helm_cluster_addon.go index e0ea11ec..66a113f3 100644 --- a/api/v1alpha1/helm_cluster_addon.go +++ b/api/v1alpha1/helm_cluster_addon.go @@ -32,8 +32,11 @@ const ( HelmClusterAddonLabelSourceName = "helm.deckhouse.io/cluster-addon" ) -// HelmClusterAddon represents a single cluster-wide installation of a Helm chart, which may include custom resource definitions (CRDs) and requires cluster-admin permissions to deploy. Only one instance of a specific chart can be installed at any given time. - +// HelmClusterAddon describes a Helm release managed at the cluster level. +// +// The Helm chart may contain CRDs and other cluster-wide resources, so `ClusterAdmin` permissions are required to create a HelmClusterAddon. +// Only one HelmClusterAddon resource can exist in the cluster for a given Helm chart from a specific repository. +// // +kubebuilder:object:root=true // +kubebuilder:subresource:status // +kubebuilder:metadata:labels={heritage=deckhouse,module=operator-helm} @@ -135,29 +138,27 @@ func (r *HelmClusterAddon) ForceReconcileRequired() bool { type HelmClusterAddonSpec struct { Chart HelmClusterAddonChartRef `json:"chart"` - // Values holds the values for this HelmClusterAddon release. + // Custom Helm chart values. // +kubebuilder:pruning:PreserveUnknownFields // +optional Values *apiextensionsv1.JSON `json:"values"` - // Namespace to deploy cluster addon release + // Namespace to deploy a cluster addon release into. // +kubebuilder:default:="default" // +optional // +kubebuilder:validation:MinLength=3 // +kubebuilder:validation:MaxLength=63 Namespace string `json:"namespace"` - // Maintenance specifies the reconciliation strategy for the resource. - // When set to "NoResourceReconciliation", the controller will stop updating the - // underlying resources, allowing for manual intervention or maintenance - // without the operator overwriting changes. - // When empty (""), standard reconciliation is active. + // Resource reconciliation mode. + // + // When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + // When set to an empty value (`""`), the standard reconciliation mode is used. // +kubebuilder:validation:Enum="";NoResourceReconciliation // +optional Maintenance string `json:"maintenance,omitempty"` } type HelmClusterAddonChartRef struct { - // Specifies the name of the Helm chart to be installed - // from the defined repository (e.g., "ingress-nginx" or "redis"). + // Name of the Helm chart in the specified repository (for example, `ingress-nginx` or `redis`). // +kubebuilder:validation:MinLength=1 HelmClusterAddonChartName string `json:"helmClusterAddonChart"` // The minimum below is 1, not 3: the referenced kind shipped without a minimum of @@ -165,46 +166,44 @@ type HelmClusterAddonChartRef struct { // This note is outside the doc comment on purpose — a doc comment becomes the // field's description in the CRD. - // Specifies the name of the HelmClusterAddonRepository custom resource that contains - // the connection details and credentials for the repository where - // the chart is located. + // Name of the HelmClusterAddonRepository resource. + // + // The specified repository is used as the Helm chart source. // +kubebuilder:validation:MinLength=1 // +kubebuilder:validation:MaxLength=63 HelmClusterAddonRepository string `json:"helmClusterAddonRepository"` - // Versions holds the HelmClusterAddon chart version. + // Helm chart version to install. Version string `json:"version"` } type HelmClusterAddonStatus struct { - // LastAppliedChart represents the latest chart that triggered addon install or update. + // Helm chart used during the last addon installation or upgrade. // +optional LastAppliedChart *HelmClusterAddonLastAppliedChartRef `json:"lastAppliedChart,omitempty"` - // LastAppliedValues represents the latest values that triggered addon install or update. + // Custom Helm chart values used during the last addon installation or upgrade. // +optional LastAppliedValues *apiextensionsv1.JSON `json:"lastAppliedValues,omitempty"` - // Conditions represent the latest available observations of the addon state. + // Conditions reflecting the current state of the resource. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` - // Generation represents resource generation that was last processed by the controller. + // Latest resource generation processed by the controller. ObservedGeneration int64 `json:"observedGeneration,omitempty"` - // LastForceReconcileTime is the time the most recent force reconcile request was - // processed. It records that the request was acted on, not that it succeeded: - // the outcome is reported by Ready. + // Time when the last forced reconciliation request was processed. + // + // This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + // Reconciliation results are reflected in the `Ready` condition. // +optional LastForceReconcileTime *metav1.Time `json:"lastForceReconcileTime,omitempty"` } type HelmClusterAddonLastAppliedChartRef struct { - // Specifies the name of the Helm chart to be installed - // from the defined repository (e.g., "ingress-nginx" or "redis"). + // Helm chart name. // +optional HelmClusterAddonChartName string `json:"helmClusterAddonChart,omitempty"` - // Specifies the name of the HelmClusterAddonRepository custom resource that contains - // the connection details and credentials for the repository where - // the chart is located. + // Name of the HelmClusterAddonRepository resource. // +optional HelmClusterAddonRepository string `json:"helmClusterAddonRepository,omitempty"` - // Versions holds the HelmClusterAddon chart version. + // Helm chart version. // +optional Version string `json:"version,omitempty"` } diff --git a/api/v1alpha1/helm_cluster_addon_chart.go b/api/v1alpha1/helm_cluster_addon_chart.go index 3e005760..90a63755 100644 --- a/api/v1alpha1/helm_cluster_addon_chart.go +++ b/api/v1alpha1/helm_cluster_addon_chart.go @@ -27,7 +27,9 @@ const ( HelmClusterAddonChartLabelSourceName = "helm.deckhouse.io/cluster-addon-chart" ) -// HelmClusterAddonChart represents a specific Helm chart discovered within a HelmClusterAddonRepository. These resources are automatically managed during repository synchronization and are immutable to user modifications. +// HelmClusterAddonChart describes a Helm chart discovered in a HelmClusterAddonRepository. +// +// HelmClusterAddonChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/helm_cluster_addon_repository.go b/api/v1alpha1/helm_cluster_addon_repository.go index e73e302b..210609a0 100644 --- a/api/v1alpha1/helm_cluster_addon_repository.go +++ b/api/v1alpha1/helm_cluster_addon_repository.go @@ -36,7 +36,7 @@ const ( // name longer than a label value can hold already breaks the internal objects that // carry it. -// HelmClusterAddonRepository represents a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources. +// HelmClusterAddonRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/helm_cluster_application_chart.go b/api/v1alpha1/helm_cluster_application_chart.go index c2d8fba4..ad79c19e 100644 --- a/api/v1alpha1/helm_cluster_application_chart.go +++ b/api/v1alpha1/helm_cluster_application_chart.go @@ -27,7 +27,9 @@ const ( HelmClusterApplicationChartLabelSourceName = "helm.deckhouse.io/cluster-application-chart" ) -// HelmClusterApplicationChart represents a specific Helm chart discovered within a HelmClusterApplicationRepository. These resources are automatically managed during repository synchronization and are immutable to user modifications. +// HelmClusterApplicationChart describes a Helm chart discovered in a HelmClusterApplicationRepository. +// +// HelmClusterApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/helm_cluster_application_repository.go b/api/v1alpha1/helm_cluster_application_repository.go index 56bbcaad..25beb33f 100644 --- a/api/v1alpha1/helm_cluster_application_repository.go +++ b/api/v1alpha1/helm_cluster_application_repository.go @@ -28,7 +28,7 @@ const ( HelmClusterApplicationRepositoryLabelSourceName = "helm.deckhouse.io/cluster-application-repository" ) -// HelmClusterApplicationRepository represents a cluster-wide Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from any namespace. +// HelmClusterApplicationRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmApplication resources from any namespace. // // +kubebuilder:object:root=true // +kubebuilder:subresource:status diff --git a/api/v1alpha1/repository_types.go b/api/v1alpha1/repository_types.go index 06b18399..911fa4df 100644 --- a/api/v1alpha1/repository_types.go +++ b/api/v1alpha1/repository_types.go @@ -25,27 +25,28 @@ import ( // HelmClusterApplicationRepository differ only in scope and in who may reference // them. Declaring the shape once makes a divergence between the schemas impossible // by construction, and lets the controller reconcile all three through one code -// path. The field descriptions are the ones the released HelmClusterAddonRepository -// CRD already carries: sharing them changes no generated schema. +// path. // // This note is outside every doc comment on purpose: a doc comment on a Spec or // Status type becomes the description of the spec or status field in the CRD. type RepositorySpec struct { - // URL of the Helm repository. Supports http(s):// and oci:// protocols. + // URL of the Helm or OCI repository. + // + // Supported schemes: `http(s)://` and `oci://`. // +kubebuilder:validation:Required // +kubebuilder:validation:XValidation:rule="self.matches('^(https?|oci)://.+$')",message="URL must have a valid protocol (http, https, oci) and a non-empty path" URL string `json:"url"` - // Auth contains authentication credentials for the repository. + // Credentials for repository authentication. // +optional Auth *RepositoryAuth `json:"auth,omitempty"` - // CACertificate is the PEM encoded CA certificate for TLS verification. + // CA certificate in PEM format for verifying the repository TLS certificate. // +optional CACertificate string `json:"caCertificate,omitempty"` - // InsecureSkipVerify disable TLS certificate verification. + // Disables verification of the repository TLS certificate. // +optional InsecureSkipVerify bool `json:"insecureSkipVerify,omitempty"` } @@ -60,30 +61,31 @@ type RepositoryAuth struct { } type RepositoryStatus struct { - // Conditions represent the latest available observations of the repository state. + // Conditions reflecting the current state of the repository. // +optional Conditions []metav1.Condition `json:"conditions,omitempty"` - // Generation represents resource generation that was last processed by the controller. + // Latest resource generation processed by the controller. ObservedGeneration int64 `json:"observedGeneration,omitempty"` - // LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - // including creating and pruning chart resources. + // Time of the last successful repository synchronization. // +optional LastSuccessfulSyncTime *metav1.Time `json:"lastSuccessfulSyncTime,omitempty"` - // NextSyncTime is the scheduled time of the next synchronization attempt. + // Scheduled time of the next repository synchronization attempt. // +optional NextSyncTime *metav1.Time `json:"nextSyncTime,omitempty"` - // LastForceReconcileTime is the time the most recent force reconcile request was - // processed. It records that the request was acted on, not that it succeeded: - // the outcome is reported by Ready and Synced. + // Time when the last forced reconciliation request was processed. + // + // This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + // Reconciliation results are reflected in the `Ready` and `Synced` conditions. // +optional LastForceReconcileTime *metav1.Time `json:"lastForceReconcileTime,omitempty"` - // ConsecutiveFetchFailures counts consecutive failures to read from the repository. - // It drives the retry backoff and resets on the first success. + // Number of consecutive failed attempts to access the repository. + // + // Used to determine the delay before the next attempt and reset after a successful attempt. // +optional ConsecutiveFetchFailures int32 `json:"consecutiveFetchFailures,omitempty"` - // ChartCount is the number of charts the repository offered when it was last read - // successfully. It is absent until the first successful read, so a repository that - // has never been read is distinguishable from one that offers no charts. + // Number of charts discovered during the last successful repository synchronization. + // + // The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. // +optional ChartCount *int32 `json:"chartCount,omitempty"` } diff --git a/crds/helmapplicationcharts.yaml b/crds/helmapplicationcharts.yaml index 437c084b..1e1d7d6a 100644 --- a/crds/helmapplicationcharts.yaml +++ b/crds/helmapplicationcharts.yaml @@ -20,9 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationChart represents a specific Helm chart discovered - within a HelmApplicationRepository. These resources are automatically managed - during repository synchronization and are immutable to user modifications. + description: |- + HelmApplicationChart describes a Helm chart discovered in a HelmApplicationRepository. + + HelmApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -47,8 +48,7 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -95,43 +95,46 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: Detailed description of the reason specified in + `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -139,7 +142,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmapplicationrepositories.yaml b/crds/helmapplicationrepositories.yaml index 41b78859..32cb6b7b 100644 --- a/crds/helmapplicationrepositories.yaml +++ b/crds/helmapplicationrepositories.yaml @@ -45,9 +45,9 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplicationRepository represents a Helm or OCI-compliant - repository containing Helm charts that can be referenced by HelmApplication - resources from the same namespace. + description: HelmApplicationRepository describes a Helm or OCI-compliant repository + containing Helm charts that can be referenced by HelmApplication resources + from the same namespace. properties: apiVersion: description: |- @@ -72,7 +72,7 @@ spec: spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -87,15 +87,17 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository + TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -108,14 +110,13 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -163,31 +164,30 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: - description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + description: Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization + description: Scheduled time of the next repository synchronization attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmapplications.yaml b/crds/helmapplications.yaml index 965bd259..68d138ba 100644 --- a/crds/helmapplications.yaml +++ b/crds/helmapplications.yaml @@ -46,13 +46,14 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmApplication represents an installation of a Helm chart inside - a single namespace. The release is deployed into the namespace of the resource - itself. The chart is applied with a ServiceAccount bound to a Role that - grants every permission inside that namespace, so the right to create a - HelmApplication is equivalent to administrator rights in its namespace; - the Role and the binding belong to the module and are reconciled, so an - edit to either does not outlast the application that needs it. + description: |- + HelmApplication describes a Helm release within a single namespace. + + The release is deployed in the same namespace as the HelmApplication resource. + + The chart is deployed using a ServiceAccount with permissions to perform any operation on all resources in the namespace. Therefore, namespace administrator permissions are required to create a HelmApplication. + + The Role and RoleBinding associated with the ServiceAccount are managed by the module and automatically reconciled to their desired state. Any manual changes to these resources are overwritten. properties: apiVersion: description: |- @@ -80,28 +81,27 @@ spec: properties: clusterRepository: description: |- - Specifies the name of the cluster-wide HelmClusterApplicationRepository custom - resource that contains the connection details and credentials for the - repository where the chart is located. + Name of the HelmClusterApplicationRepository resource. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 3 type: string name: - description: |- - Specifies the name of the Helm chart to be installed - from the referenced repository (e.g., "nginx" or "redis"). + description: Name of the Helm chart in the specified repository + (for example, `nginx` or `redis`). minLength: 1 type: string repository: description: |- - Specifies the name of the HelmApplicationRepository custom resource in the same - namespace that contains the connection details and credentials for the - repository where the chart is located. + Name of the HelmApplicationRepository resource in the same namespace. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 3 type: string version: - description: Version holds the HelmApplication chart version. + description: Helm chart version to install. minLength: 1 type: string required: @@ -114,17 +114,16 @@ spec: rule: has(self.repository) != has(self.clusterRepository) maintenance: description: |- - Maintenance specifies the reconciliation strategy for the resource. - When set to "NoResourceReconciliation", the controller will stop updating the - underlying resources, allowing for manual intervention or maintenance - without the operator overwriting changes. - When empty (""), standard reconciliation is active. + Resource reconciliation mode. + + When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + When set to an empty value (`""`), the standard reconciliation mode is used. enum: - "" - NoResourceReconciliation type: string values: - description: Values holds the values for this HelmApplication release. + description: Custom Helm chart values. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -132,8 +131,7 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the application state. + description: Conditions reflecting the current state of the resource. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -180,42 +178,40 @@ spec: type: object type: array lastAppliedChart: - description: LastAppliedChart represents the latest chart that triggered - application install or update. + description: Helm chart used during the last application installation + or upgrade. properties: clusterRepository: - description: |- - Specifies the name of the HelmClusterApplicationRepository custom resource the - chart was last taken from. + description: Name of the HelmClusterApplicationRepository resource + used during the last application installation or upgrade. type: string name: - description: Specifies the name of the Helm chart the release - was last deployed from. + description: Name of the Helm chart used during the last application + installation or upgrade. type: string repository: - description: |- - Specifies the name of the HelmApplicationRepository custom resource the chart - was last taken from. + description: Name of the HelmApplicationRepository resource used + during the last application installation or upgrade. type: string version: - description: Version holds the chart version the release was last - deployed from. + description: Helm chart version used during the last application + installation or upgrade. type: string type: object lastAppliedValues: - description: LastAppliedValues represents the latest values that triggered - application install or update. + description: Custom Helm chart values used during the last application + installation or upgrade. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` condition. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddoncharts.yaml b/crds/helmclusteraddoncharts.yaml index 7a96f230..e0255e3d 100644 --- a/crds/helmclusteraddoncharts.yaml +++ b/crds/helmclusteraddoncharts.yaml @@ -20,9 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonChart represents a specific Helm chart discovered - within a HelmClusterAddonRepository. These resources are automatically managed - during repository synchronization and are immutable to user modifications. + description: |- + HelmClusterAddonChart describes a Helm chart discovered in a HelmClusterAddonRepository. + + HelmClusterAddonChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -47,8 +48,7 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -95,43 +95,46 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: Detailed description of the reason specified in + `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -139,7 +142,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmclusteraddonrepositories.yaml b/crds/helmclusteraddonrepositories.yaml index cc364047..09f9fd87 100644 --- a/crds/helmclusteraddonrepositories.yaml +++ b/crds/helmclusteraddonrepositories.yaml @@ -45,7 +45,7 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterAddonRepository represents a Helm or OCI-compliant + description: HelmClusterAddonRepository describes a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources. properties: @@ -72,7 +72,7 @@ spec: spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -87,15 +87,17 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository + TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -108,14 +110,13 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -163,31 +164,30 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: - description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + description: Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization + description: Scheduled time of the next repository synchronization attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusteraddons.yaml b/crds/helmclusteraddons.yaml index 8b22eefd..697d39de 100644 --- a/crds/helmclusteraddons.yaml +++ b/crds/helmclusteraddons.yaml @@ -33,6 +33,11 @@ spec: name: v1alpha1 schema: openAPIV3Schema: + description: |- + HelmClusterAddon describes a Helm release managed at the cluster level. + + The Helm chart may contain CRDs and other cluster-wide resources, so `ClusterAdmin` permissions are required to create a HelmClusterAddon. + Only one HelmClusterAddon resource can exist in the cluster for a given Helm chart from a specific repository. properties: apiVersion: description: |- @@ -59,21 +64,20 @@ spec: chart: properties: helmClusterAddonChart: - description: |- - Specifies the name of the Helm chart to be installed - from the defined repository (e.g., "ingress-nginx" or "redis"). + description: Name of the Helm chart in the specified repository + (for example, `ingress-nginx` or `redis`). minLength: 1 type: string helmClusterAddonRepository: description: |- - Specifies the name of the HelmClusterAddonRepository custom resource that contains - the connection details and credentials for the repository where - the chart is located. + Name of the HelmClusterAddonRepository resource. + + The specified repository is used as the Helm chart source. maxLength: 63 minLength: 1 type: string version: - description: Versions holds the HelmClusterAddon chart version. + description: Helm chart version to install. type: string required: - helmClusterAddonChart @@ -82,23 +86,22 @@ spec: type: object maintenance: description: |- - Maintenance specifies the reconciliation strategy for the resource. - When set to "NoResourceReconciliation", the controller will stop updating the - underlying resources, allowing for manual intervention or maintenance - without the operator overwriting changes. - When empty (""), standard reconciliation is active. + Resource reconciliation mode. + + When set to `NoResourceReconciliation`, the controller pauses reconciliation of managed resources, allowing them to be modified manually without the controller overwriting the changes. + When set to an empty value (`""`), the standard reconciliation mode is used. enum: - "" - NoResourceReconciliation type: string namespace: default: default - description: Namespace to deploy cluster addon release + description: Namespace to deploy a cluster addon release into. maxLength: 63 minLength: 3 type: string values: - description: Values holds the values for this HelmClusterAddon release. + description: Custom Helm chart values. x-kubernetes-preserve-unknown-fields: true required: - chart @@ -106,8 +109,7 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the addon state. + description: Conditions reflecting the current state of the resource. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -154,38 +156,33 @@ spec: type: object type: array lastAppliedChart: - description: LastAppliedChart represents the latest chart that triggered - addon install or update. + description: Helm chart used during the last addon installation or + upgrade. properties: helmClusterAddonChart: - description: |- - Specifies the name of the Helm chart to be installed - from the defined repository (e.g., "ingress-nginx" or "redis"). + description: Helm chart name. type: string helmClusterAddonRepository: - description: |- - Specifies the name of the HelmClusterAddonRepository custom resource that contains - the connection details and credentials for the repository where - the chart is located. + description: Name of the HelmClusterAddonRepository resource. type: string version: - description: Versions holds the HelmClusterAddon chart version. + description: Helm chart version. type: string type: object lastAppliedValues: - description: LastAppliedValues represents the latest values that triggered - addon install or update. + description: Custom Helm chart values used during the last addon installation + or upgrade. x-kubernetes-preserve-unknown-fields: true lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` condition. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object diff --git a/crds/helmclusterapplicationcharts.yaml b/crds/helmclusterapplicationcharts.yaml index 64c367ad..98259701 100644 --- a/crds/helmclusterapplicationcharts.yaml +++ b/crds/helmclusterapplicationcharts.yaml @@ -20,10 +20,10 @@ spec: - name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationChart represents a specific Helm chart - discovered within a HelmClusterApplicationRepository. These resources are - automatically managed during repository synchronization and are immutable - to user modifications. + description: |- + HelmClusterApplicationChart describes a Helm chart discovered in a HelmClusterApplicationRepository. + + HelmClusterApplicationChart resources are automatically created and updated by the controller during repository synchronization and are not intended for manual modification. properties: apiVersion: description: |- @@ -48,8 +48,7 @@ spec: status: properties: conditions: - description: Conditions represent the latest available observations - of the chart state. + description: Conditions reflecting the current state of the Helm chart. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -96,43 +95,46 @@ spec: type: object type: array iconURL: - description: IconURL is the URL to the Helm chart icon (applicable - to Helm Chart repository charts only). + description: |- + URL of the Helm chart icon. + + Applicable only to charts from Helm repositories. type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer versions: description: |- - Versions lists every chart version the controller has examined. A version is - usable when it has no unavailableReason; for an OCI repository a usable version - also carries the media type of the layer that holds it. + List of discovered Helm chart versions. + + A version is available for installation if `unavailableReason` is not set. + For versions from an OCI repository, a supported layer media type must also be specified. items: properties: mediaType: description: |- - MediaType is the OCI media type of the layer that holds this chart version. It - is set only for a version of an oci:// repository, and only when the layer is - supported: an empty value there means the version cannot be deployed. + OCI media type of the layer containing the Helm chart version. + + Populated only for versions from an OCI repository (`oci://`) with a supported layer type. + If the field is not set, the version is unavailable for installation. type: string ociRef: description: |- - OCIRef is the OCI reference this version is published at, as recorded from - the repository index. It is set only for a version of a helm repository whose - index entry points at a registry instead of a chart archive; such a version is - deployed through an internal OCIRepository even though its repository is a helm - one. + OCI reference to the published Helm chart version. + + Populated only for a version from a Helm repository if the corresponding repository index entry references an OCI repository instead of a chart archive. + Such a version is installed using an internal OCIRepository. type: string unavailableMessage: - description: UnavailableMessage carries human readable detail - for UnavailableReason. + description: Detailed description of the reason specified in + `unavailableReason`. type: string unavailableReason: description: |- - UnavailableReason explains why this version cannot be deployed. Its absence means - the version is usable. + Reason why the Helm chart version is unavailable for installation. + + If the field is not set, the version is available. enum: - RemovedFromRepository - UnsupportedMediaType @@ -140,7 +142,7 @@ spec: - InvalidChartReference type: string version: - description: Helm chart version + description: Helm chart version. minLength: 1 type: string required: diff --git a/crds/helmclusterapplicationrepositories.yaml b/crds/helmclusterapplicationrepositories.yaml index 1e11a5e4..3acf125b 100644 --- a/crds/helmclusterapplicationrepositories.yaml +++ b/crds/helmclusterapplicationrepositories.yaml @@ -45,9 +45,9 @@ spec: name: v1alpha1 schema: openAPIV3Schema: - description: HelmClusterApplicationRepository represents a cluster-wide Helm - or OCI-compliant repository containing Helm charts that can be referenced - by HelmApplication resources from any namespace. + description: HelmClusterApplicationRepository describes a Helm or OCI-compliant + repository containing Helm charts that can be referenced by HelmApplication + resources from any namespace. properties: apiVersion: description: |- @@ -72,7 +72,7 @@ spec: spec: properties: auth: - description: Auth contains authentication credentials for the repository. + description: Credentials for repository authentication. properties: password: description: Repository authentication password. @@ -87,15 +87,17 @@ spec: - username type: object caCertificate: - description: CACertificate is the PEM encoded CA certificate for TLS - verification. + description: CA certificate in PEM format for verifying the repository + TLS certificate. type: string insecureSkipVerify: - description: InsecureSkipVerify disable TLS certificate verification. + description: Disables verification of the repository TLS certificate. type: boolean url: - description: URL of the Helm repository. Supports http(s):// and oci:// - protocols. + description: |- + URL of the Helm or OCI repository. + + Supported schemes: `http(s)://` and `oci://`. type: string x-kubernetes-validations: - message: URL must have a valid protocol (http, https, oci) and a @@ -108,14 +110,13 @@ spec: properties: chartCount: description: |- - ChartCount is the number of charts the repository offered when it was last read - successfully. It is absent until the first successful read, so a repository that - has never been read is distinguishable from one that offers no charts. + Number of charts discovered during the last successful repository synchronization. + + The field is not populated until the first successful synchronization, which distinguishes a repository that has not yet been synchronized from a repository that contains no charts. format: int32 type: integer conditions: - description: Conditions represent the latest available observations - of the repository state. + description: Conditions reflecting the current state of the repository. items: description: Condition contains details for one aspect of the current state of this API Resource. @@ -163,31 +164,30 @@ spec: type: array consecutiveFetchFailures: description: |- - ConsecutiveFetchFailures counts consecutive failures to read from the repository. - It drives the retry backoff and resets on the first success. + Number of consecutive failed attempts to access the repository. + + Used to determine the delay before the next attempt and reset after a successful attempt. format: int32 type: integer lastForceReconcileTime: description: |- - LastForceReconcileTime is the time the most recent force reconcile request was - processed. It records that the request was acted on, not that it succeeded: - the outcome is reported by Ready and Synced. + Time when the last forced reconciliation request was processed. + + This value indicates that the request was processed but does not indicate that reconciliation completed successfully. + Reconciliation results are reflected in the `Ready` and `Synced` conditions. format: date-time type: string lastSuccessfulSyncTime: - description: |- - LastSuccessfulSyncTime is the last time the chart catalog was fully brought up to date, - including creating and pruning chart resources. + description: Time of the last successful repository synchronization. format: date-time type: string nextSyncTime: - description: NextSyncTime is the scheduled time of the next synchronization + description: Scheduled time of the next repository synchronization attempt. format: date-time type: string observedGeneration: - description: Generation represents resource generation that was last - processed by the controller. + description: Latest resource generation processed by the controller. format: int64 type: integer type: object