Require Transition from Beta

[deads2k]

Require Transition from Beta

• Prevent APIs from staying in beta for an extended period of time.
• Kubernetes Enhancement Proposal: https://github.com/kubernetes/enhancements/tree/master/keps/sig-architecture/1635-prevent-permabeta
• Primary contact (assignee): deads2k
• Responsible SIGs: sig-architecture
• Enhancement target (which target equals to which milestone):
  • Alpha release target (x.y)
  • Beta release target (x.y)
  • Stable release target (x.y) 1.19

1. Tags indicating when an API was introduced in beta APIs are now required: // +k8s:prerelease-lifecycle-gen:introduced=1.8. The deprecation (three releases later) and the removal (three releases after that) are automatically created in generated code to reduce toil.
2. The warning KEP will increase client-side visibility: Warning mechanism for use of deprecated APIs #1693
3. We will automatically stop serving removed code levels: stop serving deleted APIs kubernetes#90983. This particular PR can be delayed until 1.20 because there are no versions to stop serving in 1.19.

[johnbelamaric]

/assign @deads2k
/milestone v1.19
/stage stable

I am updating the enhancements team tracking sheet. David, just to confirm you still plan on getting this in for 1.19?

[johnbelamaric]

/sig api-machinery

[sftim]

If this merges lands, there's a nice-to-have enhancement I recommend to the Hugo shortcode feature-state on the website: automatically track deprecation and removal information.

[zestrells]

Hi @deads2k - My name is Zachary, 1.19 Docs shadow. Is this enhancement work planned for 1.19 and does it require any new docs (or modifications to existing docs)? If not, can you please update the 1.19 Enhancement Tracker Sheet, or let me know, I can do it for you :)
If docs are required, just a friendly reminder that we are looking for a PR against k/website (branch dev-1.19) due by Friday, June 12, it can just be a placeholder PR at this time. Let me know if you have any questions!

[sftim]

Oh, by the way, I started drafting a blog post about this.

[zestrells]

Hi @deads2k - Just a reminder that docs placeholder PR against dev-1.19 is due by June 12th. Does this enhancement require any changes to docs? If so, can you update here with a link to the PR once you have it in place? If not, please update the same, so that the tracking sheet can be updated accordingly. Thanks!

[sftim]

(I'd expect to see a PR updating https://kubernetes.io/docs/reference/using-api/deprecation-policy/ and possibly also https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning)

[johnbelamaric]

This is a policy about how long something can be in the system before being deprecated. It actually doesn't change anything about the deprecation policy described in that document. I don't think this needs user-facing documentation. It's more of a policy for the development process.

That is, everything in the versioning and deprecation policy documents stay the same. What changes is how the decision is made as to when to deprecate an API that is languishing. Previously, it was arbitrary; now, there is a policy. When it actually is deprecated, those documents kick in, just as they are today.

Functionally, I believe @deads2k is adding some metadata to the APIs to provide a "deprecated as of release X" indicator. This would then be used by #1693 which absolutely needs docs.

[kikisdeliveryservice]

Hi @deads2k

To follow-up on the email sent to k-dev on Monday, I wanted to let you know that Code Freeze has been extended to Thursday, July 9th. You can see the revised schedule here: https://github.com/kubernetes/sig-release/tree/master/releases/release-1.19
We expect all PRs to be merged by that time. Please let me know if you have any questions. 😄

Best,

Kirsten

[sftim]

I don't see a need for user facing documentation about the requirement either.
I would like to blog about the change though to let people know that assumptions about “beta” APIs might no longer hold.

• I mean, on the main Kubernetes blog.

[palnabarun]

Hi @deads2k 👋, I see that kubernetes/kubernetes#90983 was filed in relation to this enhancement. However, there has been no progress on that PR since some time. Do you think that the PR will be merged by the Code Freeze on Thursday, July 9th?

Thank you. 🙂

---

Code Freeze begins on Thursday, July 9th EOD PST

[deads2k]

kubernetes/kubernetes#90983. This particular PR can be delayed until 1.20 because there are no versions to stop serving in 1.19.

The rest of the required pieces have landed and the deprecation clocks have all been set. This in combination with the warning KEP will clearly notify users of the risk.

[sftim]

@deads2k I opened a WIP pull request to announce the new policy in a blog post: kubernetes/website#21274

It sounds like this KEP is looking likely to move forward. If that is right let me know and I'll put more work into the announcement / look for people to collaborate on details.

Update: I revised it.

[kikisdeliveryservice]

Hi @deads2k

Enhancements Lead here. Is there any further work intended for this in 1.20? I am unclear as to whether this is stable yet or not. Could you please clarify the state?

Thanks!
Kirsten

[kikisdeliveryservice]

Hi @deads2k @johnbelamaric

Will this be done in 1.20? Enhancements Freeze is October 6th, so please let me know.

Given the context, this doesn't seem like it needs test plans or graduation criteria, correct? We'd just need to track this and have some sort of docs /comms update?

Thanks,
Kirsten

[sftim]

Would be good to see docs updates around the deprecation policy - see #1635 (comment)

[sftim]

Maybe on https://kubernetes.dev/ now that's a thing?

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[deads2k]

This was implemented back in 1.19 and has not changed since. The automatic removal made it slightly easier to enforce, the policy is the same. I've updated the KEP to show the individual steps to mechnically make the transition in #2293 . Closing since this is done.

/close

[k8s-ci-robot]

@deads2k: Closing this issue.

In response to this:

This was implemented back in 1.19 and has not changed since. I've updated the KEP to show the individual steps to mechnically make the transition in #2293 . Closing since this is done.

/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/test-infra repository.

[liggitt]

(I'd expect to see a PR updating https://kubernetes.io/docs/reference/using-api/deprecation-policy/ and possibly also https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning)

opened kubernetes/website#36663