fix(docs): Add fluxcd webhook guide (#33002)

**Description**  ⚒️ Fixes #  **⚙️ Type of change** - [ ] ⚙️ Feature/App addition - [ ] 🪛 Bugfix - [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] 🔃 Refactor of current code - [x] 📜 Documentation Changes **🧪 How Has This Been Tested?**  **📃 Notes:**  **✔️ Checklist:** - [ ] ⚖️ My code follows the style guidelines of this project - [ ] 👀 I have performed a self-review of my own code - [ ] #️⃣ I have commented my code, particularly in hard-to-understand areas - [x] 📄 I have made changes to the documentation - [ ] 🧪 I have added tests to this description that prove my fix is effective or that my feature works - [ ] ⬆️ I increased versions for any altered app according to semantic versioning - [ ] I made sure the title starts with `feat(chart-name):`, `fix(chart-name):`, `chore(chart-name):`, `docs(chart-name):` or `fix(docs):` **➕ App addition** If this PR is an app addition please make sure you have done the following. - [ ] 🖼️ I have added an icon in the Chart's root directory called `icon.png` --- _Please don't blindly check all the boxes. Read them and only check those that apply. Those checkboxes are there for the reviewer to see what is this all about and the status of this PR with a quick glance._
2025-03-08 15:10:46 +01:00
parent 46db7d757f
commit 8f6bb6883b
2 changed files with 154 additions and 0 deletions
@@ -0,0 +1,154 @@
+---
+title: FluxCD Webhook
+---
+
+:::warning
+
+This guide isnt covered by the Support Policy and is considered more advanced. 
+If you face issues feel free to open a thread in the appropiate Channel in our Discord server.
+
+:::
+
+## Prerequisites
+
+- Having a running Kubernetes cluster
+- Bootstrapped fluxcd
+- Knowledge on how to add charts/kubernetes resources with fluxcd
+- Usage of an ingress to make the webhook accessible from outside your network
+
+## Initial Setup
+
+- Create a new folder called `webhooks` inside the `flux-system` folder.
+- Add a subfolder called `github`
+- Add the necessary kustomization to the `webhooks` folder for the github directory
+- Next we will need 3 files inside the github folder:
+  ```yaml
+    // receiver.yaml 
+
+    apiVersion: notification.toolkit.fluxcd.io/v1
+    kind: Receiver
+    metadata:
+      name: github-receiver
+      namespace: flux-system
+    spec:
+      type: github
+      events:
+        - "ping"
+        - "push"
+      secretRef:
+        name: github-webhook-token
+      resources:
+        - kind: GitRepository
+          name: cluster
+          namespace: flux-system
+
+  ```
+
+  ```yaml
+  // webhook.secret.yaml
+
+  apiVersion: v1
+  kind: Secret
+  metadata:
+      name: github-webhook-token
+      namespace: flux-system
+  stringData:
+      token: YOURSECRETKEY
+
+  ```
+
+  ```yaml
+  // ingress.yaml
+
+  apiVersion: networking.k8s.io/v1
+  kind: Ingress
+  metadata:
+    name: webhook-receiver
+    namespace: flux-system
+    annotations:
+        cert-manager.io/cluster-issuer: domain-1-le-prod
+        cert-manager.io/private-key-rotation-policy: Always
+        traefik.ingress.kubernetes.io/router.entrypoints: websecure
+        traefik.ingress.kubernetes.io/router.middlewares: traefik-chain-basic@kubernetescrd
+        traefik.ingress.kubernetes.io/router.tls: "true"
+  spec:
+    rules:
+    - host: flux-webhook.${DOMAIN_0}
+      http:
+        paths:
+        - pathType: Prefix
+          path: /
+          backend:
+            service:
+              name: webhook-receiver
+              port:
+                number: 80
+    tls:
+      - hosts:
+        - flux-webhook.${DOMAIN_0}
+        secretName: flux-webhook-tls-0
+
+  ```
+
+- Add the necessary kustomization to add all 3 of those files to your cluster
+
+## Create your Webhook Token
+
+- Run the following command to generate your Webhook Token
+
+  ```bash
+  TOKEN=$(head -c 12 /dev/urandom | shasum | cut -d ' ' -f1)
+  echo $TOKEN
+  ```
+- Replace `YOURSECRETKEY` with your generated Webhook Token
+- Make sure to run `clustertool encrypt` to encrypt your files
+- Push changes to your cluster before continuing
+
+## Get Receiver URL:
+
+After pushing the changes to your cluster and waiting for reconcile. 
+Run the following command to get your receiver url:
+
+```bash
+
+kubectl -n flux-system get receiver/github-receiver
+
+```
+
+Output should look something like this:
+
+```bash
+
+NAME     READY   STATUS
+github-receiver   True    Receiver initialised with URL: /hook/bed6d00b5555b1603e1f59b94d7fdbca58089cb5663633fb83f2815dc626d92b
+
+```
+Next you will have to add your domain and subdomain to it.
+Example
+```yaml
+https://flux-webhook.mydomain.com/hook/bed6d00b5555b1603e1f59b94d7fdbca58089cb5663633fb83f2815dc626d92b
+```
+
+:::warning
+
+Make sure the flux-webhook.mydomain.com is accessible from outside your network. Otherwise it will not work.
+
+:::
+
+## Adding the webhook to github
+
+- Open your cluster repository on Github and go to settings
+- Next select `Webhooks` on the left menu
+- Click `Add webhook`
+- Add your Receiver Url into the `Payload URL`
+- Select the `Content type` to `application/x-www-form-urlencoded`
+- Add your Webhook Token to the `Secret` field
+- Leave the rest of the options default
+- Click `Add webhook` to finish the creation
+
+## Finishing Steps
+
+You should now see your Webhook in the Github Webhook Menu.
+Click on it and check the `Recent Deliveries` if the test was successfull
+
+If it worked. Your done and now each push to the main branch should trigger a reconcile on your cluster.