Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document Kubernetes API policy #1642

Merged
merged 4 commits into from
Oct 22, 2020
Merged

Document Kubernetes API policy #1642

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fc314de
Document Kubernetes API policy
Aug 17, 2020
1ff71b7
Clarify that server APIs are targeted
Sep 7, 2020
e218299
Add supported Kubernetes versions to release drafter.
Oct 21, 2020
8156f97
Merge branch 'main' into nfnt/doc-kubernetes-apis
Oct 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions development.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member Author

@nfnt nfnt Aug 18, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, and this is developer-facing, not user facing.... So, I'm not sure if we need to change anything here?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. needs to support CRDs (version 1.15+) (there are earlier versions but the crd support was too influx IMO)
  2. 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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Functionality using APIs that don't conform to this rule should be placed behind a feature gate.

## Running Locally

These details will show using kind as a local kubernetes cluster. These instructions should work with minikube as well.
Expand Down