Merge pull request #97 from fluxcd/helm-webhooks

Add webhook receivers section to Helm guide

docs/guides/helmreleases.md

@@ -1,4 +1,4 @@
-# Manage Helm releases
+# Manage Helm Releases
 
 The [helm-controller](../components/helm/controller.md) allows you to
 declaratively manage Helm chart releases with Kubernetes manifests.
@@ -93,7 +93,7 @@ helm-controller.
     See the [`HelmRelease` CRD docs](../components/helm/helmreleases.md)
     for more details.
 
-## Receive notifications
+## Configure notifications
 
 The default toolkit installation configures the helm-controller to
 broadcast events to the [notification-controller](../components/notification/controller.md).
@@ -126,3 +126,67 @@ apiVersion: notification.fluxcd.io/v1alpha1
 ```
 
 ![helm-controller alerts](../diagrams/helm-controller-alerts.png)
+
+## Configure webhook receivers
+
+When using semver ranges for Helm releases, you may want to trigger an update
+as soon as a new chart version is published to your Helm repository.
+In order to notify source-controller about a chart update,
+you can [setup webhook receivers](webhook-receivers.md).
+
+First generate a random string and create a secret with a `token` field:
+
+```sh
+TOKEN=$(head -c 12 /dev/urandom | shasum | cut -d ' ' -f1)
+echo $TOKEN
+
+kubectl -n gitops-system create secret generic webhook-token \	
+--from-literal=token=$TOKEN
+```
+
+When using [Harbor](https://goharbor.io/) as your Helm repository, you can define a receiver with:
+
+```yaml
+apiVersion: notification.fluxcd.io/v1alpha1
+kind: Receiver
+metadata:
+  name: helm-podinfo
+  namespace: gitops-system
+spec:
+  type: harbor
+  secretRef:
+    name: webhook-token
+  resources:
+    - kind: HelmRepository
+      name: podinfo
+```
+
+The notification-controller generates a unique URL using the provided token and the receiver name/namespace.
+
+Find the URL with:
+
+```console
+$ kubectl -n gitops-system get receiver/helm-podinfo
+
+NAME           READY   STATUS
+helm-podinfo   True    Receiver initialised with URL: /hook/bed6d00b5555b1603e1f59b94d7fdbca58089cb5663633fb83f2815dc626d92b
+```
+
+Log in to the Harbor interface, go to Projects, select a project, and select Webhooks.
+Fill the form with:
+
+* Endpoint URL: compose the address using the receiver LB and the generated URL `http://<LoadBalancerAddress>/<ReceiverURL>`
+* Auth Header: use the `token` string
+
+With the above settings, when you upload a chart, the following happens:
+
+* Harbor sends the chart push event to the receiver address
+* Notification controller validates the authenticity of the payload using the auth header
+* Source controller is notified about the changes
+* Source controller pulls the changes into the cluster and updates the `HelmChart` version
+* Helm controller is notified about the version change and upgrades the release
+
+!!! hint "Note"
+    Besides Harbor, you can define receivers for **GitHub**, **GitLab**, **Bitbucket**
+    and any other system that supports webhooks e.g. Jenkins, CircleCI, etc.
+    See the [Receiver CRD docs](../components/notification/receiver.md) for more details.

mkdocs.yml

@@ -40,7 +40,7 @@ nav:
   - Introduction: index.md
   - Get Started: get-started/index.md
   - Guides:
-      - Manage Helm releases: guides/helmreleases.md
+      - Manage Helm Releases: guides/helmreleases.md
       - Setup Notifications: guides/notifications.md
       - Setup Webhook Receivers: guides/webhook-receivers.md
   - Toolkit Components: