Walkthrough: Setting up Jenkins X on a Kubernetes cluster

Set up Jenkins X on a Kubernetes cluster hosted on GKE

By Kara de la Marck | Tuesday, March 10, 2020

Setup used in this tutorial

GitHub as our Git provider and a GitHub user account, eg MarckK
A Google Cloud Platform (GCP) account with the ability to provision kubernetes resources / create kubernetes clusters
Jenkins X jx binary installed. See here for instructions on installing the jx binary.
The Kubernetes command-line tool, which can be installed to your local installation using the jx install command:

jx install dependencies -d kubectl

We are going to create a GitHub organisation which will have two members, a GitHub user account, eg MarckK, and a GitHub ‘Pipeline’ bot account, eg jx-bot.

We can create a new GitHub organisation by clicking the + at the top right of GitHub’s top navigation bar or by clicking to the create an organization page. I chose the free ‘Team for Open Source’ plan for my new GitHub organisation; this means the organisation will not have unlimited private repositories. Name your organisation anything you like, eg jenkins-x-space.
Invite your GitHub user account, eg MarckK, to the organisation. This GitHub user account will create and manage development repositories.
Next we create a GitHub Pipeline bot account. This Pipeline bot will automate pull request notifications and create preview environments for quick validation and acceptance for code merging. Your Pipeline bot should be created as a member of your GitHub organisation, eg jenkins-x-space.

Create an entirely new account that will be only for your bot. Name your bot anything you like, eg jx-bot.

The bot account must have a token created in your organization that authenticates the bot and allows it to perform various tasks on the repositories within your organization.

Generate a Git token for your Pipeline Bot with the correct permissions via this GitHub Link and copy the 40 character token.

The 40 character token generated by GitHub is only shown once so you must copy this immediately before you close the browser tab or window, as the token cannot be retrieved once it is displayed. You will be asked for this token later, so please do keep a copy of it.

At this point, I signed out of my GitHub Pipeline bot account and back into my GitHub user account, eg MarckK.

Step 1 - Create a Kubernetes cluster

jx create cluster gke will create a cluster on Google Kubernetes Engine (GKE), which you can initialise with a name. From the command-line run:

jx create cluster gke --skip-installation -n <cluster name>

The program opens a web browser and you will be asked to choose the email address associated with your GCP account and to allow the Google Cloud SDK access to your account. After confirming, you can close the browswer page.
Back at the command-line, the jx create cluster program prompts you to choose your Google Cloud Project from the available list.
The program prompts you to choose the Zone nearest to where you would like to install your cluster. For example, if you want your cluster to serve users primarily in the east coast of the United states, you choose us-east1-b from the available list.
The program runs automatically through default questions and begins creating the cluster in your specified zone.

Towards the end, you will see output similar to:

NAME         LOCATION         MASTER_VERSION  MASTER_IP      MACHINE_TYPE   NODE_VERSION    NUM_NODES  STATUS
walkthrough  europe-north1-a  1.14.10-gke.17  35.228.74.166  n1-standard-2  1.14.10-gke.17  3          RUNNING

Congratulations you now have a Kubernetes cluster!

Step 2 - Installing Jenkins X on a cluster

First clone the Jenkins X Boot configuration repo and cd into your newly cloned repo.
Open the jx-requirements.yml file of your newly cloned repo, eg. jenkinx-x-boot-config/jx-requirements.yml. This specifies the requirements of your installation, including:
- what Kubernetes provider to use
- whether to store secrets in the local file system or vault
- if you are using Terraform to manage your cloud resources
Note, this is the main configuration file for jx boot and where you make most of your configuration changes.

The jx-requirements.yml file is interesting to review, see the defaults in place, and make any changes you need.
For my setup, I knew there was one change I needed to make to the jx-requirements.yml. By default, Jenkins X will create private environment repos. You can see this configured in jx-requirements.yml as environmentGitPublic: false. However, I set up a free open source GitHub organization to hold the environment repositories that will be created by Jenkins X, and this type of GitHub organization account does not have access to private repos. To configure Jenkins X to create public environment repositories, set environmentGitPublic to true in jx-requirements.yml.
Save your changes and then on the command line run:

jx boot

If you are not in a clone of a boot git repository then jx boot will clone this repository and cd into the clone.

You can read more about Jenkins X Boot in the documentation.

Your Git and the pre-installation set up for Jenkins X will be checked and validated. You will see printed out:

`Currently connected cluster is <cluster_name> in <cluster_location> in project ```<your_chosen_project>``

You will be asked to confirm that you would like to jx boot your <cluster_name>.

Then you will be asked a series of questions to ensure Jenkins X is installed properly on your cluster:

You will be asked to input the Git Owner name for environment repositories: Type in the organistion you created, eg jenkins-x-space.
You will be asked to provide Comma-separated git provider usernames of approvers for development environment repository: Type in the name of the GitHub account that is a member of the organisation you created, eg MarckK.
You may receive a Warning that TLS is not enabled so your webhooks will be called using HTTP. You will be asked for confirmation to continue.
- If you type ‘No’, the jx boot process will end with error: cannot continue because TLS is not enabled.
- If you type ‘Yes’, then namespace jx will be created in your cluster and Jenkins X booted in that namespace.
You may be asked if you wish to upgrade jx. It is recommended you say ‘Yes’ and then re-run jx boot.
There will be information logged on enabling storage on GKE. You do not need to enable storage for this walkthrough tutorial.
You will see information on the pipeline steps of JX Boot.
You will be asked Jenkins X Admin Username: Type in a username or press return to have the default username of admin.
You will then be asked for Jenkins X Admin Password: Type one in.
You will then be asked for Pipeline bot Git username: Type in the name of the Pipeline Bot you created, eg jx-bot.
You will then be asked for Pipeline bot Git email address: Type in the email address you used when setting up your Pipeline Bot.
You will then be asked for Pipeline bot Git token: Type in the token generated and saved previously.
You will be asked, Do you want to configure an external Docker Registry?: ‘No’ is sufficient for this tutorial
More pipeline steps will be run. You should see output that your pods are running and other verification information telling you the state of your Jenkins x set-up.

Then you will see confirmation on the state of your installation process, such as:

Installation is currently looking: GOOD

In the organisation you created, eg jenkins-x-space, there should now be 3 additional repositories for the dev, staging, and production environments, which map to the dev, staging, and production namespaces in your cluster.

Jenkins X should be installed on your Kubernetes cluster. 🎉

To see the Jenkins X environments that have been created, the corresponding GitOps git repos, and the default promotion strategy between environments:

jx get environments

You should see something similar to:

 NAME       LABEL       KIND        PROMOTE NAMESPACE     ORDER CLUSTER SOURCE                                                                    REF    PR
dev        Development Development Never   jx            0             https://github.com/jenkins-x-space/environment-walkthrough-dev.git        master
staging    Staging     Permanent   Auto    jx-staging    100           https://github.com/jenkins-x-space/environment-walkthrough-staging.git    master
production Production  Permanent   Manual  jx-production 200           https://github.com/jenkins-x-space/environment-walkthrough-production.git master

Note the following details in the PROMOTE column:

Development has Never promote, because you’re working locally in this environment and not deploying anything.
The Staging environment’s default is to Auto promote, meaning any merge performed on the repo’s master branch will automatically be deployed as a new version to staging.
The Production environment’s default is to have a Manual promotion strategy, meaning that you will have to manually promote your staging application version into production by using a jx promotion command.

The SOURCE column shows each environment’s configuration git repo.

Step 3 - Create an application

Now that you have a working cluster with Jenkins X installed, you are going to create an application that can be built & deployed with Jenkins X.

Using a quickstart

JX has a create quickstart command that will create a build from a standardised template. To run this command, change your directory so that you are no longer within the jenkins-x-boot-config directory, then type the following:

jx create quickstart --git-public=true

We are adding the --git-public=true flag to ensure that our new quickstart application will create repositories that are public on GitHub, as our freemium GitHub organisation requires.

For this example, select golang-http.

You will be asked a series of questions such as:

Do you wish to use <your GitHub user name> as the Git user name?: Choose y
Who should be the owner of the repository?: Choose the organisation you have created, eg jenkins-x-space.
Enter the new repository name: Choose a name for your new application, such as jx-tutorial

JX will then guide you through setting up the git repository for the application.

If this is the first application you have created, it may take a few minutes to download all of the required builder images in order to build/deploy the application.

To view the status of the application, you can use the following:

jx get activity -f jx-tutorial -w

Note: -f is for –filter and -w is for –watch

When the pipeline is complete, to view the application in each environment along with urls:

jx get applications

Promote the application to production

Using the jx promote command, you can push this version from staging to production.

cd jx-tutorial

If you have 2FA enabled on your GitHub account, then you may need to use an api token as your password when prompted.

jx promote jx-tutorial --version 0.0.1 --env production

You can check the progress of the production deployment using:

jx get activity -f jx-tutorial -w

jx get applications

Congratulations

You’re all set!

You now have a fully configured Jenkins X installation on Google Kubernetes Engine.

To avoid running up unnecessary costs, you may wish to shut down your kubernetes cluster at this point. To view all clusters running with the current account use:

gcloud container clusters list

To delete the cluster run:

gcloud container clusters delete <clustername> --zone <zone>

←Previous