Chapter 5. Getting Started for developers

5.1. Preparing development environment

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

5.1.1. Installing Container Development Kit (CDK) on your local machine

As a developer, if you want to get started quickly, the most practical alternative is to install Red Hat CDK on your 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
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).

Prerequisites

  • Java Version

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

Procedure

To install the CDK on your local machine:

  1. For Fuse on OpenShift, we recommend that you install version 3.16 of CDK. Detailed instructions for installing and using CDK 3.16 are provided in the Red Hat CDK 3.16 Getting Started Guide.
  2. Configure your OpenShift credentials to gain access to the Red Hat Ecosystem Catalog by following the instructions in Authenticating with registry.redhat.io for container images.

  3. Install the Fuse on OpenShift images and templates manually as described in Chapter 2, Getting Started for administrators.

    Note

    Your version of CDK might have Fuse on OpenShift images and templates pre-installed. However, you must install (or update) the Fuse on OpenShift images and templates after you configure your OpenShift credentials.

  4. Before you proceed with the examples in this chapter, you should read and thoroughly understand the contents of the Red Hat CDK 3.16 Getting Started Guide.

5.1.2. Getting 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.11.
  • 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.

5.1.3. Installing Client-Side tools

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

  • Apache Maven 3.6.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.6.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.16 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.16 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.

Additional Resources

(Optional) Red Hat JBoss CodeReady Studio: Red Hat JBoss CodeReady Studio is an Eclipse-based development environment that includes support for developing Fuse on OpenShift applications. For details about how to install this development environment, see Install Red Hat JBoss CodeReady Studio.

5.1.4. Configuring Maven repositories

Configure the Maven repositories, which hold the archetypes and artifacts that you will need for building an Fuse on OpenShift project on your local machine.

Procedure

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

  2. Add the following Maven repositories.

5.2. Creating and deploying applications on Fuse on OpenShift

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 Builds OpenShift Container Platform guide.
S2I source workflow
S2I with build input from a Git source. This workflow is characterized by the fact that the build is executed entirely on the OpenShift server. For more details, see Git Source from the Builds OpenShift Container Platform guide.

5.2.1. Creating and deploying an application 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.

Note
Running quickstarts with JDK11
Use the correct JDK11 profile during the compile time if you want to use JDK11 based image at runtime. When building and deploying the quickstarts using JDK11, ensure that you have installed JDK11 on your build machine and then build your quickstarts using the correct JDK11 profile.

Procedure

  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-sb2-790047-redhat-00004/archetypes-catalog-2.2.0.fuse-sb2-790047-redhat-00004-archetype-catalog.xml \
  -DarchetypeGroupId=org.jboss.fuse.fis.archetypes \
  -DarchetypeArtifactId=spring-boot-camel-xml-archetype \
  -DarchetypeVersion=2.2.0.fuse-sb2-790047-redhat-00004

    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': : fuse79-spring-boot
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  org.example.fis: :
Confirm properties configuration:
groupId: org.example.fis
artifactId: fuse79-spring-boot
version: 1.0-SNAPSHOT
package: org.example.fis
 Y: : Y

    When prompted, enter org.example.fis for the groupId value and fuse79-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 fuse79-spring-boot subdirectory. You can inspect the XML DSL code in the fuse79-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. Switch to openshift project (if not already in the openshift project) as follows. 

    oc project openshift

  5. Run the following command to ensure that Fuse on OpenShift images and templates are already installed and you can access them. 

    oc get template -n openshift

    If the images and templates are not pre-installed, or if the provided versions are out of date, install (or update) the Fuse on OpenShift images and templates manually. For more information on how to install Fuse on OpenShift images see Chapter 2, Getting Started for administrators.

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

    cd fuse79-spring-boot
mvn oc:deploy -Popenshift

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

    ...
[INFO] OpenShift platform detected
[INFO] Using project: openshift
[INFO] Creating a Service from openshift.yml namespace openshift name fuse79-spring-boot
[INFO] Created Service: target/jkube/applyJson/openshift/service-fuse79-spring-boot.json
[INFO] Using project: openshift
[INFO] Creating a DeploymentConfig from openshift.yml namespace openshift name fuse79-spring-boot
[INFO] Created DeploymentConfig: target/jkube/applyJson/openshift/deploymentconfig-fuse79-spring-boot.json
[INFO] Creating Route openshift:fuse79-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: 2020-12-04T12:15:06+05:30
[INFO] Final Memory: 63M/688M
[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.

  7. 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).
  8. In the left hand side panel, expand Home and then click Status to view the Project Status page for the openshift project.

  9. Click fuse79-spring-boot to view the Overview information page for the fuse79-spring-boot application.

    Overview

  10. In the left hand side panel, expand Workloads.
  11. Click Pods. All the running pods in the openshift project are displayed.

  12. Click on the pod Name (in this example, fuse79-spring-boot-xxxxx) to view the details of the running pod.

    Pod Details

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

    ...
06:45:54.311 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 130
06:45:56.265 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 898
06:45:58.265 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 414
06:46:00.265 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 486
06:46:02.265 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 093
06:46:04.265 [Camel (MyCamel) thread #1 - timer://foo] INFO simple-route - >>> 080

  14. To shut down the running pod,

    1. On the Project Status page for the openshift project, click fuse79-spring-boot application.
    2. Click the Overview tab to view to the overview information page of the application.
    3. Click the edit pod count icon next to Desired Count. The Edit Count window is displayed.
    4. Use the down arrow to scale down to zero to stop the pod.

5.2.2. Undeploying and redeploying the project

You can undeploy or redeploy your projects, as follows:

Procedure

  • To undeploy the project, enter the command: 

    mvn oc:undeploy

  • To redeploy the project, enter the commands: 

    mvn oc:undeploy
mvn oc:deploy -Popenshift

5.2.3. Creating and deploying an application using the S2I source workflow

In this section, you will use the OpenShift S2I source workflow to build and deploy a Fuse on OpenShift application 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.

Procedure

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

  2. Switch to openshift project (if not already in the openshift project) as follows. 

    oc project openshift

  3. Run the following command to ensure that Fuse on OpenShift templates are already installed and you can access them. 

    oc get template -n openshift

    If the images and templates are not pre-installed, or if the provided versions are out of date, install (or update) the Fuse on OpenShift images and templates manually. For more information on how to install Fuse on OpenShift images see Chapter 2, Getting Started for administrators.

  4. Enter the following command to create the resources required for running the Red Hat Fuse 7.9 Camel XML DSL with Spring Boot quickstart template. This will create a deployment config and build config for the quickstart. The information about the default parameters of the quickstart and the resources created is displayed on the terminal. 

    oc new-app s2i-fuse7-spring-boot-camel-xml

--> Deploying template "openshift/s2i-fuse7-spring-boot-camel-xml" to project openshift
...
--> Creating resources ...
    imagestream.image.openshift.io "s2i-fuse7-spring-boot-camel-xml" created
    buildconfig.build.openshift.io "s2i-fuse7-spring-boot-camel-xml" created
    deploymentconfig.apps.openshift.io "s2i-fuse7-spring-boot-camel-xml" created
--> Success
    Build scheduled, use 'oc logs -f bc/s2i-fuse7-spring-boot-camel-xml' to track its progress.
    Run 'oc status' to view your app.
  5. Navigate to the OpenShift web console in your browser (https://OPENSHIFT_IP_ADDR, replace OPENSHIFT_IP_ADDR with the IP address of the cluster) and log in to the console with your credentials (for example, with username developer and password, developer).
  6. In the left hand side panel, expand Home. Click Status to view the Project Status page. All the existing applications in the selected namespace (for example, openshift) are displayed.

  7. Click s2i-fuse7-spring-boot-camel-xml to view the Overview information page for the quickstart.

    Spring Boot Camel XML Overview

  8. Click the Resources tab and then click View logs to view the build log for the application.

    Spring Boot Camel XML build logs

  9. In the left hand side panel, expand Workloads.

  10. Click Pods and then click s2i-fuse7-spring-boot-camel-xml-xxxx. The pod details for the application are displayed.

    Spring Boot Camel XML pod details

  11. To shut down the running pod,

    1. On the Project Status page for the openshift project, click s2i-fuse7-spring-boot-camel-xml-xxxx application.
    2. Click the Overview tab to view to the overview information page of the application.
    3. Click the edit pod count icon next to Desired Count. The Edit Count window is displayed.
    4. Use the down arrow to scale down to zero to stop the pod.