Update docs for deprecation of Endpoints API #49831

danwinship · 2025-02-19T00:42:45Z

Updates documentation to reflect the fact that Endpoints are now officially deprecated in 1.33 (KEP-4974).

This includes some updates to the EndpointSlice documentation to get rid of some historical baggage and focus on describing the API as it is now. (It does not add any of the missing information to the section about topology because that will need to be updated for KEP-3015 anyway so I'll just fix it all then.)

There are a lot of instances of the word "endpoints" in the documentation, but a lot of them refer to the generic concept. I think I've fixed most of them at least...

/label tide/merge-method-squash

- FQDN is not a supported AddressType - Update documentation around `serving` vs `ready` to just explain how it works now, without the historical context. (In particular, describe `serving` first, and then explain `ready` as being almost the same thing as `serving` rather than vice versa). - Fix feature-state version macro for `terminating` - Remove a note about some deprecated v1beta1 EndpointSlice fields that is just confusing if you didn't know that v1beta1 had a different topology API. - Remove the "Comparison with Endpoints"/"Motivation" section.

netlify · 2025-02-19T00:43:03Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	`0d29bb5`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/67f5502e5cd9f80008681da2

content/en/docs/concepts/services-networking/service.md

content/en/docs/reference/glossary/endpoint.md

sftim · 2025-02-21T10:56:01Z

content/en/docs/reference/glossary/endpoint.md

@@ -1,17 +0,0 @@
---
-title: Endpoints


Maybe we could have a glossary entry for endpoint rather than Endpoints?

And then the revised entry could mention EndpointSlice.

So, effectively replace both existing glossary entries with the new combined one? Is there any way to make the old ones redirect? Or should I keep the old ones too, but just have basically the same information in all three?

Well, the glossary entry id is endpoint. So we / you could:

explain what we mean by the term endpoint

mention EndpointSlices

find everywhere this glossary term is used within English docs, and check that the changes haven't made the page misleading

minimum viable rewrites where needed

Well, the glossary entry id is endpoint

The filename is endpoint.md, though it says id: endpoints inside... But people seem to link to it as term_id="endpoint" and it works so I'm not sure what's going on there...

find everywhere this glossary term is used within English docs

In main, the only links to the endpoint glossary entry are here and here, which are both using the glossary entry to explain Endpoints resources specifically, not endpoints as a concept in general. (And both links go away in this PR.)

explain what we mean by the term endpoint

So this is tricky because the docs use the word "endpoint" with a lowercase "e" to refer not just to the Endpoints/EndpointSlice thing, but also to refer to REST APIs ("The Kubernetes API server serves an aggregated OpenAPI v2 spec via the /openapi/v2 endpoint.") So I'm not sure we want a generic glossary entry for "endpoint" unless it's going to cover both meanings?

cover both meanings

We can do that. I'm all over doing so.

This glossary should be preserved.
We are breaking the site build when removing this file.
In addition to that, having a glossary for "endpoint" in the general sense is good.

Urvashi0109 · 2025-04-03T11:13:10Z

Hello @danwinship 👋! I'm reaching out from the Docs team. Just checking in as we approach Docs Freeze on 8th April, 2025 18:00 PDT.
This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs. The status of this enhancement is marked as at risk for docs freeze. Thank you!

rayandas · 2025-04-08T06:13:47Z

@danwinship 1.33 Docs team here! This PR is still not in a shape to merge. Just a friendly reminder, Docs Freeze which is on 8th April, 2025 18:00 PDT

rayandas · 2025-04-08T06:16:02Z

/retest

danwinship · 2025-04-08T16:36:16Z

Brought back the endpoint glossary item, with a generic definition, though there are no in-tree links to it from the English docs.

netlify · 2025-04-08T16:43:52Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`0d29bb5`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/67f5502e714a42000891f3d0
😎 Deploy Preview	https://deploy-preview-49831--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rayandas · 2025-04-08T18:01:38Z

@bowei Could you please give a technical review?

rayandas · 2025-04-08T18:08:17Z

The changes are addressed. Just need another quick review from Docs @tengqm @lmktfy Thanks!

danwinship · 2025-04-08T19:36:59Z

/assign @aojea

rayandas · 2025-04-09T05:49:56Z

Hello @danwinship 👋, 1.33 Docs team here. This PR did not meet deadline for docs freeze. Enhancements without required documentation may be removed from the current release. If you still wish to include this enhancement in 1.33, please file an exception request. Thanks!

aojea · 2025-04-09T06:26:04Z

content/en/docs/reference/glossary/endpoint.md

 full_link: 
 short_description: >
-  Endpoints track the IP addresses of Pods with matching Service selectors.
+  An endpoint of a Service is one of the Pods (or external servers) that implements the Service.


despite is deprecated the API exist, so I think the old definition still applies

I see, it was dicussed here #49831 (comment) , it seems is the preference to follow this path

aojea · 2025-04-09T06:27:29Z

/lgtm

k8s-ci-robot · 2025-04-09T06:27:35Z

LGTM label has been added.

Git tree hash: 6eadb136a74de61938124dce95d87098c60fddc2

tengqm · 2025-04-09T09:07:13Z

/approve

k8s-ci-robot · 2025-04-09T09:07:27Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: tengqm

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:

~~content/en/docs/OWNERS~~ [tengqm]

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

rayandas · 2025-04-09T09:11:10Z

Marking this PR as tracked for Docs freeze. Thanks!

danwinship added 4 commits February 18, 2025 19:31

KEP-4974: Update documentation for Endpoints deprecation

6fb21ab

Fix up examples that still used kubectl get endpoints

4f21c78

Replace various passing references to Endpoints with EndpointSlices

2411fae

k8s-ci-robot added tide/merge-method-squash Denotes a PR that should be squashed by tide when it merges. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language labels Feb 19, 2025

k8s-ci-robot requested review from bowei and divya-mohan0209 February 19, 2025 00:42

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Feb 19, 2025

sftim reviewed Feb 21, 2025

View reviewed changes

content/en/docs/concepts/services-networking/service.md Outdated Show resolved Hide resolved

content/en/docs/reference/glossary/endpoint.md Show resolved Hide resolved

sftim reviewed Feb 21, 2025

View reviewed changes

danwinship mentioned this pull request Feb 14, 2025

Deprecate v1.Endpoints kubernetes/enhancements#4974

Open

4 tasks

Update main headings for Endpoints and Endpoint Slice Mirroring

57347a6

Update glossary for Endpoints deprecation

0d29bb5

danwinship force-pushed the deprecate-endpoints branch from a57fa8d to 0d29bb5 Compare April 8, 2025 16:34

k8s-ci-robot assigned aojea Apr 8, 2025

aojea reviewed Apr 9, 2025

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Apr 9, 2025

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Apr 9, 2025

k8s-ci-robot merged commit 649bda2 into kubernetes:dev-1.33 Apr 9, 2025
6 checks passed

danwinship deleted the deprecate-endpoints branch April 9, 2025 12:32

Uh oh!

Update docs for deprecation of Endpoints API #49831

Update docs for deprecation of Endpoints API #49831

Uh oh!

Conversation

danwinship commented Feb 19, 2025

Uh oh!

netlify bot commented Feb 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

danwinship Mar 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Urvashi0109 commented Apr 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rayandas commented Apr 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rayandas commented Apr 8, 2025

Uh oh!

danwinship commented Apr 8, 2025

Uh oh!

netlify bot commented Apr 8, 2025

✅ Pull request preview available for checking

Uh oh!

rayandas commented Apr 8, 2025

Uh oh!

rayandas commented Apr 8, 2025

Uh oh!

danwinship commented Apr 8, 2025

Uh oh!

rayandas commented Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aojea commented Apr 9, 2025

Uh oh!

k8s-ci-robot commented Apr 9, 2025

Uh oh!

tengqm commented Apr 9, 2025

Uh oh!

k8s-ci-robot commented Apr 9, 2025

Uh oh!

Uh oh!

rayandas commented Apr 9, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

netlify bot commented Feb 19, 2025 •

edited

Loading

danwinship Mar 1, 2025 •

edited

Loading

Urvashi0109 commented Apr 3, 2025 •

edited

Loading

rayandas commented Apr 8, 2025 •

edited

Loading

rayandas commented Apr 9, 2025 •

edited

Loading