List available endpoints for kube-apiserver (#132581)

Fix tests and formatting

Use ListedPaths for finding useful endpoints

Fix maps import

Update dependencies

Fix lint

Add option to pass listedpaths

Remove apiserver component check

Install statuz in genericapiserver

Register zpagesfeatures

Fix import order

Avoid adding non-debugging endpoints

Fix tests

Fix tests

fix tests

Sort paths

Sort in-place

Copy paths before sorting

Fix string initialization

Move sorting to later stage

Fix imports

Kubernetes-commit: c7d6c09683344d6dacbe5ba3383a8217c1d4ccd7

Author: itssimrank

go.mod

@@ -28,8 +28,8 @@ require (
 	go.uber.org/zap v1.27.0
 	go.yaml.in/yaml/v2 v2.4.2
 	golang.org/x/sys v0.31.0
-	k8s.io/apimachinery v0.0.0-20250717170243-9b71f293aa0c
-	k8s.io/client-go v0.0.0-20250717170920-715e46ed5728
+	k8s.io/apimachinery v0.0.0-20250723005633-58c4eb072ebf
+	k8s.io/client-go v0.0.0-20250724024901-5f1f878e5cd4
 	k8s.io/klog/v2 v2.130.1
 	k8s.io/utils v0.0.0-20250604170112-4c0f3b243397
 	sigs.k8s.io/json v0.0.0-20241014173422-cfa47c3a1cc8
@@ -80,7 +80,7 @@ require (
 	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
-	k8s.io/api v0.0.0-20250717170527-b7a83e2941aa // indirect
+	k8s.io/api v0.0.0-20250724064529-b87ac725dbf9 // indirect
 	k8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect
 	sigs.k8s.io/structured-merge-diff/v6 v6.3.0 // indirect

go.sum

@@ -210,12 +210,12 @@ gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
 gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-k8s.io/api v0.0.0-20250717170527-b7a83e2941aa h1:9T75LAFccLxRh1V7SjtTxnpY9H4DoTlajvyLQQuViZg=
-k8s.io/api v0.0.0-20250717170527-b7a83e2941aa/go.mod h1:KToU1jTzT+gkd8q+fEft6oTAtPXK9a4pXEqdI6xhoLE=
-k8s.io/apimachinery v0.0.0-20250717170243-9b71f293aa0c h1:NoUgdWNyboxIpLhCjKQrm/sGuLKjEYyNf+K4eioV6s8=
-k8s.io/apimachinery v0.0.0-20250717170243-9b71f293aa0c/go.mod h1:v1p1Jsze3IHLy5gU17yVqR2qLO7jgYeX6mw3HZy2AEU=
-k8s.io/client-go v0.0.0-20250717170920-715e46ed5728 h1:RCOjgxJWj3E8V4gSUuuSaBPlOz8gpqoZsSA5PUUQvHM=
-k8s.io/client-go v0.0.0-20250717170920-715e46ed5728/go.mod h1:OVZIe2J7VRQKdzsLDwmqAQyKxd1CKuTEVR7jW9uca2g=
+k8s.io/api v0.0.0-20250724064529-b87ac725dbf9 h1:szZeh22FWBBbJjDCHrh8P35J6afaiuPOpaTsgaEyX4Q=
+k8s.io/api v0.0.0-20250724064529-b87ac725dbf9/go.mod h1:70o+sJgHYrO2nPMKeEsmpidpEUMobuxHMhjK/ud9+og=
+k8s.io/apimachinery v0.0.0-20250723005633-58c4eb072ebf h1:R1l0xAevbhH2Bg0iJuabo8/i9m31D1ehh2ZJPFKh9bc=
+k8s.io/apimachinery v0.0.0-20250723005633-58c4eb072ebf/go.mod h1:v1p1Jsze3IHLy5gU17yVqR2qLO7jgYeX6mw3HZy2AEU=
+k8s.io/client-go v0.0.0-20250724024901-5f1f878e5cd4 h1:cUaPGCS7dfX5d85Q8ZJBD2rdK5C6tbWEtGFdBcH+bxo=
+k8s.io/client-go v0.0.0-20250724024901-5f1f878e5cd4/go.mod h1:kgDY5crqhNpktphA+cjWLcLLjrF5apg7TWTtaVyhUm8=
 k8s.io/klog/v2 v2.130.1 h1:n9Xl7H1Xvksem4KFG4PYbdQCQxqc/tTUyrgXaOhHSzk=
 k8s.io/klog/v2 v2.130.1/go.mod h1:3Jpz1GvMt720eyJH1ckRHK1EDfpxISzJ7I9OYgaDtPE=
 k8s.io/kube-openapi v0.0.0-20250710124328-f3f2b991d03b h1:MloQ9/bdJyIu9lb1PzujOPolHyvO06MXG5TUIj2mNAA=

zpages/statusz/registry.go

@@ -32,11 +32,25 @@ type statuszRegistry interface {
 	goVersion() string
 	binaryVersion() *version.Version
 	emulationVersion() *version.Version
+	paths() []string
 }
 
 type registry struct {
 	// componentGlobalsRegistry compatibility.ComponentGlobalsRegistry
 	effectiveVersion compatibility.EffectiveVersion
+	// listedPaths is an alphabetically sorted list of paths to be reported at /.
+	listedPaths []string
+}
+
+// Option is a function to configure registry.
+type Option func(reg *registry)
+
+// WithListedPaths returns an Option to configure the ListedPaths.
+func WithListedPaths(listedPaths []string) Option {
+	cpyListedPaths := make([]string, len(listedPaths))
+	copy(cpyListedPaths, listedPaths)
+
+	return func(reg *registry) { reg.listedPaths = cpyListedPaths }
 }
 
 func (*registry) processStartTime() time.Time {
@@ -66,3 +80,11 @@ func (r *registry) emulationVersion() *version.Version {
 
 	return nil
 }
+
+func (r *registry) paths() []string {
+	if r.listedPaths != nil {
+		return r.listedPaths
+	}
+
+	return nil
+}

zpages/statusz/statusz.go

@@ -21,6 +21,8 @@ import (
 	"html"
 	"math/rand"
 	"net/http"
+	"sort"
+	"strings"
 	"time"
 
 	"k8s.io/component-base/compatibility"
@@ -29,7 +31,14 @@ import (
 )
 
 var (
-	delimiters = []string{":", ": ", "=", " "}
+	delimiters            = []string{":", ": ", "=", " "}
+	nonDebuggingEndpoints = map[string]bool{
+		"/apis":        true,
+		"/api":         true,
+		"/openid":      true,
+		"/openapi":     true,
+		"/.well-known": true,
+	}
 )
 
 const DefaultStatuszPath = "/statusz"
@@ -43,8 +52,15 @@ type mux interface {
 	Handle(path string, handler http.Handler)
 }
 
-func NewRegistry(effectiveVersion compatibility.EffectiveVersion) statuszRegistry {
-	return &registry{effectiveVersion: effectiveVersion}
+type ListedPathsOption []string
+
+func NewRegistry(effectiveVersion compatibility.EffectiveVersion, opts ...func(*registry)) statuszRegistry {
+	r := &registry{effectiveVersion: effectiveVersion}
+	for _, opt := range opts {
+		opt(r)
+	}
+
+	return r
 }
 
 func Install(m mux, componentName string, reg statuszRegistry) {
@@ -59,7 +75,7 @@ func handleStatusz(componentName string, reg statuszRegistry) http.HandlerFunc {
 		}
 
 		fmt.Fprintf(w, headerFmt, componentName)
-		data, err := populateStatuszData(reg)
+		data, err := populateStatuszData(reg, componentName)
 		if err != nil {
 			klog.Errorf("error while populating statusz data: %v", err)
 			http.Error(w, "error while populating statusz data", http.StatusInternalServerError)
@@ -71,7 +87,7 @@ func handleStatusz(componentName string, reg statuszRegistry) http.HandlerFunc {
 	}
 }
 
-func populateStatuszData(reg statuszRegistry) (string, error) {
+func populateStatuszData(reg statuszRegistry, componentName string) (string, error) {
 	randomIndex := rand.Intn(len(delimiters))
 	delim := html.EscapeString(delimiters[randomIndex])
 	startTime := html.EscapeString(reg.processStartTime().Format(time.UnixDate))
@@ -83,14 +99,19 @@ func populateStatuszData(reg statuszRegistry) (string, error) {
 	if reg.emulationVersion() != nil {
 		emulationVersion = fmt.Sprintf(`Emulation version%s %s`, delim, html.EscapeString(reg.emulationVersion().String()))
 	}
+	paths := aggregatePaths(reg.paths())
+	if paths != "" {
+		paths = fmt.Sprintf(`Paths%s %s`, delim, html.EscapeString(paths))
+	}
 
 	status := fmt.Sprintf(`
 Started%[1]s %[2]s
 Up%[1]s %[3]s
 Go version%[1]s %[4]s
 Binary version%[1]s %[5]s
 %[6]s
-`, delim, startTime, uptime, goVersion, binaryVersion, emulationVersion)
+%[7]s
+`, delim, startTime, uptime, goVersion, binaryVersion, emulationVersion, paths)
 
 	return status, nil
 }
@@ -100,3 +121,26 @@ func uptime(t time.Time) string {
 	return fmt.Sprintf("%d hr %02d min %02d sec",
 		upSince/3600, (upSince/60)%60, upSince%60)
 }
+
+func aggregatePaths(listedPaths []string) string {
+	paths := make(map[string]bool)
+	for _, listedPath := range listedPaths {
+		folder := "/" + strings.Split(listedPath, "/")[1]
+		if !paths[folder] && !nonDebuggingEndpoints[folder] {
+			paths[folder] = true
+		}
+	}
+
+	var sortedPaths []string
+	for p := range paths {
+		sortedPaths = append(sortedPaths, p)
+	}
+	sort.Strings(sortedPaths)
+
+	var path string
+	for _, p := range sortedPaths {
+		path += " " + p
+	}
+
+	return path
+}

zpages/statusz/statusz_test.go

@@ -36,6 +36,7 @@ Up: %s
 Go version: %s
 Binary version: %v
 Emulation version: %v
+Paths:  /livez /readyz
 `
 
 const wantTmplWithoutEmulation = `
@@ -47,6 +48,19 @@ Up: %s
 Go version: %s
 Binary version: %v
 
+Paths:  /livez /readyz
+`
+
+const wantTmplWithKubeApiserverComp = `
+%s statusz
+Warning: This endpoint is not meant to be machine parseable, has no formatting compatibility guarantees and is for debugging purposes only.
+
+Started: %v
+Up: %s
+Go version: %s
+Binary version: %v
+
+Paths:  /livez /readyz
 `
 
 func TestStatusz(t *testing.T) {
@@ -58,6 +72,7 @@ func TestStatusz(t *testing.T) {
 	fakeEvStr := "1.30"
 	fakeBinaryVersion := parseVersion(t, fakeBvStr)
 	fakeEmulationVersion := parseVersion(t, fakeEvStr)
+	fakeListedPaths := []string{"/livez/poststarthook/peer-discovery-cache-sync", "/livez/post", "/readyz/informer-sync", "/readyz/log", "/readyz/ping"}
 	tests := []struct {
 		name           string
 		componentName  string
@@ -80,6 +95,7 @@ func TestStatusz(t *testing.T) {
 				goVer:        fakeGoVersion,
 				binaryVer:    fakeBinaryVersion,
 				emulationVer: fakeEmulationVersion,
+				listedPaths:  fakeListedPaths,
 			},
 			wantStatusCode: http.StatusOK,
 			wantBody: fmt.Sprintf(
@@ -101,6 +117,7 @@ func TestStatusz(t *testing.T) {
 				goVer:        fakeGoVersion,
 				binaryVer:    fakeBinaryVersion,
 				emulationVer: nil,
+				listedPaths:  fakeListedPaths,
 			},
 			wantStatusCode: http.StatusOK,
 			wantBody: fmt.Sprintf(
@@ -112,6 +129,27 @@ func TestStatusz(t *testing.T) {
 				fakeBinaryVersion,
 			),
 		},
+		{
+			name:          "valid request for kube-apiserver",
+			componentName: "kube-apiserver",
+			reqHeader:     "text/plain; charset=utf-8",
+			registry: fakeRegistry{
+				startTime:    fakeStartTime,
+				goVer:        fakeGoVersion,
+				binaryVer:    fakeBinaryVersion,
+				emulationVer: nil,
+				listedPaths:  fakeListedPaths,
+			},
+			wantStatusCode: http.StatusOK,
+			wantBody: fmt.Sprintf(
+				wantTmplWithKubeApiserverComp,
+				"kube-apiserver",
+				fakeStartTime.Format(time.UnixDate),
+				fakeUptime,
+				fakeGoVersion,
+				fakeBinaryVersion,
+			),
+		},
 	}
 
 	for _, tt := range tests {
@@ -166,6 +204,7 @@ type fakeRegistry struct {
 	goVer        string
 	binaryVer    *version.Version
 	emulationVer *version.Version
+	listedPaths  []string
 }
 
 func (f fakeRegistry) processStartTime() time.Time {
@@ -183,3 +222,7 @@ func (f fakeRegistry) binaryVersion() *version.Version {
 func (f fakeRegistry) emulationVersion() *version.Version {
 	return f.emulationVer
 }
+
+func (f fakeRegistry) paths() []string {
+	return f.listedPaths
+}