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/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/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/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..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: |- @@ -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,48 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 @@ -146,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 13086c9d..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: |- @@ -56,6 +56,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 +65,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 +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 @@ -105,58 +110,47 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 923bd1d5..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: |- @@ -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"). + 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: @@ -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,41 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 45c958f2..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: |- @@ -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,48 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 @@ -146,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 18bb24dc..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: @@ -56,6 +56,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 +65,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 +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 @@ -105,58 +110,47 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 6a31b1e8..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: |- @@ -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"). + 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 @@ -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,41 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 7a2e9283..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: |- @@ -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,48 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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 @@ -147,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 cba2d039..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: |- @@ -56,6 +56,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 +65,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 +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 @@ -105,58 +110,47 @@ 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. + description: 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. + description: 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. + description: 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. + 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: 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 +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/docs/ADMIN_GUIDE.md b/docs/ADMIN_GUIDE.md new file mode 100644 index 00000000..dc183168 --- /dev/null +++ b/docs/ADMIN_GUIDE.md @@ -0,0 +1,583 @@ +--- +title: "Administrator guide" +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 `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 Helm repository is the entry point for every other resource. It contains Helm charts for a following installation in the cluster. + +To add a new Helm addon repository, create a [HelmClusterAddonRepository](/modules/operator-helm/cr.html#helmclusteraddonrepository) resource: + +{{< tabs name="create-addon-repository" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +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 >}} + +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="Via 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 see a list of versions, run the following command: + +```shell +d8 k get helmclusteraddonchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Example output: + +```text +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="Via web interface" %}} + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addon charts". + +{{% /tab %}} +{{< /tabs >}} + +### Checking the repository state + +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="Via command line" %}} + +Run the following command: + +```shell +d8 k get helmclusteraddonrepository podinfo -o yaml +``` + +Example output: + +```text +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="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 over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible repository states" >}} + +| Condition | Value | Reason | Description | +| --- | --- | --- | --- | +| `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 `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 ([`status.conditions`](cr.html#helmclusteraddon-v1alpha1-status-conditions)). To assess the state of an addon: + +{{< tabs name="check-addon-conditions" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k get helmclusteraddon podinfo -o yaml +``` + +Example output: + +```text +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="Via web interface" %}} + +1. Go to the "System" tab. +1. Go to "Helm operator" → "Addons". +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 | Description | +| --- | --- | --- | --- | +| `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: `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 >}} + +{{< /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). + +To add an application chart repository, create a [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository) resource: + +{{< tabs name="create-cluster-application-repository" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +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 list all Helm charts available in a repository: + +{{< tabs name="list-cluster-application-charts" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k get helmclusterapplicationcharts -l repository=podinfo-shared +``` + +{{% /tab %}} + +{{% tab name="Via 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 >}} + +For details on working with the charts in this repository, refer to the ["User guide"](user_guide.html) page. + +## Connecting a private repository + +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="Via command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="warning" >}} +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 + +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="Via command line" %}} + +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), 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 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 >}} + +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}' +``` + +{{% /tab %}} + +{{% tab name="Via 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 (such as the number of replicas and other parameters). + +{{< tabs name="enable-addon-maintenance" >}} +{{% tab name="Via command line" %}} + +To enable maintenance mode, 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 disable maintenance mode, 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="Via 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/ADMIN_GUIDE.ru.md b/docs/ADMIN_GUIDE.ru.md new file mode 100644 index 00000000..3423b68f --- /dev/null +++ b/docs/ADMIN_GUIDE.ru.md @@ -0,0 +1,584 @@ +--- +title: "Руководство администратора" +description: "Управление cluster-wide-ресурсами модуля operator-helm: репозитории, каталоги чартов и аддоны." +weight: 40 +--- + +Руководство описывает порядок работы с модулем `operator-helm` через cluster-wide-ресурсы. Для работы с данными кастомными ресурсами необходимы права не ниже уровня [роли `ClusterAdmin`](/modules/user-authz/#текущая-ролевая-модель). + +## Добавление репозитория аддонов + +Helm-репозиторий аддонов — это точка входа для всех остальных ресурсов. +Он содержит Helm-чарты для последующей установки в кластере. + +Чтобы добавить новый Helm-репозиторий аддонов, создайте [ресурс 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 >}} + +После создания ресурса HelmClusterAddonRepository модуль синхронизирует репозиторий и создаст отдельный [объект 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 +``` + +Пример вывода: + +```text +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 >}} + +### Проверка состояния репозитория + +Состояние репозитория отражают условия в его статусе ([`status.conditions`](cr.html#helmclusteraddonrepository-v1alpha1-status-conditions)). Для оценки состояния репозитория: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k get helmclusteraddonrepository podinfo -o yaml +``` + +Пример вывода: + +```text +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` присутствуют только пока они применимы: `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="В командной строке" %}} + +Выполните команду: + +```shell +d8 k get helmclusteraddon podinfo -o yaml +``` + +Пример вывода: + +```text +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` присутствуют, только пока применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. Условия `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как аддон проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Добавление репозитория с чартами приложений + +С помощью создания [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): + +{{< 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). Чтобы вывести список доступных в репозитории Helm-чартов: + +{{< 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) добавьте к нему аннотацию `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) добавьте к нему аннотацию `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 >}} + +Завершение принудительной реконсиляции можно отследить по полю [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmclusteraddon-v1alpha1-status-lastforcereconciletime) ресурса. Например: + +```shell +d8 k get helmclusteraddon podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{% /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/CONFIGURATION.md b/docs/CONFIGURATION.md index 80620c13..670ff985 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: "Configuration parameters of the operator-helm module." weight: 20 --- diff --git a/docs/CONFIGURATION.ru.md b/docs/CONFIGURATION.ru.md index 7ceffe57..f78d7012 100644 --- a/docs/CONFIGURATION.ru.md +++ b/docs/CONFIGURATION.ru.md @@ -1,5 +1,5 @@ --- title: "Настройки" -description: "Deckhouse Kubernetes Platform, параметры конфигурации модуля operator-helm." +description: "Параметры конфигурации модуля operator-helm." weight: 20 --- diff --git a/docs/CR.md b/docs/CR.md index ea293afd..bf1803d6 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: "Custom resources of the operator-helm module." weight: 60 --- diff --git a/docs/CR.ru.md b/docs/CR.ru.md index e22d7ed5..7361d4d9 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: "Кастомные ресурсы модуля operator-helm." weight: 60 --- 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.md b/docs/README.md index 1f5bf889..8536add2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,44 +1,87 @@ --- title: "Module operator-helm" -description: "Deckhouse Kubernetes 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 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 lets you control declaratively the Helm chart deployment in the Deckhouse Platform (DP) cluster. -The module controller monitors the state of HelmClusterAddon and HelmApplication resources and automatically reconciles Helm releases in the cluster with the specified parameters. +Depending on the scope of created resources, Helm charts are divided in addons and applications: -## Main Features +- **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. -- 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. +To enable the module, use one of the methods described on the ["Configuration"](configuration.html) page. +## Key features -## Custom Resources +The module provides the following capabilities: -The following custom resources are used to manage Helm charts in the module: +- 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. -- **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. +## Custom resources -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. +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. -## Limitations +```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; + + ADM(["fa:fa-user
DP
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-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 DP administrator works with the following cluster-wide resources: + +- [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 manages the following resources in the designated namespace: + +- [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. + +For configuration examples for the resources described above, refer to the ["Administrator guide"](admin_guide.html) and ["User guide"](user_guide.html) pages. + +## Limitations -See [usage examples](example.html) for practical scenarios. +- 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 2e1cc807..a6519ffe 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -1,43 +1,87 @@ --- title: "Модуль operator-helm" -description: "Deckhouse Kubernetes Platform — модуль operator-helm для декларативного управления Helm-чартами." +description: "Модуль operator-helm для декларативного управления Helm-чартами в Deckhouse Platform." weight: 10 --- -Модуль `operator-helm` позволяет декларативно управлять развёртыванием Helm-чартов в кластере. Он автоматизирует установку чартов с помощью кастомных ресурсов и охватывает два уровня: кластерное семейство аддонов для администраторов кластеров и DevOps-инженеров и пространственное (namespaced) семейство приложений, которое позволяет владельцу namespace устанавливать чарты в собственном namespace без прав на весь кластер. +Модуль `operator-helm` позволяет декларативно управлять развёртыванием Helm-чартов в кластере Deckhouse Platform (DP). -Контроллер модуля отслеживает состояние ресурсов HelmClusterAddon и HelmApplication и автоматически приводит Helm-релизы в кластере в соответствие с заданными параметрами. +В зависимости от области видимости создаваемых ресурсов Helm-чарты разделяются на аддоны и приложения: + +- **Аддоны** ([HelmClusterAddon](cr.html#helmclusteraddon)) могут создавать кастомные и другие cluster-wide-ресурсы. Установкой аддонов и управлением ими занимается администратор DP. +- **Приложения** ([HelmApplication](cr.html#helmapplication)) создают только namespaced-ресурсы. Администратор неймспейса может устанавливать приложения и управлять ими в пределах своего неймспейса. + +Чтобы включить модуль, воспользуйтесь одним из способов, описанных [в разделе «Настройки»](configuration.html). ## Основные возможности -- Развёртывание 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-чартов и их версий; +- установка чартов администратором неймспейса без предоставления прав на cluster-wide-ресурсы; +- поддержка общих репозиториев приложений, доступных во всех неймспейсах; +- устранение отклонений от заданной конфигурации; +- режим обслуживания, который приостанавливает реконсиляцию для ручного вмешательства в релиз; +- поддержка приватных репозиториев с использованием корпоративного PKI; +- управление через [CLI-утилиту `d8`](/products/kubernetes-platform/documentation/v1/cli/d8/) или веб-интерфейс DP. ## Кастомные ресурсы -Для управления Helm-чартами в модуле используются следующие кастомные ресурсы: +Кастомные ресурсы модуля разделяются по области видимости на cluster-wide-ресурсы, которыми управляет администратор DP, и namespaced-ресурсы, которыми управляет администратор соответствующего неймспейса. -- **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
Администратор
DP"]):::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 -- Семейство аддонов (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), повторная установка которых на уровне кластера недопустима. + 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) — описывает 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) — описывает Helm-релиз приложения, включая целевую версию чарта, репозиторий и параметры установки. В качестве источника чарта можно использовать [HelmApplicationRepository](/modules/operator-helm/cr.html#helmapplicationrepository) из того же неймспейса или [HelmClusterApplicationRepository](/modules/operator-helm/cr.html#helmclusterapplicationrepository). + +Примеры настройки вышеописанных ресурсов приведены в [«Руководстве администратора»](admin_guide.html) и [«Руководстве пользователя»](user_guide.html). + +## Ограничения -Примеры использования приведены в разделе [примеры использования](example.html). +- Для одного ресурса [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 da74f8e4..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 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..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 new file mode 100644 index 00000000..0b319fbc --- /dev/null +++ b/docs/USER_GUIDE.md @@ -0,0 +1,521 @@ +--- +title: "User guide" +description: "Installing Helm charts in your own namespace with the operator-helm module." +weight: 50 +--- + +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 Helm application repository is the entry point for every other resource. +It contains Helm charts for a following installation within a designated 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="Via command line" %}} + +Run the following command: + +```shell +d8 k apply -f - <}} + +{{< alert level="info" >}} +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 >}} + +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="Via 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 see a list of versions, run the following command: + +```shell +d8 k -n test get helmapplicationchart -l repository=podinfo,chart=podinfo -o yaml +``` + +Example output: + +```text +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="Via 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 ([`status.conditions`](cr.html#helmapplicationrepository-v1alpha1-status-conditions)). To assess the state of a repository: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k -n test get helmapplicationrepository podinfo -o yaml +``` + +Example output: + +```text +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="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 over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible repository states" >}} + +| Condition | Value | Reason | Description | +| --- | --- | --- | --- | +| `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: `Reconciling` is present until the work is finished, `Stalled` is present until the cause of the failure is fixed. + +{{< /alert >}} + +{{< /details >}} + +## Deploying an application + +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="Via 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 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-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. + +{{< details summary="Viewing the available shared application Helm charts" >}} + +To view a list of 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="Via 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 Deckhouse Platform administrator. +{{< /alert >}} + +{{< alert level="info" >}} +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. + +{{< 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 ([`status.conditions`](cr.html#helmapplication-v1alpha1-status-conditions)). To assess the state of an application: + +{{< tabs name="check-application-conditions" >}} +{{% tab name="Via command line" %}} + +Run the following command: + +```shell +d8 k -n test get helmapplication podinfo -o yaml +``` + +Example output: + +```text +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="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 over its status. The pop-up window shows information about its state. + +{{% /tab %}} +{{< /tabs >}} + +{{< details summary="Viewing the possible application states" >}} + +| Condition | Value | Reason | Description | +| --- | --- | --- | --- | +| `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: `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 >}} + +{{< /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="Via command line" %}} + +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), 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 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 >}} + +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}' +``` + +{{% /tab %}} + +{{% tab name="Via 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 (such as the number of replicas and other parameters). + +{{< tabs name="enable-application-maintenance" >}} +{{% tab name="Via command line" %}} + +To enable maintenance mode, 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 disable maintenance mode, 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="Via 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 >}} diff --git a/docs/USER_GUIDE.ru.md b/docs/USER_GUIDE.ru.md new file mode 100644 index 00000000..b8834412 --- /dev/null +++ b/docs/USER_GUIDE.ru.md @@ -0,0 +1,521 @@ +--- +title: "Руководство пользователя" +description: "Установка Helm-чартов в собственном неймспейсе с помощью модуля operator-helm." +weight: 50 +--- + +Руководство описывает порядок работы с namespaced-ресурсами модуля, включая репозитории чартов, их каталоги и приложения. Для работы с данными кастомными ресурсами необходимы права не ниже уровня [роли `Admin`](/modules/user-authz/#текущая-ролевая-модель) в соответствующем неймспейсе. + +## Добавление репозитория приложений + +Helm-репозиторий приложений — это точка входа для всех остальных ресурсов. +Он содержит Helm-чарты для последующей установки в рамках выбранного неймспейса. + +Чтобы добавить новый Helm-репозиторий приложений, создайте ресурс [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 >}} + +После создания ресурса HelmApplicationRepository модуль синхронизирует репозиторий и создаст отдельный [объект 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 +``` + +Пример вывода: + +```text +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 >}} + +### Проверка состояния репозитория + +Состояние репозитория отражают условия в его статусе ([`status.conditions`](cr.html#helmapplicationrepository-v1alpha1-status-conditions)). Для оценки состояния репозитория: + +{{< tabs name="check-repository-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k -n test get helmapplicationrepository podinfo -o yaml +``` + +Пример вывода: + +```text +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` присутствуют только пока они применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. + +{{< /alert >}} + +{{< /details >}} + +## Развёртывание приложения + +Чтобы развернуть приложение, создайте [ресурс HelmApplication](/modules/operator-helm/cr.html#helmapplication) в том же неймспейсе, указав репозиторий, имя и версию чарта: + +{{< tabs name="create-application" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k apply -f - <}} +Приложения могут разворачиваться не только из Helm-чартов локального для неймспейса репозитория, но и из общего репозитория, который завёл администратор Deckhouse Platform. Общие репозитории описываются с помощью [ресурса 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)) и его создал администратор Deckhouse Platform. +{{< /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 >}} + +### Проверка состояния приложения + +Состояние приложения отражают условия в его статусе ([`status.conditions`](cr.html#helmapplication-v1alpha1-status-conditions)). Для оценки состояния приложения: + +{{< tabs name="check-application-conditions" >}} +{{% tab name="В командной строке" %}} + +Выполните команду: + +```shell +d8 k -n test get helmapplication podinfo -o yaml +``` + +Пример вывода: + +```text +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` | `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` присутствуют, только пока применимы: `Reconciling` — пока работа не завершена, `Stalled` — пока причина сбоя не устранена. Условия `Installed`, `UpdateInstalled` и `ConfigurationApplied` появляются по мере того, как приложение проходит соответствующие этапы, и несут тот же вердикт, что и `Ready`. + +{{< /alert >}} + +{{< /details >}} + +## Принудительный запуск реконсиляции + +При работе с приложениями и репозиториями может возникнуть необходимость принудительного запуска реконсиляции. В штатном режиме работы запуск реконсиляции происходит автоматически в случае внесения изменений в ресурсы либо изменения состояния их зависимостей. + +В случае с приложениями принудительная реконсиляция может быть полезна, если при развёртывании либо изменении настроек приложения возникла критическая ошибка. Без ручного вмешательства контроллеры в составе модуля более не будут предпринимать попытки реконсиляции. + +При работе с репозиториями запуск принудительной реконсиляции позволяет выполнить синхронизацию репозитория, не дожидаясь очередного запуска по расписанию. + +{{< tabs name="force-reconcile-application" >}} +{{% tab name="В командной строке" %}} + +Для принудительной реконсиляции [ресурса 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) добавьте к нему аннотацию `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 >}} + +Завершение принудительной реконсиляции можно отследить по полю [`status.lastForceReconcileTime`](/modules/operator-helm/cr.html#helmapplication-v1alpha1-status-lastforcereconciletime) ресурса. Например: + +```shell +d8 k -n test get helmapplication podinfo -o jsonpath='{.status.lastForceReconcileTime}' +``` + +{{% /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 >}} 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") + } +}