Improve scheduler CLI description

[dharmab]

What type of PR is this?

Uncomment only one /kind <> line, hit enter to put that in a new line, and remove leading whitespace from that line:

/kind api-change
/kind bug
/kind cleanup
/kind deprecation
/kind design

/kind documentation

/kind failing-test
/kind feature
/kind flake

What this PR does / why we need it:

This PR adds a few explanatory sentences to the kube-scheduler CLI description (which is in turn used to generate the documentation website). To understand why this is needed, let's look at the first few lines of the documentation for other core CLI components from the perspective of a new user or contributor:

The kubelet is the primary “node agent” that runs on each node.

The Kubernetes network proxy runs on each node. This reflects services as defined in the Kubernetes API on each node and can do simple TCP, UDP, and SCTP stream forwarding or round robin TCP, UDP, and SCTP forwarding across a set of backends.

The Kubernetes controller manager is a daemon that embeds the core control loops shipped with Kubernetes.

The Kubernetes API server validates and configures data for the api objects which include pods, services, replicationcontrollers, and others. The API Server services REST operations and provides the frontend to the cluster’s shared state through which all other components interact.

So far, not bad. Some of the descriptions are a little wordy, but in general from reading the first one or two sentences, a new user reading the docs has a basic idea of what each component does.

What about kube-scheduler?

The Kubernetes scheduler is a policy-rich, topology-aware, workload-specific function that significantly impacts availability, performance, and capacity. The scheduler needs to take into account individual and collective resource requirements, quality of service requirements, hardware/software/policy constraints, affinity and anti-affinity specifications, data locality, inter-workload interference, deadlines, and so on. Workload-specific requirements will be exposed through the API as necessary.

This... is very confusing. A new user reading this doesn't learn what the scheduler actually does, just that it seems to do... something important?

I've copied a couple of sentences from https://kubernetes.io/docs/concepts/scheduling/kube-scheduler/#scheduling to clarify the documentation here.

I wonder if the entire paragraph quoted above is really entirely necessary? It reads like the opening paragraph of a requirements specification doc, not the quick help text most people expect from a CLI tool.

Which issue(s) this PR fixes:

Special notes for your reviewer:

Does this PR introduce a user-facing change?:

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

[k8s-ci-robot]

Welcome @dharmab!

It looks like this is your first PR to kubernetes/kubernetes 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/kubernetes has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[k8s-ci-robot]

Hi @dharmab. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

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.

[dharmab]

/assign @bsalamat

[Ye-Tian-Zero]

/ok-to-test

[sftim]

/sig docs

[sftim]

/retest

[sftim]

Things I'd want readers to learn, instead of this:

• you can have more than one scheduler in your cluster (for high availability)
• you can have more than one scheduler in your cluster (if you deploy multiple, different schedulers, and configure things)
• kube-scheduler is part of the control plane
• kube-scheduler works by first filtering out nodes where the Pod can't possibly be placed, and then scoring what's left to find a good (good enough?) fit
  • https://kubernetes.io/docs/concepts/configuration/scheduling-framework/ talks about the full cycle, but I'd not mention that
• kube-scheduler considers multiple constraints when scheduling, but I wouldn't list which ones (at least not here)

[dharmab]

I've updated this with a more substantial rewrite to incorporate these points while still being short enough to understand.

[sftim]

/lgtm

[dharmab]

@sftim Thanks for the reviews, anything else needed to get this merged?

[dims]

/assign @Huang-Wei @k82cn

/retest

[zacharysarah]

/lgtm

@dims @cblecker 👋 What's the path to merge here?

[cblecker]

@zacharysarah The author has been asked to squash the two commits in the PR into a single commit by an approver: #88371 (comment)

I assume when this is done, @Huang-Wei will approve the PR as an approver for this part of the code base.

[dharmab]

Thanks for looking at this @Huang-Wei and @zacharysarah . I've squashed the commits.

[damemi]

/lgtm

[Huang-Wei]

/approve
/retest

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: dharmab, Huang-Wei

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• cmd/kube-scheduler/OWNERS [Huang-Wei]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Huang-Wei]

/retest

[Huang-Wei]

@dharmab could you take a look at the CI failures?

[Huang-Wei]

/hold
until CI failures get resolved.

[dharmab]

Rebasing to see if that resolves the CI failure

[sftim]

/retest

[Huang-Wei]

/lgtm
/hold cancel

[fejta-bot]

/retest
This bot automatically retries jobs that failed/flaked on approved PRs (send feedback to fejta).

Review the full test history for this PR.

Silence the bot with an /lgtm cancel or /hold comment for consistent failures.

[fejta-bot]

/retest
This bot automatically retries jobs that failed/flaked on approved PRs (send feedback to fejta).

Review the full test history for this PR.

Silence the bot with an /lgtm cancel or /hold comment for consistent failures.

[dharmab]

[measurement call PodStartupLatency - PodStartupLatency error: pod startup: too high latency 99th percentile: got 7.323477279s expected: 5s]

This looks like an unrelated failure. Can that test be ignored?

[fejta-bot]

/retest
This bot automatically retries jobs that failed/flaked on approved PRs (send feedback to fejta).

Review the full test history for this PR.

Silence the bot with an /lgtm cancel or /hold comment for consistent failures.

[Huang-Wei]

/retest