Bug 1443588

Summary: [DOCS] Document OCP image versioning policies
Product: OpenShift Container Platform Reporter: Marko Myllynen <myllynen>
Component: DocumentationAssignee: brice <bfallonf>
Status: CLOSED CURRENTRELEASE QA Contact: Marko Myllynen <myllynen>
Severity: low Docs Contact: Vikram Goyal <vigoyal>
Priority: medium    
Version: 3.5.0CC: aos-bugs, bfallonf, cpatters, erich, jokerman, jswensso, misalunk, mmccomas, myllynen, tdawson
Target Milestone: ---Keywords: Reopened
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: 2017-06-16 05:57:53 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:

Description Marko Myllynen 2017-04-19 14:07:11 UTC
OCP images have different version tags like:

openshift3/registry-console                       3.3
openshift3/registry-console                       3.3-10
openshift3/registry-console                       latest
openshift3/registry-console                       v3.3
openshift3/registry-console                       3.4
openshift3/registry-console                       3.4-6
openshift3/registry-console                       v3.4

We should document the versioning policy to allow users to understand what are all these tags used for and which one to use for example when constructing the advanced installation inventory file.

Thanks.

Comment 1 Troy Dawson 2017-04-19 15:08:41 UTC
Here is the policies for the versions:

latest - as well as no tag (which defaults to latest) :
**Users and scripts should not use the latest tag when dealing with openshift images**
Reason:  There are many openshift images with the same name, but for different versions of openshift.  When any of these images are uploaded to the registry, they are tagged 'latest'.
We still support older versions of OpenShift, so we are constantly updating those images.  Thus, the image marked "latest" could be for a 3.3, 3.4 or 3.5 version.
Again, do not use the "latest" tag.

v3.5, v3.4, v3.3, - v<short-version number>
These tags are what users or scripts should use to get the latest image for a specific version of openshift.
In the example above, the v3.4 tag, currently points to 3.4-6.  If we were to update the registry-console image, the v3.4 tag would change to point to that new tag (example: v3.4 -> 3.4-8)

Here is a different example that will help explain the other tags better than the above version.

openshift3/logging-fluentd 3.3.0
openshift3/logging-fluentd 3.3.0-20
openshift3/logging-fluentd 3.3.1
openshift3/logging-fluentd 3.3.1-2
openshift3/logging-fluentd 3.3.1-7
openshift3/logging-fluentd v3.3
openshift3/logging-fluentd 3.4.0
openshift3/logging-fluentd 3.4.0-11
openshift3/logging-fluentd 3.4.1
openshift3/logging-fluentd 3.4.1-2
openshift3/logging-fluentd 3.4.1-6
openshift3/logging-fluentd v3.4

3.3.0, 3.3.1, 3.4.0, 3.4.1 - <full version number>
This points to the latest image for that version.  This gets changed with each update, just like the v3.4 does.
In the above example, 3.4.1 points to 3.4.1-6.  If there was an update to 3.4.1, it would change to point to that tag.  (example: 3.4.1 -> 3.4.1-8)

3.4.0-11, 3.4.1-2, 3.4.1-6 - <full version number>-<release number>
These tags are unique and do not change.  3.4.1-2 should always have the same shasum and should never change.
In short, these are the images/tags, that all other tags point to.

Comment 2 Marko Myllynen 2017-04-19 15:14:03 UTC
Thanks Troy, excellent info - I think the only missing piece anymore is the difference between v3.4 vs 3.4 (which actually seems to be present only for some images).

Comment 3 Troy Dawson 2017-04-19 15:35:47 UTC
That's why I picked that second example.
In the original example 3.4 is the full version number, which makes it a little confusing because v3.4 is also pointing to the same thing.
Having examples with longer version numbers makes for better examples.

Comment 5 Marko Myllynen 2017-04-27 09:35:37 UTC
(In reply to Troy Dawson from comment #1)
> 
> latest - as well as no tag (which defaults to latest) :
> **Users and scripts should not use the latest tag when dealing with
> openshift images**
> Reason:  There are many openshift images with the same name, but for
> different versions of openshift.  When any of these images are uploaded to
> the registry, they are tagged 'latest'.
> We still support older versions of OpenShift, so we are constantly updating
> those images.  Thus, the image marked "latest" could be for a 3.3, 3.4 or
> 3.5 version.
> Again, do not use the "latest" tag.

We should underline that the above is specifically about OpenShift images; for example during containerized installation we still get rhel7/etcd:latest. Thanks.

Comment 8 brice 2017-05-09 05:17:51 UTC
I've created the following for this BZ:

https://github.com/openshift/openshift-docs/pull/4374

Marko, Troy, can I ask for a review that this is what you're asking for?

But also, with using the `latest` tag, should we be advising against that altogether? When saying "don't use this with OpenShift images" can we get more specific?

Thanks!

Comment 10 Troy Dawson 2017-05-09 15:00:50 UTC
As for being specific, I can't speak for more than the official OCP images, which start with openshift3/<name>
The other images coming from OpenShift Origin and CentOS, may, or may not be tagged in a similar fashion as OCP.  But I believe they will still have a "latest" issue, unless they do some other way of tagging latest.

Comment 11 Marko Myllynen 2017-05-10 09:06:08 UTC
(In reply to brice from comment #8)
> I've created the following for this BZ:
> 
> https://github.com/openshift/openshift-docs/pull/4374

I think this looks good, perhaps one sentence of the purpose / the need for having both vX.Y and X.Y.Z tags might be helpful but even without those this is very helpful. Thanks!

Comment 12 brice 2017-05-11 05:13:17 UTC
Troy, Marko.

Thanks. I've updated the PR with a few more points. If you have any suggestions, please let me know.

Comment 13 openshift-github-bot 2017-05-17 04:41:43 UTC
Commit pushed to master at https://github.com/openshift/openshift-docs

https://github.com/openshift/openshift-docs/commit/8a4f904a7ed4c0c313775fb8d2f1222840289cde
Merge pull request #4374 from bfallonf/versions_1443588

Bug 1443588 Added info on image tag policy