From cf21f30f80324fdb9ea490914629d8939c1ae642 Mon Sep 17 00:00:00 2001 From: Sean Eagan Date: Tue, 29 Sep 2020 09:42:46 -0500 Subject: [PATCH] Document HelmRelease desired state transitions This documents what is considered a desired state transition, and the resulting upgrade and status condition semantics. --- api/v2alpha1/condition_types.go | 6 +-- api/v2alpha1/helmrelease_types.go | 6 +-- .../helm.toolkit.fluxcd.io_helmreleases.yaml | 6 +-- docs/api/helmrelease.md | 6 +-- docs/spec/v2alpha1/helmreleases.md | 41 +++++++++++-------- 5 files changed, 37 insertions(+), 28 deletions(-) diff --git a/api/v2alpha1/condition_types.go b/api/v2alpha1/condition_types.go index 85651490d..37911c1ba 100644 --- a/api/v2alpha1/condition_types.go +++ b/api/v2alpha1/condition_types.go @@ -51,14 +51,14 @@ const ( // ReadyCondition represents the status of the last reconciliation attempt. ReadyCondition string = "Ready" - // ReleasedCondition represents the status of the last release attempt (install/upgrade/test) against the current state. + // ReleasedCondition represents the status of the last release attempt (install/upgrade/test) against the latest desired state. ReleasedCondition string = "Released" - // TestSuccessCondition represents the status of the last test attempt against the current state. + // TestSuccessCondition represents the status of the last test attempt against the latest desired state. TestSuccessCondition string = "TestSuccess" // RemediatedCondition represents the status of the last remediation attempt (uninstall/rollback) due to a failure of the - // last release attempt against the current state. + // last release attempt against the latest desired state. RemediatedCondition string = "Remediated" ) diff --git a/api/v2alpha1/helmrelease_types.go b/api/v2alpha1/helmrelease_types.go index c21a5325a..d25f56b9d 100644 --- a/api/v2alpha1/helmrelease_types.go +++ b/api/v2alpha1/helmrelease_types.go @@ -623,17 +623,17 @@ type HelmReleaseStatus struct { // +optional HelmChart string `json:"helmChart,omitempty"` - // Failures is the reconciliation failure count against the latest observed state. + // Failures is the reconciliation failure count against the latest desired state. // It is reset after a successful reconciliation. // +optional Failures int64 `json:"failures,omitempty"` - // InstallFailures is the install failure count against the latest observed state. + // InstallFailures is the install failure count against the latest desired state. // It is reset after a successful reconciliation. // +optional InstallFailures int64 `json:"installFailures,omitempty"` - // UpgradeFailures is the upgrade failure count against the latest observed state. + // UpgradeFailures is the upgrade failure count against the latest desired state. // It is reset after a successful reconciliation. // +optional UpgradeFailures int64 `json:"upgradeFailures,omitempty"` diff --git a/config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml b/config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml index 923123498..473098c74 100644 --- a/config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml +++ b/config/crd/bases/helm.toolkit.fluxcd.io_helmreleases.yaml @@ -429,7 +429,7 @@ spec: type: array failures: description: Failures is the reconciliation failure count against - the latest observed state. It is reset after a successful reconciliation. + the latest desired state. It is reset after a successful reconciliation. format: int64 type: integer helmChart: @@ -438,7 +438,7 @@ spec: type: string installFailures: description: InstallFailures is the install failure count against - the latest observed state. It is reset after a successful reconciliation. + the latest desired state. It is reset after a successful reconciliation. format: int64 type: integer lastAppliedRevision: @@ -467,7 +467,7 @@ spec: type: integer upgradeFailures: description: UpgradeFailures is the upgrade failure count against - the latest observed state. It is reset after a successful reconciliation. + the latest desired state. It is reset after a successful reconciliation. format: int64 type: integer type: object diff --git a/docs/api/helmrelease.md b/docs/api/helmrelease.md index 4406851fa..c000d90e4 100644 --- a/docs/api/helmrelease.md +++ b/docs/api/helmrelease.md @@ -996,7 +996,7 @@ int64 (Optional) -

Failures is the reconciliation failure count against the latest observed state. +

Failures is the reconciliation failure count against the latest desired state. It is reset after a successful reconciliation.

@@ -1009,7 +1009,7 @@ int64 (Optional) -

InstallFailures is the install failure count against the latest observed state. +

InstallFailures is the install failure count against the latest desired state. It is reset after a successful reconciliation.

@@ -1022,7 +1022,7 @@ int64 (Optional) -

UpgradeFailures is the upgrade failure count against the latest observed state. +

UpgradeFailures is the upgrade failure count against the latest desired state. It is reset after a successful reconciliation.

diff --git a/docs/spec/v2alpha1/helmreleases.md b/docs/spec/v2alpha1/helmreleases.md index 7bb0d32e8..e8901ba00 100644 --- a/docs/spec/v2alpha1/helmreleases.md +++ b/docs/spec/v2alpha1/helmreleases.md @@ -7,10 +7,10 @@ action trigger configuration, individual action configuration, and statusing. ## Helm release placement -The namespace/name in which to deploy the helm release defaults to the namespace/name of the +The namespace/name in which to deploy the Helm release defaults to the namespace/name of the `HelmRelease`. These can be overridden respectively via `spec.targetNamespace` and `spec.releaseName`. If `spec.targetNamespace` is set, `spec.releaseName` defaults to -`-`. +`-`. ## Helm chart template @@ -29,7 +29,7 @@ Supported source types: * [Bucket](https://github.com/fluxcd/source-controller/blob/master/docs/spec/v1alpha1/buckets.md) The `HelmChart` is created in the same namespace as the `sourceRef`, -with a name of `-`. +with a name matching the `HelmRelease` `-`. The `chart.spec.chart` can either contain: @@ -60,8 +60,8 @@ spec: - kind: Secret name: prod-tls-values valuesKey: crt - targetPath: tls.crt - optional: true + targetPath: tls.crt + optional: true ``` The definition of the listed keys for items in `spec.valuesFrom` is as follows: @@ -90,18 +90,21 @@ The definition of the listed keys for items in `spec.valuesFrom` is as follows: ## Reconciliation -If a helm release with the matching namespace/name is not found it will be installed, otherwise -it will be upgraded. +If no Helm release with the matching namespace/name is found it will be installed. It will +be upgraded any time the desired state is updated, which consists of: -The timeout for any individual Kubernetes operation (like Jobs for hooks) during the performance -of helm actions can be configured via `spec.timeout` and can be overridden per action -via `spec..timeout`. +* `spec` (and thus `metadata.generation`) +* Latest `HelmChart` revision available +* [`ConfigMap` and `Secret` values overrides](#values-overrides). Changes to these do not trigger an + immediate reconciliation, but will be handled upon the next reconciliation. This is to avoid + a large number of upgrades occuring when multiple resources are updated. + +If the latest Helm release revision was not made by the helm-controller, it may not match the +desired state, so an upgrade is made in this case as well. The `spec.interval` tells the reconciler at which interval to reconcile the release. The interval time units are `s`, `m` and `h` e.g. `interval: 5m`, the minimum value should be 60 seconds. -The reconcilation can be suspended by setting `spec.susped` to `true`. - The reconciler can be told to reconcile the `HelmRelease` outside of the specified interval by annotating the object with a `fluxcd.io/reconcileAt` annotation. For example: @@ -109,6 +112,12 @@ by annotating the object with a `fluxcd.io/reconcileAt` annotation. For example: kubectl annotate --overwrite helmrelease/podinfo fluxcd.io/reconcileAt="$(date +%s)" ``` +Reconcilation can be suspended by setting `spec.susped` to `true`. + +The timeout for any individual Kubernetes operation (like Jobs for hooks) during the performance +of Helm actions can be configured via `spec.timeout` and can be overridden per action +via `spec..timeout`. + ### Disabling resource waiting For install, upgrade, and rollback actions resource waiting is enabled by default, @@ -276,21 +285,21 @@ to true if at least one retry is configured. When the controller completes a reconciliation, it reports the result in the status sub-resource. -The following `status.condtions` types are supported: +The following `status.condtions` types are supported. Here, "desired state" is as detailed in [reconciliation](#reconciliation): ```go const ( // ReadyCondition represents the status of the last reconciliation attempt. ReadyCondition string = "Ready" - // ReleasedCondition represents the status of the last release attempt (install/upgrade/test) against the current state. + // ReleasedCondition represents the status of the last release attempt (install/upgrade/test) against the latest desired state. ReleasedCondition string = "Released" - // TestSuccessCondition represents the status of the last test attempt against the current state. + // TestSuccessCondition represents the status of the last test attempt against the latest desired state. TestSuccessCondition string = "TestSuccess" // RemediatedCondition represents the status of the last remediation attempt (uninstall/rollback) due to a failure of the - // last release attempt against the current state. + // last release attempt against the latest desired state. RemediatedCondition string = "Remediated" ) ```