You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@camel.apache.org by lb...@apache.org on 2020/09/21 15:09:52 UTC
[camel-k-runtime] 01/03: Document Knative component #247
This is an automated email from the ASF dual-hosted git repository.
lburgazzoli pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel-k-runtime.git
commit 1a45f5366a1b4ca07f8a4fcb6c9b02869afad612
Author: lburgazzoli <lb...@gmail.com>
AuthorDate: Mon Aug 24 15:57:22 2020 +0200
Document Knative component #247
---
camel-knative/camel-knative-api/pom.xml | 1 -
camel-knative/camel-knative/pom.xml | 13 ++
.../knative/KnativeComponentConfigurer.java | 5 +
.../apache/camel/component/knative/knative.json | 7 +-
.../src/main/docs/knative-component.adoc | 238 +++++++++++++++++++++
.../camel/component/knative/KnativeComponent.java | 5 +-
.../camel/component/knative/KnativeEndpoint.java | 6 +-
pom.xml | 10 +
8 files changed, 277 insertions(+), 8 deletions(-)
diff --git a/camel-knative/camel-knative-api/pom.xml b/camel-knative/camel-knative-api/pom.xml
index ec1d00a..1e11e7d 100644
--- a/camel-knative/camel-knative-api/pom.xml
+++ b/camel-knative/camel-knative-api/pom.xml
@@ -84,7 +84,6 @@
<plugin>
<groupId>org.apache.camel</groupId>
<artifactId>camel-package-maven-plugin</artifactId>
- <version>${camel-version}</version>
<configuration>
<failFast>false</failFast>
</configuration>
diff --git a/camel-knative/camel-knative/pom.xml b/camel-knative/camel-knative/pom.xml
index a0152c9..f6a3701 100644
--- a/camel-knative/camel-knative/pom.xml
+++ b/camel-knative/camel-knative/pom.xml
@@ -105,6 +105,19 @@
</executions>
</plugin>
<plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-package-maven-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>update-readme</id>
+ <goals>
+ <goal>update-readme</goal>
+ </goals>
+ <phase>process-classes</phase>
+ </execution>
+ </executions>
+ </plugin>
+ <plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<version>${build-helper-maven-plugin-version}</version>
diff --git a/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java b/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
index fb57da7..1168e20 100644
--- a/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
+++ b/camel-knative/camel-knative/src/generated/java/org/apache/camel/component/knative/KnativeComponentConfigurer.java
@@ -23,6 +23,8 @@ public class KnativeComponentConfigurer extends PropertyConfigurerSupport implem
case "basicPropertyBinding": target.setBasicPropertyBinding(property(camelContext, boolean.class, value)); return true;
case "bridgeerrorhandler":
case "bridgeErrorHandler": target.setBridgeErrorHandler(property(camelContext, boolean.class, value)); return true;
+ case "environmentpath":
+ case "environmentPath": target.setEnvironmentPath(property(camelContext, java.lang.String.class, value)); return true;
case "lazystartproducer":
case "lazyStartProducer": target.setLazyStartProducer(property(camelContext, boolean.class, value)); return true;
case "transport": target.setTransport(property(camelContext, org.apache.camel.component.knative.spi.KnativeTransport.class, value)); return true;
@@ -37,6 +39,7 @@ public class KnativeComponentConfigurer extends PropertyConfigurerSupport implem
Map<String, Object> answer = new CaseInsensitiveMap();
answer.put("basicPropertyBinding", boolean.class);
answer.put("bridgeErrorHandler", boolean.class);
+ answer.put("environmentPath", java.lang.String.class);
answer.put("lazyStartProducer", boolean.class);
answer.put("transport", org.apache.camel.component.knative.spi.KnativeTransport.class);
answer.put("transportOptions", java.util.Map.class);
@@ -51,6 +54,8 @@ public class KnativeComponentConfigurer extends PropertyConfigurerSupport implem
case "basicPropertyBinding": return target.isBasicPropertyBinding();
case "bridgeerrorhandler":
case "bridgeErrorHandler": return target.isBridgeErrorHandler();
+ case "environmentpath":
+ case "environmentPath": return target.getEnvironmentPath();
case "lazystartproducer":
case "lazyStartProducer": return target.isLazyStartProducer();
case "transport": return target.getTransport();
diff --git a/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json b/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
index c1c562a..8e0f5ed 100644
--- a/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
+++ b/camel-knative/camel-knative/src/generated/resources/org/apache/camel/component/knative/knative.json
@@ -3,7 +3,7 @@
"kind": "component",
"name": "knative",
"title": "Knative",
- "description": "This component allows to interact with KNative events.",
+ "description": "This component allows to interact with Knative.",
"deprecated": false,
"firstVersion": "3.0.0",
"label": "cloud,eventing",
@@ -21,6 +21,7 @@
"lenientProperties": false
},
"componentProperties": {
+ "environmentPath": { "kind": "property", "displayName": "Environment Path", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The path ot the environment definition" },
"transport": { "kind": "property", "displayName": "Transport", "group": "common", "label": "", "required": false, "type": "object", "javaType": "org.apache.camel.component.knative.spi.KnativeTransport", "deprecated": false, "secret": false, "defaultValue": "http", "description": "The transport implementation." },
"transportOptions": { "kind": "property", "displayName": "Transport Options", "group": "common", "label": "", "required": false, "type": "object", "javaType": "java.util.Map<java.lang.String, java.lang.Object>", "deprecated": false, "secret": false, "description": "Transport options." },
"bridgeErrorHandler": { "kind": "property", "displayName": "Bridge Error Handler", "group": "consumer", "label": "consumer", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by [...]
@@ -28,8 +29,8 @@
"basicPropertyBinding": { "kind": "property", "displayName": "Basic Property Binding", "group": "advanced", "label": "advanced", "required": false, "type": "boolean", "javaType": "boolean", "deprecated": false, "secret": false, "defaultValue": false, "description": "Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities" }
},
"properties": {
- "type": { "kind": "path", "displayName": "Type", "group": "common", "label": "", "required": false, "type": "object", "javaType": "org.apache.camel.component.knative.spi.Knative.Type", "enum": [ "endpoint", "channel", "event" ], "deprecated": false, "secret": false, "description": "The Knative type" },
- "name": { "kind": "path", "displayName": "Name", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The Knative name" },
+ "type": { "kind": "path", "displayName": "Type", "group": "common", "label": "", "required": false, "type": "object", "javaType": "org.apache.camel.component.knative.spi.Knative.Type", "enum": [ "endpoint", "channel", "event" ], "deprecated": false, "secret": false, "description": "The Knative resource type" },
+ "name": { "kind": "path", "displayName": "Name", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "description": "The name that identifies the Knative resource" },
"ceOverride": { "kind": "parameter", "displayName": "Ce Override", "group": "common", "label": "", "required": false, "type": "object", "javaType": "java.util.Map<java.lang.String, java.lang.Object>", "prefix": "ce.override.", "deprecated": false, "secret": false, "configurationClass": "org.apache.camel.component.knative.KnativeConfiguration", "configurationField": "configuration", "description": "CloudEvent headers to override" },
"cloudEventsSpecVersion": { "kind": "parameter", "displayName": "Cloud Events Spec Version", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "enum": [ "0.1", "0.2", "0.3", "1.0" ], "deprecated": false, "secret": false, "defaultValue": "1.0", "configurationClass": "org.apache.camel.component.knative.KnativeConfiguration", "configurationField": "configuration", "description": "Set the version of the cloudevents spec." },
"cloudEventsType": { "kind": "parameter", "displayName": "Cloud Events Type", "group": "common", "label": "", "required": false, "type": "string", "javaType": "java.lang.String", "deprecated": false, "secret": false, "defaultValue": "org.apache.camel.event", "configurationClass": "org.apache.camel.component.knative.KnativeConfiguration", "configurationField": "configuration", "description": "Set the event-type information of the produced events." },
diff --git a/camel-knative/camel-knative/src/main/docs/knative-component.adoc b/camel-knative/camel-knative/src/main/docs/knative-component.adoc
new file mode 100644
index 0000000..4b0d15c
--- /dev/null
+++ b/camel-knative/camel-knative/src/main/docs/knative-component.adoc
@@ -0,0 +1,238 @@
+[[knative-component]]
+= Knative Component
+:docTitle: Knative
+:artifactId: camel-knative
+:description: This component allows to interact with Knative.
+:since: 3.0
+:supportLevel: Preview
+:component-header: Both producer and consumer are supported
+
+*Since Camel {since}*
+
+*{component-header}*
+
+The Knative component provides support for interacting with https://knative.dev/[Knative].
+
+Maven users will need to add the following dependency to their `pom.xml`
+for this component.
+
+[source,xml]
+------------------------------------------------------------
+<dependency>
+ <groupId>org.apache.camel.k</groupId>
+ <artifactId>camel-knative</artifactId>
+ <version>x.x.x</version>
+ <!-- use the same version as your Camel K version -->
+</dependency>
+------------------------------------------------------------
+
+== URI format
+
+[source]
+----
+knative:type/name[?options]
+----
+
+You can append query options to the URI in the following format:
+
+[source]
+------------------------------------------------------------
+?option=value&option=value&...
+------------------------------------------------------------
+
+== Options
+
+// component options: START
+The Knative component supports 17 options, which are listed below.
+
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *ceOverride* (common) | CloudEvent headers to override | | Map
+| *cloudEventsSpecVersion* (common) | Set the version of the cloudevents spec. The value can be one of: 0.1, 0.2, 0.3, 1.0 | 1.0 | String
+| *cloudEventsType* (common) | Set the event-type information of the produced events. | org.apache.camel.event | String
+| *configuration* (common) | Set the configuration. | | KnativeConfiguration
+| *environment* (common) | The environment | | KnativeEnvironment
+| *environmentPath* (common) | The path ot the environment definition | | String
+| *filters* (common) | Set the filters. | | Map
+| *serviceName* (common) | The name of the service to lookup from the KnativeEnvironment. | | String
+| *transport* (common) | The transport implementation. | | KnativeTransport
+| *transportOptions* (common) | Set the transport options. | | Map
+| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
+| *replyWithCloudEvent* (consumer) | Transforms the reply into a cloud event that will be processed by the caller. When listening to events from a Knative Broker, if this flag is enabled, replies will be published to the same Broker where the request comes from (beware that if you don't change the type of the received message, you may create a loop and receive your same reply). When this flag is disabled, CloudEvent headers are removed from the reply. | false | boolean
+| *reply* (consumer) | If the consumer should construct a full reply to knative request. | true | Boolean
+| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and [...]
+| *apiVersion* (advanced) | The version of the k8s resource referenced by the endpoint. | | String
+| *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
+| *kind* (advanced) | The type of the k8s resource referenced by the endpoint. | | String
+|===
+// component options: END
+
+// endpoint options: START
+The Knative endpoint is configured using URI syntax:
+
+----
+knative:type/name
+----
+
+with the following path and query parameters:
+
+=== Path Parameters (2 parameters):
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *type* | The Knative resource type. The value can be one of: endpoint, channel, event | | Type
+| *name* | The name that identifies the Knative resource | | String
+|===
+
+
+=== Query Parameters (17 parameters):
+
+
+[width="100%",cols="2,5,^1,2",options="header"]
+|===
+| Name | Description | Default | Type
+| *ceOverride* (common) | CloudEvent headers to override | | Map
+| *cloudEventsSpecVersion* (common) | Set the version of the cloudevents spec. The value can be one of: 0.1, 0.2, 0.3, 1.0 | 1.0 | String
+| *cloudEventsType* (common) | Set the event-type information of the produced events. | org.apache.camel.event | String
+| *environment* (common) | The environment | | KnativeEnvironment
+| *filters* (common) | Set the filters. | | Map
+| *serviceName* (common) | The name of the service to lookup from the KnativeEnvironment. | | String
+| *transportOptions* (common) | Set the transport options. | | Map
+| *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean
+| *replyWithCloudEvent* (consumer) | Transforms the reply into a cloud event that will be processed by the caller. When listening to events from a Knative Broker, if this flag is enabled, replies will be published to the same Broker where the request comes from (beware that if you don't change the type of the received message, you may create a loop and receive your same reply). When this flag is disabled, CloudEvent headers are removed from the reply. | false | boolean
+| *exceptionHandler* (consumer) | To let the consumer use a custom ExceptionHandler. Notice if the option bridgeErrorHandler is enabled then this option is not in use. By default the consumer will deal with exceptions, that will be logged at WARN or ERROR level and ignored. | | ExceptionHandler
+| *exchangePattern* (consumer) | Sets the exchange pattern when the consumer creates an exchange. The value can be one of: InOnly, InOut, InOptionalOut | | ExchangePattern
+| *reply* (consumer) | If the consumer should construct a full reply to knative request. | true | Boolean
+| *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and [...]
+| *apiVersion* (advanced) | The version of the k8s resource referenced by the endpoint. | | String
+| *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean
+| *kind* (advanced) | The type of the k8s resource referenced by the endpoint. | | String
+| *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean
+|===
+// endpoint options: END
+
+
+== Supported Knative resources
+
+The component support the following Knative resources you can target or exposes using the `type` path parameter:
+
+- **channel** allow producing or consuming events to or from a https://knative.dev/docs/eventing/channels/[**Knative Channel**]
+- **endpoint** allow exposing or targeting serverless workloads using https://knative.dev/docs/serving/spec/knative-api-specification-1.0/#service[**Knative Services**]
+- **event** allow producing or consuming events to or from a https://knative.dev/docs/eventing/broker[**Knative Broker**]
+
+== Knative Environment
+
+As the Knative component hides the technical details of how to communicate with Knative services to the user (protocols, addresses, etc.), it needs some metadata that describe the Knative environment to set-up the low level transport details. In order to do so, the component needs a so called `Knative Environment` which is essence is a Json document made by a number of `service` elements which looks like the below example:
+
+[source,json]
+------------------------------------------------------------
+{
+ "services": [
+ {
+ "type": "channel|endpoint|event", <1>
+ "name": "", <2>
+ "metadata": {
+ "service.url": "http://my-service.svc.cluster.local" <3>
+ "knative.event.type": "", <4>
+ "camel.endpoint.kind": "source|sink", <5>
+ }
+ }, {
+ ...
+ }
+ ]
+}
+------------------------------------------------------------
+<1> the type of the Knative resource
+<2> the name of the resource
+<3> the url of the service to invoke (for producer only)
+<4> the Knative event type received or produced by the component
+<5> the type of the Camel Endpoint associated to this Knative resource (source=consumer, sink=producer)
+
+The `metadata` fields has some additional advanced fields:
+
+[width="100%",cols="1,5,3",options="header"]
+|===
+| Name | Description | Example
+| *filter.*
+| The prefix to define filters to be applied to the incoming message headers.
+| ```filter.ce.source=my-source```
+
+| *knative.kind*
+| The type of the k8s resource referenced by the endpoint.
+| ```knative.kind=InMemoryChannel```
+
+| *knative.apiVersion*
+| The version of the k8s resource referenced by the endpoint
+| ```knative.apiVersion=messaging.knative.dev/v1beta1```
+
+| *knative.apiVersion*
+| The version of the k8s resource referenced by the endpoint.
+| ```knative.apiVersion=messaging.knative.dev/v1beta1```
+
+| *knative.reply*
+| If the consumer should construct a full reply to knative request.
+| ```knative.reply=false```
+
+| *ce.override.*
+| The prefix to define CloudEvents values that have to be overridden.
+| ```ce.override.ce-type=MyType```
+
+|===
+
+== Knative Transport
+
+As today the component only support `http` as transport as it is the only supported protocol on Knative side but the transport is pluggable by implementing the following interface:
+
+[source,java]
+----
+
+public interface KnativeTransport extends Service {
+ /**
+ * Create a camel {@link org.apache.camel.Producer} in place of the original endpoint for a specific protocol.
+ *
+ * @param endpoint the endpoint for which the producer should be created
+ * @param configuration the general transport configuration
+ * @param service the service definition containing information about how make reach the target service.
+ * @return
+ */
+ Producer createProducer(
+ Endpoint endpoint,
+ KnativeTransportConfiguration configuration,
+ KnativeEnvironment.KnativeServiceDefinition service);
+
+ /**
+ * Create a camel {@link org.apache.camel.Producer} in place of the original endpoint for a specific protocol.
+ *
+ * @param endpoint the endpoint for which the consumer should be created.
+ * @param configuration the general transport configuration
+ * @param service the service definition containing information about how make the route reachable from knative.
+ * @return
+ */
+ Consumer createConsumer(
+ Endpoint endpoint,
+ KnativeTransportConfiguration configuration,
+ KnativeEnvironment.KnativeServiceDefinition service, Processor processor);
+}
+----
+
+== Examples
+
+[source,java]
+----
+CamelContext context = new DefaultCamelContext();
+
+KnativeComponent component = context.getComponent("knative", KnativeComponent.class);
+component.getConfiguration().setEnvironmentPath("classpath:knative.json"); // <1>
+
+RouteBuilder.addRoutes(context, b -> {
+ b.from("knative:endpoint/myEndpoint") // <2>
+ .to("log:info");
+});
+----
+<1> set the location of the `Knative Environment` file
+<2> expose knative service
diff --git a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
index d863be5..078168f 100644
--- a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
+++ b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeComponent.java
@@ -40,13 +40,16 @@ import org.slf4j.LoggerFactory;
public class KnativeComponent extends DefaultComponent {
private static final Logger LOGGER = LoggerFactory.getLogger(KnativeComponent.class);
+ @Metadata
private KnativeConfiguration configuration;
+
+ @Metadata
private String environmentPath;
@Metadata(defaultValue = "http")
private Knative.Protocol protocol = Knative.Protocol.http;
- @Metadata(defaultValue = "http")
+ @Metadata
private KnativeTransport transport;
@Metadata
diff --git a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
index b846cc8..9cac875 100644
--- a/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
+++ b/camel-knative/camel-knative/src/main/java/org/apache/camel/component/knative/KnativeEndpoint.java
@@ -41,7 +41,7 @@ import org.apache.camel.support.PropertyBindingSupport;
import org.apache.camel.util.ObjectHelper;
/**
- * This component allows to interact with KNative events.
+ * This component allows to interact with Knative.
*/
@UriEndpoint(
firstVersion = "3.0.0",
@@ -50,9 +50,9 @@ import org.apache.camel.util.ObjectHelper;
title = "Knative",
label = "cloud,eventing")
public class KnativeEndpoint extends DefaultEndpoint {
- @UriPath(description = "The Knative type")
+ @UriPath(description = "The Knative resource type")
private final Knative.Type type;
- @UriPath(description = "The Knative name")
+ @UriPath(description = "The name that identifies the Knative resource")
private final String name;
private final CloudEventProcessor cloudEvent;
@UriParam
diff --git a/pom.xml b/pom.xml
index a7febd7..5429468 100644
--- a/pom.xml
+++ b/pom.xml
@@ -246,6 +246,16 @@
<artifactId>maven-javadoc-plugin</artifactId>
<version>${maven-javadoc-plugin-version}</version>
</plugin>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-component-maven-plugin</artifactId>
+ <version>${camel-version}</version>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-package-maven-plugin</artifactId>
+ <version>${camel-version}</version>
+ </plugin>
</plugins>
</pluginManagement>
<plugins>