Camel K - User Demo

Walk your first steps with Camel K by creating and running your first integration service that integrates with a legacy backend.

This hands-on lab is based on the following blog article in Red Hat Developers:

https://developers.redhat.com/articles/2023/03/09/try-camel-k-developer-sandbox

To recap what work is ahead, the sequence diagram below illustrates the flow you’re about to create.

The Camel K integration will expose an HTTP entry point, and upon client requests, it’ll fetch XML data from a (simulated) legacy backend, transform its response into JSON, and return it to the client application.

Assuming you have followed the article’s instructions, you should be all set to get hands-on with Camel K in the OpenShift Dev Spaces workspace.

Lab Preparations

Before we start real work, let’s prepare some equipment before riding the Camel.

Toggle auto-save off

You’ll be making live code changes which Camel K can pick up in real time. You need to ensure the changes do not trigger a reload every time you press a key, but only when you manually save your changes.

Warning

The auto-save option in the menu does not always show when it’s active/inactive. If you see in your editor’s file tab a permanent white dot ⭘ when you make changes, it means auto-save is OFF.

Open your terminal

Make sure you make visible your terminal in the IDE. You can toggle it using the keyboard keys Ctrl+` or simply find the option from the menu system as per the picture below:
Create a working folder

Execute the commands below to create a new directory from where you can work and is visible in your project explorer:
```
mkdir lab
cd lab
```
Set your working project in OpenShift

Make sure your CLI oc client (OpenShift client) points to your personal Developer Sandbox project (aka namespace):
```
oc projects -q | grep dev | xargs oc project
```
Note
The Developer Sandbox only allows 1 project (namespace) per user.

The command above should output something similar to:
```
Now using project "<your-username>-dev" on server "https://172.30.0.1:443".
```
Warning
Not specifying your target project (namespace) in OpenShift may result in a deployment failure.

You’re now all set and ready start riding the Camel.

Development Phase

This section guides you into creating your code and iterate over it using Camel K’s 'developer mode'.

Create your integration definition

To swiftly create a skeleton Camel route definition, we can use the camel client ( Camel JBang client) from the terminal. Execute the following command:
```
camel init user.xml
```
The above command initialises an XML Camel definition. Camel also supports languages like Java, YAML, and others.
Open it in your editor

You’ll find your newly created integration file under the following path in your project explorer:
- lab/user.xml
  
  Note
  The project tree also includes other Camel resources from other lab tutorials, contained in the same source GitHub project.
Click on the Camel source file to display it in your code editor.

The code you’ll find in the file contains a default Camel route written using the XML DSL (Domain Specific Language), but Camel also provides a Java DSL and a YAML DSL.
Make changes on the Camel route

To make our new example a bit more interesting than the article’s service called roll-dice, we will create an adaptation layer that will collect data in XML format from a remote server and will translate it to JSON. This is a very typical use case where modern API façades serve data collected from legacy systems.

Replace the default Camel route by the following one:
```
    <route id="xml">
        <from uri="timer:xml?repeatCount=1"/>

        <removeHeaders pattern="*"/>
        <to uri="https://random-data-api.com/api/v2/users?response_type=xml"/>

        <log message="${body}"/>
    </route>
```
In the route above you’ll see:
1. The starting timer component configured to trigger only once (repeatCount=1)
2. Then an outgoing HTTP(S) call is prepared to consume a remote free to use API that provides random data. In this example, the API returns random user data, and we specify it to be in XML format.
3. The log statement to output the returned XML payload.
Press Ctrl+s (linux) or ⌘+s (mac) to save your changes.

Run the integration

Run the Camel route by executing the following command.

Note	Camel K will build and deploy the process in the Developer Sandbox for you.

kamel run user.xml --dev \
-d camel-jackson \
-d camel-jacksonxml

Note

The command includes the --dev flag to instruct the Camel K client to run in 'developer mode'. This mode hooks up your terminal with the running pod in OpenShift and displays the pod’s log outputs. It also enables fast iteration code updates where new edits on your code are immediately pushed to the environment in real-time allowing very fast coding cycles.

Note

You’ll notice the command above includes two explicit dependencies. Camel K analyses the code to resolve dependencies automatically, however, there is a pending ticket asking to include data formats (automatic translators in Camel). When the ticket will be resolved, the explicit dependencies will no longer be necessary.

When you run the command above, you should see in your terminal a long XML response containing random user data from the backend printed on the screen, and should contain fields similar to:

[1] 2023-01-10 18:24:41,778 INFO  [use.xml:17] (Camel (camel-1) thread #1 - timer://xml) <?xml version="1.0" encoding="UTF-8"?>
[1] <hash>
[1]   ...
[1]   <username>tyree.konopelski</username>
[1]   <email>tyree.konopelski@email.com</email>
[1]   ...

If you have a look to your topology view from your OpenShift developer console, you should see the integration running as a pod, as per the picture below:

Iterate with live code changes

Let’s now enjoy the magic of Camel K by modifying the code on the fly to pursue our goal, that is, to return the data in JSON format, and expose the service via HTTP.

Apply XML to JSON conversion

From the code below, take the snippet with the (copy) button and inject it in your code in the same region as shown below, right after the outgoing HTTP invocation:

    <route id="xml">
        <from uri="timer:xml?repeatCount=1"/>

        <removeHeaders pattern="*"/>
        <to uri="https://random-data-api.com/api/v2/users?response_type=xml"/>

        <unmarshal>
            <jacksonXml/>
        </unmarshal>
        <marshal>
            <json/>
        </marshal>

        <log message="${body}"/>
    </route>

Note	the marshal/unmarshal directive in Camel converts data via the use of Camel data formats. These are automatic data format converters. In the code above, the XML response is unmarshalled into a mid-step Java structure, and then marshalled into the final JSON data.

Press ctrl+s (linux) or ⌘+s (mac) to save your changes.

The Camel K client, running in 'dev mode', catches the changes and pushes the new definition to OpenShift, causing the Camel K operator to react and trigger a fast build/deploy replacing the previous version. From the developer’s perspective, this happens transparently and very fast.

You will see in the terminal Camel reloading the new definition and triggering a new HTTP request and this time displaying the result in JSON format, similar to:

{  … ,"email": "edith.green@email.com", …,"username": "edith.green"}

Note	The sample above is trimmed to just show some of the relevant fields. Your response will contain many other fields.

Expose the integration as an HTTP service

Since the payload is now transformed in the desired output format, we can perform one last edit to expose the service to be consumable via an HTTP entry point.

Replace the starting timer activity with the platform-http component. From the code below, take the snippet with the (copy) button and replace the current timer activity in your code in the same region as shown below, right at the start the Camel route:

    <route id="xml">

        <from uri="platform-http:/user"/>

        <removeHeaders pattern="*"/>
        <to uri="https://random-data-api.com/api/v2/users?response_type=xml"/>
        <unmarshal>
            <jacksonXml/>
        </unmarshal>
        <marshal>
            <json/>
        </marshal>
        <log message="${body}"/>
    </route>

The new platform-http activity above tells Camel to use the native HTTP library to accept incoming invocations using the /user path.

Press ctrl+s (linux) or ⌘+s (mac) to save your changes.

Once more, the platform’s operator reacts and deploys a new version of the definition, except this time, we can invoke the service from a terminal to test it.

Note	When Camel K defines an HTTP entrypoint it automatically deploys it as a Knative serverless application by default. You will see the pod scale to zero when no traffic comes in. When a request comes in, Knative scales up the pod and the application consumes it and responds.

If you have a look to your topology view from your OpenShift developer console, you’ll see the integration running as serverless app (can scale to zero), as per the picture below:

Test the service

Now, test the service from a new terminal. Choose the Split option from the current terminal’s top right corner, as shown below:

From the new terminal, run the following cURL command to test your service:
```
curl `kn route list -o jsonpath={.items[?(@.metadata.name==\"user\")].status.url}`/user | jq
```
Note
The curl command resolves the URL by using the Knative client kn and extracting the http route of the service.

Note
The command includes a pipe to parse the JSON response with JQuery, which nicely renders the returned JSON payload.

You should see curl returning new randomly generated user data, in the expected JSON format.

Note
If the pod was scaled to zero, the curl command will trigger it to scale to 1 and process the request.

You should see in your IDE a view similar to the picture below showing both terminals, the logs from the Camel K integration running in the Developer Sandbox, and the curl command output:

Did you obtain the a JSON response similar to the one shown above?

You’ve successfully tested your Camel K HTTP service !!

Inspect the logs to investigate possible causes of failure.

Consider the development phase done.
Press ctrl+c to stop your Camel K instance.

When stopped, you’ll notice the pod in your Developer Sandbox disappear:

Did you see your user pod deleted?

You’re ready to step to the next chapter !!

You can try running oc delete integration user to force deleting the pod.

Deploy your integration

Running the kamel client with the --dev flag (dev mode) showed you in the previous chapter how to hook your terminal with the running pod (dev mode) in the Developer Sandbox. Now you will deploy your integration detached from your IDE.

Execute the deployment command

All it takes to deploy your integration is to remove the --dev flag.
Copy and paste the command below to push the integration to the Developer Sandbox:
```
kamel run user.xml \
-d camel-jackson \
-d camel-jacksonxml
```
What really happens behind the scenes when executing the command above is that the kamel client converts your source code into an Integration CRD (Custom Resource Definition) defined in YAML and then pushes it to the Developer Sandbox.

It is the Camel K operator, not visible to you, running in the Developer Sandbox, that picks up the CRD and triggers a build and deploys it.
Visualise your pod

If you switch to your Developer Sandbox topology view, you’ll see the pod running again, only this time is not hooked to your terminal:
Use the CLIs to confirm

You can use your terminal to obtain information about your running integration.

Using your kamel client, execute:
```
kamel get
```
Which should return something similar to:
```
NAME    PHASE   KIT
user    Running camel-k-operator/kit-ceu0v85mq41b5tocq4sg
```
Using your oc client (OpenShift client), execute:
```
oc get integration
```
Which should return something similar to:
```
NAME   PHASE     KIT                        REPLICAS
user   Running   kit-ceu0v85mq41b5tocq4sg   1
```
Invoke the service as an external client

You can notice, from your topology view, your pod showing a small icon to open the URL exposed by the service:

Click on it.

If your browser renders “Resource not found” or another error message, make sure your address bar uses HTTP (not HTTPS), and you include the service path ‘/user’ at the end of the URL, something similar to:
- http://…(long address value here)…/user
In your browser, you should see user data in JSON format, similar to:

You can also obtain the route details with the following command and use its URL from your favourite local HTTP client/tester, like Postman, Swagger or others.
```
kn route list -o jsonpath={.items[?(@.metadata.name==\"user\")].status.url}
```
Embedding the kn command in a cURL allows you to invoke the service as an external consumer.
- Copy/paste the following cURL command to simulate an external call and obtain a response from the Camel service:
  
  curl `kn route list -o jsonpath={.items[?(@.metadata.name==\"user\")].status.url}`/user | jq
  
  The invocation should return the expected JSON payload.

Did you see succeed to invoke the user service as an external consumer?

Well done !! make sure you follow the instructions below to clean your project.

Make sure your route is in place, and you force your browser to use HTTP with the /user path.

Clean up your project

When you’re done playing in your Developer Sandbox, you can clean up your project (namespace) by un-deploying your Camel K user integration by issuing the following command:

```
kamel delete user
```
or
```
oc delete integration user
```

Did you clean your sandbox project with the instructions above?

Well done !! Your namespace should be clean and ready for your next project.

Make sure your route was deleted, and your Camel K integration was removed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

walkthrough.adoc

walkthrough.adoc

Camel K - User Demo

Lab Preparations

Development Phase

Deploy your integration

Clean up your project

Files

walkthrough.adoc

Latest commit

History

walkthrough.adoc

File metadata and controls

Camel K - User Demo

Lab Preparations

Development Phase

Deploy your integration

Clean up your project