Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 3. Get Started for Developers

You can start using Fuse Integration Services by creating an application and deploying it to OpenShift using one of the following OpenShift Source-to-Image (S2I) application development workflows:

S2I binary workflow
S2I with build input from a binary source. This workflow is characterised by the fact that the build is partly executed on the developer’s own machine. After building a binary package locally, this workflow hands off the binary package to OpenShift. For more details, see Binary Source from the OpenShift 3.5 Developer Guide.
S2I source workflow
S2I with build input from a Git source. This workflow is characterised by the fact that the build is executed entirely on the OpenShift server. For more details, see Git Source from the OpenShift 3.5 Developer Guide.

3.1. Prerequisites

3.1.1. Access to an OpenShift Server

The fundamental requirement for developing and testing FIS projects is having access to an OpenShift Server. You have the following basic alternatives:

3.1.1.1. Install Container Development Kit (CDK) on Your Local Machine

To get started quickly, the most practical alternative for a developer is to install Red Hat CDK on their local machine. Using CDK, you can boot a virtual machine (VM) instance that runs an image of OpenShift on Red Hat Enterprise Linux (RHEL) 7. An installation of CDK consists of the following key components:

  • A virtual machine (libvirt, VirtualBox, or Hyper-V)
  • Minishift to start and manage the Container Development Environment

For FIS 2.0, we recommend you install version 3.1 of CDK. Detailed instructions for installing and using CDK 3.1 are provided in the following guide:

If you opt to use CDK, we recommend that you read and thoroughly understand the content of the preceding guides before proceeding with the examples in this chapter.

Note

If you are using a CDK version earlier than 3.1, you need to install the FIS image streams and templates manually. See Chapter 2, Get Started for Administrators.

Important

Red Hat CDK is intended for development purposes only. It is not intended for other purposes, such as production environments, and may not address known security vulnerabilities. For full support of running mission-critical applications inside of docker-formatted containers, you need an active RHEL 7 or RHEL Atomic subscription. For more details, see Support for Red Hat Container Development Kit (CDK).

3.1.1.2. Get Remote Access to an Existing OpenShift Server

Your IT department might already have set up an OpenShift cluster on some server machines. In this case, the following requirements must be satisfied for getting started with FIS 2.0:

  • The server machines must be running a supported version of OpenShift Container Platform (as documented in the Supported Configurations page). The examples in this guide have been tested against version 3.5.
  • Ask the OpenShift administrator to install the latest FIS 2.0 container base images and the FIS templates on the OpenShift servers.
  • Ask the OpenShift administrator to create a user account for you, having the usual developer permissions (enabling you to create, deploy, and run OpenShift projects).
  • Ask the administrator for the URL of the OpenShift Server (which you can use either to browse to the OpenShift console or connect to OpenShift using the oc command-line client) and the login credentials for your account.

3.1.2. Java Version

On your developer machine, make sure you have installed a Java version that is supported by JBoss Fuse 6.3. For details of the supported Java versions, see Supported Configurations.

3.1.3. Install the Requisite Client-Side Tools

We recommend that you have the following tools installed on your developer machine:

Apache Maven 3.3.x
Required for local builds of OpenShift projects. Download the appropriate package from the Apache Maven download page. Make sure that you have at least version 3.3.x (or later) installed, otherwise Maven might have problems resolving dependencies when you build your project.
Git
Required for the OpenShift S2I source workflow and generally recommended for source control of your FIS projects. Download the appropriate package from the Git Downloads page.
OpenShift client

If you are using CDK, you can add the oc binary to your PATH using minishift oc-env which displays the command you need to type into your shell (the output of oc-env will differ depending on OS and shell type): 

$ minishift oc-env
export PATH="/Users/john/.minishift/cache/oc/v1.5.0:$PATH"
# Run this command to configure your shell:
# eval $(minishift oc-env)

For more details, see Using the OpenShift Client Binary in CDK 3.1 Getting Started Guide.

If you are not using CDK, follow the instructions in the CLI Reference to install the oc client tool.

(Optional) Docker client

Advanced users might find it convenient to have the Docker client tool installed (to communicate with the docker daemon running on an OpenShift server). For information about specific binary installations for your operating system, see the Docker installation site.

For more details, see Reusing the docker Daemon in CDK 3.1 Getting Started Guide.

Important

Make sure that you install versions of the oc tool and the docker tool that are compatible with the version of OpenShift running on the OpenShift Server.

3.2. Prepare Your Development Environment

After installing the required software and tools, prepare your development environment as follows.

3.2.1. Configure Maven Repositories

Configure the Maven repositories, which hold the archetypes and artifacts you will need for building an FIS project on your local machine. Edit your Maven settings.xml file, which is usually located in ~/.m2/settings.xml (on Linux or macOS) or Documents and Settings\<USER_NAME>\.m2\settings.xml (on Windows). The following Maven repositories are required:

You must add the preceding repositories both to the dependency repositories section as well as the plug-in repositories section of your settings.xml file.

3.2.2. (Optional) Install Developer Studio

Red Hat JBoss Developer Studio is an Eclipse-based development environment, which includes support for developing Fuse Integration Services applications. For details of how to install this development environment, see Install Red Hat JBoss Developer Studio.

3.3. Create and Deploy a Project Using the S2I Binary Workflow

In this section, you will use the OpenShift S2I binary workflow to create, build, and deploy an FIS project.

  1. Create a new FIS project using a Maven archetype. For this example, we use an archetype that creates a sample Spring Boot Camel project. Open a new shell prompt and enter the following Maven command: 

    mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate \
  -DarchetypeCatalog=https://maven.repository.redhat.com/ga/io/fabric8/archetypes/archetypes-catalog/2.2.195.redhat-000017/archetypes-catalog-2.2.195.redhat-000017-archetype-catalog.xml \
  -DarchetypeGroupId=org.jboss.fuse.fis.archetypes \
  -DarchetypeArtifactId=spring-boot-camel-xml-archetype \
  -DarchetypeVersion=2.2.195.redhat-000017

    The archetype plug-in switches to interactive mode to prompt you for the remaining fields: 

    Define value for property 'groupId': : org.example.fis
Define value for property 'artifactId': : fis-spring-boot
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  org.example.fis: :
[INFO] Using property: spring-boot-version = 1.4.1.RELEASE
Confirm properties configuration:
groupId: org.example.fis
artifactId: fis-spring-boot
version: 1.0-SNAPSHOT
package: org.example.fis
spring-boot-version: 1.4.1.RELEASE
 Y: :

    When prompted, enter org.example.fis for the groupId value and fis-spring-boot for the artifactId value. Accept the defaults for the remaining fields.

  2. If the previous command exited with the BUILD SUCCESS status, you should now have a new FIS project under the fis-spring-boot subdirectory. You can inspect the XML DSL code in the fis-spring-boot/src/main/resources/spring/camel-context.xml file. The demonstration code defines a simple Camel route that continuously sends message containing a random number to the log.

  3. In preparation for building and deploying the FIS project, log in to the OpenShift Server as follows: 

    oc login -u developer -p developer https://OPENSHIFT_IP_ADDR:8443

    Where, OPENSHIFT_IP_ADDR is a placeholder for the OpenShift server’s IP address as this IP address is not always the same.

    Note

    The developer user (with developer password) is a standard account that is automatically created on the virtual OpenShift Server by CDK. If you are accessing a remote server, use the URL and credentials provided by your OpenShift administrator.

  4. Create a new project namespace called test (assuming it does not already exist), as follows: 

    oc new-project test

    If the test project namespace already exists, you can switch to it using the following command: 

    oc project test

  5. You are now ready to build and deploy the fis-spring-boot project. Assuming you are still logged into OpenShift, change to the directory of the fis-spring-boot project, and then build and deploy the project, as follows: 

    cd fis-spring-boot
mvn fabric8:deploy

    At the end of a successful build, you should see some output like the following: 

    ...
[INFO] OpenShift platform detected
[INFO] Using project: test
[INFO] Creating a Service from openshift.yml namespace test name fis-spring-boot
[INFO] Created Service: target/fabric8/applyJson/test/service-fis-spring-boot.json
[INFO] Updating ImageStream fis-spring-boot from openshift.yml
[INFO] Creating a DeploymentConfig from openshift.yml namespace test name fis-spring-boot
[INFO] Created DeploymentConfig: target/fabric8/applyJson/test/deploymentconfig-fis-spring-boot.json
[INFO] F8: HINT: Use the command `oc get pods -w` to watch your pods start up
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:23 min
[INFO] Finished at: 2016-11-10T17:46:05+01:00
[INFO] Final Memory: 66M/666M
[INFO] ------------------------------------------------------------------------
    Note

    The first time you run this command, Maven has to download a lot of dependencies, which takes several minutes. Subsequent builds will be faster.

  6. Navigate to the OpenShift console in your browser and log in to the console with your credentials (for example, with username developer and password, developer).

  7. In the OpenShift console, scroll down to find the test project namespace. Click the test project and an overview of the fis-spring-boot service opens, as shown.

    OpenShift console test namespace overview showing fis-spring-boot service and associated pods

  8. Click in the centre of the pod icon (blue circle) to view the list of pods for fis-spring-boot.

    List of pods associated with the fis-spring-boot service

  9. Click on the pod Name (in this example, fis-spring-boot-1-1rieh) to view the details of the running pod.

    Detail view of the running pod for fis-spring-boot

  10. Click on the Logs tab to view the application log and scroll down the log to find the random number log messages generated by the Camel application. 

    ...
07:30:32.406 [Camel (camel) thread #0 - timer://foo] INFO  simple-route - >>> 985
07:30:34.405 [Camel (camel) thread #0 - timer://foo] INFO  simple-route - >>> 741
07:30:36.409 [Camel (camel) thread #0 - timer://foo] INFO  simple-route - >>> 796
07:30:38.409 [Camel (camel) thread #0 - timer://foo] INFO  simple-route - >>> 211
07:30:40.411 [Camel (camel) thread #0 - timer://foo] INFO  simple-route - >>> 511
07:30:42.411 [Camel (camel) thread #0 - timer://foo] INFO simple-route - >>> 942
  11. Click Overview on the left-hand navigation bar to return to the overview of the services in the test namespace. To shut down the running pod, click the down arrow get started s2i binary 05 beside the pod icon. When a dialog prompts you with the question Scale down deployment fis-spring-boot-1?, click Scale Down.

  12. (Optional) If you are using CDK, you can shut down the virtual OpenShift Server completely by returning to the shell prompt and entering the following command: 

    minishift stop

3.3.1. Redeploy and Undeploy the Project

To redeploy or undeploy your projects, you can use the following commands.

  • To redeploy the project, rerun mvn fabric8:deploy.
  • To undeploy the project, run mvn fabric8:undeploy.

3.3.2. Opening the HawtIO Console

To open the HawtIO console for a pod running the FIS Spring Boot example, proceed as follows:

  1. From the Applications → Pods view in your OpenShift project, click on the pod name to view the details of the running FIS Spring Boot pod. On the right-hand side of this page, you see a summary of the container template:

    Container Template View

  2. From this view, click on the Open Java Console link to open the HawtIO console.

    HawtIO console view
    Note

    In order to configure OpenShift to display a link to HawtIO console in the pod view, the pod running a FIS image must declare a tcp port within a name attribute set to jolokia: 

    {
  "kind": "Pod",
  [...]
  "spec": {
    "containers": [
      {
        [...]
        "ports": [
          {
            "name": "jolokia",
            "containerPort": 8778,
            "protocol": "TCP"
          }

3.4. Create and Deploy a Project Using the S2I Source Workflow

In this section, you will use the OpenShift S2I source workflow to build and deploy an FIS project based on a template. The starting point for this demonstration is a quickstart project stored in a remote Git repository. Using the OpenShift console, you will download, build, and deploy this quickstart project in the OpenShift server.

  1. Navigate to the OpenShift console in your browser (https://OPENSHIFT_IP_ADDR:8443, replace OPENSHIFT_IP_ADDR with the IP address that was displayed in the case of CDK) and log in to the console with your credentials (for example, with username developer and password, developer).
  2. On the Projects screen of the OpenShift console, click New Project.

  3. On the New Project screen, enter test in the Name field and click Create. The Select Image or Template screen now opens.

    Note

    If the test project already exists in OpenShift, click on the test project and then click Add to Project to open the Add to Project screen.

  4. On the Add to Project screen, from the Browse Catalog tab, click Java to open the list of Java templates.

    get started s2i source 01

  5. Scroll down to find the s2i-spring-boot-camel-xml template and click the Select button.

    get started s2i source 011

  6. The s2i-spring-boot-camel-xml template form opens, as shown below. You can accept all of the default settings on this form. Scroll down to the bottom of the form and click Create.

    get started s2i source 02
    Note

    If you want to modify the application code (instead of just running the quickstart as is), you would need to fork the original quickstart Git repository and fill in the appropriate values in the Git repository URL and Git reference fields.

  7. The Application created screen now opens. Click Continue to overview to go to the Overview tab of the OpenShift console (which shows an overview of the available services and pods in the current project). If you have not previously created any application builds in this project, this screen will be empty.
  8. In the navigation pane on the left-hand side, select Builds→Builds to open the Builds screen.

  9. Click the s2i-spring-boot-camel-xml build name to open the s2i-spring-boot-camel-xml build page, as shown below.

    get started s2i source 04

  10. Click View log to view the log for the latest build — if the build should fail for any reason, the build log can help you to diagnose the problem.

    Note

    The build can take several minutes to complete, because a lot of dependencies must be downloaded from remote Maven repositories. To speed up build times, we recommend you deploy a Nexus server on your local network.

  11. If the build completes successfully, click Overview in the left-hand navigation pane to view the running pod for this application.

  12. Click in the centre of the pod icon (blue circle) to view the list of pods for s2i-spring-boot-camel-xml.

    List of pods associated with the s2i-spring-boot-camel-xml service

  13. Click on the pod Name (in this example, s2i-spring-boot-camel-xml-1-hviyy) to view the details of the running pod.

    Detail view of the running pod for s2i-spring-boot-camel-xml

  14. Click on the Logs tab to view the application log and scroll down the log to find the log messages generated by the Camel application.

    View of the application log showing log messages
  15. Click Overview on the left-hand navigation bar to return to the overview of the services in the test namespace. To shut down the running pod, click the down arrow get started s2i binary 05 beside the pod icon. When a dialog prompts you with the question Scale down deployment s2i-spring-boot-camel-xml-1?, click Scale Down.

  16. (Optional) If you are using CDK, you can shut down the virtual OpenShift Server completely by returning to the shell prompt and entering the following command: 

    minishift stop