README.md

Deploy a Serverless Application that detects sentiment of text on Red Hat OpenShift

Introduction

This tutorial aims to demonstrate the serverless functionality on Red Hat OpenShift. In this tutorial you will deploy an application that is made of frontend and backend. The frontend is an angular application that consists of a simple form where the user submits a sentence which is then processed in the backend to later view the output of the sentiment. The backend is a python application based on Flask that uses TextBlob library to detect the sentiment in addition to Cloudant to save and fetch results.
The following Architecture diagram gives an overview of the project's components.

Prerequisites

For this tutorial you will need:

• Your own GitHub account
• Sign up for your IBM Cloud account – https://ibm.biz/BdfFXA
• Register for the live stream and access the replay – https://www.crowdcast.io/e/serverless-knative
• Red Hat OpenShift Cluster 4 on IBM Cloud. You can get it from
  • URL: https://oc-knative.mybluemix.net/
  • Key: oslab
• oc CLI (can be downloaded from this link or you can use it at http://shell.cloud.ibm.com/.

Estimated Time

It will take you around 30 minutes to complete this tutorial.

Steps

• Fork and Clone the GitHub repo
• Create Cloudant Database on IBM Cloud
• Install OpenShift Serverless Operator from OperatorHub
• Log into the OpenShift cluster from the CLI
• Create Project
• Add Environment Variables to your Backend Application
• Create Backend Application
• Edit your Frontend application
• Create your frontend application
• Test Your application and View logs
• View the Database

Fork and Clone the GitHub repo

• First thing you need to do is fork the GitHub repository to your own GitHub account so you can make your own changes later.
• Clone your fork of the repository.
  

git clone https://github.com/<YOUR-ACCOUNT-NAME>/serverless-sentiment

Create Cloudant Database on IBM Cloud

• In this tutorial we will be using Cloudant to save the JSON objects in the database. Create the service on IBM Cloud and name it 'cloudant-sentiment'.

Note: you may need to create the Cloudant database service using your own IBM Cloud account, not the 'Advowork' account.

• Once created, go to the newly provisioned service and create credentials from 'Service Credentials' tab, make sure the role is 'Manager'. You will be using these credentials in your code at a later step.
• Next, go to Dashboard under Manage tab and click 'Launch Dashboard'.
  
• Then create the Database as shown in the image. Name it 'sample', select Non-parttioned, and click Create.
• The sample database opens automatically. Leave the database empty for now. At a later step, you will create the documents through the backend.

Install OpenShift Serverless from OperatorHub

• From the web console, you can install the OpenShift Serverless Operator using the OperatorHub tool in your OpenShift dashboard. Use Update Channel version 4.5. If necessary, create a new project named knative-serving to install into.

Login from the CLI

• Go to the web console and click on your username at the top right then 'Copy Login Command', then display the token and copy the oc login command in your terminal.
  
  
• Create knative-serving project to create Knative Serving Service.

oc new-project knative-serving

• From the web console, go back to the Serverless Operator and open details page, make sure you are in the knative-serving namespace. Click 'create instance' for Knative Serving.
• You will be redirected to a new page 'Create Knative Serving', make sure its name is 'knative-serving', there's no need to make any changes, just click create.
• Once created, you will notice that it has been added under Knative Serving.
• Check if Knative Serving was installed successfully. The value of Ready must equal True before you can proceed.

oc get knativeserving.operator.knative.dev/knative-serving -n knative-serving --template='{{range .status.conditions}}{{printf "%s=%s\n" .type .status}}{{end}}'

Create Project

• From the CLI, create a project and name it 'sentiment-project' as shown in the following command.
  

oc new-project sentiment-project

• Make sure that you are in the correct project using the following command.
  

oc project sentiment-project

Add Environment Variables to your Backend Application

• In this step, you will be using secrets to pass your Cloudant service credentials to the applications. Use the following command and make sure to replace <YOUR-CLOUDANT-API-KEY-HERE> with the contents of apikey from the Cloudant credentials you captured above.

oc create secret generic secret --from-literal=apikey=<YOUR-CLOUDANT-API-KEY-HERE> -n sentiment-project

• Add the URL of your Cloudant instance as a configmap using the following command. Make sure to replace the value of <YOUR-CLOUDANT-URL-HERE> with the contents of url from the Cloudant credentials you captured above.

oc create configmap my-config --from-literal=url=<YOUR-CLOUDANT-URL-HERE> -n sentiment-project

Create Backend Application

• In this step, you will be creating the backend application through the service.yaml file that's in the backend directory in the github repo. Use the following command.
  

oc apply -f https://raw.githubusercontent.com/nerdingitout/serverless-sentiment/main/backend/service.yaml

The yaml file contains the following information. Make sure that the namespace matches the name of the project you created.

apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: sentiment 
  namespace: sentiment-project 
spec:
  template:
    spec:
      containers:
        - image: s4saif/senti:v7

• Once created, you can find the newly deployed application on the topology as shown below. Keep in mind that it is a serverless application so the pods will be terminated if you aren't accessing it which means the circle around the pod will be colored in white. If you try to access the application externally, you will notice new pods have been created, which will change the color to dark blue. You might notice that the application is inaccessible, but don't worry much, we will be using the it with the frontend application.
• Make sure to copy the route of the backend, because you will be using it to make an API call from your frontend application. To view the route of the backend from the CLI, write the following command.

oc get route.serving.knative.dev

Edit your Frontend application

• In your forked repo, you will need to replace the URL in the typescript code. Open ./frontend/src/app/frontend-app/frontend-app.component.ts in your preferred editor. In line 22, replace <ADD-BACKEND-URL-HERE> in the onSubmit() function with the URL of the backend that you copied earlier.
  

  onSubmit(){
    this.apiSentiment='';
    // Simple POST request with a JSON body and response type <any>, replace backend url in the api post request
    this.http.post<any>('<ADD-BACKEND-URL-HERE>'+'/api/post_sentiment', { text: this.Sentence.value }).subscribe(data => {
      this.apiSentimentNum = data.sentiment;
      this.apiText = data.text;
    .
    .
    .
    })
  }

• In your forked repo, you will need to replace the URL in your build configuration. Open ./frontend/yamls/buildconfig.yaml and replace the value of uri in line 18 with the URL of your forked GitHub repo as shown below.

spec:
  output:
    to:
      kind: ImageStreamTag
      name: angular:latest
  runPolicy: Serial
  source:
    git:
      ref: main
      uri: <YOUR-GITHUB-REPO-URL-HERE>
    type: Git

Create your frontend application

• To create the frontend application, in this tutorial, use the oc apply command on the files in the ./frontend/yamls/ directory. Use the following command for your local directory.

cd frontend
oc apply -f ./yamls/

Alternatively, if you committed and pushed your changes to the two files to GitHub, you can use the following commands with your URL (make sure to replace the username).

oc apply -f https://raw.githubusercontent.com/<YOUR-USERNAME>/serverless-sentiment/main/frontend/yamls/buildconfig.yaml

oc apply -f https://raw.githubusercontent.com/<YOUR-USERNAME>/serverless-sentiment/main/frontend/yamls/dc.yaml

oc apply -f https://raw.githubusercontent.com/<YOUR-USERNAME>/serverless-sentiment/main/frontend/yamls/is.yaml

oc apply -f https://raw.githubusercontent.com/<YOUR-USERNAME>/serverless-sentiment/main/frontend/yamls/service.yaml

• Expose your frontend application to access it externally

oc expose service angular

• Get the route of your frontend application

oc get routes

Test Your application and View logs

• Open the frontend application from the external route and submit messages in the form.
• Use the oc get pods command to see the pods from the serverless application get created and destroyed. Run it multiple times and notice changes in how the application scales up and down everytime you submit your sentences through the frontend application.

oc get pods

• You can also view

oc get all -n sentiment-project

View the Database

Summary

In this tutorial, you performed several tasks to build an entire appliction that makes use of Knative serverless functionality. On Red Hat OpenShift, you can build serverless applications through the Serverless Operator that is based on the Knative project. In this tutorial, you used one of the main components of Knative, which is Knative Serving. Knative Serving autoscales your application on demand and scales it down to zero when it's not used, and through this tutorial you were able to learn how it works.