Scalable web application on Red Hat OpenShift on IBM Cloud

Configure CLI

In this step, you'll configure oc to point to your newly created cluster. The Red Hat OpenShift on IBM Cloud Container Platform CLI exposes commands for managing your applications, as well as lower level tools to interact with each component of your system. The CLI is available using the oc command.

1. When the cluster is ready, click on OpenShift web console to open the console.
2. On the web console, from the dropdown menu in the upper right of the page, click Copy Login Command and then click the Display Token link.
3. Copy the text found under Log in with this token.
4. Once logged-in using the oc login command, run the command below to see all the namespaces in your cluster.

   oc get ns
   

Create a project

A Kubernetes namespace provides a mechanism to scope resources in a cluster. In Red Hat OpenShift on IBM Cloud, a project is a Kubernetes namespace with additional annotations.

1. Define an environment variable named MYPROJECT and set the application name by replacing <your-initials> with your own initials :

   export MYPROJECT=<your-initials>-openshiftapp
   

2. Create a new project.

   oc new-project $MYPROJECT
   

   After creating a project using the above command, you are automatically switched to that project and all commands that follow run in the context of that project. If you need to switch projects or go back into that project at a later stage, use the oc project $MYPROJECT command.

Deploy an application

With the oc new-app command you can create applications from source code in a local or remote Git repository.

1. Create an application using the docker build strategy to build a container image from a Dockerfile in the repo. You are setting the application name to the project name for simplicity.

   oc new-app https://github.com/IBM-Cloud/openshift-node-app --name=$MYPROJECT --strategy=docker --as-deployment-config
   

   If a Jenkins file exists in the root or specified context directory of the source repository when creating a new application, Red Hat OpenShift on IBM Cloud generates a pipeline build strategy. Otherwise, it generates a source build strategy. You can always override the build strategy by setting the --strategy flag.

2. To check the builder container image creation and pushing to the internal Red Hat OpenShift on IBM Cloud Container Registry (OCR), run the command below.

   oc logs -f buildconfig/$MYPROJECT
   

   Your cluster is set up with the internal Red Hat OpenShift on IBM Cloud Container Registry so that Red Hat OpenShift on IBM Cloud can automatically build, deploy, and manage your application lifecycle from within the cluster.

3. Wait until the build is successful and the image is pushed. You can check the status of deployment and service by running the command below.

   oc status
   

Access the application through IBM provided domain

To access the application, you need to create a route. A route announces your service to the world.

1. Create a route by running the command below in a terminal.

   oc expose service/$MYPROJECT
   

2. You can access the application through an IBM provided domain. Run the command below to obtain the URL.

   oc get route/$MYPROJECT
   

3. Copy the value for the hostname under HOST/PORT value and paste the URL in a browser to see your application in action at http://<hostname>. Make sure to use http in the URL.

4. Set an environment variable pointing to the hostname.

   export HOST=<hostname>
   

Secure the default IBM provided domain route

1. To create a secured HTTPS route encrypted with the default certificate for Red Hat OpenShift on IBM Cloud, you can use the create route command.

   oc create route edge $MYPROJECT-https --service=$MYPROJECT --port=3000
   

2. For the HTTPS HOST URL, run oc get routes. Copy and paste the URL with HTTPS(https://<HOST>) next to the route $MYPROJECT-https in a browser. This time you can use https in the URL.

Manual scaling

1. You can achieve manual scaling of your pods with oc scale command. The command sets a new size for a deployment configuration or replication controller

   oc scale dc/$MYPROJECT --replicas=2
   

2. You can see a new pod being provisioned by running oc get pods command.
3. Rerun the Monitoring step to see the updated metrics.

Autoscaling

You can use a horizontal pod autoscaler (HPA) to specify how Red Hat OpenShift on IBM Cloud should automatically increase or decrease the scale of a deployment configuration(dc) or replication controller(rc), based on metrics collected from the pods that belong to that dc or rc.

1. Before you can setup autoscaling for your pods, you first need to set resource limits on the pods running in the cluster. Limits allows you to choose the minimum and maximum CPU and memory usage for a pod. You can set the limits and requests on a container using oc set resources command.

   oc set resources dc/$MYPROJECT --limits=cpu=250m,memory=512Mi --requests=cpu=100m,memory=256Mi
   

   To verify, run oc describe dc/$MYPROJECT and look for Limits and Requests.
2. To create an autoscaler, you need to run the oc autoscale command with the lower(min) and upper(max) limits for the number of pods that can be set by the autoscaler and the target average CPU utilization (represented as a percent of requested CPU) over all the pods. For testing, let's set --cpu-percent to 5%.

   oc autoscale dc/$MYPROJECT \
    --min=1 \
    --max=5 \
    --cpu-percent=5
   

3. Rerun the Monitoring step to generate load on the application.
4. You can see new pods being provisioned by running oc get pods --watch command or by looking at the application in the web console.
5. Remove the auto scaler:

   oc delete hpa/$MYPROJECT
   

Clone a sample application

In this section, you will clone a GitHub repository which comes with a template file and a shell script to generate a yaml file from your previously created environment variables. The generated file is used to build a container image, push the image to the private container registry and deploy a new application.

1. In a terminal, run the command below to clone the GitHub repository to your machine:

   git clone https://github.com/IBM-Cloud/openshift-node-app
   

2. Change to the application directory:

   cd openshift-node-app
   

Update the BuildConfig and Push the builder image to Container Registry

In this step, you run a script to update the sections of the openshift.template.yaml file and generate a new yaml file pointing to your Container Registry namespace.

1. Run the below bash script to update the placeholders in the openshift.template.yaml file and to generate openshift_private_registry.yaml file.

   ./generate_yaml.sh use_private_registry
   

2. Run the export command from the output to set the existing MYPROJECT environment variable with the new application name. Run echo $MYPROJECT to see the new application name.

3. Optionally, check the generated openshift_private_registry.yaml file to see if all the placeholders are updated with the respective environment variables. The below are 3 places to do a quick check. You can skip to the next section.

4. Optional Locate the ImageStream object with the name attribute set to your project ($MYPROJECT) and check whether the placeholders $MYREGISTRY,$MYNAMESPACE, and $MYPROJECT under dockerImageRepository definition of spec are updated

   -
   apiVersion: image.openshift.io/v1
   kind: ImageStream
   metadata:
     annotations:
       openshift.io/generated-by: OpenShiftNewApp
     creationTimestamp: null
     labels:
       app: $MYPROJECT
       app.kubernetes.io/component: $MYPROJECT
       app.kubernetes.io/instance: $MYPROJECT
     name: $MYPROJECT
   spec:
     dockerImageRepository: $MYREGISTRY/$MYNAMESPACE/$MYPROJECT
     lookupPolicy:
       local: false
   status:
       dockerImageRepository: ""
   

   An image stream and its associated tags provide an abstraction for referencing container images from within Red Hat OpenShift on IBM Cloud Container Platform

5. Optional Check the spec under BuildConfig section for the output set to kind DockerImage and placeholders under name updated.

   spec:
     nodeSelector: null
     output:
       to:
         kind: DockerImage
         name: $MYREGISTRY/$MYNAMESPACE/$MYPROJECT:latest
       pushSecret:
         name: push-secret
   

   A build is the process of transforming input parameters into a resulting object. Most often, the process is used to transform input parameters or source code into a runnable image. A BuildConfig object is the definition of the entire build process.

6. Optional Search for containers, check the image and name

   containers:
   - image: $MYREGISTRY/$MYNAMESPACE/$MYPROJECT:latest
     name: $MYPROJECT
   

7. If updated, save the YAML file.

Deploy the application using the IBM Cloud Container Registry

In this section, you will deploy the application to the cluster using the generated openshift_private_registry.yaml file. Once deployed, you will access the application by creating a route.

1. Create a new OpenShift application along with a buildconfig(bc), deploymentconfig(dc), service(svc), imagestream(is) using the updated yaml.

   oc apply -f openshift_private_registry.yaml
   

2. To check the builder container image creation and pushing to the Container Registry, run the command below.

   oc logs -f bc/$PRIVREG
   

   In the logs, you should see the below message if the container image is pushed to the private container registry.

   Pushing image us.icr.io/mods15/vmac-openshift-app-registry:latest ...
   Getting image source signatures
   Copying blob sha256:9d038e1c7afbe92c29313557c02110e8fb796818ebb78441c68929381103a94b
   Copying blob sha256:61c671f49591a059c9b6728a9f84c16f5b00126470112ee9c9f9e01dbbfcc3ea
   Copying blob sha256:e2787650308235c87eff7d2b88c3ab217e84b74a3fa9696103bd46bb99068c7a
   Copying blob sha256:dcef409117430ed9906a59ad0a3ea0752061fbf8a9e544f4edd77667a25d85ae
   Copying blob sha256:a1f889dd610c6510c7fc091a51c247463f3cc9a7c67bdc397c9632168808f7d2
   Copying blob sha256:bd278801acd18ada10f43b732113a6fffc163011862ea6cde729f8dc59e64222
   Copying blob sha256:2d6c03ed5d15be86cdef7d9c0c9fea40a3f6b89662bca59680d037074f52bb38
   Copying blob sha256:fa2ef7f80d6fc9543f6eb472846931ed1cec2b5f776d1b67bcb1b9942e1a947e
   Copying blob sha256:ff5a4e4d3690ccc931900b63714d326cc53a58e644f8d0a4f06bf8c62f11c5c7
   Copying config sha256:01aa1ebb7be74529867106100c4e699ca2ae87f8242460771527f772e6a3d174
   Writing manifest to image destination
   Storing signatures
   Successfully pushed us.icr.io/mods15/vmac-openshift-app-registry@sha256:6847b889397704b9fb8c3122c84b505c3dc5f99a0669fb69f534d3504eec385d
   Push successful
   

3. You can check the status of deployment and service.

   oc status
   

4. Manually import the latest image stream to ensure the deployment takes place as soon as possible.

   oc import-image $PRIVREG
   

   You can also use the command if the deployment is taking more time, Refer to this link for more info.

5. Expose the service to create a new route.

   oc expose service/$PRIVREG
   

6. You can access the application through IBM provided domain. Run the command below to obtain the URL.

   oc get route/$PRIVREG
   

7. Copy the value for the hostname under HOST/PORT value and paste the URL in a browser to see your application in action at http://<hostname>. Make sure to use http in the URL.

   You should see the same application exposed on a different route and deployed using the container image stored in a private container registry.

Create a Git deploy token

In this section, you will create a Git deploy token to allow read-only access to your repository.

To generate a deploy token:

1. In the navigation panel of the Git repo page, click Settings > Repository.
2. Click on Expand next to Deploy Tokens.
   1. In the Name filed, type foropenshift and then select read_repository under Scopes. Finally click on Create deploy token.
   2. Save the generated username and password for future reference.
3. In the navigation panel, click on Project overview then click on Clone and copy Clone with HTTPS URL. Save the URL for future reference.
4. Define environment variables for the username, password and private Git repo URL to be used with the YAML file later in the tutorial

   export GIT_TOKEN_USERNAME=<PRIVATE_GIT_DEPLOY_TOKEN_USERNAME>
   export GIT_TOKEN_PASSWORD=<PRIVATE_GIT_DEPLOY_TOKEN_PASSWORD>
   export REPO_URL=<PRIVATE_GIT_REPO_URL>
   

Deploy a new application using the private registry and the code from private repository

1. Run the below bash script to update the placeholders in the openshift.template.yaml file and to generate openshift_private_repository.yaml file.

   ./generate_yaml.sh use_private_repository
   

2. Run the export command from the output to set the existing MYPROJECT environment variable with new project name.

3. Additional to the private container registry placeholders, the script will also replace the REPO_URL under BuildConfig spec with the the environment variables you set in the above step,

    source:
      git:
        uri: $REPO_URL
      type: Git
   

4. Create a new openshift application along with a buildconfig(bc), deploymentconfig(dc), service(svc), imagestream(is) using the updated yaml

   oc apply -f openshift_private_repository.yaml
   

5. You can check the builder logs.

   oc logs -f bc/$PRIVREPO
   

6. You can check the status of deployment and service using.

   oc status
   

7. Manually import the latest image stream to ensure the deployment takes place as soon as possible.

   oc import-image $PRIVREPO
   

8. Expose the service to create a new route.

   oc expose service/$PRIVREPO
   

9. You can access the application through IBM provided domain. Run the command below to obtain the URL.

   oc get route/$PRIVREPO
   

10. Copy the value for the hostname under HOST/PORT value and paste the URL in a browser to see your application in action at http://<hostname>. Make sure to use http in the URL.

    A new application is deployed using the code from the private Git repo and the container image from the private registry namespace.

Update the application and redeploy

In this step, you will automate the build and deploy process. Whenever you update the application and push the changes to the private repository, a new build runs generating a new version of the container image. This image is then deployed automatically.

1. You will create a new GitLab Webhook trigger. Webhook triggers allow you to trigger a new build by sending a request to the Red Hat OpenShift on IBM Cloud Container Platform API endpoint.You can define these triggers using GitHub, GitLab, Bitbucket, or Generic webhooks.

   oc set triggers bc $PRIVREPO --from-gitlab
   

2. To add a webhook on the GitLab repository, you need a URL and a secret

   • For webhook GitLab URL,

     oc describe bc/$PRIVREPO | grep -A 1 "GitLab"
     

   • For secret that needs to be passed in the webhook URL,

     oc get bc/$PRIVREPO -o yaml | grep -A 3 "\- gitlab"
     

   • Replace <secret> in the webhook GitLab URL with the secret value under gitlab in the above command output.

3. Open your private git repo in a browser using the Git repo HTTPS link then click on Settings and click Webhooks.

4. Paste the URL, select Push events as the Trigger and click on Add webhook. You should see Webhook was created message.

5. Update the ImagePolicy of the image stream to query Container Registry at a scheduled interval to synchronize tag and image metadata. This will update the tags definition

   oc tag $MYREGISTRY/$MYNAMESPACE/${PRIVREPO}:latest ${PRIVREPO}:latest --scheduled=true
   

6. Open the cloned repository in an IDE to update the h1 tag of local public/index.html file and change it to Congratulations! <insert your name>.

7. Save and push the code to the repository.

    git add public/index.html
   

    git commit -m "Updated with my name"
   

    git push -u origin master
   

8. You can check the progress of the build and deploy with oc status command. Once the deployment is successful, refresh the route HOST address to see the updated web app.

   Sometimes, the deployment may take up to 15 minutes to import the latest image stream. You can either wait or manually import using oc import-image $PRIVREPO command. Refer to this link for more info.

With HTTP

1. Create a route exposing the service at a hostname by replacing <HOSTNAME> with your hostname(e.g.,www.example.com or openshiftapp.example.com), so that external clients can reach it by name.

   oc expose svc/$PRIVREPO --hostname=<HOSTNAME> --name=$PRIVREPO-domain --port=3000
   

2. Access your application at http://<HOSTNAME>/

With HTTPS

1. To create a secured HTTPS route, you can use your own certificate and key files from a CA like Let's Encrypt or order through Secrets Manager. Pass them with the create route command

   oc create route edge $PRIVREPO-httpsca --service=$PRIVREPO --cert=example.pem --key=example.key --hostname=<www.HOSTNAME> --port=3000
   

   Here, you have used Edge termination. To learn about other secured routes and termination types like passthrough and re-encryption, run oc create route --help command)