GitOps with FluxCD
Notification Controller
Webhook Receiver
In this guide, we’ll dive into the Flux Notification Controller—the component that allows you to trigger on-demand reconciliations via webhooks. You’ll learn how to set up a secure receiver endpoint, configure GitHub webhooks, and instantly reconcile changes in your Git repository.
Why Use Webhooks?
By default, the Flux Source Controller polls your Git repos at a specified interval (e.g., every 15 minutes):
flux create source git my-nginx \
--url https://github.com/sidd-harth/nginx \
--branch main \
--interval 15m
When you push a change, Flux waits for the next scheduled poll before reconciling. Webhooks let you bypass that delay—immediately notifying Flux of new commits or tag updates.
Notification Controller Overview
Component | Purpose |
---|---|
Receiver | Listens on HTTP port 9292 inside the cluster for inbound webhook events. |
Secret Validation | Verifies each incoming POST request using a shared HMAC token. |
Event Handling | Forwards validated events to Flux controllers (e.g., Source Controller) to trigger an immediate pull. |
Step 1: Create a Git Source
First, define your Git repository as a Flux GitRepository
source:
flux create source git my-nginx \
--url https://github.com/sidd-harth/nginx \
--branch main \
--interval 15m
Step 2: Generate a Webhook Secret
Create a Kubernetes secret to secure your receiver endpoint:
kubectl -n flux-system create secret generic webhook-token \
--from-literal=token=secret-token-dont-share
Note
Keep your secret token safe—anyone with this token can trigger reconciliations.
Step 3: Expose the Notification Receiver
Expose the Notification Controller on port 80 (target port 9292). Choose LoadBalancer
or NodePort
based on your cluster:
kubectl -n flux-system expose deployment notification-controller \
--name receiver \
--port 80 \
--target-port 9292 \
--type LoadBalancer
Step 4: Define the Receiver Resource
Create a Receiver
resource to handle GitHub ping
and push
events for your GitRepository:
flux create receiver github-receiver \
--type github \
--event ping,push \
--secret-ref webhook-token \
--resource GitRepository/my-nginx
Verify readiness:
flux get receivers github-receiver
Expected output:
NAME SUSPENDED READY MESSAGE
github-receiver False True Receiver initialized with URL: /hook/be1782fa344b4a24ea458be2dde11f9c289b91e
Step 5: Configure GitHub Webhook
- Open your GitHub repository settings and select Webhooks.
- Click Add webhook.
- Set Payload URL to the path shown by
flux get receivers
(e.g.,https://<LB-IP>/hook/...
). - Choose
application/json
as the content type. - Enter the Secret:
secret-token-dont-share
. - Select Let me select individual events, then check Push and Ping.
How It Works
- Push Event
GitHub sends a POST to the Flux receiver endpoint. - Validation
The Notification Controller computes an HMAC using the shared secret and compares it to theX-Hub-Signature
header. - Reconciliation
Upon successful validation, the controller signals the Source Controller. Flux pulls the latest manifests immediately, regardless of the polling interval.
Warning
Ensure your webhook endpoint is secured by a network policy or firewall to prevent unauthorized access.
Next Steps
The Flux Notification Controller also supports alert providers and various event sources (e.g., DockerHub, SQS). Stay tuned for upcoming tutorials:
- Configuring Alert Providers
- Consuming DockerHub Image Update Events
- Integrating with Cloud Event Brokers
Links and References
Watch Video
Watch video content