docs: rework the module documentation

CHANGELOG/v0.0.2.yaml

@@ -1,5 +1,5 @@
 features:
-  - apply deckhouse runtime time review recommendations
+  - apply deckhouse runtime review recommendations
 fixes: []
 security: []
 chore: []

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: []

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:

CHANGELOG/v0.1.0.ru.yaml

@@ -1,7 +1,7 @@
 features:
-  - "внедрить ограниченный PSS"
+  - "внедрён ограниченный PSS"
 fixes:
-  - "запретить использование системных пространств имен"
+  - "запрещено использование системных пространств имен"
 security: []
 chore:
-  - "добавить генерацию журнала изменений и заметок о выпуске"
+  - "добавлена генерация журнала изменений и заметок о выпуске"

CHANGELOG/v0.1.0.yaml

@@ -1,5 +1,5 @@
 features:
-  - "enforce restricted pss"
+  - "enforce restricted PSS"
 fixes:
   - "forbid to use system namespaces"
 security: []

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:

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}')"

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"`
 }

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"`
 }

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

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