Skip to content

Latest commit

 

History

History
1071 lines (850 loc) · 28.9 KB

walkthrough.adoc

File metadata and controls

1071 lines (850 loc) · 28.9 KB

Camel - Prototype and deploy on OpenShift

Use Camel’s fast prototyping using low-code UI and commands to build your integration flows and deploy them on OpenShift.

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


The sequence diagram below illustrates the flow you’re about to create.

seq diagram


The Camel 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 in the OpenShift Dev Spaces workspace.


Introduction

If you haven’t used Apache Camel before, or haven’t played with recent versions and tools, it’s important you read below all the pieces that are at play, and understand they are conceived to converge into providing a unified development experience.

To briefly introduce the set of tools you’re about to use, here’s a list of the components that will help you along the way:

  • Dev Spaces / VS Code: the IDE you’ll be using to create the Camel processes.

  • Apache Camel: the integration framework you’ll use packed with Enterprise Integration Patterns and Components (connectors).

  • Kaoto: visual editor for Apache Camel to create your Camel routes and processes in VS Code.

  • Camel JBang: Camel CLI (command line interface) designed to boost prototyping and accelerate your work to create, test and deploy your applications.

  • Quarkus: The runtime used by Camel to deploy your integration processes on OpenShift

  • OpenShift: Kubernetes environment where you will deploy your Camel project.

  • OpenShift client: OpenShift’s CLI (command line interface) to help users manage projects in the environment.


No Java

One big highlight of the exercises you’re about to embark on is that although Apache Camel is Java based, you won’t see a single line of Java, nor have to define or manage dependencies. Those concerns are kept hidden to allow the developer become more productive by focussing on the business case at hand.

Note
 It goes without saying that at any moment in time Java code can be injected within your Apache Camel processes to incorporate the custom handling you need. Apache Camel excels in this respect thanks to its open framework architecture and extensibility.


Lab Preparations

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

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


Enable auto-save

Tip
 Ignore this step if auto-save is already enabled in your environment.

  1. Toggle auto-save on (✓)

    You’ll be making live code changes which Camel can pick up in real time. When the file is saved Camel hot-reloads the changes.
    To speed up hot-reloads, toggle (✓) auto-save in your editor, as illustrated below:

    autosave
    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 a terminal

From DevSpaces, open a terminal following the steps illustrated below:

toggle terminal


Copy/Paste commands

You’ll use command actions all along the lab.
To execute commands, perform the steps described below, as illustrated:

copypaste

  1. Click the button Copy to clipboard

  2. Paste the command in the terminal:

    • on Linux: Ctrl+Shift+v

    • on Mac: ⌘+v

  3. Try it with:

    echo "this is a copy/paste test"
    Warning
    		 It’s been reported that these key-combos not always work. Your machine may not respond to the above descriptions. Please try other key or mouse click alternatives, for example, right-click, or middle-click.

  4. If the paste action fails and you see DevSpaces showing the following notification:

    clipboard notification

    Find in your web browser’s settings where to enable clipboard permissions. The image below shows how to enable them using Chrome:

    clipboard settings


Prepare your working folder

  1. 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


  2. Set your working project in OpenShift

    Make sure your CLI oc client (OpenShift client) points to your personal Developer Sandbox project (aka namespace):

    oc project $WORKSPACE_NAMESPACE
    Note
    		 The Developer Sandbox only allows 1 project (namespace) per user.

    The command above should output something similar to:

    Already on 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.


Tips for a better learning

If you have a wide monitor, or can organise your browser tabs in a multi-monitor configuration, it is mostly recommended to position your DevSpaces view and your lab instructions side by side, as per the image below:

better learning


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


Is your terminal open and located in your lab directory?

👍 You’re ready to roll!

Review the instructions above and ensure you run the setup script.

Base Camel route

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

This section introduces you to Camel JBang. You will use it to create your base Camel route and explore some of things you can during the development phase.


  1. Create your initial integration definition

    Make sure you’re working from your lab directory:

    cd /projects/devsandbox-camel/lab

    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.camel.yaml

    The above command initialises a YAML-based Camel definition. Other languages, like Java and XML, are also supported.


  2. Open the route in the visual editor

    You’ll find your newly created integration file under the following path in your project explorer:

    • lab/user.camel.yaml

      camel route users
      Note
      		 Ignore other Camel resources (folders) in the project tree, they belong to other lab tutorials included in the same GitHub repository.

    Click on the Camel source file to display it in Kaoto (Camel's visual editor).

    camel route users kaoto

    The visual editor will show you the default Camel route initialised in step 1, consisting in a timer-to-log processing flow that generates an event every second. Each execution defines a payload (body) and writes it to log.


  3. Run the integration with:

    camel run *
    Note
    		 the * indicates to load all source files in the folder.

    After Camel finishes the start up phase, you’ll see a new trace every second, similar to:

    2024-10-24 07:21:27.941  INFO ... : Hello Camel from route1
2024-10-24 07:21:28.941  INFO ... : Hello Camel from route1
2024-10-24 07:21:29.941  INFO ... : Hello Camel from route1


Explore more Camel JBang features

To quickly illustrate another useful feature, Camel JBang includes a web based Developer Console.

Stop Camel with Ctrl+c.
And activate the Developer Console using the flag --console as per the command below:

camel run * --console

Dev Spaces will prompt you to open the port 8080.
Do so and, in your browser’s address bar, change the URL’s path to the following one:

  • /q/dev

Note
 Make sure your browser uses plain http:// (https://)

Follow the actions illustrated below to open in a new browser tab:

][width=50%

You’ll find a ton of information you can access.
Try for example:

  • top: Display the top routes

    When refreshing the page after a few LLM interactions, it should show something similar to:

    Top Routes:

    Route Id: route1
    From: timer://yaml?period=1000
    Source: file:user.camel.yaml:1
    Total: 73
    Failed: 0
    Inflight: 0
    Mean Time: 0ms
    Max Time: 8ms
    Min Time: 0ms
    Last Time: 0ms
    Delta Time: 0ms
    Total Time: 8ms


Another console option you can look at is:

  • source: Dump route source code

    It will render the source code of your Camel route in YAML DSL:

    Source:

    Id: route1
    Source: file:user.camel.yaml:1

    #1 - from:
    #2     uri: "timer:yaml"
    #3     parameters:
    #4       period: "1000"
    #5     steps:
    #6       - setBody:
    #7           simple: "Hello Camel from ${routeId}"
    #8       - log: "${body}"


The examples from above show cool features (out of many) Camel JBang includes.
Feel free to explore more by reading its ​documentation page.

Tip

You can always invoke Camel JBang's help command, from the terminal, to discover all options and flags available:

camel --help

You also have more granular help per-command. For example, try the following:

camel get --help


Is your base route created and have you seen other Camel JBang options?

👍 You’re ready to roll!

Please review the steps of this chapter and try again.

Fast Prototyping

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

This section shows you to prototype your project in fast iteration cycles. Camel JBang’s provides a 'developer mode' that allows it to detect and apply on-the-fly any changes you perform.

To make the example interesting, the service you will create will operate as an adaptation layer, collecting data in XML format from a remote server and transforming it to JSON. This is a very typical use case where modern API façades serve data obtained from legacy systems.

Here’s again the sequence diagram illustrating the process you’re about to create.

seq diagram


Follow the commands below:

  1. If you haven’t done so yet, stop Camel with Ctrl+c.

  2. Run the integration in 'developer mode':

    camel run * --dev
    Note
    		 the --dev flag activates the developer mode.

  3. Start making changes in the Camel route.

    Because you’re running Camel in developer mode, every change you do in the editor will trigger a hot-reload and automatic restart.

    Update the timer definition.
    Look at the figure below and follow these steps:

    1. Click the timer activity to open the configuration pane.

    2. Click All (properties).

    3. Use the filter repeat to search and find properties.

    4. Set the repeatCount property to 1.

    5. Close the configuration pane.

    kaoto timer update

    In the logs, you will see Camel react by restarting and executing the route only once, because repeatCount was set to 1:

    2024-10-24 10:22:23.443  INFO ... : Routes reloaded summary (total:1 started:1)
2024-10-24 10:22:23.443  INFO ... :     Started route-4178 (timer://yaml) (source: user.camel.yaml:4)
2024-10-24 10:22:24.442  INFO ... : Hello Camel from route-4178


  4. Define an HTTPS call

    1. Copy the endpoint URL below:

      https://random-data-api.com/api/v2/users?response_type=xml
      Note
      		 The parameter response_type tells the server to return the data in XML format.

    2. Look at the figure below and follow these steps:

      1. Click the 3 dots ⋮ in setBody.

      2. Click ⟳ Replace.

      3. Use the filter https to search and find the component.

      4. Select the HTTPS component.

      5. Click on the HTTPS step.

      6. Paste the URL (you copied above) in the Http Uri property.

      7. Close the configuration pane.

      kaoto https

      In the logs, you will see Camel reacting and fetching an XML response from the backend, similar to the sample lot traces below:

      ... : Routes reloaded summary (total:1 started:1)
... :     Started route-4178 (timer://yaml) (source: user.camel.yaml:4)
... : <?xml version="1.0" encoding="UTF-8"?>
<hash>
  <id type="integer">9582</id>
  <uid>837ec527-7925-4904-84ac-8b9113c2dbd8</uid>
  <password>iobemgl1ZH</password>
  <first-name>Carl</first-name>
  <last-name>Auer</last-name>
  <username>carl.auer</username>
  <email>[email protected]</email>
  ...


  5. Define an HTTP listener

    Now, expose the process as a service. Replace the Timer event producer with an HTTP listener.

    Look at the figure below and follow these steps:

    1. Click the 3 dots ⋮ in timer.

    2. Click ⟳ Replace.

    3. Use the filter platform-http to search and find the component.

    4. Select the Platform HTTP card.

    5. Click on the platform-http step.

    6. Set the Path property to:

      Important
      		 
      /user

    7. Close the configuration pane.

    kaoto platform http

    In the logs, you will see Camel reacting with traces similar to:

    ... : Routes reloaded summary (total:1 started:1)
... :     Started route-4178 (platform-http:///user) (source: user.camel.yaml:5)
    Note
    		 In contrast with previous updates, this time no execution takes place as Camel waits for HTTP requests to comes in.


  6. Clean incoming HTTP headers

    To ensure the process cleanly calls the HTTP endpoint and to prevent header propagation, you need to include a step to clean the incoming HTTP headers.

    Look at the figure below and follow these steps:

    1. Click the 3 dots ⋮ in platform-http.

    2. Click + Add step.

    3. Use the filter removeheaders to search and find the component.

    4. Select the Remove Headers card.

    5. Click on the removeHeaders step.

    6. Set the Pattern property to *.

    7. Close the configuration pane.

    kaoto remove headers

    At this point your Camel route should look in Kaoto as the picture below:

    kaoto flow phase 1

    In the logs, you should see Camel having reacted from the updates above and showing the following traces:

    ... : Routes reloaded summary (total:1 started:1)
... :     Started route-4178 (platform-http:///user) (source: user.camel.yaml:5)


  7. Test the listener

    To validate what you’ve done so far, test the listener from a new terminal. Choose the Split option from the current terminal’s top right corner, as shown below:

    terminal split

    From the new terminal, run the following cURL command to test your service:

    curl -s http://localhost:8080/user | bat -pP -lxml
    Note
    		 The command also includes a pipe to colorize the XML output for better reading.

    The invocation should return an XML payload similar to:

    <?xml version="1.0" encoding="UTF-8"?>
<hash>
  <id type="integer">9867</id>
  <uid>f7907251-4336-40d3-8502-a1021a1a10b4</uid>
  <password>KsbN09mckU</password>
  <first-name>Danny</first-name>
  <last-name>Stehr</last-name>
  <username>danny.stehr</username>
  <email>[email protected]</email>
  ...

    So far so good.


  8. Apply XML to JSON transformation

    Keep iterating the prototype by introducing XML to JSON translation.

    In Camel there are many strategies available to convert XML into JSON. In this case you will use the Marshal/Unmarshal EIP to update the flow. You do it by adding two extra steps to the process: first Unmarshal (XML) and then Marshal (JSON).

    1. Start by unmarshalling the XML data

      Look at the figure below and follow these steps:

      1. Right-click on the https step.

      2. Select the ↓ Append option.

      3. Use the filter unmarshal to search and find the component.

      4. Select the Unmarshal card.

      5. Click on the unmarshal step.

      6. Select the Jackson XML Data Format.

      7. Close the configuration pane.

      kaoto unmarshal xml

    2. Then marshal to JSON

      Look at the figure below and follow these steps:

      1. Right-click on the unmarshal step.

      2. Select the ↓ Append option.

      3. Use the filter marshal to search and find the component.

      4. Select the Marshal card.

      5. Click on the marshal step.

      6. Select the Json Data Format.

      7. Close the configuration pane.

      kaoto marshal json

    At this point your Camel route should look in Kaoto as the picture below:

    kaoto flow phase 2

    In the logs, you should see Camel having reacted from the updates above and showing the following traces:

    ... : Routes reloaded summary (total:1 started:1)
... :     Started route-4178 (platform-http:///user) (source: user.camel.yaml:5)


  9. Test the XML to JSON transformation

    Test the Unmarshal/Marshal steps with the command below:

    curl -s http://localhost:8080/user | jq
    Note
    		 The command also includes a pipe to colorize the JSON output for better reading.

    The invocation should return JSON data, similar to:

    {
  "phone-number": "+63 890.053.3511 x6876",
  "address": {
    "city": "Feestport",
    "street-name": "Cecil Camp",
    "street-address": "12806 Abbott Summit",
  ...


Did your last curl command return JSON data?

Well done !!

Go back in your footsteps and review the actions.

Deploy your integration

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

You’ve completed your prototype, it is time to deploy it.
The Camel CLI (Camel JBang) includes a Kubernetes plugin that makes it very easy to deploy your application on Openshift.

Camel JBang and the Kubernetes plugin will do all the work for you. Your code gets analysed and all the necessary dependencies automatically detected and downloaded, then containerised and deployed on Openshift.

Follow the commands below:

  1. If you haven’t done so already, stop Camel with Ctrl+c.

  2. Make sure you’re working from your lab directory:

    cd /projects/devsandbox-camel/lab

  3. Run the following command from your terminal to deploy your application:

    camel kubernetes run * --cluster-type=openshift --trait route.enabled=true --trait route.tls-termination=edge
    Note

    • The --cluster-type flag indicates the Kubernetes flavour of your target environment.

    • The route.enabled=true trait indicates to create an Openshift route to allow external access.

    • The route.tls-termination=edge trait enables secure HTTP (HTTPS).

    The execution will export the code into a Camel Quarkus application and deploy it on Openshift.

    Note
    		 Be patient, the execution may take 3 to 5 minutes the first time as Camel analyses the code, downloads required dependencies, builds and deploys the application.

    In the logs you’ll see following traces:

    ...
Exporting application ...
Deploying to Openshift ...
Invalid AnsiLogger Stream -> Swapping to default sdt out logger.
[INFO] Adding existing Deployment with name: user.
[INFO] Adding existing Service with name: user.
[INFO] Adding existing Route with name: user.


Check your deployment

You can inspect when your deployment is ready by issuing the following command:

watch oc get deployments

Your Camel application will be ready when user shows READY 1/1, similar to the output below:

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
user                        1/1     1            1           4m25s
workspace7c6e32fd061c4d25   1/1     1            1           17m
Tip
 Stop the watch with Ctrl+c.


Open the Developer Console

You can also visually inspect your pod by opening Openshift’s Developer Console following the actions below:

  1. At the bottom-left of your screen, click the >< button.

  2. Then at the top, select:

    • Dev Spaces: Open OpenShift Console

  3. If a list of namespaces shows, select your namespace.

  4. Your Camel Quarkus Application is labelled with user.

openshift developer console


Do you see your Camel application deployed in the Developer Console?

Well done !!

Review the instructions and try again.

Test your deployed integration

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

  • Because the application has been deployed alongside your DevSpaces workspace pod (see picture below), in the same OpenShift namespace, you can call it from your same subnet.

    pod user

    Use the following command to test the deployed application:

    curl -s http://user:80/user | jq
    Note
    		 you can directly call the service user on port 80 because the pod runs in the same namespace.

    Again, you should see a similar JSON response as per your previous test run locally.

    {
  "phone-number": "+375 1-790-160-4090 x0991",
  "address": {
    "city": "East Justinafurt",
    "street-name": "Jerde Club",
    "street-address": "860 Yaeko Ramp",
    ...


Test the service using its external URL

  • When the Camel application was deployed using the Kubernetes plugin, the command included the route.enabled setting to expose the service for external consumption.

    Use the route to call the service as if it was an external call. Follow the commands below:

    echo https://`oc get route user -o jsonpath={.spec.host}`/user

    Then, use the URL generated on a browser tab or click as indicated, like in the image below:

    test route

    You should see in your browser the JSON response obtained, similar to:

    browser test
    Tip
    		 When using Chrome, you can tick on the Pretty print check box to beautify the JSON response


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

Well done !!

Make sure your route exists, and you’re using the /user path.


Undeploy your Camel integration

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

The list below summarises the main resources created by the Camel Kubernetes plugin during the deployment process on OpenShift:

  • an ImageStream: your application containerised.

  • a Deployment: your application deployment definition

  • a Service: a Kubernetes service to access your Camel integration.

  • a Route: an OpenShift route to expose the service to external clients.

If you wanted to undeploy your application to free up resources in the environment you would need to manually delete the items on the list above, plus additional residual (not listed) resources.

Thankfully, the Camel Kubernetes plugin makes it super simple to undeploy your integration in one single command.

Execute the command below to remove user from your namespace:

camel kubernetes delete user

In your terminal, you should see an execution output similar to:

Deleted: Service 'user'
Deleted: Imagestreams 'openjdk-17'
Deleted: Imagestreams 'user'
Deleted: Buildconfigs 'user'
Deleted: Deployments 'user'
Deleted: Routes 'user'

Verify your deployment has been deleted by issuing the following Openshift command:

oc get deployments

The command should return your workspace deployment only:

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
workspace7c6e32fd061c4d25   1/1     1            1           16m


Did you manage to successfully undeploy your user Camel integration?

Well done !!

Review the instructions in this chapter and try again.


More Camel examples to learn from

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}


👏 👏 👏 Congratulations for getting this far 👏 👏 👏


For those thirsty of knowledge willing to learn more about other Camel use cases we strongly recommend to try out another exciting tutorial.

Follow the link below to visit the introductory article that will take you to the learning material:


Warning
 Before you go, please make sure you clean your sandbox namespace to free up resources.
Click  Next  for detailed instructions.

Clean up your Developer Sandbox account

kbd { color: black; background-color: lightgrey; border: 1px solid black; box-shadow: 0px 1px black; font-size: .85em; line-height: .85em; display: inline-block; font-weight: 600; letter-spacing: .05em; padding: 3px 5px; white-space: nowrap; border-radius:5px; }pre {background-color: black; color: white}

Before you go, make sure you leave your account clean from artifacts so that you can play with other tutorials in the future or simply do solo experimentation.


Delete workspace in Dev Spaces

When you’re done playing with the workspace, follow the guidance below to delete it entirely from the environment.

Warning
 Your VSCode environment along with these lab instructions will be deleted from your sandbox.

First, stop your workspace by following the actions below:

  1. At the bottom-left of your screen, click the >< button.

  2. Then at the top, select:

    • Dev Spaces: Stop Workspace

workspace stop

Stopping your workspace will make your browser switch to the Dev Spaces dashboard.

From the dashboard, follow the steps indicated below:

  1. Click Workspaces, from the left menu.

  2. Tick the checkbox for devsandbox-catalog-ai-labs.

  3. Click the button  Delete .

    workspace delete


Is your namespace clean from artifacts?

You’ve successfully cleaned up your namespace !!

Review the instructions in this chapter and try again.