kubernetes-client/java: the official Java client, and its versioning story

What it is and what it is not

The README is one line of description: Java client for the Kubernetes API. Everything operational is a wiki link, and the wiki is structured in numbered pages covering installation, client versioning and compatibility, code examples, development and contributing, generating Java CRD models, known issues and a troubleshooting FAQ.

That structure tells you what the project considers its own hard problems. Installation is a solved problem. Versioning is not, because the client has to track Kubernetes itself while staying usable by applications that update on their own schedule. The known issues page existing as a distinct document is a sign that most real support questions are version-specific.

The badges at the top of the README place the project on Maven Central under the `io.kubernetes` group with the `client-java` artifact, plus a Sonatype snapshot badge for the snapshot repository. The default branch is `master`.

A useful detail is the CRD model generation page. Since Kubernetes clusters hold custom resources defined by CRDs, a Java client that only knows the built-in types is only half useful, and the project treats generating Java models for a custom resource as a documented, supported task rather than something users improvise.

The 20.0.0 breaking change that splits the user base

The README has a short Release section that deserves more attention than it gets. Starting from version 20.0.0, corresponding to Kubernetes 1.28, the `client-java-api` module introduced non-backward-compatible changes: optional parameters are consolidated into a single object, and Java 8 support was removed.

A library that removes a Java version and reorganizes its parameter model at the same time is a real migration, not a version bump. Anyone on Java 8 is given an explicit escape hatch rather than a soft warning: a legacy SDK module version is available with a `-legacy` suffix, for example `20.0.0-legacy`, for Java 8 users or anyone preferring the old SDK interface.

That dual-line arrangement is the pattern to understand. From 20.0.0 onward there are two supported shapes of the same client, one modern and one frozen in the older interface. It means the fix for an old deployment is a version pin rather than a code rewrite, and it means the maintainers are carrying two API surfaces.

For a new integration, there is no reason to choose the legacy line. For an existing one, the question is whether upgrading buys anything, which is a dependency decision rather than a technical one.

Version numbers that track Kubernetes minor releases

The release tags run v26.0.0 on 2026-03-30, v26.0.1 on 2026-06-10 and v27.0.0 on 2026-07-01. The wiki page on client versioning and compatibility is the place this is documented in full.

What the tags themselves show is a straightforward correspondence with Kubernetes. Version 20.0.0 was Kubernetes 1.28, so v27 is a few Kubernetes versions further along on the same counter.

A detail in the release notes is worth flagging rather than glossing over. The v27.0.0 and v26.0.1 notes are identical: the same pull request list, down to the same dependabot bumps for the Google auth library, the AWS STS SDK, commons-io, spring-test, protobuf and Spring Boot. The first line of both explains why, noting that PR generation is still not working so the 22.0.0 release changes were cloned manually by the maintainer.

The pull request numbers tell the rest of the story. The v27.0.0 and v26.0.1 notes reference pull requests in the 3780s, while v26.0.0 references pull requests in the 4270s. The newer tags carry notes generated from an older snapshot of history, which is what a manual clone of release changes produces. Read those two release notes as approximate rather than as an exact account of what changed in each version.

What the release cadence says about the dependency surface

Look inside the v26.0.0 notes and almost every line is a dependency update: the Maven javadoc plugin, mockito-junit-jupiter, the AWS STS SDK, assertj-core, the Maven compiler plugin. The single non-dependabot line is a replacement of a deprecated nexus URL with a new endpoint.

That is the shape of maintaining a client library against a platform whose own dependencies move constantly. The Java client sits on the Kubernetes API, on client-go equivalents expressed as generated models, on protobuf, on Jackson-style JSON handling, and on cloud provider SDKs for the credential paths. Every one of those has its own release schedule, and a client release is often just the moment the maintainers found the time to absorb the movement.

The Spring Boot bump in the v27 notes, from 3.3.5 to 3.4.0, shows the same thing in a second direction. The client offers Spring integration, so the Spring release cadence pulls on this project too.

Repository metadata reads consistently with steady rather than intense activity: 4,001 stars, 20 open issues, not archived, last push on 2026-09-23. The fork count is the outlier, at 2,109, roughly half the star total, which is what you would expect from an artifact that corporate platform teams vendor and modify internally rather than depend on directly.

Where the documentation actually lives

The README links seven numbered wiki pages and stops. Installation is on page one, versioning and compatibility on page two, code examples on page three, and the contributor-facing pages follow, including CRD model generation, known issues and an FAQ.

For a library this old and this widely embedded, the known issues page is often the most useful document in the list. Client libraries accumulate a long tail of behaviours that surprise people, such as how resource version conflicts surface, how watches behave against a cache, and how a generated model handles a field the server added after your client was built. Those are not documentation gaps so much as accumulated facts.

The wiki arrangement does have a cost. GitHub wikis are less versioned than the repository, so a page can change without appearing in a diff. For a project where version compatibility is the main source of confusion, that is an unusual place to keep the compatibility guidance, which is why the README points at page two by name rather than folding the key facts into itself.

There is also no runnable code aimed at users in the README. The only command block is for maintainers, updating the Maven project version across all pom files, including the optional `fluent-gen` module:

./scripts/update-version.sh 28.0.0-SNAPSHOT

The helper delegates to the Maven Versions Plugin, and the README gives the equivalent Maven invocation for anyone who would rather run it directly.

Editorial conclusion

This is the client to reach for when you are writing Java against a Kubernetes API, because it is the one the project itself ships rather than a community wrapper. The decision that needs care is the version line: since 20.0.0 the client has dropped Java 8 and consolidated optional parameters into a single object, so an existing integration either moves or pins a legacy module. Version 27.0.0 is the current tagged release, dated 2026-07-01. Start with the versioning and compatibility wiki page before choosing a version, since that is the page that settles the question.

Frequently asked questions

Official sources

1. kubernetes-client/java on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases