Lab: Jenkins Pipelines with IKS
Overview
In this lab you will be enabling CI/CD connecting your Git repository with the guestbook app to a Continuous Integration/Continuous Deployment pipeline built with Jenkins that will deploy to a IBM Cloud Kubernetes Service cluster.
Note: You will need to create a GitHub account if you don't have one already.
Setup
If you haven't already, set up the guestbook
application that will be deployed:
Open a new browser window or tab and go to the guestbook application repository
Click on the Fork icon.
Note: you need to fork the repo to have full access to turn of Git WebHooks feature for the repo in later section.
If you have Git installed on your machine, go ahead and clone your fork of the guestbook application, then
cd
into that directory. From a terminal window, execute the following commands (replace the url with your forked repo url):
Lab Steps
We will now configure the CI/CD pipeline with Jenkins to automate application deployment to a IBM Kubernetes cluster.
Step 0: Create and collect: API Key, Registry Namespace and Cluster Name
We will need all these values when we configure our Jenkins pipeline later.
Login to the IBM Cloud console. Make sure you have the right account selected in the dropdown (the one with your Kubernetes cluster which you want to deploy to) and open the cloud shell by clicking the icon on the top right of the screen.
Create an API key using the following command (replace
[key name]
with a name of your choosing). Save the key value by Copy and Pasting it to a text editor, we will use it later in our Jenkins Pipeline.Create or access a container registry namespace.
First, see if you have access to an existing namespace already.
If you get a value above, copy and paste to a text editor for later. If you have no namespaces created, run the following command to create one (replace
[namespace name]
with a name of your choosing).
Access and save the name of your Kubernetes Cluster on IBM Cloud.
Save the cluster name to a variable by using the following command (replace
[cluster name]
with your cluster name from above step):
Step 1: Add Jenkinsfile to the Guestbook App
We will add a JenkinsFile to your guestbook repository. Download this JenkinsFile to your machine. Inspect the JenkinsFile to learn what stages we will setup in the next steps. For your convenience, here is a curl command you can use to download the file.
To add the file your guestbook repo, you can either (option 1) use the git CLI if you have it installed or (option 2) do it from the browser.
(Option 1) Save/move the Jenkinsfile to the root of your guestbook project (where you cloned it).
Configure git client (if needed):
Add the Jenkinsfile and commit the changes:
Push the changes to your repo:
(Option 2) Upload the file and commit using a web browser.
From your fork of the github repo, click on
Add file
, thenUpload files
.Choose the Jenkinsfile.ext you download earlier and click the
Commit changes
button.
Step 2: Set up the CI/CD pipeline
In this section we will be connecting your forked Git repo of this app to set up a Continuous Integration/Continuous Deployment pipeline built with Jenkins. This pipeline contains 3 main steps as follows:
Stage
Purpose
Build Docker Image
Builds the Docker image based on the Dockerfile
Push Docker Image to Registry
Uploads the Docker image to the Docker image registry within ICP
Deploy New Docker Image
Updates the image tag in the Kubernetes deployment triggering a rolling update
More details of this pipeline can be found in the Jenkinsfile.
Log into Jenkins using the URL provided to you by your instructor with the credentials provided to you.
The pipeline should have already been created for you.
Click on your pipeline to open it and then click on the
Configure
link in the navigation area at the left to change it's properties.Scroll down to the
This project is parameterized
section, here you will have to set some values to connect this pipeline to your cluster.Set the value of
API_KEY
to the API_KEY you created and saved earlier for your ibmcloud account. We will be using this key to give Jenkins access to deploy to your cluster and to push images to your container registry. To update the value, click on the 'Change Password' button next to the field and paste your API key.Set the value of the
CLUSTER_NAME
to the name of your Kubernetes cluster you want to deploy to.Set the value of the
REGISTRY_NS
to the name of your container registry namespace you viewed (or created) earlier. We will deploy our application image to this location.Leave the default value of
REGION
unless instructed otherwise. This should match the location of your Kubernetes cluster.
Scroll down to the
Build Trigger
section and selectGitHub hook trigger for GIT SCM polling
.Scroll down to the Pipeline section and find the Definition drop down menu. Select Pipeline script from SCM and for SCM select Git.
For Repository URL enter the url to the cloned repository that you forked earlier (i.e.
https://github.com/[your username]/guestbook.git
)Change the Script Path to
Jenkinsfile.ext
.Click Save.
Step 3: Manually trigger a build to test pipeline
In Jenkins in the navigation area on the left click on
Build with Parameters
. Accept the defaults of the parameters and click onBuild
To see the console output, click on the build number in the Build History and then click on Console Output
If the build is successful the end of the console output should look like the following:
The Stage View of the pipeline should look like the following:
When the pipeline is finish deploying, launch the app to verify the it has been deployed and is running, run the following command to get the port number of your deployed app:
Run the following command to get the external IP address of the first worker node in your cluster:
Your app's URL is the IP address of the first worker node with the port number of the deployed app. For example if your external IP is 169.61.73.182 and the port is 30961 the URL will be
http://169.61.73.182:30961
Enter the URL in your browser's address bar and verify that the application loads.
Step 4: Trigger a build via a commit to Github
Now you'll configure Github to trigger your pipeline whenever code is committed.
Go back to Github and find your cloned repository
Click on the repository settings
Under
Options
selectWebhooks
and clickAdd webhook
For the Payload URL use
<Jenkins URL>/github-webhook/
where<Jenkins URL>
is the URL you used to login to Jenkins (Note Don't forget the trailing/
)Change content type to application/json
Accept the other defaults and click
Add webhook
In the Github file browser drill down to /v1/guestbook/public/index.html
Click on the pencil icon to edit index.html and on line 12 locate the header of the page
Change
Guestbook - v1
toGuestbook - updated!
... or whatever you want!At the bottom of the UI window add a commit message and click on Commit changes
Switch back to Jenkins and open the pipeline that you were working on earlier.
Verify that your pipeline starts building.
When the pipeline is finish deploying, force-refresh (
⌘ + shift + R
on mac) the browser window where you previously loaded the app to verify the change you made.Note: If you closed the browser window, follow steps 5 - 9 of the previous section to get the URL of the application again.
Summary
You created a Jenkins pipeline to automatically build and deploy an app that has been updated in Github.
Last updated