Chapter 16. Connecting to Knative resources

You can create a simple integration that does any of the following:

  • Connects to a Knative channel to obtain or send messages
  • Exposes the integration as a Knative service
  • Calls a Knative service
Important

Connecting to Knative resources is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process. For more information about the support scope of Red Hat Technology Preview features, see https://access.redhat.com/support/offerings/techpreview/.

The exchanged messages can be of any format, however, messages are typically in JSON format.

For example, a simple integration might periodically poll Salesforce for new leads. When a Salesforce connection finds a new lead it can send a message that contains the details to a Knative channel. Multiple simple integrations can obtain messages from that same Knative channel. Each integration can perform different actions on the lead data.

See the following topics for details:

16.1. Enabling connections to Knative resources

You must enable Knative connections before you can add them to simple integrations.

Knative connections might have been enabled when Fuse Online was installed. To check this, view the content of the syndesis custom resource. If the camelk and knative add-ons specify enabled: true then Knative connections are already enabled.

Prerequisites

  • The oc client tool is installed in, and connected to, the OCP cluster in which Fuse Online is running.
  • Fuse Online is running on OpenShift Container Platform on-site in a customer-managed environment.
  • The Fuse Online runtime is Camel K.
  • In the cluster in which Fuse Online is installed, each Knative resource that you want an integration to connect to is also installed. Before you can install Knative resources, you must install the OpenShift Serverless Operator and the Knative Eventing Operator.
  • You have permission to install Fuse Online.

Procedure

  1. Log in to OpenShift with an account that has permission to install Fuse Online. For example:

    $ oc login -u developer -p developer
  2. Switch to the project in which Fuse Online is running, for example:

    $ oc project my-integration-project
  3. Edit the syndesis custom resource:

    1. Invoke the following command, which typically opens the resource in an editor:

      oc edit syndesis
    2. Update the resource to specify the following:

      spec:
        addons:
           camelk:
             enabled: true
           knative:
             enabled: true
    3. Save the resource.

      Saving this change to the syndesis custom resource triggers syndesis-operator, which is responsible for installing Fuse Online, to redeploy syndesis-server.

      If camelk and knative are already enabled, you can close the file. Connections to Knative resources are enabled.

Result

In the Fuse Online console, on the Connections page, a Knative connection is now available. You can add the same Knative connection to any number of simple integrations. Configuration of the connection action, specifies the Knative resource that the connection accesses.

16.2. Subscribing to a Knative channel to obtain messages

To trigger integration execution upon receiving a message from a Knative channel, add a Knative connection as a simple integration’s start connection. An integration that starts this way automatically scales down to 0 pods when no messages have been received from the channel for a specified number of minutes. The default is 1 minute.

This automatic scaling saves resources, which is an advantage over simple integrations that start with other kinds of connections, such as a connection to an AMQ broker.

Prerequisites

  • Connections to Knative resources are enabled.
  • The Knative resource that you want to obtain messages from is in the same cluster as Fuse Online
  • You know the name of the Knative channel that you want the connection to obtain messages from.

Procedure

  1. In Fuse Online, in the left panel, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the Knative connection.
  4. Select the Receive from Channel action.
  5. Click in the Channel name field to display a list of available Knative channels.
  6. Select the Knative channel name for the resource that you want to obtain messages from.
  7. Click Next to specify the Receive from Channel action’s output type. This is the type that the connection passes to the next step in the integration.

    1. In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.

      However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.

      To specify the data type, click in the Select Type field and select one of the following as the schema type:

      • JSON schema is a document that describes the structure of JSON data. The document’s media type is application/schema+json.
      • JSON instance is a document that contains JSON data. The document’s media type is application/json.
      • XML schema is a document that describes the structure of XML data. The document’s file extension is .xsd.
      • XML instance is a document that contains XML data. The document’s file extension is .xml.
    2. In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of application/schema+json.
    3. In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify Vendor as the data type name.

      You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Fuse Online displays the type name in the integration visualization and in the data mapper.

    4. In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
    5. Click Next.

Result

Fuse Online prompts you to add the simple integration’s finish connection.

During execution, each time the selected Knative channel receives a new message, the Knative connection passes the message to the next step in the integration,

Next steps

Add all needed connections to the integration. Then add a data mapper step after the Knative connection that starts the integration. Map the source message field to a target field in the next connection.

16.3. Sending messages to a Knative channel

In a simple integration, a Knative connection can send a message to a Knative channel in the middle of a flow or to finish a simple integration. To do this, add a Knative connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • Knative connections are enabled.
  • The Knative resource that you want to send messages to is installed in the same cluster as Fuse Online.
  • You know the name of the Knative channel that you want the connection to send messages to.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. On the Choose a connection page, click the Knative connection.
  3. Select the Send to Channel action.
  4. Click in the Channel name field to display a list of the Knative channels that are available in the cluster that is running Fuse Online.
  5. Select the channel that you want the integration to send messages to.
  6. Click Next to specify the Send to Channel action’s input type. This is the type that the integration sends to the Knative channel.

    1. In the Select Type field, if the data type does not need to be known, or if the output from the previous integration step is the expected type, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.

      However, a structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.

      To specify the data type, click in the Select Type field and select one of the following as the schema type:

      • JSON schema is a document that describes the structure of JSON data. The document’s media type is application/schema+json.
      • JSON instance is a document that contains JSON data. The document’s media type is application/json.
      • XML schema is a document that describes the structure of XML data. The document’s file extension is .xsd.
      • XML instance is a document that contains XML data. The document’s file extension is .xml.
    2. In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of application/schema+json.
    3. In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify Vendor as the data type name.

      You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Fuse Online displays the type name in the integration visualization and in the data mapper.

    4. In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
    5. Click Next.

Result

In the integration visualization, the connection appears where you added it. During execution, this connection sends a message to the selected Knative channel.

Next steps

Add all needed connections to the integration. Then add a data mapper step just before the Knative connection that sends messages to a Knative channel. Map a source field to the Knative connection target message field.

16.4. Exposing a simple integration as a Knative service

In a simple integration, the start connection can be a Knative connection that exposes the integration as a Knative service. An integration that starts this way automatically scales down to 0 pods when there have been no calls to the service for a specified number of minutes. The default is 1 minute.

This automatic scaling saves resources, which is an advantage over simple integrations that start with other kinds of connections, such as a connection to an AMQ broker.

Prerequisites

  • Connections to Knative resources are enabled.
  • Knative is installed in the same cluster that Fuse Online is running in.

Procedure

  1. In Fuse Online, in the left panel, click Integrations.
  2. Click Create Integration.
  3. On the Choose a connection page, click the Knative connection.
  4. Select the Expose as Service action.

Result

Fuse Online prompts you to add the simple integration’s finish connection.

When Fuse Online publishes the integration, the Camel K runtime creates a Knative serving.knative.dev service. This service:

  • Is an alternative to a Kubernetes deployment object
  • Can automatically scale to 0 after a period of no activity
  • Should not be confused with the Kubernetes Service

Publication makes the integration available to be called at the root path ( / ). Clients can invoke execution of the integration by calling it as an HTTP endpoint and passing data as needed. Typically, the passed data is in JSON format.

In this release, it is expected that the primary use for exposing an integration as a Knative service is that other Fuse Online integrations call that service. In this scenario, the integration that calls the service selects the service name and does not need to specify a path.

16.5. Calling a Knative service from a simple integration

In a simple integration, a Knative connection can call a Knative service in the middle of the integration or to finish the integration. To do this, add a Knative connection to the middle of a flow or as a simple integration’s finish connection.

Prerequisites

  • Knative connections are enabled.
  • You know the name of the Knative service that you want the connection to call. The service is running in the same cluster as Fuse Online.
  • You are creating or editing a flow and Fuse Online is prompting you to add to the integration. Or, Fuse Online is prompting you to choose a finish connection.

Procedure

  1. On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Fuse Online is prompting you to choose the finish connection.
  2. On the Choose a connection page, click the Knative connection.
  3. Select the Call Service action.
  4. Click in the Service name field to display a list of the Knative services that are available in the cluster that is running Fuse Online.
  5. Select the service that you want the integration to call.

    If you exposed an integration as a Knative service and that is the service that you want to call, the name of the service is similar, if not identical, to the name of the integration.

  6. Click Next to specify the Call Service action’s input type. This is the type that the integration sends to the Knative service.

    1. In the Select Type field, if the data type does not need to be known, or if the output from the previous integration step is the expected type, accept Type specification not required and click Next. You do not need to follow this subset of instructions.

      A structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.

      To specify the data type, click in the Select Type field and select one of the following as the schema type:

      • JSON schema is a document that describes the structure of JSON data. The document’s media type is application/schema+json.
      • JSON instance is a document that contains JSON data. The document’s media type is application/json.
      • XML schema is a document that describes the structure of XML data. The document’s file extension is .xsd.
      • XML instance is a document that contains XML data. The document’s file extension is .xml.
    2. In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of application/schema+json.
    3. In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify Vendor as the data type name.

      You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Fuse Online displays the type name in the integration visualization and in the data mapper.

    4. In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
    5. Click Next.
  7. Specify the Call Service action’s output type.

    This is the type that the Knative service returns to the integration when the Knative connection is a middle connection.

    Repeat the previous subset of instructions to specify the output type. Or, if the Knative service response is empty, accept Type specification not required.

  8. Click Next to add the connection.

Result

In the integration visualization, the connection appears where you added it.

During execution, this connection calls the specified Knative service. The call includes the output from the previous integration step (the step before this Knative connection). If this Knative connection is a middle connection, the connection passes the service output to the next step in the integration.

Next steps

Add any other needed connections to the integration. If you specified input and/or output types, add data mapper steps before and/or after the Knative connection and map fields as needed.