Improve wording for “What is Kubernetes”

[kenhtanaka]

In the section titled "Why you need Kubernetes and what it can do" the first bullet point reads:

• Service discovery and load balancing Kubernetes can expose a container using the DNS name or using their own IP address. If traffic to a container is high, Kubernetes is able to load balance and distribute the network traffic so that the deployment is stable.

I'm not clear on the meaning here with regards to load balancing being a benefit with one container. I'm new to Kubernetes, but I assume that multiple containers make more sense. Would this be an accurate rewrite?

• Service discovery and load balancing Kubernetes can expose a container using the DNS name or using their own IP address. If traffic to one container is high, Kubernetes is able to load balance and distribute some of the network traffic to other available containers so that the deployment is stable.

[sftim]

/retitle Improve working for “What is Kubernetes”
/language en

The original wording is more appropriate. Balancing, whether it's network traffic, a finance ledger, or weights on beam, is something done in aggregate.

Additionally, the thing that Kubernetes directs traffic to is actually a different endpoint - usually a Pod. It's OK to be simple but the more detail we add to this overview, it becomes more problematic not to cover the full detail.

I like having a simple summary that doesn't yet include all the detail. We could look for a different wording that implies that the one overloaded container might be part of a broader set of some kind (without mentioning the actual implementation details: ReplicaSet, Deployment, etc).

[kenhtanaka]

I see, "Balancing" implies an aggregate action to me too, so with regards to "a container" I wasn't sure if I was making the right assumption that "there must be other containers" to make that work. I think this would be clearer to me to identify a broader set (change in italics):

• Service discovery and load balancing Kubernetes can expose a container using the DNS name or using their own IP address. If traffic to one of the containers is high, Kubernetes is able to load balance and distribute the network traffic so that the deployment is stable.

Would that wording meet your goal of keeping a simple summary that is still accurate?

[sftim]

/retitle Improve wording for “What is Kubernetes”

How about:
Service discovery and load balancing Kubernetes can expose a container using the DNS name or using their own IP address. When there are multiple containers backing a service, Kubernetes is able to load balance and distribute the network traffic. Load balancing helps ensure that a workload can stay available even if one container stops working, or during deployments.

[kenhtanaka]

Yes, that reads much clearer to me.

[sftim]

/triage accepted
/kind cleanup

[mehabhalodiya]

/good-first-issue

[nitishfy]

/assign

[nitishfy]

Hey @sftim , I've opened the PR for this issue. Kindly look at it and feel free to suggest some changes if necessary.

[sftim]

I've reviewed the PR for this issue. Kindly look at it and feel free to suggest some changes if necessary.

English nit: you've opened a PR and are requesting a review.

[nitishfy]

@sftim My bad! Sorry, I mean I've made changes to the PR as required so now I'm asking for review if any further changes are required to be made before merging.

[sftim]

/remove-help

We shouldn't label updates to the What Is Kubernetes page as good first issues, unless the fixes are genuinely trivial. Updates to that page always require extra review.

[nitishfy]

I think we can close this issue. WDYT @sftim ?

[kenhtanaka]

As @sftim commented on Apr 13, does this change when merged? I'm not familiar with your workflow on when https://kubernetes.io/docs/concepts/overview/ will change.

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.

This bot triages issues and PRs according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[sftim]

/remove-lifecycle stale

BTW, once someone merges a fix for this issue, we can close the issue. I think there is room to improve the wording in https://kubernetes.io/docs/concepts/overview/

[nitishfy]

@sftim As far as the last comment by @reylejano (#34037 (comment)) , Do you think that any change is required?

[sftim]

I still think we should make an improvement (see my previous comment). It needs to be a change that reviewers agree is a benefit to the Kubernetes docs.

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale