Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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 <token>` 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
```
10 changes: 5 additions & 5 deletions controllers/httproute_controller.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -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
}
Expand All @@ -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
}
Expand Down
4 changes: 2 additions & 2 deletions controllers/httproute_controller_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -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])
}
}
})
Expand Down
Loading