Merge pull request #93 from seaneagan/helmrelease-doc-updates

api/v2alpha1/condition_types.go

@@ -17,16 +17,17 @@ limitations under the License.
 package v2alpha1
 
 const (
-	// ReleasedCondition represents the fact that the HelmRelease has been
-	// successfully released.
+	// ReleasedCondition represents the status of the last release attempt
+	// (install/upgrade/test) against the latest desired state.
 	ReleasedCondition string = "Released"
 
-	// TestSuccessCondition represents the fact that the tests for the HelmRelease
-	// are succeeding.
+	// TestSuccessCondition represents the status of the last test attempt against
+	// the latest desired state.
 	TestSuccessCondition string = "TestSuccess"
 
-	// RemediatedCondition represents the fact that the HelmRelease has been
-	// successfully remediated.
+	// RemediatedCondition represents the status of the last remediation attempt
+	// (uninstall/rollback) due to a failure of the last release attempt against the
+	// latest desired state.
 	RemediatedCondition string = "Remediated"
 )
 
@@ -53,7 +54,7 @@ const (
 
 	// TestFailedReason represents the fact that the Helm tests for the HelmRelease
 	// failed.
-	TestFailedReason string = "TestsFailed"
+	TestFailedReason string = "TestFailed"
 
 	// RollbackSucceededReason represents the fact that the Helm rollback for the
 	// HelmRelease succeeded.

api/v2alpha1/helmrelease_types.go

@@ -33,7 +33,7 @@ import (
 const HelmReleaseKind = "HelmRelease"
 const HelmReleaseFinalizer = "finalizers.fluxcd.io"
 
-// HelmReleaseSpec defines the desired state of a Helm Release.
+// HelmReleaseSpec defines the desired state of a Helm release.
 type HelmReleaseSpec struct {
 	// Chart defines the template of the v1alpha1.HelmChart that should be created
 	// for this HelmRelease.
@@ -500,6 +500,7 @@ const (
 	// RollbackRemediationStrategy represents a Helm remediation strategy of Helm
 	// rollback.
 	RollbackRemediationStrategy RemediationStrategy = "rollback"
+
 	// UninstallRemediationStrategy represents a Helm remediation strategy of Helm
 	// uninstall.
 	UninstallRemediationStrategy RemediationStrategy = "uninstall"
@@ -639,17 +640,17 @@ type HelmReleaseStatus struct {
 	// +optional
 	HelmChart string `json:"helmChart,omitempty"`
 
-	// Failures is the reconciliation failure count against the latest observed
+	// 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
+	// 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
+	// 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

@@ -46,7 +46,7 @@ spec:
           metadata:
             type: object
           spec:
-            description: HelmReleaseSpec defines the desired state of a Helm Release.
+            description: HelmReleaseSpec defines the desired state of a Helm release.
             properties:
               chart:
                 description: Chart defines the template of the v1alpha1.HelmChart
@@ -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

@@ -564,7 +564,7 @@ relative path in the SourceRef. Ignored when omitted.</p>
 (<em>Appears on:</em>
 <a href="#helm.toolkit.fluxcd.io/v2alpha1.HelmRelease">HelmRelease</a>)
 </p>
-<p>HelmReleaseSpec defines the desired state of a Helm Release.</p>
+<p>HelmReleaseSpec defines the desired state of a Helm release.</p>
 <div class="md-typeset__scrollwrap">
 <div class="md-typeset__table">
 <table>
@@ -914,7 +914,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>Failures is the reconciliation failure count against the latest observed
+<p>Failures is the reconciliation failure count against the latest desired
 state. It is reset after a successful reconciliation.</p>
 </td>
 </tr>
@@ -927,7 +927,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>InstallFailures is the install failure count against the latest observed
+<p>InstallFailures is the install failure count against the latest desired
 state. It is reset after a successful reconciliation.</p>
 </td>
 </tr>
@@ -940,7 +940,7 @@ int64
 </td>
 <td>
 <em>(Optional)</em>
-<p>UpgradeFailures is the upgrade failure count against the latest observed
+<p>UpgradeFailures is the upgrade failure count against the latest desired
 state. It is reset after a successful reconciliation.</p>
 </td>
 </tr>

docs/spec/README.md

@@ -1,12 +1,12 @@
 # Helm Controller
 
-The Helm Controller is a Kubernetes operator, allowing one to declaratively manage Helm chart
-releases with Kubernetes manifests.
+The Helm Controller is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
+allowing one to declaratively manage Helm chart releases with Kubernetes manifests.
 
 ## Motivation
 
 The main goal is to provide an automated operator that can perform Helm actions (e.g.
-install, upgrade, rollback, test) and continuously reconcile the state of Helm releases.
+install, upgrade, uninstall, rollback, test) and continuously reconcile the state of Helm releases.
 
 When provisioning a new cluster, one may wish to install Helm releases in a specific order, for
 example because one relies on a service mesh admission controller managed by a `HelmRelease` and
@@ -17,7 +17,7 @@ and this chart needs to be installed first.
 When dealing with an incident, one may wish to suspend the reconciliation of some Helm releases,
 without having to stop the reconciler and affect the whole cluster.
 
-When operating a cluster, different teams may wish to receive notification about the status of
+When operating a cluster, different teams may wish to receive notifications about the status of
 their Helm releases. For example, the on-call team would receive alerts about all failures in
 the prod namespace, while the frontend team may wish to be alerted when a new version of the
 frontend chart was released, no matter the namespace.
@@ -34,7 +34,7 @@ actions that should be (conditionally) executed. Based on this the reconciler:
 - fetches the available chart artifact
 - performs a Helm install or upgrade action if needed
 - performs a Helm test action if enabled
-- performs a reconciliation strategy as configured (rollback, uninstall) if any Helm action failed
+- performs a reconciliation strategy (rollback, uninstall) and retries as configured if any Helm action failed
 
 The controller that runs these Helm actions relies on [source-controller](https://github.com/fluxcd/source-controller)
 for providing the Helm charts from Helm repositories or any other source that source-controller

docs/spec/v2alpha1/README.md

@@ -6,12 +6,17 @@ Kubernetes manifests.
 ## Specification
 
 - [`HelmRelease` CRD](helmreleases.md)
-    + [Source reference](helmreleases.md#source-reference)
+    + [Specification](helmreleases.md#specification)
+        * [Reference types](helmreleases.md#reference-types)
+        * [Status specification](helmreleases.md#status-specification)
+    + [Helm release placement](helmreleases.md#helm-release-placement)
+    + [Helm chart template](helmreleases.md#helm-chart-template)
+    + [Values overrides](helmreleases.md#values-overrides)
     + [Reconciliation](helmreleases.md#reconciliation)
-    + [`HelmRelease` dependencies](helmreleases.md#helmrelease-dependencies)
-    + [Configuring failure remediation](helmreleases.md#configuring-failure-remediation)
-    + [Enabling Helm rollback actions](helmreleases.md#enabling-helm-rollback-actions)
-    + [Enabling Helm test actions](helmreleases.md#configuring-helm-test-actions)
+        * [Disabling resource waiting](helmreleases.md#disabling-resource-waiting)
+        * [`HelmRelease` dependencies](helmreleases.md#helmrelease-dependencies)
+        * [Configuring Helm test actions](helmreleases.md#configuring-helm-test-actions)
+        * [Configuring failure remediation](helmreleases.md#configuring-failure-remediation)
     + [Status](helmreleases.md#status)
 
 ## Implementation