Promoting sigs.k8s.io/karpenter to package version v1.0.0

[jonathan-innis]

The Karpenter maintainer team introduced an RFC proposal in May of 2024 to propose API changes and roadmap to Karpenter v1. These changes have since been merged across the repo and the maintainer team is ready to promote the sigs.k8s.io/karpenter package tagged as v1.0.0, alongside its APIs at v1.

Why We Have Chosen to Upgrade the Package to v1.0.0

The sigs.k8s.io/karpenter package has long-been in a production-ready state for users, but has not reflected this production-ready state through its versioning scheme. Given the first initial release of v1 APIs within Karpenter, the maintainer team feels this is the best time to make the bump to v1.0.0.

This versioning scheme also allows us to stop versioning the sigs.k8s.io/karpenter package in lock-step with the aws/karpenter-provider-aws package, a practice that was legacy from a time when the sigs.k8s.io/karpenter package was owned by the AWS organization and was named aws/karpenter-core. We believe this upgrade to v1.0.0 will allow us to update our versioning to properly signal breaking and non-breaking changes to downstream integrations.

How This Affects Downstream Integrations (e.g. CloudProviders)

With this change, the sigs.k8s.io/karpenter package would now be referenced through go.mods as v1.0.0, reflecting the repo package tag. Downstream integrations (such as CloudProviders: aws/karpenter-provider-aws, Azure/karpenter-provider-azure, etc.) would need to update their go.mods to reference the new package version.

sigs.k8s.io/karpenter v1.0.0

How This Affects Our Stability Guarantees

The v1 APIs that are released alongside the v1 package upgrade will carry different guarantees than the package itself.

The v1 package itself will not have these same guarantees as the v1 APIs available inside of the package. v1 APIs released in this package are guaranteed by Kubernetes stability guarantees; package functions, struct, etc. are not. See https://kubernetes.io/docs/reference/using-api/ for more details on Kubernetes stability guidelines.

Practically, what this means is that exported methods within the sigs.k8s.io/karpenter package (including the cloudprovider interface) are subject to a breaking change within the v1.x.y major version without a bump to v2.x.y. Starting in v1.0.0, we will signal a breaking change to the sigs.k8s.io/karpenter package through a minor version bump to the package. This includes scenarios where exported functions change their signatures or interfaces/structures like the cloudprovider interface make changes that break downstream integrations. Patch version upgrades will signal non-breaking changes to the package including additional functionality or new function signatures or structs that don't affect existing integrations.

This versioning strategy follows the prior art of other Kubernetes project integrations that have gone v1.0.0, including Kubernetes itself:

1. https://github.com/kubernetes/sig-release/blob/master/release-engineering/versioning.md
2. https://github.com/kubernetes-sigs/cluster-api/blob/main/CONTRIBUTING.md#versioning

[jonathan-innis]

/triage accepted

[sftim]

Extra credit: document the stability guarantees.

[elmiko]

makes sense to me

[jonathan-innis]

Thanks folks for the feedback! v1.0.0 is out!

[jonathan-innis]

/close

[k8s-ci-robot]

@jonathan-innis: Closing this issue.

In response to this:

/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-sigs/prow repository.