Chapter 3. Get Started for Developers

You can start using Fuse on OpenShift 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 characterized 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.9 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.9 Developer Guide.

3.1. Prerequisites

3.1.1. Access to an OpenShift Server

The fundamental requirement for developing and testing Fuse on OpenShift 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 Fuse on OpenShift, we recommend you install version 3.4 of CDK. Detailed instructions for installing and using CDK 3.4 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 guide before proceeding with the examples in this chapter.

Note

Recent versions of CDK have Fuse on OpenShift images and templates pre-installed. If the images and templates are not pre-installed, however, or if the provided versions are out of date, you will need to install (or update) the Fuse on OpenShift images 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 Fuse on OpenShift:

  • 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.9.
  • Ask the OpenShift administrator to install the latest Fuse on OpenShift container base images and the Fuse on OpenShift 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 Fuse 7.0. 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 Fuse on OpenShift 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.4 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.4 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 Fuse on OpenShift 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 on OpenShift applications. For details about 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 Fuse on OpenShift project.

  1. Create a new Fuse on OpenShift 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.0.fuse-000110-redhat-5/archetypes-catalog-2.2.0.fuse-000110-redhat-5-archetype-catalog.xml \
      -DarchetypeGroupId=org.jboss.fuse.fis.archetypes \
      -DarchetypeArtifactId=spring-boot-camel-xml-archetype \
      -DarchetypeVersion=2.2.0.fuse-000110-redhat-5

    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': : fuse70-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.5.13.RELEASE
    Confirm properties configuration:
    groupId: org.example.fis
    artifactId: fuse70-spring-boot
    version: 1.0-SNAPSHOT
    package: org.example.fis
    spring-boot-version: 1.5.13.RELEASE
     Y: :

    When prompted, enter org.example.fis for the groupId value and fuse70-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 Fuse on OpenShift project under the fuse70-spring-boot subdirectory. You can inspect the XML DSL code in the fuse70-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 Fuse on OpenShift 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 fuse70-spring-boot project. Assuming you are still logged into OpenShift, change to the directory of the fuse70-spring-boot project, and then build and deploy the project, as follows:

    cd fuse70-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 fuse70-spring-boot
    [INFO] Created Service: target/fabric8/applyJson/test/service-fuse70-spring-boot.json
    [INFO] Using project: test
    [INFO] Creating a DeploymentConfig from openshift.yml namespace test name fuse70-spring-boot
    [INFO] Created DeploymentConfig: target/fabric8/applyJson/test/deploymentconfig-fuse70-spring-boot.json
    [INFO] Creating Route test:fuse70-spring-boot host: null
    [INFO] F8: HINT: Use the command `oc get pods -w` to watch your pods start up
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 05:38 min
    [INFO] Finished at: 2018-02-22T12:08:11+01:00
    [INFO] Final Memory: 63M/272M
    [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 to open the test project namespace. The Overview tab of the test project opens, showing the fuse70-spring-boot application.
  8. Click the arrow on the left of the fuse70-spring-boot deployment to expand and view the details of this deployment, as shown.

    OpenShift console test namespace overview showing fuse70-spring-boot application and associated pods
  9. Click in the centre of the pod icon (blue circle) to view the list of pods for fuse70-spring-boot.

    List of pods associated with the fuse70-spring-boot service
  10. Click on the pod Name (in this example, fuse70-spring-boot-1-kxdjm) to view the details of the running pod.

    Detail view of the running pod for fuse70-spring-boot
  11. 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
  12. Click Overview on the left-hand navigation bar to return to the applications overview 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 fuse70-spring-boot-1?, click Scale Down.
  13. (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. Undeploy and Redeploy the Project

You can undeploy or redeploy your projects, as follows:

  • To undeploy the project, enter the command:

    mvn fabric8:undeploy
  • To redeploy the project, enter the commands:

    mvn fabric8:undeploy
    mvn fabric8:deploy

3.3.2. Opening the HawtIO Console

To open the HawtIO console for a pod running the Fuse on OpenShift 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 Fuse on OpenShift 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 Fuse on OpenShift 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 a Fuse on OpenShift 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. In the Catalog search field, enter JBoss Fuse 7.0 Camel XML as the search string and select the JBoss Fuse 7.0 Camel XML DSL with Spring Boot template.

    get started s2i source 01
  3. The Information step of the template wizard opens. Click Next.
  4. The Configuration step of the template wizard opens, as shown. From the Add to Project dropdown, select My Project.

    Note

    Alternatively, if you prefer to create a new project for this example, select Create Project from the Add to Project dropdown. A Project Name field then appears for you to fill in the name of the new project.

  5. You can accept the default values for the rest of the settings in the Configuration step. 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.

  6. The Results step of the template wizard opens. Click Close.
  7. In the left-hand My Projects pane, click My Project. The Overview tab of the My Project project opens, showing the s2i-fuse70-spring-boot-camel-xml application.
  8. Click the arrow on the left of the s2i-fuse70-spring-boot-camel-xml deployment to expand and view the details of this deployment, as shown.

    get started s2i source 03
  9. In this view, you can see the build log. 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.

  10. If the build completes successfully, the pod icon shows as a blue circle with 1 pod running. Click in the centre of the pod icon (blue circle) to view the list of pods for s2i-fuse70-spring-boot-camel-xml.

    Note

    If multiple pods are running, you would see a list of running pods at this point. Otherwise (if there is just one pod), you get straight through to the details view of the running pod.

  11. The pod details view opens. 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.

    Details view of the running pod
  12. Click Overview on the left-hand navigation bar to return to the overview of the applications in the My Project 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-fuse70-spring-boot-camel-xml-1?, click Scale Down.
  13. (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