WSO2 Products Dockerized: Image Tagging Mechanism

WSO2, the world’s #1 open source integration vendor, provides official Docker images for its products. The previous articles of this series provided an introduction to these Docker images and detailed guides for their usage. This write up intends to dig deep into the tagging mechanism adopted by WSO2, for its product Docker images.

Published in

FAUN — Developer Community 🐾

9 min readSep 15, 2019

Before stepping into advanced details pertaining to the focused topic, let me quickly enlighten you on the expected learning outcomes of this write up.

Purpose of Docker image tags
Factors and best practices considered in WSO2 product Docker image tagging mechanism
WSO2 product Docker image tag formats
Usage best practices of WSO2 product Docker image tags

Without further ado, let us move into details associated with the discussed topic.

Note:

With the introduction of all new WSO2 Updates 2.0.0, the tagging mechanism for product Docker images packaging WSO2 Updates underwent several changes.

Please refer to this article for an exhaustive description about the new tagging mechanism.

What are WSO2 Product Docker Images?

WSO2 has made its product Docker images available at multiple Docker registries.

Public WSO2 organization at Docker Hub
Self-hosted, private Docker registry maintained by WSO2 Inc.

This is a topic which had been thoroughly covered in the introductory guide of this series, WSO2 Products Dockerized. I strongly recommend you to dive into this introduction, prior to proceeding into the next sections of this write up.

What are Docker Image Tags?

A Fully Qualified Image Name (FQIN) of a Docker image is of the following format.

hostname[:port]/username/reponame[:tag]

As per this informative guide on referencing Docker images, a Docker image name has three primary components.

Docker registry location (includes the hostname and the optional port specification)
Username
Image repository name (along with an optional tag specification)

The Docker image tag specification conveys the information about a specific image version/variant. In the case of WSO2 product Docker images, an image tag may imply,

the version of the product profile or runtime packaged
the base Operating System (OS) platform of the image
information pertaining to the WSO2 Update process of the relevant product profile (specific to images hosted at the WSO2 Private Docker Registry)

For example, the FQIN of the Alpine Linux based Docker image available at Docker Hub for WSO2 Identity Server version 5.8.0 is as follows:

wso2/wso2is:5.8.0-alpine3.10

As you may have noticed, the image tag reflects the information pertaining to the version of the product profile and base OS of the image.

Any Docker image has a unique ID. For example, a Docker image ID could be in the form sha256:5656491eb217440b92afff0a5c822efb769988b2b8e4d64e9303fce8584c48fe. As you may have noticed, this is not a human friendly reference. Hence, a FQIN acts as a human friendly, reference alias to this ID.

You may recall that a Docker image tag is considered optional. In other terms, a Docker image can be referenced without specifying a tag. When the tag is unspecified, it is set to latest, by default.

At the time of writing, the latest WSO2 Identity Server version is 5.8.0. Hence, the corresponding, Linux Ubuntu based Docker image should possess a tag reference named latest (detailed information as to why the Ubuntu based Docker image has been tagged latest will be discussed in a later section).

Also, this implies that the same Docker image may be referenced via multiple tags.

When deciding on the image tagging mechanism for WSO2 product Docker images, numerous factors and industry accepted best practices have been taken into consideration.

Let us now look into these, in more detail.

Factors Affecting the WSO2 Product Docker Image Tagging Mechanism

As you may already know, WSO2 product Docker images are available for use via the Docker Hub and WSO2 Private Docker Registry.

The formats of the tags used for WSO2 product Docker images differ based on the hosted registry. But there are several common factors which affect the tag formats in any of the aforementioned registries.

Version of the relevant WSO2 product
Base OS platform of the image

The following additional factors come into play, when WSO2 products are packaged with WSO2 Updates.

WSO2 Update Manager (WUM) based timestamp

The WUM client tool is used to obtain the WSO2 product packs containing WSO2 Updates, which are to be packaged in the Docker images hosted at the Private Registry.

Any of these Docker images will package the latest WSO2 Updates. In this case, all WSO2 Updates up to the referred timestamp for a particular product-version combination, are included in the packaged product.

WSO2 Update Channels
Git release tag version of the particular WSO2 product Docker resources, used to build the image

This factor has been deemed vital for generating a unique tag for a given image and in the case of debugging issue(s) associated with source files used to generate a Docker image.

Industry Accepted Best Practices considered in WSO2 Product Docker Image Tagging Mechanism

This effort led us towards evaluating the recommended best practices for the Official Docker Library images and miscellaneous resources (e.g. this informative guide based on Microsoft’s experience on containerized deployments).

The outcome of this effort pushed us towards maintaining a combination of tag types namely,

Stable tags

This type of tags typically reflects the version of the relevant WSO2 product, the base OS platform of the image and WSO2 Update Channel information (specific to images hosted at the WSO2 Private Docker Registry).

They avoid detailed information about the WUM based timestamp or the Git release tag version of the source used to build the image.

This type of tags is primarily defined for easier referencing and is recommended for use only in evaluatory resources for container platforms (e.g. Docker Compose resources for WSO2 Identity and Access Management or Kubernetes resources for a simplified deployment of WSO2 Identity and Access Management).

Further, this type of tags is kept as short as possible, for convenience.

WSO2 product Docker images hosted at the Docker Hub are completely based on this type of tags whereas, a subset of all tags set for an image hosted at the WSO2 Private Docker Registry, will be of this type.

Unique tags

This type of tags typically takes all the factors highlighted in the section Factors Affecting the WSO2 Product Docker Image Tagging Mechanism, when reflecting information about a WSO2 product Docker image.

Tags of this nature are essential for users to distinguish the contents of a particular product Docker image used, in a given deployment environment (e.g. to distinguish the level of WSO2 Updates, up to which the deployments have been tested in development and production environments).

Also, unique tags will be crucial when aligning with the self-healing model of modern container orchestration systems (refer this article for a detailed example).

Hence, it is highly recommended to use unique image tags for deployments of the post-evaluation stage of the product, especially when multiple environments are involved.

Only images hosted at the WSO2 Private Docker Registry are set with tags of this type, as they are shipped with WSO2 Updates and are highly recommended for use in production grade deployments.

WSO2 Product Docker Image Tag Formats

Now, let us dig deep into the varied formats of tags set to WSO2 product Docker images, based on the Docker registry.

Images hosted at the public WSO2 organization at Docker Hub

As mentioned in the section Industry Accepted Best Practices considered in WSO2 Product Docker Image Tagging Mechanism, only stable tags are set to Docker images hosted at this public registry.

As of now, WSO2 assumes Ubuntu as the default, base OS of WSO2 product Docker images. Thus, the base OS platform name is not included in Ubuntu based Docker image tags.

The stable image tag set for a WSO2 product profile Docker image hosted at the Docker Hub is of the following format.

{product-version}-{base-os-platform}{base-os-platform-version}

For example, the FQIN of the WSO2 Identity Server version 5.8.0 Docker image based on Alpine version 3.10 (non-default, base OS platform) is of the following nature.

wso2/wso2is:5.8.0-alpine3.10

On the other hand, the FQIN of the Ubuntu based image (default, base OS platform) of this product-version combination is as follows:

wso2/wso2is:5.8.0

Further, WSO2 sets the latest tag to the Ubuntu based image (default, base OS platform) of the most recently released version of the product profile.

At the time of writing, the latest version of WSO2 Identity Server is 5.8.0. Hence, the Ubuntu based image of this product-version combination will be tagged as latest.

Let us now summarize the highlighted FQINs for WSO2 Identity Server Docker images hosted at the Docker Hub, via the following diagram.

Multiple Tags of the WSO2 Identity Server Docker Image hosted at the Docker Hub

Images hosted at the WSO2 Private Docker Registry

A product Docker image hosted at this registry is set with a combination of stable and unique image tags.

As in the case of Private Registry images, WSO2 assumes Linux Ubuntu as the default, base OS of WSO2 product Docker images. Also, the full WSO2 Update Channel is assumed to be the default Update Channel. Thus, these default values are not explicitly defined in the relevant Docker image tags.

A stable image tag set for a WSO2 product profile Docker image hosted at the Private Registry is of the following format.

{product-version}-{update-channel}-{base-os-platform}{base-os-platform-version}

For example, a WSO2 Identity Server Docker image based on Alpine version 3.10 (non-default, base OS platform) and packages version 5.8.0 of WSO2 Identity Server with WSO2 Updates obtained via the security WSO2 Update Channel (non-default Update Channel) —

wso2is-5.8.0+1565855673150.security.zip will have the following FQIN.

docker.wso2.com/wso2is:5.8.0-security-alpine3.10

Note: As mentioned before, the WSO2 Private Docker Registry will host only the Docker images, which package the latest WSO2 Updates for every product-version combination. Hence, the tag generated from the above format will always refer to the Docker image packaging the latest WSO2 Updates for a given product profile.

In addition to the stable tags, WSO2 sets unique tags based on the following formats.

{product-version}.{wum-timestamp}-{update-channel}-{base-os-platform}{base-os-platform-version}

This format is not entirely unique as it does not include the information pertaining to the source used to build the relevant Docker image. Yet, the tag yields a unique image tag, when the WSO2 product content packaged within the image are concerned.

As per the previous example, this format generates the following FQIN.

docker.wso2.com/wso2is:5.8.0.1565855673150-security-alpine3.10

{product-version}.{wum-timestamp}.{docker-release-version-number}-{update-channel}-{base-os-platform}

This tag format generates a completely unique Docker image tag.

In the above tag format, the docker-release-version-number refers to the Git release tag version of the particular WSO2 product Docker resources used to build the image. For example, if the aforementioned Docker image is created using the WSO2 Identity and Access Management Docker resource release version v5.8.0.3, the docker-release-version-number will be 3. This yields the following tag.

docker.wso2.com/wso2is:5.8.0.1565855673150.3-security-alpine3.10

Multiple Tags of the Alpine based WSO2 Identity Server Docker Image hosted at the WSO2 Private Docker Registry (discussed in the example)

On the other hand, FQINs of the Ubuntu based image (default, base OS platform) of this product-version combination packaging the latest WSO2 Updates from the full WSO2 Update Channel (default Update Channel), as per the previously highlighted tag formats will be as follows (assuming the product distribution packaged to be wso2is-5.8.0+1567933846116.full.zip):

docker.wso2.com/wso2is:5.8.0docker.wso2.com/wso2is:5.8.0.1567933846116docker.wso2.com/wso2is:5.8.0.1567933846116.3

Also, WSO2 sets the latest tag to the Docker image satisfying the aforementioned factors.

Multiple Tags of the Ubuntu based WSO2 Identity Server Docker Image hosted at the WSO2 Private Docker Registry (discussed in the example)

Conclusion

This write up provides a concise guide pertaining to the WSO2 product Docker image tagging mechanism. To be precise, this is part of the introductory guide for WSO2 product Docker images belonging to this series.

Until we meet again with another write up of this series,

Happy Dockering to you!!!

References

Referencing Docker Images — https://windsock.io/referencing-docker-images/
Docker Tagging: Best practices for tagging and versioning docker images — https://blogs.msdn.microsoft.com/stevelasker/2018/03/01/docker-tagging-best-practices-for-tagging-and-versioning-docker-images/

Also Part of this Series

WSO2 Products Dockerized: An Introduction — https://medium.com/@chirangaalwis/wso2-products-dockerized-an-introduction-5045a197befa
WSO2 Products Dockerized: Advanced Usage — Part 1 — https://medium.com/faun/wso2-products-dockerized-advanced-usage-part-1-ae255ef02661
WSO2 Products Dockerized: Advanced Usage — Part 2 — https://medium.com/faun/wso2-products-dockerized-advanced-usage-part-2-9c851b0db557
WSO2 Products Dockerized: Remote Debug Dockerized WSO2 Products with IntelliJ IDEA — https://medium.com/faun/wso2-products-dockerized-remote-debug-dockerized-wso2-products-with-intellij-idea-111ca8ae60c

Follow us on Twitter 🐦 and Facebook 👥 and join our Facebook Group 💬.

To join our community Slack 🗣️ and read our weekly Faun topics 🗞️, click here⬇