Archive date: 2021-02-25
This content is no longer being updated or maintained. The content is provided “as is.” Given the rapid evolution of technology, some content, steps, or illustrations may have changed.In this tutorial, learn how to use Appsody to deploy a sample insurance quote application to Red Hat® OpenShift® using IBM Cloud Pak for Applications pre-built Tekton pipelines. Specifically, we show you how to push the code up to a GitHub repo, create a webhook so Tekton and Github can communicate, and use Tekton pipelines to automatically build the application and deploy it to our OpenShift cluster on every code change.
This tutorial is an extension of the Create an insurance quote application using Appsody code pattern. The original code pattern shows you how deploy to an IBM Kubernetes Service and to store container images on the IBM Container Registry. This tutorial deploys to OpenShift using Tekton and stores container images on OpenShift’s internal registry.
Recall that the sample application consists of:
- a front end constructed with Node.js (we used the
nodejs-express
collection) - a back end constructed with Java (we used the
java-spring-boot2
collection)
Learning objectives
After completing this exercise, you will understand how to:
- Use the pre-built Tekton pipelines that come with IBM Cloud Pak for Applications
- Create a webhook in Tekton
- Deploy the sample application to OpenShift using Tekton
Prerequisites
Understand the “Create an insurance quote application using Appsody” code pattern. Specifically, performing Steps 1-3 (clone, run frontend locally, run backend locally) is essential before starting this tutorial.
Install the Appsody CLI.
- Get access to a Red Hat OpenShift on IBM Cloud cluster, with IBM Cloud Pak for Applications installed.
- (Optional) Obtain a Dacadoo API key.
- Record the URL for the API (usually
https://models.dacadoo.com/score/2
) and thekey
(something similar toUFDzMHAfsEg0oKzGp4rCSmXPClKKq3hDPLbPdvc2h
). - There is a mock implementation of the API in the code that you can use if you do not want to register.
- Record the URL for the API (usually
Estimated time
Completing the steps in this tutorial should take about 45 minutes.
Steps
- Launch the Tekton dashboard
- Get a GitHub access token
- Upload an insurance quote front end and back end to GitHub
- Add webhooks to Tekton to watch GitHub repo changes
- Test it all
1. Launch the Tekton dashboard
To launch the Tekton dashboard, navigate to your Cloud Pak for Applications dashboard and select the Tekton link.
You can also obtain the URL for the Tekton dashboard by using oc get routes
. Use the address that looks like tekton-dashboard-kabanero.xyz.domain.containers.appdomain.cloud
.
$ oc get routes --namespace kabanero
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
icpa-landing ibm-cp-applications.cpa-workshop-dev-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud icpa-landing <all> reencrypt/Redirect None
kabanero-cli kabanero-cli-kabanero.cpa-workshop-dev-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud kabanero-cli <all> passthrough None
kabanero-landing kabanero-landing-kabanero.cpa-workshop-dev-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud kabanero-landing <all> passthrough None
tekton-dashboard tekton-dashboard-kabanero.cpa-workshop-dev-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud tekton-dashboard <all> reencrypt/Redirect None
Review pre-installed pipelines and tasks on Cloud Pak for Applications
There are five pipelines, one for each Appsody collection (Java MicroProfile, Spring, Node.js, Express, and LoopBack). Pipelines are a first-class structure in Tekton and are a series of tasks.
Run this command to see the available pipelines:
oc get pipeline -n kabanero
You will see something similar to this.
$ oc get pipeline -n kabanero
NAME AGE
java-microprofile-build-deploy-pipeline 15d
java-spring-boot2-build-deploy-pipeline 15d
nodejs-build-deploy-pipeline 15d
nodejs-express-build-deploy-pipeline 15d
nodejs-loopback-build-deploy-pipeline 15d
pipeline0 15d
These are visible through the Tekton UI, too:
There are 10 tasks, two for each collection included in Kabanero. Each collection has two tasks, a build task and a deploy task.
Run this command to see the tasks:
oc get pipeline -n kabanero
You will see something similar to this.
$ oc get tasks -n kabanero
NAME AGE
java-microprofile-build-task 27d
java-microprofile-deploy-task 27d
java-spring-boot2-build-task 27d
java-spring-boot2-deploy-task 27d
monitor-result-task 27d
nodejs-build-task 27d
nodejs-deploy-task 27d
nodejs-express-build-task 27d
nodejs-express-deploy-task 27d
nodejs-loopback-build-task 27d
nodejs-loopback-deploy-task 27d
pipeline0-task 27d
These are visible through the Tekton UI, too:
2. Update Kabanero to deploy to alternate namespaces with Tekton
Out of the box, Kabanero only allows deployments to the Kabanero namespace. It is recommended that you create separate namespaces either for individual applications or classes of application. To do this, you need to add these new namespaces to the Kabanero custom resource.
Find the resource:
$ oc get kabaneros -n kabanero
NAME AGE VERSION READY
kabanero 13d 0.1.0 True
Edit the Kabanero custom resource:
oc edit kabaneros kabanero -n kabanero
Add a targetNamespaces
key to spec
with, in this case, a single value of insurance-quote
:
spec:
collections:
repositories:
- activateDefaultCollections: true
name: incubator
url: https://github.com/kabanero-io/collections/releases/download/v0.1.2/kabanero-index.yaml
targetNamespaces:
- insurance-quote
Update app-deploy.yml
to specify the namespace
Go to your front-end code cd ~/appsody-apps/quote-frontend
and update app-deploy.yaml
to include the namespace
apiVersion: appsody.dev/v1beta1
kind: AppsodyApplication
metadata:
name: quote-frontend
namespace: insurance-quote
Go to your back-end code cd ~/appsody-apps/quote-backend
and update app-deploy.yaml
to include the namespace
apiVersion: appsody.dev/v1beta1
kind: AppsodyApplication
metadata:
name: quote-backend
namespace: insurance-quote
2. Get a GitHub access token
When using Tekton, building a pipeline requires you to pull code from either a public or private repository. When configuring Tekton, for security reasons, we will create an access token instead of using a password.
To create an access token, go to Github.com and click on your profile icon in the top left. Navigate to Settings
-> Developer Settings
-> Personal Access Tokens
. Or go directly to https://github.com/settings/tokens
To generate a new token, click on the Generate a Token
button. The token permissions need to be the repo
which gives read and write access to the repository, so check the box beside “repo.”
Once the token is created, make sure to copy it down. You need it later in this tutorial.
3. Upload the insurance quote front end and back end to GitHub
Go to https://github.com/new and create two new repositories, quote-frontend
, and quote-backend
. Do not initiatize the repos with a license file or README.
From your quote-backend
directory, run the commands below, replacing <username>
with your own.
git init
git add -A
git commit -m "first commit"
git remote add origin git@github.com:<username>/quote-backend.git
git push -u origin master
The repo for your back end code should look like this:
From your quote-frontend
directory, run the commands below, replacing <username>
with your own.
git init
git add -A
git commit -m "first commit"
git remote add origin git@github.com:<username>/quote-frontend.git
git push -u origin master
The repo for your front end code should look like this:
4. Add webhooks to Tekton to watch Github repo changes
Configure the GitHub webhook to your repo. In your Tekton dashboard, go to Webhooks
> Add Webhook
and then create the webhook.
Note that the first time you create a webhook, you must also create a new access token. Use the access token from the earlier step:
Create a webhook for the back end
Name: backend-webhook
Repository URL: http://github.com/{username}/quote-backend
Access Token: github-tekton
Namespace: kabanero
Pipeline: java-spring-boot2-build-deploy-pipeline
Service account: kabanero-operator
Docker Registry: docker-registry.default.svc:5000/insurance-quote
Create a webhook for the frontend
Name: frontend-webhook
Repository URL: http://github.com/{username}/quote-frontend
Access Token: github-tekton
Namespace: kabanero
Pipeline: nodejs-express-build-deploy-pipeline
Service account: kabanero-operator
Docker Registry: docker-registry.default.svc:5000/insurance-quote
Verify both webhooks are created successfully.
Check Github repo settings
Go to the repo and check the Settings tab to see the webhooks. Click Webhooks in the left navigation bar:
Scroll down to see any payloads being delivered. There is currently a bug where the first payload is not delivered. Don’t worry — we’ll make changes to the code which will trigger a new payload.
5. Test the webhook configuration
Now we need to test that we have our pipelines and webhooks all configured correctly. In your quote-backend
repo, change the file quote-backend/src/main/java/application/Quote.java
. Change a value in a logger statement. Then commit this change and push to your GitHub repo, for example:
git add -u
git commit -m "test change"
git push -f -u origin master
This triggers the Tekton pipleine. Go to the Tekton dashboard and access the new pipeline it created.
Wait until the task is complete, then find the route using oc get routes
:
$ oc get routes -n insurance-quote | grep backend
quote-backend quote-backend-insurance-quote.cp4apps-workshop-prop-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud
In your quote-frontend
repo, change the file app-deploy.yml
to update the BACKEND_URL
value with the URL from the previous step.
env:
- name: BACKEND_URL
value: http://quote-backend-insurance-quote.cp4apps-workshop-prop-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud/quote
This should trigger Tekton to create another pipeline, using the node-express pipeline.
Wait until the task is complete, and then find the route using oc get routes
:
$ oc get routes -n insurance-quote | grep frontend
quote-frontend quote-frontend-insurance-quote.cp4apps-workshop-prop-5290c8c8e5797924dc1ad5d1b85b37c0-0001.us-east.containers.appdomain.cloud
Open a browser to http://<url-from-above>
and see the usual interface for the insurance quote app. Try entering information to ensure the front end and back end are communicating.
Summary
Congratulations! You have deployed the sample application to OpenShift using Tekton.
Want to get more experience with Tekton and Appsody? Check out this pattern: Use Tekton to automate the deployment of applications.