Document Kubernetes API policy #1642
Conversation
This has been debated in several PRs and meetings, let's have it written down as part of our development guidelines. Signed-off-by: Jan Schlicht <jan@d2iq.com>
nfnt
requested review from
alenkacz,
gerred,
kensipe and
zen-dog
as code owners
development.md
Outdated
| @@ -31,6 +31,11 @@ The follow are a list of tools needed or useful in order to build, run, test and | |||
| * [ngrok](https://ngrok.com/) - This is currently needed for full debugging. We are looking at alternatives. It does require signing up for this service. | |||
| * [kubebuilder](https://github.com/kubernetes-sigs/kubebuilder) - Binaries for `kube-apiserver` and `etcd` from kubebuilder are used for integration testing. | |||
|
|
|||
| ## Supported Kubernetes versions | |||
|
|
|||
| Use of Kubernetes APIs is limited to APIs supported by the current version of Kubernetes at the time of a KUDO release following its [version skew policy](https://kubernetes.io/docs/setup/release/version-skew-policy/). E.g., for a version of KUDO released while Kubernetes 1.18 is current, only APIs that are supported in Kubernetes 1.16, 1.17 and 1.18 can be used. | |||
There was a problem hiding this comment.
I think all this should be still tight to a KUDO release though. If I update KUDO I don't want to check if at the time when it was released maybe also new k8s release was released thus my 1.15 cluster might not work with KUDO anymore. I think every KUDO release version should explicitly note the minimal kubernetes version.
There was a problem hiding this comment.
How about mentioning which version of Kubernetes KUDO was built against in the version command? And let's mention the Kubernetes version in our release notes. E.g., "This version of KUDO is built against the Kubernetes 1.18 API and compatible with Kubernetes clusters 1.16-1.18".
There was a problem hiding this comment.
yeah I like that. My comment was just that this mention kind of implies that one has to watch the k8s releases by themselves and align it with KUDO releases, I think that should not be the case.
Maybe we can reword it just a bit and say that this is our overall policy but to know exactly which versions are supported you have to do XXX. For now we can at least mention it on the release page for the latest release, having it in CLI would be also super nice.
There was a problem hiding this comment.
I've looked into this and opened a PR #1671 that shows the used k8s API version. I'm not sure what kind of wording we should use here though. We could mention that kudo version will show you the used API version...
There was a problem hiding this comment.
Oh, and this is developer-facing, not user facing.... So, I'm not sure if we need to change anything here?
There was a problem hiding this comment.
I have concerns around wording... which ties to the PR mentioned by @ANeumann82 . There are several topics that come to mind regarding kubernetes versions which includes:
- kubernetes API
- kubernetes client
- kubernetes server
@ANeumann82 mentions "k8s API version". I'm not sure I know exactly what that means... each kind in the API has it's version... I'm guessing for this conversation we are tying together all the APIs for a version of kubernetes... I also imagine in so do we are ignoring feature flags and extensions. The challenge to this is that the server version is the version that determines the APIs... not the client version (which seems to the the version in the PR)
I love @alenkacz recommendation on each release providing a matrix of support.
What most significantly matters for KUDO users IMO, is KUDO is based on a version of client-go. The client-go version that KUDO uses defines the constraint. The version matrix is already defined by client-go here: https://github.com/kubernetes/client-go#compatibility-matrix
based on all this... I would say that KUDO is constrained to k8s versions based on 2 factors:
- needs to support CRDs (version 1.15+) (there are earlier versions but the crd support was too influx IMO)
- the linked client-go version
The linked client-go version should be advertised for each release and the understanding of compatibility should be pushed to the client-go website.
There was a problem hiding this comment.
All very good points, I'll reword this section to distinguish between client and server API. IMO, both are important here, like you mentioned @kensipe, but there's more than just a constraint to support CRDs on the server. We need to be clear on what features we are able to support without feature flags and when to change APIs that have been deprecated. Here, CRDs are a good example: Since Kubernetes 1.16, there's a v1 CRD API. The v1beta1 API that KUDO currently uses is deprecated since Kubernetes 1.19. We developers need to decide when to change our CRDs from v1beta1 to v1. I.e. our features work is constrained by the version of the Kubernetes server API we want to target.
Signed-off-by: Jan Schlicht <jan@d2iq.com>
Signed-off-by: Jan Schlicht <jan@d2iq.com>
Signed-off-by: Jan Schlicht <jan@d2iq.com>
What this PR does / why we need it:
This has been debated in several PRs and meetings, let's have it written down as part of our development guidelines.