You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by nf...@apache.org on 2021/04/29 13:12:41 UTC
[camel-k] 27/30: doc(kamelets): kamelet bindings error handler
This is an automated email from the ASF dual-hosted git repository.
nferraro pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel-k.git
commit 8f9108672e1854357404c62295917258a34af581
Author: Pasquale Congiusti <pa...@gmail.com>
AuthorDate: Tue Apr 27 14:55:20 2021 +0200
doc(kamelets): kamelet bindings error handler
---
.../kamelets/kameletbindings-error-handler.adoc | 156 +++++++++++++++++++++
.../modules/ROOT/pages/kamelets/kamelets-user.adoc | 4 +
docs/modules/ROOT/pages/kamelets/kamelets.adoc | 1 +
pkg/resources/resources.go | 14 +-
4 files changed, 168 insertions(+), 7 deletions(-)
diff --git a/docs/modules/ROOT/pages/kamelets/kameletbindings-error-handler.adoc b/docs/modules/ROOT/pages/kamelets/kameletbindings-error-handler.adoc
new file mode 100644
index 0000000..fe3f1ce
--- /dev/null
+++ b/docs/modules/ROOT/pages/kamelets/kameletbindings-error-handler.adoc
@@ -0,0 +1,156 @@
+[[kameletbindings-error-handler]]
+= Kamelet Bindings Error Handler
+
+`Kamelet Binding`s offer a mechanism to specify an error policy to adopt in case an event produced by a `source` or consumed by a `sink`. Through the definition of an `errorHandler` you will be able to apply certain logic to the failing event, such as simply logging, ignoring the event or posting the event to a `Dead Letter Channel`.
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source: # <1>
+...
+ sink: # <2>
+...
+ errorHandler: # <3>
+----
+<1> Reference to the source that provides data
+<2> Reference to the sink where data should be sent to
+<3> Error Handler Configuration
+
+[[kameletbindings-error-handler-types]]
+== Error Handler Types
+
+We have different types of error handler: `ǹone`, `log`, `dead-letter-channel`, `bean`, `ref`. The `errorHandler` parameter is optional. The runtime will use the configuration to create an https://camel.apache.org/manual/latest/error-handler.html[Error Handler] as specified by Apache Camel.
+
+[[kameletbindings-error-handler-none]]
+=== No error handler
+
+There may be certain cases where you want to just ignore any failure happening on your integration. In this situation just use a `ǹone` error handler. Under the hood the configuration will create a https://camel.apache.org/manual/latest/error-handler.html#ErrorHandler-NoErrorHandler[`No` error handler builder].
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source:
+...
+ sink:
+...
+ errorHandler:
+ none: # <1>
+----
+<1> `none` error handler does not expect any configuration
+
+[[kameletbindings-error-handler-log]]
+=== Log error handler
+
+Apache Camel offers a default behavior for handling any failure: log to standard output. However you can use the `log` error handler to specify other behaviors such as redelivery or delay policy. Under the hood the configuration will create a https://camel.apache.org/manual/latest/error-handler.html#_defaulterrorhandler[`Default` error handler builder].
+
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source:
+...
+ sink:
+...
+ errorHandler:
+ log:
+ parameters: # <1>
+ maximumRedeliveries: 3
+ redeliveryDelay: 2000
+----
+<1> Parameters belonging to the `log` error handler type
+
+[[kameletbindings-error-handler-dlc]]
+=== Dead Letter Channel error handler
+
+The `Dead Letter Channel` is probably the most interesting error handler type as it allows you to redirect any failing event to any other component, such as a third party URI, a queue or even another `Kamelet` which will be performing certain logic with the failing event. Under the hood the configuration will create a https://camel.apache.org/manual/latest/error-handler.html#_dead_letter_channel[`Dead Letter Channel` error handler builder].
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source:
+...
+ sink:
+...
+ errorHandler:
+ dead-letter-channel:
+ endpoint:
+ ref: # <1>
+ kind: Kamelet
+ apiVersion: camel.apache.org/v1alpha1
+ name: error-handler
+ properties:
+ message: "ERROR!" # <2>
+ ...
+ parameters:
+ maximumRedeliveries: 1 # <3>
+ ...
+----
+<1> You can use `ref` or `uri`. `ref` will be interpreted by the operator according the `kind`, `apiVersion` and `name`. You can use any `Kamelet`, `KafkaTopic` channel or `Knative` destination.
+<2> Properties belonging to the endpoint (in this example, to the `Kamelet` named error handler)
+<3> Parameters belonging to the `dead-letter-channel` error handler type
+
+[[kameletbindings-error-handler-bean]]
+=== Bean error handler
+
+With the `Bean` error handler you can extend the functionality of the Error Handler by providing a custom bean to be used as Error Handler.
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source:
+...
+ sink:
+...
+ errorHandler:
+ bean:
+ type: "org.apache.camel.builder.DeadLetterChannelBuilder" # <1>
+ properties: # <2>
+ deadLetterUri: log:error
+ ...
+----
+<1> Fully qualified name of the ErrorHandlerBuilder
+<2> Properties expected by your type
+
+[[kameletbindings-error-handler-ref]]
+=== Ref error handler
+
+With the `Ref` error handler you can use any `Bean` that is expected to be found in the Camel registry at runtime.
+
+[source,yaml]
+----
+apiVersion: camel.apache.org/v1alpha1
+kind: KameletBinding
+metadata:
+ name: my-kamelet-binding
+spec:
+ source:
+...
+ sink:
+...
+ errorHandler:
+ ref: my-custom-builder # <1>
+...
+----
+<1> The name of the bean to be looked up at runtime
+
+NOTE: make sure to have the `ref` correctly bind at runtime.
\ No newline at end of file
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
index 4a334cb..ef48761 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets-user.adoc
@@ -356,6 +356,10 @@ This KameletBinding explicitly defines an URI where data is going to be pushed.
NOTE: the `uri` option is also conventionally used in Knative to specify a non-kubernetes destination.
To comply with the Knative specifications, in case an "http" or "https" URI is used, Camel will send https://cloudevents.io/[CloudEvents] to the destination.
+=== Error Handling
+
+You can configure an error handler in order to specify what to do when some event ends up with failure. See xref:kamelets/kameletbindings-error-handler.adoc[Kamelet Bindings Error Handler User Guide] for more detail.
+
[[kamelets-specification]]
== Kamelet Specification
diff --git a/docs/modules/ROOT/pages/kamelets/kamelets.adoc b/docs/modules/ROOT/pages/kamelets/kamelets.adoc
index 6ba3ff5..c0d0327 100644
--- a/docs/modules/ROOT/pages/kamelets/kamelets.adoc
+++ b/docs/modules/ROOT/pages/kamelets/kamelets.adoc
@@ -4,4 +4,5 @@
This section of the documentation contains information about Kamelets from both a user and a developer point of view:
- The xref:kamelets/kamelets-user.adoc[Kamelets User Guide] is for users that want to use Kamelets for connecting systems with their applications
+- The xref:kamelets/kameletbindings-error-handler.adoc[Kamelet Bindings Error Handler User Guide] explains how to configure an error handler on a `Kamelet Binding`
- The xref:kamelets/kamelets-dev.adoc[Kamelets Developer Guide] is a reference for developers that want to create new Kamelets and share them with users
diff --git a/pkg/resources/resources.go b/pkg/resources/resources.go
index 9f43b93..94a6ac4 100644
--- a/pkg/resources/resources.go
+++ b/pkg/resources/resources.go
@@ -106,16 +106,16 @@ var assets = func() http.FileSystem {
"/crd/bases/camel.apache.org_integrations.yaml": &vfsgen۰CompressedFileInfo{
name: "camel.apache.org_integrations.yaml",
modTime: time.Time{},
- uncompressedSize: 24066,
+ uncompressedSize: 23405,
- compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x3c\x5d\x73\xe3\xb8\x91\xef\xfa\x15\x5d\xf6\xc3\xec\x56\x49\x54\x66\x26\xa9\xbb\xf2\x3d\x79\x3d\x33\x17\xdd\x78\x6d\x97\xe5\xc9\xd6\x56\x2a\x0f\x10\xd9\x12\x11\x83\x00\x0f\x00\x25\x2b\xa9\xfc\xf7\xab\x6e\x90\x14\x29\x91\xb4\xc6\x9e\xdd\xcd\x25\xe2\xcb\x8c\x49\xa0\xd1\xdf\x5f\x00\x74\x0e\x93\x6f\xf7\x8c\xce\xe1\x5a\xc6\xa8\x1d\x26\xe0\x0d\xf8\x14\xe1\x32\x17\x71\x8a\x30\x37\x4b\xbf\x11\x16\xe1\x93\x29\x74\x22\xbc\x [...]
+ compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x3c\x5d\x73\xdb\xba\x95\xef\xfa\x15\x67\xec\x87\xdc\xcc\x48\x54\x93\xb4\xb3\x3b\xde\x27\xd7\x89\x77\xb5\xf1\xb5\x33\x96\xd3\x3b\x77\x3a\x7d\x80\xc8\x43\x0a\x35\x08\x70\x01\xd0\xb2\xda\xe9\x7f\xdf\x39\x07\x24\x45\x4a\xa4\xac\xc8\xb9\xf7\x76\xbb\xe2\x4b\x62\x12\x38\x38\xdf\x5f\x00\x74\x0e\x93\xef\xf7\x8c\xce\xe1\x46\xc6\xa8\x1d\x26\xe0\x0d\xf8\x25\xc2\x65\x21\xe2\x25\xc2\xdc\xa4\x7e\x25\x2c\xc2\xb5\x29\x75\x22\xbc\x [...]
},
"/crd/bases/camel.apache.org_kameletbindings.yaml": &vfsgen۰CompressedFileInfo{
name: "camel.apache.org_kameletbindings.yaml",
modTime: time.Time{},
- uncompressedSize: 56150,
+ uncompressedSize: 55181,
- compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x7d\xf1\x6f\xdb\x38\xf2\xef\xef\xf9\x2b\x06\xc9\x01\x6d\x81\x48\x8e\x93\xb4\xbb\xeb\xf7\x43\x91\x26\xdb\xfb\xfa\xb5\x9b\x06\x49\x7a\x87\x7b\x6d\x0f\xa0\xa5\xb1\xcd\x8b\x44\xea\x48\x2a\x8e\xdf\xb6\xff\xfb\x17\x24\x25\x59\x76\x2c\x89\x72\xec\x6e\x0b\x88\x40\xd1\xd8\xa6\x86\x33\xc3\x99\xe1\x70\xc8\x8f\x7d\x00\xde\xf6\xda\xde\x01\xbc\xa7\x01\x32\x89\x21\x28\x0e\x6a\x8a\x70\x96\x90\x60\x8a\x70\xc3\xc7\x6a\x46\x04\xc2\x [...]
+ compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x7d\xf1\x6f\xdb\x38\xf2\xef\xef\xf9\x2b\x06\xc9\x01\x6d\x01\x4b\x8e\xe3\xb4\xbb\xeb\xf7\x43\x91\x26\xdb\x7b\x7e\xed\xa6\x45\x92\xde\xe1\x5e\xdb\x03\x68\x69\x6c\xf3\x22\x91\x3a\x92\x8a\xe3\xef\xb6\xff\xfb\x17\x24\x25\x59\x76\x2c\x99\x72\xec\x6e\x0a\x88\xc0\x62\x6b\x8b\x1a\xce\x0c\x87\xc3\x99\x21\x3f\xce\x11\x78\xbb\x6b\x07\x47\xf0\x9e\x06\xc8\x24\x86\xa0\x38\xa8\x29\xc2\x59\x42\x82\x29\xc2\x35\x1f\xab\x19\x11\x08\x [...]
},
"/crd/bases/camel.apache.org_kamelets.yaml": &vfsgen۰CompressedFileInfo{
name: "camel.apache.org_kamelets.yaml",
@@ -144,7 +144,7 @@ var assets = func() http.FileSystem {
modTime: time.Time{},
uncompressedSize: 2397,
- compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xc4\x55\xc1\x6e\xe3\x36\x10\xbd\xeb\x2b\x1e\xac\xcb\x2e\x10\xdb\xc9\x02\x05\x16\xea\x49\x4d\x9c\xc6\x68\x6a\x1b\x96\xb7\xc1\x9e\x0a\x9a\x1a\x4b\x44\x28\x8e\x4a\x52\xf6\xaa\x5f\x5f\x50\xb6\x1c\xdb\x9b\xa6\x3d\x04\x58\x9e\x2c\xcd\xcc\x9b\xf7\x66\x9e\xe8\x18\xc3\xf7\x3b\x51\x8c\x47\x25\xc9\x38\xca\xe1\x19\xbe\x24\xa4\xb5\x90\x25\x21\xe3\x8d\xdf\x09\x4b\xb8\xe7\xc6\xe4\xc2\x2b\x36\xf8\x90\x66\xf7\x1f\xd1\x98\x9c\x2c\xd8\x [...]
+ compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xc4\x55\xc1\x6e\xe3\x36\x10\xbd\xeb\x2b\x1e\xac\xcb\x2e\x10\xdb\xc9\xa2\x87\x85\x7a\x52\x13\xa7\x31\x9a\xda\x86\xe5\x6d\xb0\xa7\x82\xa6\xc6\x12\x11\x8a\xa3\x92\x94\xbd\xea\xd7\x17\x94\x2d\xc7\xf6\xa6\x69\x0f\x01\x96\x27\x4b\x33\xf3\xe6\xbd\x99\x27\x3a\xc6\xf0\xfd\x4e\x14\xe3\x51\x49\x32\x8e\x72\x78\x86\x2f\x09\x69\x2d\x64\x49\xc8\x78\xe3\x77\xc2\x12\xee\xb9\x31\xb9\xf0\x8a\x0d\x3e\xa4\xd9\xfd\x47\x34\x26\x27\x0b\x36\x [...]
},
"/manager/operator-service-account.yaml": &vfsgen۰CompressedFileInfo{
name: "operator-service-account.yaml",
@@ -467,9 +467,9 @@ var assets = func() http.FileSystem {
"/traits.yaml": &vfsgen۰CompressedFileInfo{
name: "traits.yaml",
modTime: time.Time{},
- uncompressedSize: 36976,
+ uncompressedSize: 36744,
- compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x7d\x6d\x73\x1c\xb7\xd1\xe0\x77\xfd\x0a\x14\x9f\xab\xe2\x4b\xed\x0c\x29\xa7\x9c\xf8\xf6\x4e\x97\xa2\x25\x25\xa1\x6d\x49\x3c\x51\x71\xea\x4a\xa7\xca\x62\x67\x7a\x77\x21\x62\x80\x09\x80\x21\xb5\xb9\xba\xff\x7e\x85\x6e\x00\x83\xd9\x1d\x2e\x97\xb2\xe9\x32\xaf\x9e\xe4\x83\x45\x72\xa6\xd1\x68\x34\xfa\xbd\x7b\x9c\xe1\xc2\xd9\xe9\xb3\x82\x29\xde\xc0\x94\xf1\xc5\x42\x28\xe1\xd6\xcf\x18\x6b\x25\x77\x0b\x6d\x9a\x29\x5b\x70\x [...]
+ compressedContent: []byte("\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\xff\xec\x7d\x6d\x73\x1c\xb7\xd1\xe0\x77\xfd\x0a\x14\x9f\xab\xe2\x4b\xed\x0e\x29\xa7\x9c\xf8\xf6\x4e\x97\xa2\x25\x25\xa1\x6d\x49\x3c\x51\x71\xea\x4a\xa7\xca\x62\x67\x7a\x77\x21\x62\x80\x09\x80\x59\x6a\x73\x75\xff\xfd\x0a\xdd\x00\x06\x33\x3b\x24\x97\xb2\xe9\x32\xaf\x9e\xe4\x83\x45\x72\xa6\xd1\x68\x34\xfa\xbd\x7b\x9c\xe1\xc2\xd9\xd9\xb3\x29\x53\xbc\x86\x19\xe3\xcb\xa5\x50\xc2\x6d\x9f\x31\xd6\x48\xee\x96\xda\xd4\x33\xb6\xe4\x [...]
},
}
fs["/"].(*vfsgen۰DirInfo).entries = []os.FileInfo{