Chapter 2. Developing for the Cloud with OpenShift 3

2.1. Creating an OpenShift Container Platform application in CodeReady Studio

Using the OpenShift Container Platform tooling you can create, import, and modify OpenShift Container Platform applications.

2.1.1. Creating a new OpenShift Container Platform connection

You must create an OpenShift connection in the OpenShift Explorer view in CodeReady Studio to use the OpenShift tooling in the IDE. An OpenShift connection connects your IDE to an OpenShift instance (based on CDK, OpenShift Online, Kubernetes, minishift). The connection is listed in the OpenShift Explorer view of the IDE and is in the format: username@example.com {OpenShift_console_URL}. You can have more than one OpenShift connection configured in the IDE.

Procedure

  1. In the IDE, click WindowShow ViewOther
  2. Search for OpenShift Explorer, select it, and click OK
  3. In the OpenShift Explorer view, click New Connection Wizard.
  4. In the Connection list, click <New Connection>.
  5. In the Server type list, click OpenShift 3.
  6. In the Server field, type the URL for an OpenShift Container Platform server.
  7. In the Authentication section, in the Protocol list, click OAuth to authenticate using the token or click Basic to authenticate using login credentials.
  8. Click Finish.

Figure 2.1. Set up a new OpenShift Container Platform connection

Set up a New OpenShift Container Platform Connection

2.1.2. Creating a new OpenShift Container Platform project

You must create a project, which essentially is a namespace with additional annotations, to centrally manage the access to resources for regular users.

Prerequisites

  • An OpenShift Container Platform connection exists.

Procedure

  1. In the OpenShift Explorer view, right-click the connection and click New > Project. The Create OpenShift Project window appears.
  2. In the Project Name field, type a name for the project. Project names must be alphanumeric and can contain the character “-” but must not begin or end with this character.
  3. In the Display Name field, type a display name for the project. This name is used as the display name for your project in the OpenShift Explorer view and on the OpenShift Container Platform web console after the project is created.
  4. In the Description field, type a description of the project.
  5. Click Finish. The project is listed in the OpenShift Explorer view, under the relevant connection.

2.1.3. Creating a new OpenShift Container Platform application

Use the New OpenShift Application wizard in the IDE to create OpenShift Container Platform applications from default or custom templates. Using a template to create an application is helpful because you can use the same template to create multiple similar applications with different or identical configurations for each of them.

Prerequisites

  • An OpenShift Container Platform project exists.

Procedure

  1. In the OpenShift Explorer view of the IDE, right-click the connection and click NewApplication.
  2. If required, in the New OpenShift Application wizard, sign in to your OpenShift Container Platform server using the Basic protocol (username and password) or the OAuth protocol (token) and click Next.
  3. In the Select Template window, click the Server application source tab.

    Note

    To create an application from a local template, click the Local template tab and then click Browse File System or Browse Workspace to locate the template that you want to base the project on.

  4. From the list, click the template that you want to base your project on. You can also use the type filter text field to search for specific templates.
  5. Click Next.

    Figure 2.2. Select a template for project creation

    Select a template for project creation
  6. In the Template Parameters window, confirm the parameter values and click Next.
  7. In the Resource Labels window, confirm the labels that you want to add to each resource. You can also click Add or Edit to add labels or edit the existing ones.
  8. Click Finish.
  9. In the Results of creating the resources from the {template_name} window, review the details and click OK.
  10. In the Import Application window, click Use default clone destination to clone the application at the default location or in the Git Clone Location field, type or browse for the location where you want to clone the application, and click Finish.

    Figure 2.3. Selecting a Git clone location

    Selecting a Git clone location
    Note

    If the Git location chosen to clone the application already contains a folder with the application name that you are trying to import, you must select a new location for the Git clone. If you do not select a new location, the existing repository will be reused with the changes you made being retained but not reflected on the OpenShift Container Platform console.

    Figure 2.4. Git clone location reuse

    Git clone location reuse

Result: The application appears in the Project Explorer view.

Additional Resources

  • To learn more about using and creating templates with OpenShift Container Platform, see Templates.

2.1.4. Importing an existing OpenShift Container Platform application into the IDE

The OpenShift Explorer view in the IDE lists applications associated with your OpenShift Container Platform accounts. You can import the source code for these applications individually into the IDE using the Import OpenShift Application wizard. After the application is imported, you can easily modify the application source code, as required, build the application, and view it in a web browser.

Prerequisites

  • The application that you are importing in the IDE has its source specified in the build config file.

Procedure

If required, sign in to your OpenShift Container Platform server using the Basic protocol or the OAuth protocol. In the OpenShift Explorer view of the IDE, expand the connection to locate the application to import. Depending on the type of application you want to import, take the following steps: If a project has a single application under it and you want to import this application, right-click the {project name} and click Import Application. If a project has multiple applications under it and you want to import a specific application, right-click the service and then click Import Application. In the Import OpenShift Application wizard, Existing Build Configs list, click the application that you want to import and click Next. Ensure the location in the Git Clone Destination field corresponds to where you want to make a local copy of the application Git repository. Click Finish. The application is listed in the Project Explorer view.

2.1.5. Deploying an application using the server adapter

The server adapter enables you to publish the changes that you made in your workspace project to the running OpenShift application on the OpenShift instance. It enables incremental deployment of applications directly into the deployed pods on OpenShift. You can use the server adapter to push changes in your application directly to the running OpenShift application without committing the source code to the Git repository.

Procedure

  1. In the OpenShift Explorer view of the IDE, expand the connection, the project, and then the application.
  2. Right-click the {application name} and click Server Adapter.
  3. In the Server Settings window Resources section, select the service.

    Note

    The OpenShift service has a build configuration with a Git URL matching the Git remote URL of one of the workspace projects. A workspace project is selected automatically.

  4. Click Finish. The Servers view is the view in focus with the server showing [Started, Publishing…​] followed by the Console view showing the progress of application publishing.
  5. To view the application, in the OpenShift Explorer view of the IDE, right-click the application, and click Show InWeb browser. The application displays in the built-in web browser.

2.1.6. Deleting an OpenShift Container Platform project

You may choose to delete a project from the workspace to make a fresh start in project development or after you have concluded development in a project. When you delete a project, all the resources associated with the project are deleted.

Prerequisites

  • An OpenShift Container Platform project exists.

Procedure

  1. In the OpenShift Explorer view of the IDE, expand the connection to locate the project you want to delete.
  2. Right-click the {project name} and click Delete Project.
  3. In the OpenShift resource deletion window, click OK.
Note

To delete more than one project (and the containing applications), in the OpenShift Explorer view, click the project to select it and while holding the Control key select another project that you want to delete and then press Delete.

2.2. Setting up and remotely monitoring an OpenShift Container Platform application

In some scenarios, the user already has a remote instance of OpenShift Container Platform running with various applications on it and may want to monitor it. The IDE allows users to set up a connection to a remote instance of OpenShift Container Platform and then use logs (application logs and build logs) to troubleshoot and monitor running applications.

2.2.1. Setting up OpenShift Client Binaries

Prerequisites

Before setting up port forwarding or streaming application and build logs, it is mandatory to set up OpenShift Client Binaries.

Procedure

To set up the OpenShift Client Binaries, take the following steps:

  1. In the IDE, navigate to WindowPreferencesJBoss ToolsOpenShift 3.
  2. Click the here link.
  3. In the Download from GitHub section, click the Release page link.
  4. Scroll to the Assets section for the relevant version of OpenShift Origin. Click the appropriate link to begin the client tools download for the binary for your operating system.
  5. After the download is complete, extract the contents of the file.
  6. Navigate to WindowPreferencesJBoss ToolsOpenShift 3
  7. Click Browse and select the location of the OpenShift Client executable file.
  8. Click Apply and Close. OpenShift Client Binaries are now set up for your IDE.

2.2.2. Setting up Port Forwarding

Using the Application Port Forwarding window, you can connect the local ports to their remote counterparts to access data or debug the application. Port forwarding automatically stops due to any one of the following reasons:

  • The OpenShift Container Platform connection terminates
  • The IDE shuts down
  • The workspace is changed

Port forwarding must be enabled each time to connect to OpenShift Container Platform from the IDE.

Procedure

To set up port forwarding, take the following steps:

  1. In the OpenShift Explorer view, expand the connection, the project, the services, and then the Pods.
  2. Right-click the relevant pod and then click Port Forwarding.

    Figure 2.5. Setting up Port Forwarding

    Setting up Port Forwarding
  3. In the Application Port Forwarding window, click the Find free local ports for remote ports check box and then click Start All. The Status column shows Started, indicating that port forwarding is now active. Additionally, the Console view shows the status of port forwarding for the particular service.

Figure 2.6. Start Port Forwarding

Start Port Forwarding

2.2.3. Streaming Pod Logs

Pod logs are general logs for an application running on a remote OpenShift Container Platform instance. The streaming application logs feature in the IDE is used to monitor applications and use the previous pod log to troubleshoot if the application fails or returns errors.

Procedure

To stream the application logs, take the following steps:

  1. In the OpenShift Explorer view, expand the project, the services, and then the Pods.
  2. Right-click the relevant Pod and then click Pod Log.

Figure 2.7. Streaming Pod Log

Streaming Pod Log

The Console view displays the Pod log.

2.2.4. Streaming Build Logs

Build logs are logs that document changes to applications running on a remote OpenShift Container Platform instance. The streaming build logs feature in the IDE is used to view the progress of the application build process and to debug the application.

Procedure

To stream build logs, take the following steps:

  1. In the OpenShift Explorer view, expand the project, the services, and then the build.
  2. Right-click the relevant build instance and click Build Log.

Figure 2.8. Streaming Build Log

Streaming Build Log

The Console view is now the view in focus showing the build log.

2.3. Building and deploying Docker-formatted Container image to Container Development Kit OpenShift registry

In this article we deploy the Docker based microservices, frontend and bonjour, into an OpenShift Container Platform instance running on Red Hat Container Development Kit, in CodeReady Studio. We use the Helloworld-MSA tutorial available in GitHub at: https://github.com/redhat-helloworld-msa/helloworld-msa.

The article shows how you can easily build a local Docker image, not present on Docker Hub, to Container Development Environment and then deploy that image to an OpenShift Container Platform instance, using CodeReady Studio. frontend and bonjour microservices, used here, are examples of such private images that are not present in Docker Hub.

Prerequisites

  1. Install npm: Before running CodeReady Studio, install npm on your system. See the npm documentation for instructions for various platforms: https://docs.npmjs.com/getting-started/what-is-npm.
  2. Download and install JDK 8.
  3. Install CodeReady Studio and Red Hat Container Development Kit. To install CodeReady Studio, see: https://access.redhat.com/documentation/en-us/red_hat_jboss_developer_studio/12.0/html/installation_guide/ and to install Red Hat Container Development Kit, see https://access.redhat.com/documentation/en-us/red_hat_container_development_kit/3.4/html/getting_started_guide/.
  4. Clone the following projects and then import them into CodeReady Studio using the Import wizard (from File > Open Projects from File System).

  5. Set up the oc client binaries in the IDE from Window > Preferences, expand JBoss Tools, and then click OpenShift 3.

2.3.1. Installing the javascript modules

After you complete this section, a new node_modules folder is listed under the project in the Project Explorer view. This new folder indicates the download and installation of the required javascript modules.

Prerequisites

Procedure

  1. In the Project Explorer view of the IDE, expand frontend and right-click package.json.
  2. Click Run Asnpm Install to download and install the required javascript modules in the project.

2.3.2. Building the frontend microservice

frontend is a Docker based microservice that is not present on Docker Hub. It is the landing page for the application that you are building. The frontend microservice then calls other microservices (bonjour, in this case) and displays the results from these calls. This section walks you through steps to build the bonjour private image.

Prerequisites

Procedure

  1. In the Project Explorer view, expand frontend, right-click Dockerfile, and then click Run AsDocker Image Build.
  2. Set the configuration in the Docker Image Build Configuration window:

    1. In the Connection list, select Container Development Environment.
    2. In the Repository Name field, type demo/frontend.
  3. Click OK. The Docker-formatted Container image starts building against the Docker Daemon running in the Container Development Environment.

2.3.2.1. Deploying the frontend microservice

You can deploy the frontend microservice into an OpenShift Container Platform instance running on Red Hat Container Development Kit, in CodeReady Studio. After you build the frontend microservice, the Docker-formatted container image demo/frontend is available in the Docker Explorer view under the Container Development Environment option.

Prerequisites

Procedure

  1. In the Docker Explorer view of the IDE, select Container Development EnvironmentImages, right-click demo/frontend, and click Deploy to OpenShift.
  2. In the Deploy an Image window, click New.
  3. Create a new OpenShift project using the Create OpenShift Project window:

    1. In the Project Name field, type the name of the new project, demo.
    2. Optionally, complete the Display Name and Description fields.
    3. Click OK.
  4. In the Deploy an Image window, select the Push Image to Registry check box and click Next.
  5. In the Deployment Configuration & Scalability window, change the OS_PROJECT. Click OS_PROJECT to open the Environment Variable window and in the Value field, type demo (from step 5) and click OK.
  6. In the Deployment Configuration & Scalability window, click byn:[Next] and then click Finish. After the Docker-formatted Container image is pushed to the Docker Registry on OpenShift Container Platform, the Eclipse plugin generates all the required OpenShift Container Platform resources for the application to run.
  7. In the Deploy Image to OpenShift window, review the details of deploying the image and click OK.
  8. In the OpenShift Explorer view, expand the connection → {project name}ServicePod to see the Pod running. Right-click the pod and click Pod Log. The Console view shows the frontend service running. In the OpenShift Explorer view, expand the application, right-click the service, and click Show InWeb Browser. The frontend microservice in the Bonjour Service shows: Error getting value from service <microservice> This message confirms that the bonjour microservice is connected.

2.3.3. Connecting the frontend and bonjour microservices

The bonjour microservice is a node.js application that returns the string bonjour-de-<pod_ID>. You can build the bonjour microservice and then view it on the frontend microservice to validate it.

Prerequisites

Procedure

  1. In the Project Explorer view, expand bonjour and right-click package.json.
  2. Click Run As > npm Install.
  3. In the Project Explorer view, expand bonjour and right-click Dockerfile.
  4. Click Run As > Docker Image Build.
  5. Set the configuration in the Docker Image Build Configuration window:

    1. In the Connection list, select Container Development Environment.
    2. In the Repository Name field, type demo/bonjour.
  6. Click OK.

2.3.3.1. Deploying the bonjour microservice

You can deploy the Docker-formatted Container image either from the Docker Explorer view (as done in step 3 of the Building a Docker-formatted Container Image section) or, as done in this section, from the OpenShift Explorer view of the IDE.

Prerequisites

Procedure

  1. In the OpenShift Explorer view of the IDE, right-click the project (demo), and click Deploy Docker Image.
  2. To deploy the image using the Deploy an Image window:

    1. In the Docker Connection list, click the Docker connection.
    2. In the Image Name field, type demo/bonjour.
    3. Click the Push Image to Registry check box.
  3. Click Next.
  4. In the Deployment Configuration & Scalability window, click Next.
  5. In the Services and Routing Settings window, click Finish.
  6. In the Deploy Image to OpenShift window, click OK.

2.3.3.2. Scaling the pod

Scaling pods in OpenShift enables you to use resources effectively. This section walks you through steps to increase the number of pods by scaling them up.

Prerequisites

  • A pod that is up and running.

Procedure

  1. In the OpenShift Explorer view of the IDE, expand the application name (demo).
  2. Right-click the pod and click Pod Log to check if the pod is running.
  3. Navigate to the browser where you have the OpenShift application running and click Refresh Results. You will see a greeting from the bonjour service with a hostname that matches the pod name in the OpenShift Explorer view.
  4. In the OpenShift Explorer view, right-click the service and click ScaleUp. You now have two Pods running on OpenShift Container Platform.
  5. Navigate to the browser and click Refresh Results to see the service balancing between the two Pods.

2.3.4. Editing the bonjour microservice

The bonjour microservice is a node.js application that returns the string bonjour-de-<pod_ID>. This section walks you through editing this microservice.

Prerequisites

  • The bonjour microservice is available.

Procedure

  1. In the Project Explorer view, expand bonjour, and double-click bonjour.js to open it in the default editor.
  2. Find the following function:

    function say_bonjour(){
        Return “Bonjour de “ + os.hostname();
  3. Change the function as shown in the following example:

        function say_bonjour(){
        Return “Salut de “ + os.hostname();
  4. Save the file.

2.3.4.1. Viewing the edited bonjour microservice on the frontend microservice

You can use private images to build a local Docker image, not present on Docker Hub, on the Container Development Environment. The frontend and bonjour microservices are examples of such private images that are not present in Docker Hub. Then, you can deploy the private image to an OpenShift Container Platform instance, using CodeReady Studio.

Prerequisites

  • The bonjour microservice is available.

Procedure

  1. In the Project Explorer view, expand bonjour and right-click Dockerfile.
  2. Click Run AsDocker Image Build.
  3. Optional:, To edit the configuration, open the Run Configuration window.
  4. Wait for the Console view to show that the Docker-formatted container image is successfully pushed to the Docker daemon.
  5. In the Docker Explorer view, expand Container Development Environment > Images.
  6. Right-click the image and click Deploy to OpenShift.
  7. In the Deploy an Image window, click Push Image to Registry and then click Next.
  8. In the Deployment Configuration & Scalability window, click Finish. In the OpenShift Explorer view under bonjour, you can see that the pods are added running.
  9. Navigate to the browser and click Refresh Results. The new greeting displays.

2.4. Deploying the OpenShift Container Platform 3 resource

In this article, you use the s2i-spring-boot-cfx-jaxrs template in OpenShift Container Platform as an example to define resources for your OpenShift Container Platform application. Use similar steps to define resources for any other OpenShift Container Platform application.

Prerequisites

  1. Install Red Hat Container Development Kit (CDK) 3. For detailed instructions to install CDK 3, see https://access.redhat.com/documentation/en-us/red_hat_container_development_kit/3.0/html/installation_guide/.

2.4.1. Deploying the s2i-spring-boot-cfx-jaxrs template

Set up the IDE to work with CDK 3 as described in Using Container Development Kit Tooling in Red Hat CodeReady Studio. The new connection for OpenShift Container Platform is listed in the OpenShift Explorer view, making the s2i-spring-boot-cfx-jaxrs template available for use.

Procedure

To deploy the template, take the following steps:

  1. In the OpenShift Explorer view, expand the connection and right-click the {project name} and click New > Application.
  2. In the New OpenShift Application window:

    1. In the OpenShift project field, click the project that you want to create the new application in.
    2. In the Server application source tab, scroll through the list and locate and click s2i-spring-boot-cfx-jaxrs (quickstart, java, springboot, fis) - openshift.
  3. Click Finish.
  4. In the Create Application Summary window, click OK.
  5. In the Import OpenShift Application window in the Git Clone Location field, enter the location where you want to clone the template and click Finish.

    Figure 2.9. Selecting the s2i-spring-boot-cfx-jaxrs Template

    Selecting the s2i-spring-boot-cfx-jaxrs Template
  6. In the OpenShift Explorer view, expand the project, expand the s2i-spring-boot-cfx-jaxrs application and then right-click the s2i-spring-boot-cfx-jaxrs-1 build and click Build Log. The Console view shows the progress of the build. The Console view shows the latest: digest: sha256:{checksum} size: 9033 Push successful message.

2.4.2. Viewing the s2i-spring-boot-cfx-jaxrs application in the Web Console

This section is required optionally if you want to see the application running on the terminal. In absence of a service or route, you can view the application through the Pod tab in the web console.

Procedure

To view the application in the Pod:

  1. In the web console, click Applications > Pod and then click the s2i-spring-boot-cfx-jaxrs-1 pod.
  2. Click the Logs tab.
  3. In the logs, locate Jolokia: Agent started with URL https://172.17.0.6:8778/jolokia/ and copy the IP address (172.17.0.6, in this example).
  4. Click the Terminal tab.
  5. In the terminal, type the following command: curl http://{IP_address}:8080/services/helloservice/sayHello.

    Example: curl http://172.17.0.6:8080/services/helloservice/sayHello

  6. Press Enter.
  7. Append the next line with: curl http://172.17.0.6:8080/services/helloservice/sayHello/{your_name} and press Enter.

    Example: curl http://172.17.0.6:8080/services/helloservice/sayHello/John

    The Hello John, Welcome to CXF RS Spring Boot World!!! message appears, showing that application is up and running.

Figure 2.10. s2i-spring-boot-cfx-jaxrs Application in the Web Console

s2i-spring-boot-cfx-jaxrs Application in the Web Console

2.4.3. Defining services and routes using a JSON file

Use the services-route.json file to create the service for the s2i-spring-boot-cfx-jaxrs application and then create a route for the service. In this case the target port is 8080 where the route sends the request to the application.

Procedure

To define the resources, take the following steps:

  1. Copy the following content and paste it in a file, name the file services-routes.json, and save it.

    {
       "apiVersion": "v1",
       "kind": "List",
       "metadata": {},
       "items": [
          {
             "apiVersion": "v1",
             "kind": "Service",
             "metadata": {
                "name": "s2i-spring-boot-cxf-jaxrs"
             },
             "spec": {
                "ports": [
                   {
                      "name": "8080-tcp",
                      "protocol": "TCP",
                      "port": 8080,
                      "targetPort": 8080
                   },
                   {
                      "name": "8778-tcp",
                      "protocol": "TCP",
                      "port": 8778,
                      "targetPort": 8778
                   }
                ],
                "selector": {
                   "deploymentconfig": "s2i-spring-boot-cxf-jaxrs"
                }
             }
          },
          {
             "apiVersion": "v1",
             "kind": "Route",
             "metadata": {
                "name": "s2i-spring-boot-cxf-jaxrs"
             },
             "spec": {
                "to": {
                   "kind": "Service",
                   "name": "s2i-spring-boot-cxf-jaxrs",
                   "weight": 100
                },
                "port": {
                   "targetPort": "8080-tcp"
                },
                "wildcardPolicy": "None"
             }
          }
       ]
    }
  2. In the OpenShift Explorer view, right-click the project and click New > Resource.
  3. In the New OpenShift Resource window:

    1. In the OpenShift project list, click the project that you deployed the application to.
    2. In the Source pane, click Browse File System and locate and select the services-routes.json file.
    3. Click Finish.

      Figure 2.11. Selecting the service-routes.json File

      Selecting the service-routes.json File
  4. The Create Resource Summary window shows the details of the created service and route. Click OK.
  5. In the OpenShift Explorer view, right-click the project and click Show in > Web browser. The Whitelabel Error Page shows that the application has no explicit mapping.
  6. In the address bar, append the URL with services/helloservice/sayHello/. The URL should now look like: http://s2i-spring-boot-cxf-jaxrs-.{IP_address}.nip.io/services/helloservice/sayHello/.
  7. Press Enter. The web browser shows the Welcome to the CXF RS Spring Boot application, append /{name} to call the hello service message.
  8. At the end of the URL, append a name, for example: http://s2i-spring-boot-cxf-jaxrs-.{IP_address}.nip.io/services/helloservice/sayHello/John. The page displays the message: Hello John, Welcome to CXF RS Spring Boot World!!!

Figure 2.12. Viewing the s2i-spring-boot-cxf-jaxrs Application in the Web Browser

Viewing the s2i-spring-boot-cxf-jaxrs Application in the Web Browser