release: record release phases

Makefile

@@ -148,3 +148,9 @@ generate-deploy: generate-crds pkg/install/generated_templates.gogen.go
 check-generated: generate-deploy pkg/install/generated_templates.gogen.go
 	git diff --exit-code -- pkg/install/generated_templates.gogen.go
 	./hack/update/verify.sh
+
+docs-deps:
+	pip3 install -r docs/requirements.txt
+
+serve-docs: docs-deps
+	mkdocs serve

README.md

@@ -6,8 +6,9 @@
 
 The Helm Operator is a [Kubernetes operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/),
 allowing one to declaratively manage Helm chart releases. Combined with
-[Flux](https://github.com/fluxcd/flux) it can to automate releases in a
-GitOps manner, but the use of Flux is not a strict requirement.
+[Flux](https://github.com/fluxcd/flux) this can be utilized to automate
+releases in a GitOps manner, but the usage of Flux is not a strict
+requirement.
 
 The desired state of a Helm release is described through a Kubernetes
 Custom Resource named `HelmRelease`. Based on the creation, mutation or

chart/helm-operator/crds/helmrelease.yaml

@@ -7,9 +7,17 @@ spec:
   - JSONPath: .status.releaseName
     name: Release
     type: string
+    description: ReleaseName is the name of the Helm release managed by the HelmRelease,
+      as given by Helm.
+  - JSONPath: .status.phase
+    name: Phase
+    type: string
+    description: Phase is the current release phase being performed for the HelmRelease.
   - JSONPath: .status.releaseStatus
     name: Status
     type: string
+    description: ReleaseStatus is the status of the Helm release managed by the HelmRelease,
+      as given by Helm.
   - JSONPath: .status.conditions[?(@.type=="Released")].message
     name: Message
     type: string
@@ -323,6 +331,21 @@ spec:
                 by the operator.
               type: integer
               format: int64
+            phase:
+              description: Phase the release is in, one of ('ChartFetched', 'ChartFetchFailed',
+                'Installing', 'Upgrading', 'Succeeded', 'RollingBack', 'RolledBack',
+                'RollbackFailed')
+              type: string
+              enum:
+              - ChartFetched
+              - ChartFetchFailed
+              - Installing
+              - Upgrading
+              - Succeeded
+              - Failed
+              - RollingBack
+              - RolledBack
+              - RollbackFailed
             releaseName:
               description: ReleaseName is the name as either supplied or generated.
               type: string

cmd/helm-operator/main.go

@@ -268,18 +268,19 @@ func main() {
 
 	rel := release.New(
 		log.With(logger, "component", "release"),
+		helmClients,
 		kubeClient.CoreV1(),
 		ifClient.HelmV1(),
 		gitChartSync,
-		release.Config{LogDiffs: *logReleaseDiffs, UpdateDeps: *updateDependencies},
+		release.Config{LogDiffs: *logReleaseDiffs, UpdateDeps: *updateDependencies, DefaultHelmVersion: *defaultHelmVersion},
 	)
 
 	// prepare operator and start FluxRelease informer
 	// NB: the operator needs to do its magic with the informer
 	// _before_ starting it or else the cache sync seems to hang at
 	// random
 	opr := operator.New(log.With(logger, "component", "operator"),
-		*logReleaseDiffs, kubeClient, hrInformer, queue, rel, helmClients, *defaultHelmVersion)
+		*logReleaseDiffs, kubeClient, hrInformer, queue, rel)
 	go ifInformerFactory.Start(shutdown)
 
 	// wait for the caches to be synced before starting _any_ workers

deploy/crds.yaml

@@ -8,9 +8,17 @@ spec:
   - JSONPath: .status.releaseName
     name: Release
     type: string
+    description: ReleaseName is the name of the Helm release managed by the HelmRelease,
+      as given by Helm.
+  - JSONPath: .status.phase
+    name: Phase
+    type: string
+    description: Phase is the current release phase being performed for the HelmRelease.
   - JSONPath: .status.releaseStatus
     name: Status
     type: string
+    description: ReleaseStatus is the status of the Helm release managed by the HelmRelease,
+      as given by Helm.
   - JSONPath: .status.conditions[?(@.type=="Released")].message
     name: Message
     type: string
@@ -324,6 +332,21 @@ spec:
                 by the operator.
               type: integer
               format: int64
+            phase:
+              description: Phase the release is in, one of ('ChartFetched', 'ChartFetchFailed',
+                'Installing', 'Upgrading', 'Succeeded', 'RollingBack', 'RolledBack',
+                'RollbackFailed')
+              type: string
+              enum:
+              - ChartFetched
+              - ChartFetchFailed
+              - Installing
+              - Upgrading
+              - Succeeded
+              - Failed
+              - RollingBack
+              - RolledBack
+              - RollbackFailed
             releaseName:
               description: ReleaseName is the name as either supplied or generated.
               type: string

docs/helmrelease-guide/debugging.md

@@ -16,11 +16,17 @@ logs _and_ recorded as a condition on the `HelmRelease` resource. You can view
 this condition by describing the `HelmRelease` resource using `kubectl`:
 
 ```console
-kubectl describe -n <namespace> helmrelease/<name>
+$ kubectl describe -n <namespace> helmrelease/<name>
+...
+Events:
+  Type     Reason             Age   From           Message
+  ----     ------             ----  ----           -------
+  Normal   ReleaseSynced      55s   helm-operator  managed release 'default-podinfo-0' in namespace 'default' sychronized
+  Warning  FailedReleaseSync  18s   helm-operator  synchronization of release 'default-podinfo-0' in namespace 'default' failed: upgrade failed:  "" is invalid: patch: [...]
 ```
 
 In case of a release upgrade failure, the error as returned by Helm will be
-recorded in the message of `HelmUpgradeFailed`. If this does not give a
+recorded in the message of `FailedReleaseSync`. If this does not give a
 conclusive answer the logs will likely contain more information about what
 happened during the release process:
 
@@ -40,7 +46,7 @@ and `kubectl`:
 kubectl get helmrelease/<name> -n <namespace> -o yaml | yq .spec.values -y | helm upgrade -i <release name> -f - <chart>
 ```
 
-## Getting Help
+## Getting help
 
 If you still have any questions about the Helm Operator:
 

docs/index.md

@@ -55,7 +55,7 @@ a few popular ones you might want to check out:
 - [Managing Helm releases the GitOps way](https://github.com/fluxcd/helm-operator-get-started)
 - [GitOps for Istio Canary deployments](https://github.com/stefanprodan/gitops-istio)
 
-## Getting Help
+## Getting help
 
 If you have any questions about the Helm Operator and continuous delivery:
 

docs/references/helmrelease-custom-resource.md

@@ -289,40 +289,56 @@ HelmReleaseStatus
 <table>
 <tr>
 <td>
-<code>releaseName</code><br>
+<code>observedGeneration</code><br>
 <em>
-string
+int64
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ReleaseName is the name as either supplied or generated.</p>
+<p>ObservedGeneration is the most recent generation observed by
+the operator.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>releaseStatus</code><br>
+<code>phase</code><br>
+<em>
+<a href="#helm.fluxcd.io/v1.HelmReleasePhase">
+HelmReleasePhase
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Phase the release is in, one of (&lsquo;ChartFetched&rsquo;,
+&lsquo;ChartFetchFailed&rsquo;, &lsquo;Installing&rsquo;, &lsquo;Upgrading&rsquo;, &lsquo;Succeeded&rsquo;,
+&lsquo;RollingBack&rsquo;, &lsquo;RolledBack&rsquo;, &lsquo;RollbackFailed&rsquo;)</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>releaseName</code><br>
 <em>
 string
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ReleaseStatus is the status as given by Helm for the release
-managed by this resource.</p>
+<p>ReleaseName is the name as either supplied or generated.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>observedGeneration</code><br>
+<code>releaseStatus</code><br>
 <em>
-int64
+string
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ObservedGeneration is the most recent generation observed by
-the operator.</p>
+<p>ReleaseStatus is the status as given by Helm for the release
+managed by this resource.</p>
 </td>
 </tr>
 <tr>
@@ -781,6 +797,23 @@ Valid HelmReleaseConditionType values are:
 &ldquo;ChartFetched&rdquo;,
 &ldquo;Released&rdquo;,
 &ldquo;RolledBack&rdquo;</p>
+<h3 id="helm.fluxcd.io/v1.HelmReleasePhase">HelmReleasePhase
+(<code>string</code> alias)</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#helm.fluxcd.io/v1.HelmReleaseStatus">HelmReleaseStatus</a>)
+</p>
+<p>HelmReleasePhase represents the phase a HelmRelease is in.
+Valid HelmReleasePhase values are:
+&ldquo;ChartFetched&rdquo;,
+&ldquo;ChartFetchFailed&rdquo;,
+&ldquo;Installing&rdquo;,
+&ldquo;Upgrading&rdquo;,
+&ldquo;Succeeded&rdquo;,
+&ldquo;Failed&rdquo;,
+&ldquo;RollingBack&rdquo;,
+&ldquo;RolledBack&rdquo;,
+&ldquo;RollbackFailed&rdquo;,</p>
 <h3 id="helm.fluxcd.io/v1.HelmReleaseSpec">HelmReleaseSpec
 </h3>
 <p>
@@ -1026,40 +1059,56 @@ HelmValues
 <tbody>
 <tr>
 <td>
-<code>releaseName</code><br>
+<code>observedGeneration</code><br>
 <em>
-string
+int64
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ReleaseName is the name as either supplied or generated.</p>
+<p>ObservedGeneration is the most recent generation observed by
+the operator.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>releaseStatus</code><br>
+<code>phase</code><br>
+<em>
+<a href="#helm.fluxcd.io/v1.HelmReleasePhase">
+HelmReleasePhase
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Phase the release is in, one of (&lsquo;ChartFetched&rsquo;,
+&lsquo;ChartFetchFailed&rsquo;, &lsquo;Installing&rsquo;, &lsquo;Upgrading&rsquo;, &lsquo;Succeeded&rsquo;,
+&lsquo;RollingBack&rsquo;, &lsquo;RolledBack&rsquo;, &lsquo;RollbackFailed&rsquo;)</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>releaseName</code><br>
 <em>
 string
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ReleaseStatus is the status as given by Helm for the release
-managed by this resource.</p>
+<p>ReleaseName is the name as either supplied or generated.</p>
 </td>
 </tr>
 <tr>
 <td>
-<code>observedGeneration</code><br>
+<code>releaseStatus</code><br>
 <em>
-int64
+string
 </em>
 </td>
 <td>
 <em>(Optional)</em>
-<p>ObservedGeneration is the most recent generation observed by
-the operator.</p>
+<p>ReleaseStatus is the status as given by Helm for the release
+managed by this resource.</p>
 </td>
 </tr>
 <tr>

docs/references/monitoring.md

@@ -8,5 +8,6 @@ The following metrics are exposed:
 
 | Metric | Description
 |--------|---
-| `release_duration_seconds` | Release duration in seconds.
-| `release_queue_length_count` | Count of releases waiting in the queue to be processed.
+| `release_duration_seconds` | Release synchronization duration in seconds. |
+| `release_phase_duration_seconds` | Release phase synchronization duration in seconds. |
+| `release_queue_length_count` | Count of release jobs waiting in the queue to be processed. |

go.mod

@@ -35,6 +35,7 @@ require (
 	k8s.io/klog v1.0.0
 	k8s.io/kubectl v0.17.2
 	k8s.io/utils v0.0.0-20191114184206-e782cd3c129f
+	sigs.k8s.io/yaml v1.1.0
 )
 
 // github.com/fluxcd/helm-operator/pkg/install lives in this very reprository, so use that

go.sum

@@ -132,6 +132,7 @@ github.com/containerd/containerd v1.3.2/go.mod h1:bC6axHOhabU15QhwfG7w5PipXdVtMX
 github.com/containerd/continuity v0.0.0-20190426062206-aaeac12a7ffc/go.mod h1:GL3xCUCBDV3CZiTSEKksMWbLE66hEyuu9qyDOOqM47Y=
 github.com/containerd/continuity v0.0.0-20200107194136-26c1120b8d41 h1:kIFnQBO7rQ0XkMe6xEwbybYHBEaWmh/f++laI6Emt7M=
 github.com/containerd/continuity v0.0.0-20200107194136-26c1120b8d41/go.mod h1:Dq467ZllaHgAtVp4p1xUQWBrFXR9s/wyoTpG8zOJGkY=
+github.com/containerd/fifo v0.0.0-20190226154929-a9fb20d87448 h1:PUD50EuOMkXVcpBIA/R95d56duJR9VxhwncsFbNnxW4=
 github.com/containerd/fifo v0.0.0-20190226154929-a9fb20d87448/go.mod h1:ODA38xgv3Kuk8dQz2ZQXpnv/UZZUHUCL7pnLehbXgQI=
 github.com/containerd/go-runc v0.0.0-20180907222934-5a6d9f37cfa3/go.mod h1:IV7qH3hrUgRmyYrtgEeGWJfWbgcHL9CSRruz2Vqcph0=
 github.com/containerd/ttrpc v0.0.0-20190828154514-0e0f228740de/go.mod h1:PvCDdDGpgqzQIzDW1TphrGLssLDZp2GuS+X5DkEJB8o=