Proposal: Immutable image tags

[loozhengyuan]

Context

As seen in #33, some of us were caught off guard by a recent commit that made changes to the container's behaviour while keeping the same image tag. Issue #33 discusses the actual problem that caused the pgbouncer to crash but this issue focuses on preventing such changes from making its way into our production systems even though we've pinned the image tags.

Proposal

Currently, the project already provides semver-compliant image tags mapped to the specific pgbouncer versions (e.g. 1.15.0, 1.14.0). However, since edoburu/pgbouncer is a project that provides container images for the upstream pgbouncer project, changes (sometimes breaking) may be occasionally required.

One way we can do this is to roll our own semver-compliant versioning scheme but this can be confusing to new users (thinking that these are the corresponding pgbouncer versions) and they do not allow us to track a specific pgbouncer version, say 1.14.0 for example.

As such, I'm proposing to use a modified, 4-component versioning format:

X.Y.Z.V

• where X.Y.Z is the regular semver of the pgbouncer version
• where .V is the incremental version used by edoburu/pgbouncer for any changes to the Dockerfile.

For example, whenever a change is made to the Dockerfile or the entrypoint script, we will bump the last component of the version:

• 1.15.0.1 -> 1.15.0.2
• 1.14.0.1 -> 1.13.0.2
• 1.13.0.1 -> 1.13.0.2
• 1.12.0.1 -> 1.12.0.2

Using this proposed versioning scheme, at least we can ensure that all edoburu/pgbouncer image tags are immutable.

Limitations

• The proposed versioning scheme does deviate from being semver-compliant
• Immutable image tags are already possible but the current image tags give a false sense of immutability

[jflambert]

Hi @loozhengyuan!

I fully agree with you, the current tagging system is a bit barebones, and yes it really should be immutable. Unless you're using latest you should never have to deal with "new" images once you're locked into a tag.

An alternative would be v1.17.0-p0 where the first part is pgbouncer, and the -p part gets incremented which each "release". I think p stands for patch, I've seen timescaledb-ha use it. I also see k3s using a similar format such as v1.24.3+k3s1 where v1.2.4 is kubernetes itself, and the second part gets reset with each new kubernetes release.

And then each release would get documented as well. I'll be looking into it, just not immediately. Will keep you posted!

[loozhengyuan]

@jflambert Thanks for looking into this! Although I no longer work with docker-pgbouncer, I think many others would appreciate the work done to improve the existing tags. The format you proposed looks neat and is more preferable IMO since it is more semver-compliant than what I had earlier suggested.

[jflambert]

For now I'll manually tag patches as such:

edoburu/pgbouncer:vY-pX

where Y is pgbouncer itself and X is docker-pgbouncer