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
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.10. For details of the supported Java versions, see Supported Configurations.
Procedure
To install the CDK on your local machine:
- For Fuse on OpenShift, we recommend that you install version 3.17 of CDK. Detailed instructions for installing and using CDK 3.17 are provided in the Red Hat CDK 3.17 Getting Started Guide.
-
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. Install the Fuse on OpenShift images and templates manually as described in Chapter 2, Getting Started for administrators.
NoteYour 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.
- Before you proceed with the examples in this chapter, you should read and thoroughly understand the contents of the Red Hat CDK 3.17 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 usingminishift oc-env
which displays the command you need to type into your shell (the output ofoc-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.17 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.17 Getting Started Guide.
ImportantMake sure that you install versions of the
oc
tool and thedocker
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
-
Open your Maven
settings.xml
file, which is usually located in~/.m2/settings.xml
(on Linux or macOS) orDocuments and Settings\<USER_NAME>\.m2\settings.xml
(on Windows). Add the following Maven repositories.
-
Maven central:
https://repo1.maven.org/maven2
-
Red Hat GA repository:
https://maven.repository.redhat.com/ga
Red Hat EA repository:
https://maven.repository.redhat.com/earlyaccess/all
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.
-
Maven central:
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.
- 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
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 one of the following Maven commands:
To access all of the S2I quickstarts:
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-7_10_0-00015-redhat-00001/archetypes-catalog-2.2.0.fuse-sb2-7_10_0-00015-redhat-00001-archetype-catalog.xml \ -DarchetypeGroupId=org.jboss.fuse.fis.archetypes \ -DarchetypeVersion=2.2.0.fuse-sb2-7_10_0-00015-redhat-00001
To access just the
spring-boot-2-camel-xml
quickstart: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-7_10_0-00015-redhat-00001/archetypes-catalog-2.2.0.fuse-sb2-7_10_0-00015-redhat-00001-archetype-catalog.xml \ -DarchetypeGroupId=org.jboss.fuse.fis.archetypes \ -DarchetypeArtifactId=spring-boot-camel-xml-archetype \ -DarchetypeVersion=2.2.0.fuse-sb2-7_10_0-00015-redhat-00001
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': : fuse710-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: fuse710-spring-boot version: 1.0-SNAPSHOT package: org.example.fis Y: : Y
When prompted, enter
org.example.fis
for thegroupId
value andfuse710-spring-boot
for theartifactId
value. Accept the defaults for the remaining fields.
-
If the previous command exited with the
BUILD SUCCESS
status, you should now have a new Fuse on OpenShift project under thefuse710-spring-boot
subdirectory. You can inspect the XML DSL code in thefuse710-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. 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.NoteThe
developer
user (withdeveloper
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.Switch to
openshift
project (if not already in theopenshift
project) as follows.oc project openshift
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.
You are now ready to build and deploy the
fuse710-spring-boot
project. Assuming you are still logged into OpenShift, change to the directory of thefuse710-spring-boot
project, and then build and deploy the project, as follows.cd fuse710-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 fuse710-spring-boot [INFO] Created Service: target/jkube/applyJson/openshift/service-fuse710-spring-boot.json [INFO] Using project: openshift [INFO] Creating a DeploymentConfig from openshift.yml namespace openshift name fuse710-spring-boot [INFO] Created DeploymentConfig: target/jkube/applyJson/openshift/deploymentconfig-fuse710-spring-boot.json [INFO] Creating Route openshift:fuse710-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] ------------------------------------------------------------------------
NoteThe first time you run this command, Maven has to download a lot of dependencies, which takes several minutes. Subsequent builds will be faster.
-
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
). -
In the left hand side panel, expand Home and then click Status to view the Project Status page for the
openshift
project. Click fuse710-spring-boot to view the Overview information page for the fuse710-spring-boot application.
- In the left hand side panel, expand Workloads.
- Click Pods. All the running pods in the openshift project are displayed.
Click on the pod Name (in this example,
fuse710-spring-boot-xxxxx
) to view the details of the running pod.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
To shut down the running pod,
-
On the Project Status page for the
openshift
project, click fuse710-spring-boot application. - Click the Overview tab to view to the overview information page of the application.
- Click the icon next to Desired Count. The Edit Count window is displayed.
- Use the down arrow to scale down to zero to stop the pod.
-
On the Project Status page for the
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
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.NoteThe
developer
user (withdeveloper
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.Switch to
openshift
project (if not already in theopenshift
project) as follows.oc project openshift
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.
Enter the following command to create the resources required for running the Red Hat Fuse 7.10 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.
- 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).
- 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.
Click
s2i-fuse7-spring-boot-camel-xml
to view the Overview information page for the quickstart.Click the Resources tab and then click View logs to view the build log for the application.
- In the left hand side panel, expand Workloads.
Click Pods and then click
s2i-fuse7-spring-boot-camel-xml-xxxx
. The pod details for the application are displayed.To shut down the running pod,
-
On the Project Status page for the
openshift
project, click s2i-fuse7-spring-boot-camel-xml-xxxx application. - Click the Overview tab to view to the overview information page of the application.
- Click the icon next to Desired Count. The Edit Count window is displayed.
- Use the down arrow to scale down to zero to stop the pod.
-
On the Project Status page for the