|
8 | 8 | [](https://github.com/DoodleScheduling/webhook-controller/blob/master/LICENSE) |
9 | 9 |
|
10 | 10 | This HTTP proxy duplicates incoming requests and sends concurrently to multiple targets. |
11 | | -The response will be HTTP 202 Accepted if at least one matching target was found. The responses from the targets are not exposed |
12 | | -to upstream by design. |
| 11 | +The response is asynchronous by default `HTTP 202 Accepted` if at least one matching target was found. |
| 12 | +However alternatively synchronous processing is also supported (see bellow). |
13 | 13 |
|
14 | 14 | ## Why? |
15 | 15 | This proxy is especially useful for handling incoming webhooks which need to be distributed to multiple targets. |
16 | 16 | However it can be used for any other use case where a request needs to be duplicated. |
17 | 17 |
|
18 | | -## Example RequestClone |
| 18 | +## Setup |
| 19 | + |
| 20 | +The proxy should not be exposed directly to the public. Rather should traffic be routed via an ingress controller |
| 21 | +to the webhook-controller. |
19 | 22 |
|
20 | | -These two targets both match `webhook-receiver.example.com`, meaning any incoming request will be sent to both endpoints. |
21 | | -In this case to `webhook-receiver-app-1:80` and `webhook-receiver-app-2:80`. |
| 23 | +## Example Receiver |
| 24 | + |
| 25 | +In this example an incoming http request will be cloned and forwarded to `podinfo:http` and `podinfo-v2:9091`. |
| 26 | +The response will be `HTTP 202 Accepted` no matter what these targets will respond. |
22 | 27 |
|
23 | 28 | ```yaml |
24 | | -apiVersion: proxy.infra.doodle.com/v1beta1 |
25 | | -kind: RequestClone |
| 29 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 30 | +kind: Receiver |
26 | 31 | metadata: |
27 | 32 | name: webhook-receiver |
28 | | - namespace: apps |
29 | 33 | spec: |
30 | | - host: webhook-receiver.example.com |
31 | | - backend: |
32 | | - serviceName: webhook-receiver-app-1 |
33 | | - servicePort: http |
34 | | ---- |
35 | | -apiVersion: proxy.infra.doodle.com/v1beta1 |
36 | | -kind: RequestClone |
| 34 | + targets: |
| 35 | + - service: |
| 36 | + name: podinfo |
| 37 | + port: |
| 38 | + name: http |
| 39 | + - service: |
| 40 | + name: podinfo-v2 |
| 41 | + port: |
| 42 | + number: 9091 |
| 43 | +``` |
| 44 | +
|
| 45 | +Once the controller reconciled the receiver it will be registered in the proxy which by default processes incoming requests at port `8080`. |
| 46 | +Each receiver will receive its own dedicated http path to which webhooks can be send to. See `.status.webhookPath`. |
| 47 | +Usually the webhook-controller is exposed via an ingress. In this case the the webhooks must sent to `http://ingress-host/hooks/ixuxbmoofkiq9s2l61h6i2sl6hdgwnud`. |
| 48 | +**Note**: The webhookPath will not change anymore once it was set. |
| 49 | + |
| 50 | +``` |
| 51 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 52 | +kind: Receiver |
37 | 53 | metadata: |
38 | 54 | name: webhook-receiver |
39 | | - namespace: apps |
40 | 55 | spec: |
41 | | - host: webhook-receiver.example.com |
42 | | - backend: |
43 | | - serviceName: webhook-receiver-app-2 |
44 | | - servicePort: http |
| 56 | + type: Async |
| 57 | + targets: |
| 58 | + - service: |
| 59 | + name: podinfo |
| 60 | + port: |
| 61 | + name: http |
| 62 | + - service: |
| 63 | + name: podinfo-v2 |
| 64 | + port: |
| 65 | + name: http |
| 66 | + spec: |
| 67 | + responseType: Async |
| 68 | + targets: |
| 69 | + - service: |
| 70 | + name: podinfo |
| 71 | + port: |
| 72 | + name: http |
| 73 | + status: |
| 74 | + conditions: |
| 75 | + - lastTransitionTime: "2025-12-15T07:41:02Z" |
| 76 | + message: receiver successfully registered |
| 77 | + reason: ServiceBackendReady |
| 78 | + status: "True" |
| 79 | + type: Ready |
| 80 | + webhookPath: /hooks/ixuxbmoofkiq9s2l61h6i2sl6hdgwnud |
| 81 | +``` |
| 82 | +
|
| 83 | +## More configurations |
45 | 84 |
|
| 85 | +### Response type |
| 86 | +Besides async responses a receiver can also be synchronous. Meaning it will await the upstream responses. |
| 87 | +In this case `AwaitAllPreferSuccessful` will wait for both upstream targets and will send downstream the first successful http response from either targets once all targets |
| 88 | +were processed. |
| 89 | +
|
| 90 | +```yaml |
| 91 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 92 | +kind: Receiver |
| 93 | +metadata: |
| 94 | + name: webhook-receiver |
| 95 | +spec: |
| 96 | + type: AwaitAllPreferSuccessful |
| 97 | + targets: |
| 98 | + - service: |
| 99 | + name: podinfo |
| 100 | + port: |
| 101 | + name: http |
| 102 | + - service: |
| 103 | + name: podinfo-v2 |
| 104 | + port: |
| 105 | + number: 9091 |
46 | 106 | ``` |
47 | | -North south routing looks like this: |
| 107 | + |
| 108 | +The following types are supported: |
| 109 | +* `Async` - The default, does not await reponses from upstream and immeadiately acknowledges incoming requests with a `HTTP 202 Accepted`. |
| 110 | +* `AwaitAllPreferSuccessful` - Await all upstream responses and send back the first successful repsonse (>= 200 && < 400). If all of them are not successful it will send back the first error response. |
| 111 | +* `AwaitAllPreferFailed` - Await all upstream responses and send back the first failed repsonse (< 200 && >= 400). If all of them are successful it will send back the first sucessful response. |
| 112 | +* `AwaitAllReport` - Await all upstream responses and send back a json object containing all target responses including status code, body and headers. The status code of this type will always be `HTTP 200 OK`. |
| 113 | + |
| 114 | +### Path rewrite |
| 115 | + |
| 116 | +By default http requests are sent upstream to `/`. The target path can be rewritten like: |
| 117 | + |
| 118 | +```yaml |
| 119 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 120 | +kind: Receiver |
| 121 | +metadata: |
| 122 | + name: webhook-receiver |
| 123 | +spec: |
| 124 | + timeout: 3s |
| 125 | + targets: |
| 126 | + - path: /new/path |
| 127 | + service: |
| 128 | + name: podinfo |
| 129 | + port: |
| 130 | + name: http |
| 131 | + - path: /another/path |
| 132 | + service: |
| 133 | + name: podinfo-v2 |
| 134 | + port: |
| 135 | + number: 9091 |
48 | 136 | ``` |
49 | | - |
50 | | - => Ingress controller proxy => => webhook-receiver-app-1:80 |
51 | | - client webhook |
52 | | -[webhook-receiver.example.com] <= <= => webhook-receiver-app-2:80 |
53 | | - 202 Accepted |
| 137 | +
|
| 138 | +### Timeout |
| 139 | +
|
| 140 | +The default timeout for upstream requests is `10s`, this can be changed however: |
| 141 | + |
| 142 | +```yaml |
| 143 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 144 | +kind: Receiver |
| 145 | +metadata: |
| 146 | + name: webhook-receiver |
| 147 | +spec: |
| 148 | + timeout: 3s |
| 149 | + targets: |
| 150 | + - service: |
| 151 | + name: podinfo |
| 152 | + port: |
| 153 | + name: http |
| 154 | + - service: |
| 155 | + name: podinfo-v2 |
| 156 | + port: |
| 157 | + number: 9091 |
54 | 158 | ``` |
55 | 159 |
|
| 160 | +### Cross namespace targets |
56 | 161 |
|
57 | | -## Setup |
| 162 | +By default target services are only selected in the same namespace the receiver lives. A receiver can discover services across namespaces by defining a namespace selector on the target. In this case a service called `podinfo` will be disovered in any namespace on the cluster. |
58 | 163 |
|
59 | | -The proxy should not be exposed directly to the public. Rather should traffic be routed via an ingress controller |
60 | | -and only hosts which are used to duplicate requests should be routed via this proxy. |
| 164 | +```yaml |
| 165 | +apiVersion: webhook.infra.doodle.com/v1beta1 |
| 166 | +kind: Receiver |
| 167 | +metadata: |
| 168 | + name: webhook-receiver |
| 169 | +spec: |
| 170 | + type: AwaitAllPreferSuccessful |
| 171 | + targets: |
| 172 | + - service: |
| 173 | + name: podinfo |
| 174 | + port: |
| 175 | + name: http |
| 176 | + namespaceSelector: {} |
| 177 | +
|
| 178 | +``` |
| 179 | + |
| 180 | +### OpenTelemetry distributed tracing |
| 181 | +The controller supports http traces for the requests. See the `--otel-*` controller flags bellow. |
| 182 | + |
| 183 | +## Installation |
61 | 184 |
|
62 | 185 | ### Helm chart |
63 | 186 |
|
@@ -95,8 +218,6 @@ The controller can be configured using cmd args: |
95 | 218 | --otel-tls-client-cert-path string Opentelemetry gRPC mTLS client cert path |
96 | 219 | --otel-tls-client-key-path string Opentelemetry gRPC mTLS client key path |
97 | 220 | --otel-tls-root-ca-path string Opentelemetry gRPC mTLS root CA path |
98 | | ---proxy-read-timeout duration Read timeout for proxy requests. (default 10s) |
99 | | ---proxy-write-timeout duration Write timeout for proxy requests. (default 10s) |
100 | 221 | --watch-all-namespaces Watch for resources in all namespaces, if set to false it will only watch the runtime namespace. (default true) |
101 | 222 | --watch-label-selector string Watch for resources with matching labels e.g. 'sharding.fluxcd.io/shard=shard1'. |
102 | 223 | ``` |
0 commit comments