Version tagging

[warrenvw]

Version Tags

Problem Statement

Today, the versioning semantics of the stackstorm/stackstorm docker image do not meet the requirements of all users. In particular, whenever we merge changes to the st2-docker:master branch, CircleCI builds and deploys two images to docker hub. The first image has a version tag based on the most recent git tag in the st2-docker repo, and the second image has a version tag equal to latest. The problem is that the former image changes fairly regularly - which is not desired. The recommendation is that images with a semver-based version tag should be immutable.

With immutable images, it is important to consider how to version security updates (or more generally, patches) to files not provided by the st2 packages. For example, if there's a security flaw in a a system library provided by the underlying OS, then it should be possible to update the image without having to wait for the next version of StackStorm.

Another problem is that the nightly dev images do not have a latest version tag, or any means of retrieving older versions of the dev image using a version tag.

Proposed Solution

An image with a version tag equal to a semver (e.g. 2.5.0) must now be immutable. A version tag
equal to a two digit number (e.g. 2.5) is always mutable and guaranteed to point at the most recent 2.5-based image. Likewise, a version tag equal to latest is always mutable and contains latest changes merged to the st2-docker:master branch.

If a security update/patch is required for an immutable image, we take the version tag of the immutable image and append .nnn, where nnn is a three digit number beginning at 001. This is done in a manner similar to that used by vim. The two digit version tag is updated to point to this image before deploying to docker hub.

We propose creating a new image named stackstorm-dev which always uses the latest unstable StackStorm packages. The semantics of the version tags described in the previous paragraph now apply to both the stackstorm and stackstorm-dev images. However, instead of using a semver to tag the nightly stackstorm-dev image, we propose using the date instead.

While it would be simpler to deploy the stackstorm image from only the master branch, at some point we may need to use a release branch. Can we get away with only branching when required? If a backward incompatible change is made to the Dockerfile, then branch so prior versions do not pick up the change.

Specifying an Image

If a specific image is required, it is best to be explicit. For example:

stackstorm/stackstorm:2.5.0@{4e0e5869e784}

This way, even if the image tagged 2.5.0 ever changed, you would still get the image with the specified hash.

Details

To clear up any potential confusion regarding versioning of the stackstorm/stackstorm image,
we use the following table.

For sake of example, assume that 2.5.0 is the latest stable StackStorm version.

Image:Tag	StackStorm Version	Description
stackstorm:dev	2.6dev	Latest 2.6dev, and most recent changes to st2-docker:master.
stackstorm:latest	2.5.0	Changes merged to st2-docker:master branch will result in a new image being deployed.
stackstorm:2.5	2.5.0	Most recent immutable 2.5.x release
stackstorm:2.5.0	2.5.0	Immutable, even if changes merged to st2-docker:master
stackstorm:2.4.1	2.4.1	Immutable, even if changes merged to st2-docker:master
stackstorm:2.4.0	2.4.0	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.2	2.3.2	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.1	2.3.1	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.0	2.3.0	Immutable, even if changes merged to st2-docker:master

[arm4b]

• For the development version, I think just stackstorm:dev would be enough as it was before and avoid overcomplication. There are usually very few reasons someone will need previous development version of stackstorm. Let's focus on most used & popular cases.
• Same for stackstorm:2.4.1.001, - looks very confusing, - I'd suggest to avoid this too and keep it simple as possible. Your approach with latest tag already solves the security/patching issue.
• I definitely like the way with major.minor version like stackstorm:2.4 pointing to 2.4.1 or 2.4.2, depending on current released StackStorm patch version 👍

[shusugmt]

@armab

Same for stackstorm:2.4.1.001, - looks very confusing, - I'd suggest to avoid this too and keep it simple as possible. Your approach with latest tag already solves the security/patching issue.

:2.5.0 and :latest(actually it is st2 2.5.0, assuming that it is the latest st2 release version at this point) will be different if there's any breaking change merged into st2-docker after the upstream release of 2.5.0 and first :2.5.0 image is out. Of course same applies to the case with security patch. Is that really

"solves the security/patching issue"

?

I 1000% agree with not having so many tags here, but :2.5.0-nnn is still needed if we apply the policy of making :2.5.0 image immutable.

[arm4b]

Let's clarify what means "security patch" and plans about the case.

Every software becomes unsync/outdated quickly. When there is a vulnerability found in any other software (say base image which is ubuntu:trusty for stackstorm), does it mean you're going to release a patch to all possible "old" and affected versions of StackStorm docker images?
Another question: do we have any real mechanism in place of tracking the security-affected software in StackStorm images and plan to go this path consistently to track/re-release new Docker image? Is it really a problem we're trying to solve?

At StackStorm/st2 we're not doing any back-porting, but instead release a new version and ask users to update. Giving that you have latest tag in place, - that'll give you a solution and additionally encourage users to update.

Pragmatically speaking, it's good to think about it early, but I'd suggest to wait and time shows if you'll really need someday that additional tag suffix.

[shusugmt]

I get your point. Dealing with all security issues is impossible.

At StackStorm/st2 we're not doing any back-porting, but instead release a new version and ask users to update. Giving that you have latest tag in place, - that'll give you a solution and additionally encourage users to update.

So, let me clarify this part. After we fix the tagging policy, all enhancements and fixes made against st2-docker will not available to current latest release image (:2.5.0 for example) because it's immutable after the upstream release. Those are treated as 2.6dev like other core components, and once upstream releases 2.5.1 (or 2.6.0) then all those will be included in :2.5.1. This way we can keep track of the changes in st2-docker with upstream release, and make it easier for both users and maintainers/developers to know what change was made to docker image between the st2 releases.

Am I right?

[warrenvw]

@armab No, we don't have a mechanism in place right now for tracking security vulnerabilities. We can revisit this if and when this becomes an issue. In the meantime, there's nothing stopping users from building their own image as frequently as desired, and based on a specific version of st2.

@shusugmt Yes, that's my understanding.

So then, summarizing the above discussion:

Image:Tag	StackStorm Version	Description
stackstorm:dev	2.6dev	Latest 2.6dev, and most recent changes to st2-docker:master.
stackstorm:latest	2.5.0	Changes merged to st2-docker:master branch will result in a new image being deployed.
stackstorm:2.5	2.5.0	Latest 2.5.x release
stackstorm:2.5.0	2.5.0	Immutable, even if changes merged to st2-docker:master
stackstorm:2.4.1	2.4.1	Immutable, even if changes merged to st2-docker:master
stackstorm:2.4.0	2.4.0	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.2	2.3.2	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.1	2.3.1	Immutable, even if changes merged to st2-docker:master
stackstorm:2.3.0	2.3.0	Immutable, even if changes merged to st2-docker:master

[arm4b]

Looks good to me 👍
Let's also update the table in the first message and leave it here for a while so other users will have a chance to comment on the approach before actual implementation and VERSIONING.md documentation.

[warrenvw]

I've updated the first message...

[shusugmt]

missing stackstorm:2.4 (and stackstorm:2.3 too) in table? Do we explicitly delete those tags after the release of stackstorm:2.5.0?

[warrenvw]

They're not in the table because I'd planned to enable two digit tags beginning with stackstorm:2.5. It's very unlikely we'll ever release a new release < 2.5

[shusugmt]

Ah, you are right.

We should add to description of :2.5 like something below:
Latest 2.5 release. Will not be updated (or become immutable?) after the release of new minor version (2.6.0 in this case)

[warrenvw]

My view is that it should not become immutable. After 2.6.0 is released, it is technically possible there could be another 2.5 release... although extremely unlikely.

[shusugmt]

I see. Certainly it is possible that upstream will release 2.5.3 after 2.6.0 release.