Migration guide between KubeSchedulerConfig versions

[alculquicondor]

What would you like to be added

A section in this page https://kubernetes.io/docs/reference/scheduling/config/ with migration instructions between API versions (v1beta1 to v1beta2 and v1beta2 to v1beta3), similar to this https://kubernetes.io/docs/reference/using-api/deprecation-guide

Why is this needed

This is specially important after the removal of v1beta1 (kubernetes/kubernetes#104782) and the introduction of v1beta3 (kubernetes/kubernetes#104251)

Comments

The information can be recovered from release notes, although I admit they are scattered.

https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md#api-change

At least these changes are related:

• v1beta1 to v1beta2
  • Add score func for NodeResourcesFit plugin kubernetes#101822
  • custom plugin config should take precedence over default plugin config kubernetes#99582
  • scheduler CC: add v1beta2 API, deprecate plugins kubernetes#99597
• v1beta2 to v1beta3 (these would need to go in the branch for the next release)
  • Scheduling v1beta3 kubernetes#104251

[alculquicondor]

@kerthcet do you think you can take this?

FYI @damemi @ravisantoshgudimetla

[alculquicondor]

/sig scheduling

[sftim]

If there are lots of steps:

• Could we put those steps into a new page under https://k8s.io/docs/tasks/ ?
• and add a hyperlink to https://kubernetes.io/docs/reference/scheduling/config/

[alculquicondor]

The steps are 3 to 5 for each case. Does that grant a page?

[liggitt]

when considering where to put this, let's do it in a way that would make sense for something similar for v1beta2 → v1beta3 config, and v1beta3 → v1

[sftim]

when considering where to put this, let's do it in a way that would make sense for something similar for v1beta2 → v1beta3 config, and v1beta3 → v1

One page, with tabs?

Things that suggest a task:

• detailed prerequisites
• lots of steps
• potential for errors / rework / troubleshooting

Things that favor embedding in the reference page:

• one static step; if there are multiple steps, they are the kind of steps you can combine using && in a POSIX shell
• the reference docs provide lots of context for the steps in question

[sftim]

We could also consider making a whole section of tasks around upgrading. That might cover:

• some of what's in https://kubernetes.io/docs/reference/using-api/deprecation-guide/, but framed step-by-step
• how to move between different API versions for configuration files
• using kubectl convert
• how to upgrade your cluster!
• how to upgrade tools, eg kubectl

and more!

[alculquicondor]

Note that configuration files don't work with kubectl. I think they should be treated separately.

I think the changes won't make enough content for a task (at least for v1beta1 to v1beta2). It's just a handful of bullet points.

Maybe we will require a task for v1beta3 @damemi

[liggitt]

I think they should be treated separately.

I agree. The audiences are separate as well (end-users / REST API users, who are legion, vs kube-scheduler admins, which are far more rare)

[sftim]

just a handful of bullet points

Sounds like a case for leaving it in the page. We can always migrate later.

[tengqm]

I think the original proposal is as good as it stands.

[kerthcet]

@kerthcet do you think you can take this?

FYI @damemi @ravisantoshgudimetla

yeah, I can work on this if nobody assigned.

[alculquicondor]

/assign @kerthcet

[mehabhalodiya]

/triage accepted

[mehabhalodiya]

/language en

[kerthcet]

kindly reminding @mehabhalodiya , v1beta1 -> v1beta2 and v1beta2 -> v1beta3 document migration has been merged.

[mehabhalodiya]

/close

[k8s-ci-robot]

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