From 6db64c38ba9227e417575d46778b2a510e18deac Mon Sep 17 00:00:00 2001 From: Gaston Festari Date: Fri, 13 Nov 2026 15:42:08 -0300 Subject: [PATCH 1/2] refactor: rename and namespace annotations --- controllers/httproute_controller.go | 10 +++++----- controllers/httproute_controller_test.go | 4 ++-- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/controllers/httproute_controller.go b/controllers/httproute_controller.go index ebbb11a..2884cff 100644 --- a/controllers/httproute_controller.go +++ b/controllers/httproute_controller.go @@ -17,9 +17,9 @@ import ( ) const ( - triggerAnnotation = "com.example/trigger" - lastSyncedAnnotation = "com.example/syncedAt" - finalizerName = "com.example/finalizer" + triggerAnnotation = "probe-controller.local/register" + checksumAnnotation = "probe-controller.local/checksum" + finalizerName = "probe-controller.local/finalizer" ) type HTTPRouteWatcher struct { @@ -88,7 +88,7 @@ func (r *HTTPRouteWatcher) Reconcile(ctx context.Context, req ctrl.Request) (ctr return ctrl.Result{}, err } - lastSyncedHash := route.Annotations[lastSyncedAnnotation] + lastSyncedHash := route.Annotations[checksumAnnotation] if currentHash == lastSyncedHash { return ctrl.Result{}, nil } @@ -113,7 +113,7 @@ func (r *HTTPRouteWatcher) Reconcile(ctx context.Context, req ctrl.Request) (ctr if route.Annotations == nil { route.Annotations = make(map[string]string) } - route.Annotations[lastSyncedAnnotation] = currentHash + route.Annotations[checksumAnnotation] = currentHash if err := r.Update(ctx, &route); err != nil { return ctrl.Result{}, err } diff --git a/controllers/httproute_controller_test.go b/controllers/httproute_controller_test.go index f3fbd8c..0a836ec 100644 --- a/controllers/httproute_controller_test.go +++ b/controllers/httproute_controller_test.go @@ -335,8 +335,8 @@ func TestHTTPRouteWatcher_ErrorsAndAuth(t *testing.T) { t.Fatalf("finalizer present = %v, want %v", hasFinalizer, tc.wantFinalizerKept) } - if tc.wantErr && current.Annotations[lastSyncedAnnotation] != "" { - t.Fatalf("expected lastSyncedAnnotation not to be stamped on failed API call, got %q", current.Annotations[lastSyncedAnnotation]) + if tc.wantErr && current.Annotations[checksumAnnotation] != "" { + t.Fatalf("expected checksumAnnotation not to be stamped on failed API call, got %q", current.Annotations[checksumAnnotation]) } } }) From dbb62c822fc43c96aa25abfdc815f1de76329feb Mon Sep 17 00:00:00 2001 From: Gaston Festari Date: Fri, 13 Nov 2026 15:59:42 -0300 Subject: [PATCH 2/2] docs: add readme --- README.md | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2105185 --- /dev/null +++ b/README.md @@ -0,0 +1,109 @@ +# probe-controller + +A lightweight Kubernetes controller built with `controller-runtime` that watches +Gateway API `HTTPRoute` resources and sends webhook notifications to an external +API on **create**, **update**, and **delete** events. + +## How It Works + +1. **Opt-in via Annotation**: Only `HTTPRoute` resources annotated with + `probe-controller.local/register: "true"` are synced. +2. **Spec Hashing**: A SHA-256 hash of `route.spec` is kept as a + `probe-controller.local/checksum` annotation on the HTTPRoute so status-only updates from Gateway controllers do not trigger duplicate API calls. +3. **Finalizer Cleanup**: Attaches `probe-controller.local/finalizer` to tracked + routes so `DELETED` events are reliably delivered before Kubernetes removes the resource from etcd. + +## Configuration + +The following environment variables are supported: + +| Variable | Required | Description | +| --- | --- | --- | +| `EXTERNAL_API_URL` | **Yes** | Target HTTP/HTTPS endpoint that receives `POST` JSON payloads. | +| `EXTERNAL_API_TOKEN` | No | Optional Bearer token sent in the `Authorization: Bearer ` header. | + +These should be mounted from a Secret source on the namespace. + +### CLI Flags + +The following CLI flags can be passed to the binary: + +| Flag | Default | Description | +| --- | --- | --- | +| `--leader-elect` | `false` | Enable leader election for high-availability multi-replica deployments. | +| `--metrics-bind-address` | `:8080` | Address the Prometheus metrics endpoint binds to. | +| `--health-probe-bind-address` | `:8081` | Address the `/healthz` and `/readyz` endpoints bind to. | + +## Usage + +Annotate any `HTTPRoute` with `probe-controller.local/register: "true"` to +enable webhook notifications: + +```yaml +apiVersion: gateway.networking.k8s.io/v1 +kind: HTTPRoute +metadata: + name: example-route + namespace: default + annotations: + probe-controller.local/register: "true" +spec: + parentRefs: + - name: my-gateway + hostnames: + - "api.example.com" + rules: + - backendRefs: + - name: my-service + port: 8080 +``` + +### Webhook Payload Format + +The controller sends an HTTP `POST` with `Content-Type: application/json`: + +```json +{ + "event": "CREATED", + "name": "example-route", + "namespace": "default", + "hostnames": ["api.example.com"] +} +``` + +* `event` is one of `CREATED`, `UPDATED`, or `DELETED`. +* `hostnames` is omitted on `DELETED` events. + +## Deployment + +Update the image reference and Secret values (`EXTERNAL_API_URL` and + `EXTERNAL_API_TOKEN`) in `deploy/manifests/deploy.yaml`. + +Apply the manifests to your cluster: + +```bash +kubectl apply --server-side -f deploy.yaml +``` + +## Running Locally + +```bash +export EXTERNAL_API_URL="https://webhooks.example.com" +go run main.go +``` + +### Run Tests & Linter + +```bash +make test +make lint +``` + +### Build Multi-Arch Container Image + +Build `linux/amd64` and `linux/arm64` container images locally using Docker +Buildx Bake: + +```bash +make bake +```