FluxCD Webhook

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:

  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

  webhook.secret.yaml

  apiVersion: v1
  kind: Secret
  metadata:
      name: github-webhook-token
      namespace: flux-system
  stringData:
      token: YOURSECRETKEY

  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

  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:

kubectl -n flux-system get receiver/github-receiver

Output should look something like this:

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

https://flux-webhook.mydomain.com/hook/bed6d00b5555b1603e1f59b94d7fdbca58089cb5663633fb83f2815dc626d92b

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.