Skip to content

Stability#

Client Support Level; Stable

kube satisfies the client level requirements for a Stable Client.

Platform Support Level#

Our support level is determined by our continuous integration.

Github Actions continually builds and tests kube against the LTS supported environments for Ubuntu, and macOS, and Windows:

Support Source Guarantee Upstream Policy
supported Linux ubuntu-latest 2 years
supported Windows windows-latest 3 years
supported macOS macos-latest 1 year

Kubernetes Distribution Support#

We follow upstream api-conventions and is designed to work for any Kubernetes conformant distribution.

Apart from a single upstream deprecated auth plugin for GCP (that we maintain compatibility for), all kube logic is otherwise distribution agnostic.

For version compatibility against EKS, GKE, AKS, you may cross-reference with our kubernetes-version policy (designed to match their lifecycles).

Interface Changes#

Public interfaces from kube is allowed to change between minor versions, provided github release & changelog provides adequate guidance on the change, and the amount of user facing changes is minimized and trivialised. In particular:

  • PRs that perform breaking changes must have the changelog-change label
  • changes needed to user code should have a diff code comment on the change
  • changes as a result of interface changes should be explained
  • changes that affect controller-rs or version-rs, should link to a fixing commit
  • renamed functions/changed arguments/changing imports, should show what to search/replace in the PR
  • changes to experimental features using #unstable-features should have an unstable label

We prefer deprecations and duplication of logic where it avoids confusion.

Deprecation Strategy#

Altered methods/fns/constants should in general not be changed directly, but instead have a new alternative implementation introduced to avoid users receiving confusing compile errors.

New variants should have a new name, and the old variant should remain with a deprecation attribute that can guide users towards the new behaviour before the deprecated variant disappears.

Deprecation Duration

Deprecated functionality must stick around for at least 3 releases.

For instance, we deprecated runtime::utils::try_flatten_applied in 0.72.0:

/// Flattens each item in the list following the rules of [`watcher::Event::into_iter_applied`].
#[deprecated(
    since = "0.72.0",
    note = "fn replaced with the WatchStreamExt::applied_objects which can be chained onto watcher. Add `use kube::runtime::WatchStreamExt;` and call `stream.applied_objects()` instead. This function will be removed in 0.75.0."
)]
pub fn try_flatten_applied<K, S: TryStream<Ok = watcher::Event<K>>>(
    stream: S,
) -> impl Stream<Item = Result<K, S::Error>> {
    stream
        .map_ok(|event| stream::iter(event.into_iter_applied().map(Ok)))
        .try_flatten()
}

Internal usage of this function was removed when it was deprecated, but it is kept in place as a convenience to people upgrading for at least 3 versions.

The deprecation note must point out viable alternatives, and must point out the scheduled removal version.

Unstable Features#

When adding new, experimental functionality, we export them through optional features that must be explicitly enabled.

These features are opt-in using cargo features, and can be enabled from your Cargo.toml:

kube = { version = "0.80.0", features = ["runtime", "unstable-runtime"] }

Functionality released under unstable features can change between any version and are not subject to any of the usual guarantees.

Feature Selection vs. Compile Flags#

We acknowledge that using features selection for unstable functionality does come with the downside that users can sometime have these features selected for them through intermediary crates that also depend on kube.

Tokio for instance, instead relies on compile flags due to this possibility, even though it is slightly more awkward for users.

For kube, our position is more frequently a direct application dependency rather than as another library building-block. Thus, we feel the possibility of unstable features being accidentally enabled for end-users to be low enough to not warrant the extra hassle of using compile flags.

That said, library publishers that depend on kube should only publish unstable kube behavior under their own unstable feature sets, or in pre-1.0 crates.

Feature Exporting#

Features are exported by each crate initially;

E.g. from kube-runtime:

kube-runtime/Cargo.toml
18:unstable-runtime = ["unstable-runtime-subscribe"]
19:unstable-runtime-subscribe = []

then the major feature is re-exported from kube:

kube/Cargo.toml
31:unstable-runtime = ["kube-runtime/unstable-runtime"]

Major Release 1.0#

While our codebase is heavily stabilising, and we officially satisfy the upstream requirements for stability, we have not released a 1.0.0 version yet. Why is that?

Firstly, there are a handful of major features we would like to have in place first as they could influence some of our main interfaces:

  1. protobuf serialization layer is WIP
    a). This is likely to force new features (possibly making k8s-openapi opt-in)
    b). This might require core traits to be moved out of kube-core
  2. Client Api Methods is WIP
    a). This might require some re-work of the dynamic api
    b). This might change how we advertise how users should use our kube-client (though we are unlikely to ever remove Api)
  3. Controller runtime features for stream sharing are WIP
    a). This is being tested out through unstable features
    b). Controller signatures might need tweaking to accommodate these

Secondly, our api surface mirrors a huge chunk from from upstream Kubernetes (which does have some freedom to change). Breaking changes on such a large surface does occasionally happen, but increasingly on peripheral and experimental parts of the codebase.

Thirdly, some external concerns:

  • we depend on pre-1.0 libraries and upgrading these under semver would technically force major bumps
  • the public async iterator interface is still being stabilised in rust

Because of these conditions we do not have a planned release date for 1.0.0, but it is being discussed separately.

Summary#

As a brief summary to these policies and constraints, our approach to stability is to: