IBM Developer

Learning Path

Exploring Red Hat OpenShift on Power Systems Virtual Server

Tutorial

Deploy a 3-tier application on Red Hat OpenShift

Use modern hybrid cloud tools and techniques to rapidly deploy a new multi-tier application in a flexible and secure way

By

Deepak C Shetty,

Andrew Laidlaw

Introduction

In this tutorial, we will show you how to use the graphical console provided by Red Hat OpenShift Container Platform to rapidly deploy a 3-tier application in a hybrid cloud environment. Our application includes:

  • A MariaDB database at the back end to hold our application data
  • An application programming interface (API) tier based on Node.js code that connects to the database and provides some business logic
  • A web facing front end also based on Node.js code that our users interact with

This tutorial is designed to be simple to follow as you learn the concepts and terminology of the OpenShift Container Platform, and so only uses the graphical interface of OpenShift Container Platform (also known as the web console). This gives a visual representation of the application components and does not require the use of the command-line interfaces or to create configuration files using languages like YAML.

By using the graphical tools, you will be able to see how the different components of a hybrid cloud application are deployed and connected together. You can also experience how easy it is to connect separate microservices as the platform removes some of the complexity you would experience in a more traditional virtual machine (VM)-based environment. This includes the networking setup and routing required to connect components together, as well as the security benefits of disconnecting the database access credentials from the user.

The application we deploy is called “Quote of the Day” (QOD).

Once deployed in full, this application provides you with a simple webpage with the ability to get a daily quote which is different each day, or a random quote from our database of quotes.

The source code for the following three tiers of the QOD application is hosted in GitHub:

After the deployment is complete, our 3-tier application looks as shown in the following figure.

Figure 1

Prerequisites

Before you deploy this 3-tier application, make sure that the following prerequisites are fulfilled:

  • Access to a Red Hat OpenShift Container Platform cluster. I am using OpenShift version 4.10.xx on IBM Power Virtual Server. The steps mentioned in this tutorial should work on any other OpenShift platform as well, although some of the GUI screens or dialog boxes might look slightly different.
  • If you do not have access to a Red Hat OpenShift Container Platform cluster, you can access it through the Red Hat developer sandbox. Alternatively, you could deploy your own OpenShift Container Platform cluster on IBM Power Virtual Server.

Estimated time

1 hour

Steps

  1. Create a new project
  2. Deploy the database (DB) tier
    2a. Test DB tier (optional)
  3. Deploy the API tier
    3a. Test the API service – It doesn’t work
    3b. Inject environment variables using a secret
    3c. Test the API service – It works!
    3d. Create a HTTP or HTTPS (as applicable) route for API test automation (optional)
  4. Deploy the web tier
    4a. Inject environment variables during pod creation

1. Create a new project

  1. Create a new OpenShift project where we will deploy our 3-tier application. In the Administrator view, click Projects and then click Create Project.

    figure 2

    View larger image

  2. In the Create Project dialog box, enter a name for your new project and click Create. In my case I am creating a new project, named tutorial.

    figure 3

2. Deploy the database (DB) tier

In this section, we will deploy the database tier to host a MariaDB database named qod and it has tables such as quotes, genres, and authors which will be pre-populated with quotes, the different genres of the quotes, and the author of the quotes respectively.

  1. Switch to Developer persona, make sure your project is selected (‘tutorial’ in my case) and click +Add.

    figure 4

  2. Click Import from Git.

    figure 5

    Note: On older versions of OpenShift, there may be a separate From Dockerfile option, which should be chosen instead.

  3. In the Import from Git dialog box, fill in the following fields with the given values:

    • Git Repo URL: https://github.com/dpkshetty/qod-db
      (Press Tab and wait for it to show ‘Validated’)
      OpenShift will examine the Git repo and auto-detect the import strategy as Dockerfile, due to the Dockerfile present in the qod-db repository.
    • Application Name: QOD
    • Name: qod-db (This name is used for all the resources that OpenShift creates, including the DNS entry for accessing the DB microservice)
    • Keep Deployment (the default) selected.
    • Target port: 3306 (refer to the README.md file to find the port on which the DB service is designed to listen for connections).
    • Clear the Create a route to the Application checkbox.
      Note: We don’t need to expose the DB service to the outside world - hence a route to the DB service is not needed. It will only be accessed from inside the cluster and not having an external route makes the DB service more secure from external attacks too!).
    • Click Create.

    Figure 6 Figure 7 Figure 8

    What happens next is that OpenShift will fetch the source code from the GitHub repository, use the Dockerfile to create a Docker image, save that image into the internal OpenShift image registry, and create a pod (also known as application) from that Docker image, which will be our DB microservice application (our back-end tier). The application will instantiate a MariaDB instance, and create a database named qod which will have three tables named quotes, genres, and authors, all pre-populated with different quotes, genres, and authors respectively.

  4. You will be taken back to the Topology page. Click D qod-db that represents the deployment object. Wait for the build process to finish and the pod to be in the Running state. This pod is our DB microservice available on port 3306 (as seen from the service information) and the absence of a route ensures that the service cannot be accessed from outside the cluster.

    Note: If you click the icon at the lower left side of the large circle while the build is running, you can see the logs of the build process as it is run.

    Figure 9

Congratulations! You have successfully deployed the DB tier, having a DB named qod and pre-populated with quotes, authors, and genre tables.

2a. Test DB tier (optional)

For those who want to go one step deeper and check if the database and the different tables were created successfully, we can get inside the Pod and use the MySQL CLI to inspect. If you check the Dockerfile, the DB credentials are hard-coded in there, and so we will use those to access the DB and its tables.

  1. Click View Logs to go to the Pod view, then click Terminal to get inside the pod and run the MySQL CLI as shown in the following screen captures.

    Figure 10 Figure 11 Figure 12

    The MySQL CLI (shown in the above screen capture) uses username as user and password as pass (taken from the Dockerfile) and the hostname as qod-db (which is same as the name that was used when deploying the DB service).

    Figure 12a Figure 12b

  2. Notice that authors, genres, and quotes tables are pre-created.

  3. If required, run any SQL command to query these tables as shown in the following screen capture.

    Figure 13

    Notice that the SQL query command lists around 500 rows, each row having a different quote.

    Figure 14

    View larger image

3. Deploy the API tier

The API tier provides the business logic layer (in the simplest sense) for the application. It receives the request from the user (typically from the front-end web tier), processes the request by running SQL queries against the DB, and provides the response back to the user through the web interface. In the case of our QOD application, the API tier is designed to process the requests for daily and random quotes by forming the right SQL query and retrieving the quotes from the database using the qod-db microservice.

  1. Click +Add and then click Import from Git.

    Figure 15

  2. In the Import from Git dialog box, enter the following values in the required fields:

    • Git Repo URL: https://github.com/dpkshetty/qod-api
      (Press Tab and wait for it to show Validated)
      OpenShift will examine the Git repo and autodetect the import strategy as Dockerfile, due to the Dockerfile present in the qod-api repo.

      Note: Alternatively, You can also choose your own build strategy, including the option to build an image directly from the source code. This uses the Red Hat Source to Image capability and removes the requirement for developers to write their own Dockerfiles.

    • Application Name: select QOD from the existing application group using the drop-down list.
    • Name: qod-api (This name is used for all the resources that OpenShift creates, including the DNS entry for accessing the API microservice).
    • Keep Deployment (the default) selected.
    • Target port: 8080 (The README.md file states the port at which the API service is designed to run).

    • Clear the Create a route to the Application checkbox.

      NOTE: We don’t need to expose the API service to the outside world, and hence a route to the API service is not needed. It will only be accessed from inside the cluster and not having an external route makes the API service more secure from external attacks too!

  3. Click Create.

    Figure 16 Figure 17 Figure 18

    What happens next is that OpenShift will fetch the source code from the Git repo, use the Dockerfile to create a Docker image, save that image into OpenShift internal image registry, and create a pod (also known as application) from that Docker image, which will be our API microservice application, our middle tier.

  4. You will be taken back to the Topology page. Click D qod-api which represents the deployment object. Wait for the build process to finish and the pod to be in Running state. This pod is our API microservice available on port 8080 (as seen from the service information) and the absence of a route ensures the service cannot be accessed from outside the cluster.

    Figure 19

3a. Test the API service – It doesn’t work

  1. Let’s quickly check if the API service works as expected. Click the qod-api pod to enter the Pod view and then click Terminal. This will log you inside the API service pod and present you with a Linux shell.

    Figure 20 Figure 21

  2. The API service exposes many REST API endpoints, one of them being the /daily endpoint. If interested, refer to the code. This endpoint returns back the quote of the day based on today’s date. We know that the API service is running on port 8080. Use the curl utility to test if the /daily endpoint works as expected. Type the following command in the terminal and check the response. It throws an error!

    curl http://localhost:8080/daily

    Figure 22

    View larger image

    The error is expected because the API service needs to communicate with the DB service in order to process incoming requests. We haven’t provided any configuration information to the API service instructing it on how to connect to the DB service. If you look at the API service app.js code, you will see that it needs the following environment variables to be provided in order for it to connect to the DB service. The same is mentioned in the API service README file too!

    • DB_HOST
    • DB_USER
    • DB_PASS

3b. Inject environment variables using a secret

OpenShift provides a neat way to inject environment variables into a Pod, using the Secret functionality. Let’s create a secret and inject it into the API pod.

  1. Click Secrets on the left navigation menu and click Create. Then click Key/Value secret.

    Figure 23

    View larger image

    Figure 24

    View larger image

  1. On the create Key/Value secret page, enter the following values for the required fields:

    • Secret Name: qod-db-credentials
    • Key: DB_HOST
    • Value: qod-db
    • Click +Add key/value to add a new entry and enter the following values:
      • Key: DB_USER
      • Value: user
    • Click +Add key/value to add a new entry and enter the following values:
      • Key: DB_PASS
      • Value: pass
    • Click Create.

    Note: These are the environment variables needed by the API service to access the DB service as documented in the README.md file.

    Figure 25

  2. Click Add Secret to workload. On the Add secret to workload page, select the qod-api deployment option from the drop-down List, select the Environment variables option and click Save.

    Figure 26 Figure 27

    What happens next is that OpenShift will restart the qod-api pod with these environment variables injected, and this allows the API service to communicate with the DB service.

  3. Click Topology on the left navigation pane, and then click D qod-api to open the Resources tab and wait for new pod to be in the Running state.

    Figure 28

    View larger image

3c. Test the API service – It works!

  1. Click the qod-api pod to enter the pod view and then click Terminal. This will log you inside the API service pod and opens a Linux shell.

    Figure 29 Figure 30

  2. Run the curl command, and this time, it should run successfully and return us the daily quote, along with its quote ID, author, and genre information.

    curl http://localhost:8080/daily

    Figure 31

    Congratulations! You have successfully deployed the API tier and linked it with the DB tier using secrets to pass the DB credentials to the API tier. The output of the API service is in the JSON format which is not very user-friendly. This is where the web tier (covered later in the tutorial) comes into play, which consumes the API service’s output and presents it in an intuitive user-friendly way.

3d. Create a HTTP or HTTPS (as applicable) route for API test automation (optional)

In the previous steps we accessed the `/daily` REST endpoint by getting inside the pod. While this is fine for a quick check, it is not automation friendly as it involves many GUI steps. In a real world scenario, we would want to test the API layer using automated test scripts which can then be part of the DevOps build, test, and release workflow.

For testing purposes, we can create a HTTP or HTTPS (as applicable for your cluster) route for the API service such that its accessible external to the cluster. We can then use the route URL as a target in our API test automation scripts.

  1. To create a route for API service, switch to the Administrator view and click Networking –> Routes. Then click Create Route.

    Figure 32

    View larger image

  1. On the Create Route page, fill in the following values in the required fields:

    • Name: qod-api-route
    • Service: qod-api
    • Target port: 8080

    Note: My cluster mandates to use the HTTPS secure routes. You can opt to skip the following steps if this is not applicable to your cluster. You will be creating a HTTP (unsecure) route.

    Figure 33

    • Select the Secure Route checkbox (optional).
    • Specify the values for the following options:
      • TLS Termination: Edge (optional)
      • Insecure Traffic: None (optional)

    • Retain the default values for the remaining fields and click Create.

      Figure 34

  2. On the Route details page, click the location URL (that begins with https://... in my case). A new browser tab opens and displays the API server version.

    Figure 35 Figure 36

  3. Similarly, you can edit the URL and replace /version with /daily or /random to get daily and random quotes respectively.

    Figure 37

    View larger image

    Figure 38

    View larger image

  4. Optionally, retrieve a particular quote or genre by its ID too.

    Figure 39

    View larger image

    Figure 40

    Congratulations! You have successfully added a route to the API service and made its REST endpoints accessible from outside the cluster. This method can be used to run any API-level test automation after which the route can be deleted to secure the API service from outside attacks.

    In case you need to remove the route, in the Administrator view, click Routes and search for qod-api-route (if needed).

    Figure 41

  5. Click the vertical ellipsis icon (with three dots), click Delete Route, and then click Delete to delete the route.

    Figure 42

    View larger image

    Figure 43

    View larger image

    Figure 44

4. Deploy the web tier

In this section, we will deploy our front-end web tier. The web tier will have an external route because it is the service that the users interact with. Depending on the user request, it either displays the daily quote or a random quote.

  1. Switch to the Developer persona, make sure your project is selected (tutorial in my case), and click +Add.

    Figure 45

  2. Click Import from Git.

    Figure 46

  3. On the Import from Git page, fill the required values in the following fields:

    • Git Repo URL: https://github.com/dpkshetty/qod-web
      (Press Tab and wait for it to show Validated)
      OpenShift will examine the Git repo and auto-detect the import strategy as Dockerfile, because the Dockerfile is present in the qod-db repository.
    • Application: QOD
    • Name: qod-web (this name is used for all the resources that OpenShift creates, including the DNS entry for accessing the web microservice)
    • Keep Deployment (the default) selected
    • Target port: 8080 (The README.md file states the port at which the web service is designed to run)

    • Select the Create a route to the Application checkbox.

      Note: My cluster mandates HTTPS routes. If that is not the case for your cluster, you can skip the following steps used for creating a HTTPS route.

    • Select the Secure Route checkbox, and enter the following values for the other fields:
      • TLS Termination: Edge
      • Insecure Traffic: None

    • Retain the default values for the remaining fields.

      Note: Do not click Create yet! Continue with the next step.

      Figure 47 Figure 48 Figure 48a Figure 49

4a. Inject environment variables during pod creation

Like we did for the API tier, the web tier needs to be linked with the API tier for it to work successfully. From the README.md file, we can see that we need to define the QOD_API_URL environment variable. OpenShift provide a way to specify the environment variables during pod creation.

  1. Scroll down to the bottom of the form and click Deployment. which will bring up the environment variables option.

    Figure 50 Figure 51

  2. On the Deployment page, set the following values for the environment variable:

    • Name: QOD_API_URL
    • Value: http://qod-api:8080 (do not use a trailing slash at the end)

    Then, click Create.

    Figure 52

    What happens next is that OpenShift will fetch the source code from the Git repository, use the Dockerfile to create a Docker image, save that image into OpenShift internal image registry, and create a pod (also known as application) from that Docker image, which will be our web microservice application (our front-end tier). The HTTPS (or HTTP, as applicable) URL will serve our web application for users.

  3. On the Topology page, click D qod-web representing the deployment object. Wait for the build to finish and the pod to be in Running state. This pod is our web microservice available on port 8080 (as seen from the service information) and the external HTTPS (or HTTP, as applicable) route has been created.

    Figure 53 Figure 54

  4. Click the HTTPS (or HTTP, as applicable for your cluster) URL and notice that your web application is running successfully and displaying the quote of the day.

    Figure 55 Figure 56

  5. Click Random Quote to display a random quote picked from the DB each time.

    Figure 57 Figure 58 Figure 59

    This proves that the QOD_API_URL environment variable we initialized during the pod creation process using the Deployment field (under advanced options) worked and the web tier is able to communicate with the API tier successfully!

    Congratulations! You have successfully deployed the front-end web tier of your application and linked it with the API tier using environment variables and exposed an external route/URL for users to access your application.

  6. (Optional) OpenShift provides visual connectors in the Topology view to depict how the different services connect with each other. In the Topology view, hover over each service until you see an arrow pop up and drag it to connect to the other service. As shown in the following screen capture, it helps to better visualize the flow of traffic across the different services making up your application.

    Figure 60

Summary

In this tutorial, you have learnt how to deploy a simple 3-tier application in Red Hat OpenShift Container Platform using stand-alone microservices for each of the tiers. You have also learnt how to pass the credentials of a microservice to another microservice using secrets, and how to link the microservices using environment variables. You also learnt how to secure the 3-tier application by exposing only the web tier to the outside world while keep the API and database tiers secure. Most importantly, you have seen how quickly you can get a new application deployed within the OpenShift environment, without the need to set up new virtual machines, and networking or development environments, and thus speeding up the development duration and reducing the administrative burden.

There might be circumstances where you want to automate the build and deploy of your individual application tiers in response to a Github code change to achieve DevOps style CI/CD automation for your application. In such cases, refer to the Enable continuous deployment using Red Hat OpenShift S2I and GitHub webhooks tutorial to learn how to use GitHub webhooks with OpenShift to create an automated workflow. In case your OpenShift cluster is behind an enterprise firewall, you can refer to the Deliver webhooks without worrying about firewalls tutorial to learn how to get GitHub webhooks work through the firewall.

Take the next step

Join the Power Developer eXchange Community (PDeX). PDeX is a place for anyone interested in developing open source apps on IBM Power. Whether you're new to Power or a seasoned expert, we invite you to join and begin exchanging ideas, sharing experiences, and collaborating with other members today!


08 July 2022

Legend
LikeSave

Previous

Build multi-architecture container images using GitLab

Next

Install IBM Cloud Pak for Data 5.0 on Red Hat OpenShift Container Platform 4.14 on IBM Power Virtual Server