Cluster-api: Versioned naming schema for CAPI + providers.

[timothysc]

To the external observer it's very confusing to match versions of CAPI<>provider and to have a well crafted naming convention.

for v1alpha2+ IMO this needs to be addressed and documented so it's clear to downstream consumers.

/kind feature
/kind documentation

[timothysc]

/cc @vincepri @detiber @ncdc

[timothysc]

xref - https://github.com/kubernetes/enhancements/pull/1111

[timothysc]

So why can't we just follow v1alpha2.patchver. Or specifically

vMajor.Minor.Patch
v0.2.patch

[ncdc]

We can for CAPI. It's harder for providers since CAPA is already at 0.3 and CAPV is also at 0.3 and moving to 0.4.

As much as I hate to say it, I feel like we may need to live with mismatches across providers until we get to 1.0.

[detiber]

I think I agree that 1.0 seems like a good mark for aligning. I'm not sure that we won't be able to prevent another situation where there is a breaking change required for a provider upgrade outside of a cluster-api upgrade, though.

I think defining compatibility metadata that can be consumed by the cluster-api-operator would be a better approach to compatibility, we'd just need to define a story around disconnected environments.

[timothysc]

1.0 could be a year away, I think we'll need to have a rally point repo that follows semver matching with capi.

I'm starting capi-tools repo for cli-redux + capi-operator, that may be the only possible option for now to decrease confusion and point folks there for consumption.

[timothysc]

It might be possible to encode meaning into the first digit in the minor.
0.12.0
10's = alpha
20's = beta

In this case 0.12.0 = alpha2
It would work and be consistent and if we have 8 more minors we're in a bigger pickel.

I'm not crazy about the encoding, but I do think this makes it easier to reason about across providers, and I loath the idea of waiting a year.

[detiber]

@timothysc if we go this route, maybe it needs an extra digit to account for provider-related compat info.

0.121.0 = compat with capi 0.12x series, first release
0.122.0 = compat with capi 0.12x series, but requires intervention for provider release 0.121.y

[timothysc]

or, providers could also use the -x suffix to encode their specific patch version.

CAPI
0.12.0 = v1alpha2 - patch 0
0.12.1 = v1alpha2 - patch 1
0.21.0 = v1beta1 - patch 0

CAPA
0.12.0-0 = v1alpha2 based patch 0
0.12.0-1 = v1alpha2 based patch 1
0.21.0-2 = v1beta2 based patch 2

It's all semver legit and makes it clear.

[detiber]

@timothysc with that approach how would we encode a breaking/manual change for a provider for the same version of capi?

[timothysc]

IMO that should be in release notes, not necessarily encoded in version.
But we should generally avoid that in a world where we churn releases more frequently and enforce policy on what is allowed in patched versions. We're kind of breaking upstream policy today.

[ncdc]

@timothysc are you thinking that it's invalid for a provider to make a breaking change that is independent of a cluster-api version bump?

[vincepri]

I wouldn't mind the proposed approach to gain consistency in the ecosystem. I do see Jason's point about breaking changes.

If we go with this approach, we have to allow for providers to introduce changes between patch versions.

[ncdc]

Let's use a specific example. Let's pretend we've all agreed on a versioning scheme and we're cluster-api + the providers are aligned. In CAPA, we realized that our AWS resource tagging scheme had some issues, and we needed to revise it. There are no cluster-api changes required, but the CAPA changes are breaking changes (existing clusters/machines won't necessarily function properly unless they're "upgraded" (have their tags revised)). How do we handle this?

[neolit123]

i proposed this in a CAPI doc at some point:

I=CAPI=0.3.4
A=CAPA=0.1.7

example:
v0.3.4-0.1.7

still allows for:
v0.3.4-alpha.1-0.1.7-alpha.2

• probably the best option in terms of ease of understanding?
• versions can be bumped individually or both at the same time.
• a side effect is that this will treat all releases as pre-releases.

---

there is also the option to use dual tags in git:

• a CAPA version could be at v0.3.4, but this SHA will also be tagged with CAPI-0.1.7 to indicate that this CAPA release is bound to CAPI 0.1.7
• a bump in CAPI would require a bump in CAPA too.
• a bump in CAPA would need to also be tagged with the CAPI-... tag (even if keeping the old semver for CAPI).
• not humanly visible until someone checks the git tags.
• if all repos follow this, a hosted service/tool can be designed to fetch a CAPI version from tags.

---

also played a little with semver encoding too, but from past experience it doesn't work great.

[detiber]

@neolit123 One downside to the vA-I scheme you propose is that it assumes that a provider is only compatible with a specific patch version of CAPI rather than a specific minor version.

I really think the only way to provide the flexibility that we need is to document and publish compatibility metadata that higher level tools use for orchestrating.

[neolit123]

@neolit123 One downside to the vA-I scheme you propose is that it assumes that a provider is only compatible with a specific patch version of CAPI rather than a specific minor version.

i guess the PATCH from the CAPI can me omitted too.
if the PATCH in CAPI is still included it could mean a sync point - i.e. "latest CAPI version that is supported".

I really think the only way to provide the flexibility that we need is to document and publish compatibility metadata that higher level tools use for orchestrating.

IMHO a compatibility table would be needed in the READMEs regardless.

[detiber]

IMHO a compatibility table would be needed in the READMEs regardless.

The compatibility table should already be listed in the major providers. I'd like to see us add a requirement for machine-readable metadata for v1alpha2 at a specific subdirectory under the github repo that could then be consumed by the cluster-api-operator and other tooling to automatically download and consume providers.

[neolit123]

that would definitely be useful.

[timothysc]

How do we handle this?

I still stick by my previous statement that such a change is listed in the release notes as a breaking change, and don't try to encode it in version information b/c I've rarely seen that schema work properly. K8's doesn't follow that convention anyway and uses release notes to denote action required.

[ncdc]

The "problem" is that Kubernetes doesn't follow semver as it should re breaking changes only being allowed in new major versions.

[timothysc]

I'm still sticking with my assertions:

1 - Release CAPI more frequently
2 - Apply strict policy on what we can be backported
3 - Get religious about release notes and auto-generate those release notes to denote breaking changes.

If you do that, you sufficiently mitigate most of the risk for consumers who are downstream.

[vincepri]

Given that we're about to approach the endgame for this cycle, I'd like to propose something similar controller-runtime does.

• Each PR is split into 3 groups: ⚠️ Breaking Changes, ✨ New Features, 🐛 Bug Fixes.
• We use the "Release Note" section for any additional information we'd like to give users.
• Each release (regardless of semver), we auto-generate notes from the commits from the last release.

Even though this part ways with how Kubernetes releases today, it simplifies our releasing approach and we can make sure to communicate how we release and that breaking changes are allowed between minor versions.

We can always revisit the policy later on, when the project is more mature.

[chuckha]

This ties in with the goreleaser doc I'm writing. If we standardize on that tool for releases we at least get every commit in the release notes. IMO that should only be a starting point for the actual release notes, but it's a great place to start.

[joonas]

/milestone Next

[k8s-ci-robot]

@joonas: You must be a member of the kubernetes-sigs/cluster-api-maintainers GitHub team to set the milestone. If you believe you should be able to issue the /milestone command, please contact your Cluster API Maintainers and have them propose you as an additional delegate for this responsibility.

In response to this:

/milestone Next

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[vincepri]

@timothysc do you think we can close this given that we have clusterctl managing most of this for users?

[vincepri]

Closing for now, we can reopen later if necessary

/close

[k8s-ci-robot]

@vincepri: Closing this issue.

In response to this:

Closing for now, we can reopen later if necessary

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.