deckhouse · drey · Sep 2, 2026 · Sep 1, 2026 · Sep 1, 2026 · Sep 1, 2026
diff --git a/.github/workflows/build_dev.yml b/.github/workflows/build_dev.yml
@@ -31,6 +31,7 @@ jobs:
     name: Build and Push images
     outputs:
       modules_module_tag: ${{ steps.modules_module_tag.outputs.MODULES_MODULE_TAG }}
+      modules_module_digest: ${{ steps.modules_module_digest.outputs.MODULES_MODULE_DIGEST }}
     steps:
       - name: Set vars
         id: modules_module_tag
@@ -65,6 +66,21 @@ jobs:
           module_tag: ${{ steps.modules_module_tag.outputs.MODULES_MODULE_TAG }}
           svace_enabled: false
 
+      # The build action exposes no outputs, so the digest of what it just pushed
+      # is resolved here and handed to the e2e job, which asserts the cluster is
+      # running exactly this artifact.
+      - name: Resolve module digest
+        id: modules_module_digest
+        run: |
+          IMAGE="dev-registry.deckhouse.io/sys/deckhouse-oss/modules/${{ vars.MODULES_MODULE_NAME }}:${{ steps.modules_module_tag.outputs.MODULES_MODULE_TAG }}"
+          DIGEST="$(crane digest "$IMAGE")"
+          if [[ ! "$DIGEST" =~ ^sha256:[0-9a-f]{64}$ ]]; then
+            echo "::error title=Cannot resolve module digest::crane digest $IMAGE returned '$DIGEST'"
+            exit 1
+          fi
+          echo "$IMAGE -> $DIGEST"
+          echo "MODULES_MODULE_DIGEST=$DIGEST" >> "$GITHUB_OUTPUT"
+
   show_dev_manifest:
     runs-on: [self-hosted, large]
     name: Show manifest
@@ -142,6 +158,7 @@ jobs:
           KIND_CLUSTER_NAME: d8-operator-helm-${{ github.run_number }}
           DEV_REGISTRY_DOCKER_CONFIG: ${{ secrets.DEV_REGISTRY_DOCKER_CONFIG }}
           E2E_MODULE_TAG_NAME: ${{ needs.build_dev.outputs.modules_module_tag }}
+          E2E_MODULE_DIGEST: ${{ needs.build_dev.outputs.modules_module_digest }}
           E2E_MODULE_SOURCE: operator-helm
 
       - name: Delete kind cluster

diff --git a/api/v1alpha1/conditions.go b/api/v1alpha1/conditions.go
@@ -26,6 +26,10 @@ const (
 	ConditionTypeSynced               = "Synced"
 	ConditionTypeUninstallFailed      = "UninstallFailed"
 
+	// kstatus abnormal-true conditions. Present only while applicable.
+	ConditionTypeReconciling = "Reconciling"
+	ConditionTypeStalled     = "Stalled"
+
 	ReasonMaintenanceModeActive   = "MaintenanceModeActive"
 	ReasonMaintenanceModeInactive = "MaintenanceModeInactive"
 	ReasonSyncFailed              = "SyncFailed"
@@ -36,6 +40,18 @@ const (
 	ReasonUninstallFailed         = "UninstallFailed"
 	ReasonChartClaimConflict      = "ChartClaimConflict"
 
+	// HelmClusterAddonRepository condition reasons.
+	ReasonAuxiliaryResourcesFailed  = "AuxiliaryResourcesFailed"
+	ReasonCatalogUpdateFailed       = "CatalogUpdateFailed"
+	ReasonAwaitingInitialSync       = "AwaitingInitialSync"
+	ReasonProgressingWithRetry      = "ProgressingWithRetry"
+	ReasonRetriesExceeded           = "RetriesExceeded"
+	ReasonAuthenticationFailed      = "AuthenticationFailed"
+	ReasonSourceNotFound            = "SourceNotFound"
+	ReasonSourceRejectedRequest     = "SourceRejectedRequest"
+	ReasonInvalidRepositoryURL      = "InvalidRepositoryURL"
+	ReasonUnsupportedRepositoryType = "UnsupportedRepositoryType"
+
 	// HelmRelease error reasons
 	ReasonReleaseFailed = "ReleaseFailed"
 	ReasonTestFailed    = "TestFailed"

diff --git a/api/v1alpha1/helm_cluster_addon_repository.go b/api/v1alpha1/helm_cluster_addon_repository.go
@@ -28,6 +28,13 @@ const (
 	HelmClusterAddonRepositoryLabelSourceName = "helm.deckhouse.io/cluster-addon-repository"
 )
 
+// The "Next Sync" print column below is a string, not a date, on purpose: a date
+// column prints how long ago its value was, and kubectl renders any instant more
+// than a second in the future as <invalid>. nextSyncTime is always in the future.
+//
+// This note is deliberately outside the doc comment below — controller-gen folds
+// every non-marker line of that block into the resource's API description.
+
 // HelmClusterAddonRepository represents a Helm or OCI-compliant repository containing Helm charts that can be referenced by HelmClusterAddon resources.
 //
 // +kubebuilder:object:root=true
@@ -36,6 +43,10 @@ const (
 // +kubebuilder:resource:singular=helmclusteraddonrepository,scope=Cluster
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].status",description="The readiness status of the repository"
 // +kubebuilder:printcolumn:name="Synced",type="string",JSONPath=".status.conditions[?(@.type=='Synced')].status",description="Repository synchronization status"
+// +kubebuilder:printcolumn:name="Last Sync",type="date",JSONPath=".status.lastSuccessfulSyncTime",description="Time of the last successful catalog synchronization"
+// +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp"
+// +kubebuilder:printcolumn:name="Next Sync",type="string",JSONPath=".status.nextSyncTime",priority=1,description="Scheduled time of the next synchronization attempt"
+// +kubebuilder:printcolumn:name="Message",type="string",JSONPath=".status.conditions[?(@.type=='Ready')].message",priority=1
 // +genclient
 // +genclient:nonNamespaced
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -108,10 +119,31 @@ type HelmClusterAddonRepositoryAuth struct {
 
 type HelmClusterAddonRepositoryStatus struct {
 	// Conditions represent the latest available observations of the repository state.
+	//
+	// Ready reports whether the repository is usable: auxiliary resources are in place,
+	// the internal source object is healthy and the repository has responded to a catalog
+	// read on the current spec. A transient read failure does not flip Ready to False.
+	//
+	// Synced reports whether the chart catalog is up to date.
+	//
+	// Reconciling and Stalled follow the kstatus convention: they are present only while
+	// applicable. Reconciling means work is in progress or a retry is scheduled; Stalled
+	// means the repository will not recover without a change.
 	// +optional
 	Conditions []metav1.Condition `json:"conditions,omitempty"`
 	// Generation represents resource generation that was last 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.
+	// +optional
+	LastSuccessfulSyncTime *metav1.Time `json:"lastSuccessfulSyncTime,omitempty"`
+	// NextSyncTime is the scheduled time of the next synchronization attempt.
+	// +optional
+	NextSyncTime *metav1.Time `json:"nextSyncTime,omitempty"`
+	// ConsecutiveFetchFailures counts consecutive failures to read from the repository.
+	// It drives the retry backoff and resets on the first success.
+	// +optional
+	ConsecutiveFetchFailures int32 `json:"consecutiveFetchFailures,omitempty"`
 }
 
 // HelmClusterAddonRepositoryList contains a list of HelmClusterAddonRepositories.

diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
diff --git a/crds/doc-ru-helmclusteraddonrepositories.yaml b/crds/doc-ru-helmclusteraddonrepositories.yaml
@@ -31,6 +31,19 @@ spec:
             status:
               properties:
                 conditions:
-                  description: Условия отражают последние наблюдения за состоянием репозитория.
+                  description: |
+                    Условия отражают последние наблюдения за состоянием репозитория.
+
+                    `Ready` сообщает, пригоден ли репозиторий: вспомогательные ресурсы на месте, внутренний объект источника исправен, и репозиторий ответил на чтение каталога на текущей спецификации. Транзиентная ошибка чтения не переводит `Ready` в `False`.
+
+                    `Synced` сообщает, актуален ли каталог чартов.
+
+                    `Reconciling` и `Stalled` следуют соглашению kstatus: они присутствуют, только когда применимы. `Reconciling` означает, что работа выполняется или запланирован повтор; `Stalled` — что репозиторий не восстановится без вмешательства.
                 observedGeneration:
                   description: Поколение ресурса, обработанное контроллером последним.
+                lastSuccessfulSyncTime:
+                  description: Время последнего успешного приведения каталога чартов в актуальное состояние.
+                nextSyncTime:
+                  description: Запланированное время следующей попытки синхронизации.
+                consecutiveFetchFailures:
+                  description: Число подряд идущих неудачных обращений к репозиторию. Определяет задержку повтора и обнуляется при первом успехе.
diff --git a/crds/helmclusteraddonrepositories.yaml b/crds/helmclusteraddonrepositories.yaml
@@ -26,6 +26,22 @@ spec:
       jsonPath: .status.conditions[?(@.type=='Synced')].status
       name: Synced
       type: string
+    - description: Time of the last successful catalog synchronization
+      jsonPath: .status.lastSuccessfulSyncTime
+      name: Last Sync
+      type: date
+    - jsonPath: .metadata.creationTimestamp
+      name: Age
+      type: date
+    - description: Scheduled time of the next synchronization attempt
+      jsonPath: .status.nextSyncTime
+      name: Next Sync
+      priority: 1
+      type: string
+    - jsonPath: .status.conditions[?(@.type=='Ready')].message
+      name: Message
+      priority: 1
+      type: string
     name: v1alpha1
     schema:
       openAPIV3Schema:
@@ -88,8 +104,18 @@ spec:
           status:
             properties:
               conditions:
-                description: Conditions represent the latest available observations
-                  of the repository state.
+                description: |-
+                  Conditions represent the latest available observations of the repository state.
+
+                  Ready reports whether the repository is usable: auxiliary resources are in place,
+                  the internal source object is healthy and the repository has responded to a catalog
+                  read on the current spec. A transient read failure does not flip Ready to False.
+
+                  Synced reports whether the chart catalog is up to date.
+
+                  Reconciling and Stalled follow the kstatus convention: they are present only while
+                  applicable. Reconciling means work is in progress or a retry is scheduled; Stalled
+                  means the repository will not recover without a change.
                 items:
                   description: Condition contains details for one aspect of the current
                     state of this API Resource.
@@ -145,6 +171,23 @@ spec:
                   - type
                   type: object
                 type: array
+              consecutiveFetchFailures:
+                description: |-
+                  ConsecutiveFetchFailures counts consecutive failures to read from the repository.
+                  It drives the retry backoff and resets on the first success.
+                format: int32
+                type: integer
+              lastSuccessfulSyncTime:
+                description: |-
+                  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: NextSyncTime is the scheduled time of the next synchronization
+                  attempt.
+                format: date-time
+                type: string
               observedGeneration:
                 description: Generation represents resource generation that was last
                   processed by the controller.

diff --git a/docs/README.md b/docs/README.md
@@ -32,3 +32,38 @@ The following custom resources are used to manage Helm charts in the module:
 - 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.
 
 See [usage examples](example.html) for practical scenarios.
+
+## Repository Status
+
+`HelmClusterAddonRepository` reports four conditions.
+
+`Ready` tells whether the repository is usable: its auxiliary resources are in
+place, its internal source object is healthy, and the repository responded to a
+catalog read on the current spec. A transient read failure does not flip `Ready`
+to `False` — installed addons keep working and only the catalog goes stale.
+
+`Synced` tells whether the chart catalog is up to date.
+
+`Reconciling` and `Stalled` follow the kstatus convention and are present only
+while they apply. `Reconciling` means work is in progress or a retry is
+scheduled; `Stalled` means the repository will not recover on its own.
+
+| Ready | Synced | What it means | What to do |
+|---|---|---|---|
+| True | True | The repository is healthy. | Nothing. |
+| True | False | The catalog read failed but the repository was usable before. | Check the `Reconciling` message and `Last Sync`. Retries are already scheduled. |
+| False | True | The catalog is fresh, but the source of chart artifacts is unhealthy. | Check the `Ready` message: it is translated from the internal source object. |
+| False | False | The repository is unreachable or misconfigured. | Check `Stalled`: `AuthenticationFailed`, `SourceNotFound` and `InvalidRepositoryURL` need a change in `spec`. |
+| Unknown | any | The first catalog read on the current spec has not succeeded yet. | Wait for the next attempt shown in `Next Sync`. |
+
+Synchronization runs every 5 minutes. After a failed read the delay doubles —
+5m, 10m, 20m, 40m — up to one hour, and the repository is reported as `Stalled`
+with reason `RetriesExceeded` once the delay reaches the cap. Retries continue
+at that cadence, because the cause may disappear on the repository side. The
+schedule is visible in `status.nextSyncTime` and with
+`kubectl get helmclusteraddonrepository -o wide`. `kubectl get
+helmclusteraddonrepository` shows the `Last Sync` and `Age` columns by
+default, and `-o wide` adds `Next Sync` and the `Ready` message. The same
+values are in the status itself as `lastSuccessfulSyncTime` and
+`nextSyncTime`, alongside `consecutiveFetchFailures`, which counts the
+consecutive failed reads driving the backoff.
diff --git a/docs/README.ru.md b/docs/README.ru.md
@@ -32,3 +32,38 @@ weight: 10
 - Ресурс HelmClusterAddon, ссылающийся на заданный HelmClusterAddonChart, может быть создан в кластере только в единственном экземпляре. Это обусловлено тем, что Helm-чарты могут содержать определения кастомных ресурсов (CRD), повторная установка которых на уровне кластера недопустима.
 
 Примеры использования приведены в разделе [примеры использования](example.html).
+
+## Статус репозитория
+
+`HelmClusterAddonRepository` сообщает о себе четырьмя условиями.
+
+`Ready` показывает, пригоден ли репозиторий: вспомогательные ресурсы на месте,
+внутренний объект источника исправен, и репозиторий ответил на чтение каталога
+на текущей спецификации. Транзиентная ошибка чтения не переводит `Ready` в
+`False` — установленные аддоны продолжают работать, устаревает только каталог.
+
+`Synced` показывает, актуален ли каталог чартов.
+
+`Reconciling` и `Stalled` следуют соглашению kstatus и присутствуют, только
+когда применимы. `Reconciling` означает, что работа выполняется или запланирован
+повтор; `Stalled` — что репозиторий сам не восстановится.
+
+| Ready | Synced | Что означает | Что делать |
+|---|---|---|---|
+| True | True | Репозиторий исправен. | Ничего. |
+| True | False | Чтение каталога не удалось, но до этого репозиторий был пригоден. | Посмотреть сообщение `Reconciling` и колонку `Last Sync`. Повторы уже запланированы. |
+| False | True | Каталог свежий, но источник артефактов чартов неисправен. | Посмотреть сообщение `Ready` — оно транслируется от внутреннего объекта источника. |
+| False | False | Репозиторий недоступен или настроен неверно. | Посмотреть `Stalled`: `AuthenticationFailed`, `SourceNotFound` и `InvalidRepositoryURL` требуют правки `spec`. |
+| Unknown | любое | Первое чтение каталога на текущей спецификации ещё не удалось. | Дождаться следующей попытки, время которой указано в `Next Sync`. |
+
+Синхронизация выполняется каждые 5 минут. После неудачного чтения задержка
+удваивается — 5m, 10m, 20m, 40m — до часа, и по достижении потолка репозиторий
+переводится в `Stalled` с причиной `RetriesExceeded`. Повторы при этом
+продолжаются, потому что причина может уйти на стороне репозитория. Расписание
+видно в `status.nextSyncTime` и через
+`kubectl get helmclusteraddonrepository -o wide`. `kubectl get
+helmclusteraddonrepository` по умолчанию показывает колонки `Last Sync` и
+`Age`, а `-o wide` добавляет `Next Sync` и сообщение из `Ready`. Те же
+значения лежат в самом статусе — `lastSuccessfulSyncTime` и `nextSyncTime`, —
+рядом с `consecutiveFetchFailures`, который считает подряд идущие неудачные
+чтения, определяющие задержку повтора.
diff --git a/images/operator-helm-controller/go.mod b/images/operator-helm-controller/go.mod
@@ -9,6 +9,7 @@ require (
 	github.com/deckhouse/operator-helm/api v0.0.0-00010101000000-000000000000
 	github.com/google/go-containerregistry v0.20.6
 	github.com/opencontainers/go-digest v1.0.0
+	github.com/samber/lo v1.53.0
 	github.com/werf/3p-fluxcd-pkg/apis/meta v1.23.0-nelm.1
 	github.com/werf/3p-fluxcd-pkg/chartutil v1.17.0-nelm.1
 	github.com/werf/3p-helm-controller/api v0.1.5
@@ -19,6 +20,7 @@ require (
 	k8s.io/apimachinery v0.35.1
 	k8s.io/client-go v0.35.1
 	k8s.io/utils v0.0.0-20251002143259-bc988d571ff4
+	sigs.k8s.io/cli-utils v0.37.2
 	sigs.k8s.io/controller-runtime v0.23.1
 )
 
@@ -61,7 +63,6 @@ require (
 	github.com/prometheus/client_model v0.6.2 // indirect
 	github.com/prometheus/common v0.66.1 // indirect
 	github.com/prometheus/procfs v0.16.1 // indirect
-	github.com/samber/lo v1.53.0 // indirect
 	github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect