Jose Armesto's Blog

Automatically versioning your Application on Jenkins X

Fri, 01 Feb 2019 23:47:55 +0000

Having a good versioning strategy for our applications is key. Specially in Jenkins X, which follows the GitOps flow to deploy our applications, specifying which version of our application will be used on each environment.

But having to manually create tags or releases for our applications can be a tedious task. Jenkins X automatically takes care of versioning for us. It uses a tool called jx-release-version to figure out which is the next version to be released. In order to do that it checks what’s the current released version in the repository looking at the released Git tags. It can also read this version from your pom.xml file, or your Makefile.

If we use semver semantics, and versions are written in the format major.minor.patch, jx-release-version will tell you which is the next patch version.

The cool thing is that you don’t need to use Jenkins X to use jx-release-version!

Let’s go through some examples.

Using git tags

Using git tags is probably the easiest way to handle our application versions. We can create a new git tag for every new version that we want to release.

If we try to use jx-release-version on a Git repository that has no tags, it will return that the next version number to release is 0.0.1. Next time we use jx-release-version, it will increase our patch number.

$ git --no-pager tag -l
$ # there are no tags just yet!
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
v0.0.1
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
  v0.0.1
  v0.0.2

Using maven pom file

If you are using a pom.xml file that also tracks your current application version, you still can use jx-release-version. It will try to sync the git tags in your Git repository with the version that you specify in the pom.xml file.

Your release process needs to look something like this

# First we call the `jx-release-version` binary that will return the next version number to be released.
# Every time we call the binary it will try to figure out the next version number. Normally it's not a good idea to call it more than once.
RELEASE_VERSION=`jx-release-version`
echo "New release version ${RELEASE_VERSION}

# We update our current pom.xml file with this new version number.
mvn versions:set -DnewVersion=${RELEASE_VERSION}

# Changes to the pom.xml file need to be committed to our repository.
git commit -a -m 'release ${RELEASE_VERSION}'

# The git commit containing both our application changes and the change to the pom.xml file will be tagged using the same version number.
git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'

# Push the commit and tag to the remote repository.
git push origin v${RELEASE_VERSION}

If we start a new git repository that has no tags, the jx-release-version will use the version in our pom.xml file.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>io.example</groupId>
    <artifactId>example</artifactId>
    <version>1.0-0-SNAPSHOT</version>
    <packaging>pom</packaging>
</project>

The release version for 1.0.0-SNAPSHOT is 1.0.0, so jx-release-version will return 1.0.0 as the next version number to use. Similarly, if our pom.xml file had <version>0.0-23-SNAPSHOT</version> in it, jx-release-version would return 0.0.23 as the next version number to use.

Using a Makefile

Let’s say we have this Makefile that tracks the current version of our application

# This is the current version of your application
VERSION := 2.0.3-SNAPSHOT

# Use jx-release-version to calculate next version
RELEASE_VERSION := $(shell jx-release-version)

build:
	# The git commit containing our application changes will be tagged.
	git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'

	# Push the tag to the remote repository.
	git push origin v${RELEASE_VERSION}

The current version of our application is 2.0.3-SNAPSHOT. That means that the jx-release-version will return 2.0.3 as the next version number to use.

Releasing a new major/minor version

Sometimes we don’t want to just release a new patch version (like going from 1.0.5 to 1.0.6). Instead, we want to release 1.1.0, or even 2.0.0. We have said earlier that jx-release-version calculates the next version number based on the current Git tag, or current specified version on pom.xml/Makefile. So if we need to release a new major/minor version, we just have to release a new Git tag or update the pom.xml/Makefile.

For example, if the current version is 0.0.2 and we want to release 0.1.0, we first create a git tag for that and let jx-release-version do it’s thing afterwards.

# Manually create new tag for the version that we want
git tag -fa v0.1.0 -m "Release version 0.1.0"
# Use jx-release version normally
$ RELEASE_VERSION=`jx-release-version` && git tag -fa v${RELEASE_VERSION} -m 'Release version ${RELEASE_VERSION}'
$ git --no-pager tag -l
v0.0.1
v0.0.2
v0.1.0
v0.1.1

As said in the project’s README

If your project is new or has no existing git tags then running jx-release-version will return a default version of 0.0.1
If your latest git tag is 1.2.3 and you Makefile or pom.xml is 1.2.0-SNAPSHOT then jx-release-version will return 1.2.4
If your latest git tag is 1.2.3 and your Makefile or pom.xml is 2.0.0 then jx-release-version will return 2.0.0

Jenkins X Environments

Wed, 05 Dec 2018 23:47:55 +0000

This year Jenkins X has been announced. If you haven’t heard, Jenkins X is a tool that lets you automate the whole delivery process of your software to a Kubernetes cluster. One key aspect of Jenkins X is that the deployment of applications is implemented following the GitOps flow. In this approach every environment is represented by a Git repository. In this post we’ll see how Jenkins X environments work.

Environments

An installation of Jenkins X consists of:

A Development Environment which is a kubernetes namespace running tools like Jenkins, Nexus, etc. Each different team within an organization is meant to have its own development environment so that they can be as independent from each other as possible.
Other Permanent Environments which are kubernetes namespaces where our applications will be deployed into. By default Staging and Production are created. Each team can have as many Permanent Environments as they wish and call them whatever they like.
Optional Preview Environments, which are kubernetes namespaces where our applications will be deployed, just like Permanent Environments, but these are created on a PR basis, before you even merge your PR changes into master.

Under the covers this is implemented creating a custom Kubernetes resource jenkins.io/v1/Environment. Assuming that each team has a Kubernetes namespace assigned, each team will normally have a Development Environment and several different Permanent Environments. Each of these environments is represented by a jenkins.io/v1/Environment object on the namespace assigned to that team.

Teams are also represented by a jenkins.io/v1/Team object, but we will cover that on a different post.

These Environment objects contain configuration about which Git repository is associated with it, and which git branch to use.

There could be one namespace which is where all apps run across all teams - though from a kubernetes RBAC perspective, if you are working in microservices teams, it’s better for each team to manage their own microservices in their own production environment and use service linking between teams.

Development Environment

A jenkins.io/v1/Environment object created on the team’s namespace, which spec.Kind field is Dev. This environment is not linked to a Github repository, we will never promote changes here. It’s just a Kubernetes namespace used to run applications while developing, thanks to skaffold.

In the dev environment Jenkins X installs a number of core applications they believe are required at a minimum to start folks off with CI/CD on Kubernetes. They come with configuration that wires these services together meaning everything works together straight away.

Jenkins — provides both Continuous Integration and Continuous Delivery automation.
Nexus — acts as a dependency cache for applications to dramatically improve build times.
Docker registry — an in cluster Docker registry where the pipelines push application images.
Chartmuseum — a registry for publishing Helm charts.
Monocular — a UI used for discovering and running Helm charts.

Permanent Environments

These environments are where the applications will ran. By default Staging and Production are created, but more environments can be created. Staging has the Auto promote strategy and Production the Manual promote strategy. We’ll see what that means in a minute.

These environment are linked to

A GitHub repository containing a Helm chart that defines which application charts are to be installed on the environment, which versions of them and any environment specific configuration and additional resources (e.g. Secrets or operational applications like Prometheus etc).
A Kubernetes namespace where the Helm chart from the repository will be installed.

When you want to deploy to an environment, a Pull Request must be made to that environment’s repository. We can manually create the PR to deploy an application to an environment, or we can use this handy jx command

jx promote --app myapp --version 1.2.3 --env production

Typically we specify the environment while promoting to environments with the Manual promote strategy, like the Production environment. Instead of specifying the environment, we can create a Pull Request in all the environments having the Auto promote strategy using this jx command

jx promote -b --all-auto --timeout 1h --version \$(cat ../../VERSION) --no-wait

Changing the Production environment’s promote strategy from Manual to Auto you can do Continuous Deployment.

When these PRs are merged into the environment’s git repository, the environment pipeline runs, which then applies the Helm chart living on that repo to the environment’s Kubernetes namespace.

Preview Environments

Preview Environments are similar to Permanent Environments in that they are defined in a source code Git repository using Helm charts. The main difference is that Preview Environments are configured inside the application repository in the ./chart/preview folder. Also they are not permanent but created when a Pull Request is made to an application’s git repository, and then deleted some time after (manually or via automatic garbage collection).

When the Preview Environment is up and running Jenkins X will comment on your Pull Request with a link so in one click your team members can try out the preview.

You can create a preview environments using

jx preview

This will create the Environment and Namespace objects for this environment. It will also build the application creating a new Docker image that will be deployed to the preview environment using the preview chart defined in the ./chart/preview folder.

Managing environments

You can create new environments using jx

jx create env --name prod --label Production --namespace my-prod

Some interesting options are

label: The Environment label which is a descriptive string like Production or Staging.
prefix: Environment repo prefix, your Git repo will be of the form environment-$prefix-$envName.
promotion: The promotion strategy, Auto or Manual.

You can then list all existing environments

jx get environments

Or edit an existing environment (-b for no interactive)

jx edit env -b --name prod --label Production --no-gitops --namespace my-prod

Or finally delete it

jx delete environment prod

Deployment Flow

In the workflow that Jenkins X proposes, we will have a repository for each application that we want to deploy. But also we will have a repository for each environment where you want to deploy these applications. The repositories for the different environments describe all the applications that must be running on them.

So while developing your application, the usual flow would be

Create a Pull Request on the application repository: this will execute the application CI pipeline to build and test the application.
Once the Pull Request on the application repository is merged, the application pipeline will release this newly built version to a Docker Registry and promote it to the environments with the Auto promote strategy using a jx command.
If we want to deploy to production or any environment with the Manual promotion strategy, we need to execute the jx command targeting the desired environment.