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

@@ -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"
 )
 

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

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

docs/api/helmrelease.md

@@ -996,7 +996,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>Failures is the reconciliation failure count against the latest observed state.
+<p>Failures is the reconciliation failure count against the latest desired state.
 It is reset after a successful reconciliation.</p>
 </td>
 </tr>
@@ -1009,7 +1009,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>InstallFailures is the install failure count against the latest observed state.
+<p>InstallFailures is the install failure count against the latest desired state.
 It is reset after a successful reconciliation.</p>
 </td>
 </tr>
@@ -1022,7 +1022,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>UpgradeFailures is the upgrade failure count against the latest observed state.
+<p>UpgradeFailures is the upgrade failure count against the latest desired state.
 It is reset after a successful reconciliation.</p>
 </td>
 </tr>

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
-`<spec.targetNamespace>-<HelmRelease name>`.
+`<spec.targetNamespace>-<metadata.name>`.
 
 ## 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 `<HelmRelease namespace>-<HelmRelease name>`.
+with a name matching the `HelmRelease` `<metadata.namespace>-<metadata.name>`.
 
 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,25 +90,34 @@ 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.<action>.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:
 
 ```bash
 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.<action>.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"
 )
 ```