github.com/argoproj/argo-events@v1.9.1/docs/tutorials/02-parameterization.md (about) 1 # Parameterization 2 3 In the previous section, we saw how to set up a basic webhook event-source and sensor. The trigger template had `parameters` set in the sensor object, and 4 the workflow was able to print the event payload. In this tutorial, we will dig deeper into 5 different types of parameterization, how to extract particular key-value from event payload 6 and how to use default values if certain `key` is not available within event payload. 7 8 ## Trigger Resource Parameterization 9 10 If you take a closer look at the `Sensor` object, you will notice it contains a list 11 of triggers. Each `Trigger` contains the template that defines the context of the trigger 12 and actual `resource` that we expect the sensor to execute. In the previous section, the `resource` within 13 the trigger template was an Argo workflow. 14 15 This subsection deals with how to parameterize the `resource` within trigger template 16 with the event payload. 17 18 ### Prerequisites 19 20 Make sure to have the basic webhook event-source and sensor set up. Follow the [introduction](https://argoproj.github.io/argo-events/tutorials/01-introduction) tutorial if haven't done already. 21 22 ### Webhook Event Payload 23 24 Webhook event-source consumes events through HTTP requests and transforms them into CloudEvents. 25 The structure of the event the Webhook sensor receives from the event-source over the eventbus looks like following, 26 27 { 28 "context": { 29 "type": "type_of_event_source", 30 "specversion": "cloud_events_version", 31 "source": "name_of_the_event_source", 32 "id": "unique_event_id", 33 "time": "event_time", 34 "datacontenttype": "type_of_data", 35 "subject": "name_of_the_configuration_within_event_source" 36 }, 37 "data": { 38 "header": {}, 39 "body": {}, 40 } 41 } 42 43 1. `Context`: This is the CloudEvent context and it is populated by the event-source regardless of 44 type of HTTP request. 45 46 2. `Data`: Data contains following fields. 47 1. `Header`: The `header` within event `data` contains the headers in the HTTP request that was dispatched 48 to the event-source. The event-source extracts the headers from the request and put it in 49 the `header` within event `data`. 50 51 1. `Body`: This is the request payload from the HTTP request. 52 53 ### Event Context 54 55 Now that we have an understanding of the structure of the event the webhook sensor receives from 56 the event-source over the eventbus, lets see how we can use the event context to parameterize the Argo workflow. 57 58 1. Update the `Webhook Sensor` and add the `contextKey` for the parameter at index 0. 59 60 kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/tutorials/02-parameterization/sensor-01.yaml 61 62 2. Send a HTTP request to the event-source pod. 63 64 curl -d '{"message":"this is my first webhook"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 65 66 3. Inspect the output of the Argo workflow that was created. 67 68 argo logs name_of_the_workflow 69 70 You will see the following output, 71 72 _________ 73 < webhook > 74 --------- 75 \ 76 \ 77 \ 78 ## . 79 ## ## ## == 80 ## ## ## ## === 81 /""""""""""""""""___/ === 82 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 83 \______ o __/ 84 \ \ __/ 85 \____\______/ 86 87 We have successfully extracted the `type` key within the event context and parameterized 88 the workflow to print the value of the `type`. 89 90 ### Event Data 91 92 Now, it is time to use the event data and parameterize the Argo workflow trigger. 93 We will extract the `message` from request payload and get the Argo workflow to 94 print the message. 95 96 1. Update the `Webhook Sensor` and add the `dataKey` in the parameter at index 0. 97 98 kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/tutorials/02-parameterization/sensor-02.yaml 99 100 2. Send a HTTP request to the event-source pod. 101 102 curl -d '{"message":"this is my first webhook"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 103 104 3. Inspect the output of the Argo workflow that was created. 105 106 argo logs name_of_the_workflow 107 108 You will see the following output, 109 110 __________________________ 111 < this is my first webhook > 112 -------------------------- 113 \ 114 \ 115 \ 116 ## . 117 ## ## ## == 118 ## ## ## ## === 119 /""""""""""""""""___/ === 120 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 121 \______ o __/ 122 \ \ __/ 123 \____\______/ 124 125 Yay!! The Argo workflow printed the message. You can add however many number of parameters 126 to update the trigger resource on the fly. 127 128 **_Note_**: If you define both the `contextKey` and `dataKey` within a parameter, then 129 the `dataKey` takes the precedence. 130 131 **_Note_**: When `useRawData` is not specified or explicitly set to false, the parameter 132 will resolve to a string type. When `useRawData` is set to true, a number, boolean, json 133 or string parameter may be resolved. 134 135 ### Default Values 136 137 Each parameter comes with an option to configure the default value. This is specially 138 important when the `key` you defined in the parameter doesn't exist in the event. 139 140 1. Update the `Webhook Sensor` and add the `value` for the parameter at index 0. 141 We will also update the `dataKey` to an unknown event key. 142 143 kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/tutorials/02-parameterization/sensor-03.yaml 144 145 2. Send a HTTP request to the event-source pod. 146 147 curl -d '{"message":"this is my first webhook"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 148 149 3. Inspect the output of the Argo workflow that was created. 150 151 argo logs name_of_the_workflow 152 153 You will see the following output, 154 155 _______________________ 156 < wow! a default value. > 157 ----------------------- 158 \ 159 \ 160 \ 161 ## . 162 ## ## ## == 163 ## ## ## ## === 164 /""""""""""""""""___/ === 165 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 166 \______ o __/ 167 \ \ __/ 168 \____\______/ 169 170 <br/> 171 172 ### Sprig Templates 173 174 The [sprig template](https://github.com/Masterminds/sprig) exposed through `contextTemplate` and `dataTemplate` lets you alter the event 175 context and event data before it gets applied to the trigger via `parameters`. 176 177 Take a look at the example defined [here](https://github.com/argoproj/argo-events/blob/stable/examples/sensors/trigger-with-template.yaml), it contains the parameters 178 as follows, 179 180 parameters: 181 # Retrieve the 'message' key from the payload 182 - src: 183 dependencyName: test-dep 184 dataTemplate: "{{ .Input.body.message | title }}" 185 dest: spec.arguments.parameters.0.value 186 # Title case the context subject 187 - src: 188 dependencyName: test-dep 189 contextTemplate: "{{ .Input.subject | title }}" 190 dest: spec.arguments.parameters.1.value 191 # Retrieve the 'name' key from the payload, remove all whitespace and lowercase it. 192 - src: 193 dependencyName: test-dep 194 dataTemplate: "{{ .Input.body.name | nospace | lower }}-" 195 dest: metadata.generateName 196 operation: append 197 198 Consider the event the sensor received has format like, 199 200 { 201 "context": { 202 "type": "type_of_event_source", 203 "specversion": "cloud_events_version", 204 "source": "name_of_the_event_source", 205 "id": "unique_event_id", 206 "time": "event_time", 207 "datacontenttype": "type_of_data", 208 "subject": "name_of_the_configuration_within_event_source" 209 }, 210 "data": { 211 "body": { 212 "name": "foo bar", 213 "message": "hello there!!" 214 }, 215 } 216 } 217 218 The parameters are transformed as, 219 220 1. The first parameter extracts the `body.message` from event data and applies `title` filter which basically 221 capitalizes the first letter and replaces the `spec.arguments.parameters.0.value`. 222 223 1. The second parameter extracts the `subject` from the event context and again applies `title` filter and replaces the 224 `spec.arguments.parameters.1.value`. 225 226 1. The third parameter extracts the `body.name` from the event data, applies `nospace` filter which removes all 227 white spaces and then `lower` filter which lowercases the text and appends it to `metadata.generateName`. 228 229 Send a curl request to event-source as follows, 230 231 curl -d '{"name":"foo bar", "message": "hello there!!"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 232 233 and you will see an Argo workflow being sprung with name like `webhook-foobar-xxxxx`. 234 235 Check the output of the workflow, it should print something like, 236 237 ____________________________ 238 < Hello There!! from Example > 239 ---------------------------- 240 \ 241 \ 242 \ 243 ## . 244 ## ## ## == 245 ## ## ## ## === 246 /""""""""""""""""___/ === 247 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 248 \______ o __/ 249 \ \ __/ 250 \____\______/ 251 252 <br/> 253 254 ### Operations 255 256 Sometimes you need the ability to append or prepend a parameter value to 257 an existing value in trigger resource. This is where the `operation` field within 258 a parameter comes handy. 259 260 1. Update the `Webhook Sensor` and add the `operation` in the parameter at index 0. 261 We will prepend the message to an existing value. 262 263 kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/tutorials/02-parameterization/sensor-04.yaml 264 265 2. Send a HTTP request to the event-source. 266 267 curl -d '{"message":"hey!!"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 268 269 3. Inspect the output of the Argo workflow that was created. 270 271 argo logs name_of_the_workflow 272 273 You will see the following output, 274 275 __________________ 276 < hey!!hello world > 277 ------------------ 278 \ 279 \ 280 \ 281 ## . 282 ## ## ## == 283 ## ## ## ## === 284 /""""""""""""""""___/ === 285 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 286 \______ o __/ 287 \ \ __/ 288 \____\______/ 289 290 ## Trigger Template Parameterization 291 292 The parameterization you saw above deals with the trigger resource, but sometimes 293 you need to parameterize the trigger template itself. This comes handy when you have 294 the trigger resource stored on some external source like S3, Git, etc. and you need 295 to replace the url of the source on the fly in trigger template. 296 297 Imagine a scenario where you want to parameterize the parameters of trigger to 298 parameterize the trigger resource. What?... 299 300 The sensor you have been using in this tutorial has one parameter defined in the 301 trigger resource under `k8s`. We will parameterize that `parameter` by 302 applying a parameter at the trigger template level. 303 304 1. Update the `Webhook Sensor` and add parameters at trigger level. 305 306 kubectl -n argo-events apply -f https://raw.githubusercontent.com/argoproj/argo-events/stable/examples/tutorials/02-parameterization/sensor-05.yaml 307 308 2. Send a HTTP request to the event-source. 309 310 curl -d '{"dependencyName":"test-dep", "dataKey": "body.message", "dest": "spec.arguments.parameters.0.value", "message": "amazing!!"}' -H "Content-Type: application/json" -X POST http://localhost:12000/example 311 312 3. Inspect the output of the Argo workflow that was created. 313 314 argo logs name_of_the_workflow 315 316 You will see the following output, 317 318 ___________ 319 < amazing!! > 320 ----------- 321 \ 322 \ 323 \ 324 ## . 325 ## ## ## == 326 ## ## ## ## === 327 /""""""""""""""""___/ === 328 ~~~ {~~ ~~~~ ~~~ ~~~~ ~~ ~ / ===- ~~~ 329 \______ o __/ 330 \ \ __/ 331 \____\______/ 332 333 Great!! You have now learned how to apply parameters at trigger resource and template level. 334 Keep in mind that you can apply default values and operations like prepend and append for 335 trigger template parameters as well.