kubernetes/apiserver is a mirror, not a place to contribute

This repository is generated and read-only

The first thing the README says is that this is an automatically published staged repository for Kubernetes, that contributions including issues and pull requests should be made to the main Kubernetes repository, and that the repository is read-only for importing and not used for direct contributions.

The synchronisation direction is spelled out under the heading about where it comes from. apiserver is synced from the kubernetes/kubernetes staging directory at src/k8s.io/apiserver. Code changes are made in that location, merged into k8s.io/kubernetes, and later synced here.

So the practical consequences are immediate. Opening a pull request against this repository is the wrong move, and the .import-restrictions file at the top level is the mechanism that enforces it. Reading the repository to understand the code is fine and is what it is for, but a team that wants a change made has to make it upstream in the staging tree.

That inversion catches people out. A patch that works locally against a vendored copy of this library will be overwritten by the next sync, because the sync is authoritative. The upstream staging directory is the only durable place to put a change.

The library covers the whole aggregation stack

The project describes itself as a generic library for building a Kubernetes aggregated API server, and the purpose section lists what that means in practice. The library contains code to create a Kubernetes aggregation server complete with delegated authentication and authorization, kubectl compatible discovery information, an optional admission chain, and versioned types.

Each of those four items is a substantial piece of work that an API server author would otherwise write.

Delegated authentication and authorization is the security model of aggregation: instead of a separate API server validating its own tokens and permissions, requests arrive already authenticated by the front proxy and are checked against the main API server's SubjectAccessReview machinery. An aggregated server built on this library inherits that model instead of reimplementing it, which is the point of the library existing.

kubectl compatible discovery information is what makes a custom API group usable with ordinary tooling. If the discovery document does not match what kubectl expects, the resource exists but is awkward or impossible to work with from the command line.

The optional admission chain is the extension point for validation and mutation of incoming objects, and the versioned types handle the storage and conversion machinery needed to serve more than one version of a resource.

The named first consumers are k8s.io/kubernetes, k8s.io/kube-aggregator, and github.com/kubernetes-incubator/service-catalog, which is a good indication of the maturity level and of what to read as a working example.

No compatibility guarantees, and branches track Kubernetes

The compatibility section is unusually blunt. There are no compatibility guarantees for this repository, yet. It is in direct support of Kubernetes, so branches will track Kubernetes and be compatible with that repo. As the layers are separated more cleanly, the compatibility guarantee will be reviewed, and the stated goal is to make this easier to use in the future.

The list of things you should not do says the same thing twice. One entry is not to directly modify any files under pkg in this repo, because those are driven from the staging directory in k8s.io/kubernetes. The second is not to expect compatibility, because the repository is changing quickly in direct support of Kubernetes and the API is not yet stable enough for API guarantees.

For an adopter this means the dependency behaves differently from a normal library. There is no semver promise to lean on, no deprecation window, and no changelog that maps to your version. The only stable coordinate is the Kubernetes release you target.

The practical mitigation is to pin to a Kubernetes branch rather than to a version of this library. Because branches track Kubernetes, a pinned branch gives you a moving target that moves in step with the upstream cluster version you are building for, which is the coupling you actually care about. The go.mod file reflects that coupling, with the module path k8s.io/apiserver and a go 1.27.0 directive.

module k8s.io/apiserver

go 1.27.0

The version string of the library is therefore not something you choose. You choose the Kubernetes release, and the library comes with it.

The dependency list is the real feature list of an API server

Reading go.mod tells you what an aggregated API server actually needs to run, and the list is long enough to justify a library like this one.

Storage runs on etcd, with the api, client and server packages of etcd v3.7.2 all present. The gRPC stack comes from google.golang.org/grpc v1.84.0 with protobuf v1.36.12, and the OpenTelemetry instrumentation wraps both the gRPC and HTTP paths, with otelhttp, otelgrpc, the OTLP trace exporter and the SDK at v1.47.0. Logging is go.uber.org/zap v1.27.1.

Two dependencies stand out for what they imply about the feature set. github.com/google/cel-go v0.29.2 is the Common Expression Language implementation, which is what a CEL based admission policy needs. And github.com/coreos/go-oidc/v3 v3.21.0 with go-jose v4.1.5 is OIDC and JOSE handling, which belongs to the delegated authentication path and to service account token verification.

The rest is plumbing that any HTTP API server needs: emicklei/go-restful for the REST layer, gorilla/websocket for streaming, spf13/pflag for flags, fsnotify for file watching, golang.org/x/net for the HTTP stack, and evanphx/json-patch.v4 for JSON patch application. There are also test-oriented dependencies such as stretchr/testify and google/go-cmp in the main require block.

The point for an evaluator is that this is a full-featured server framework rather than a thin routing layer. You are adopting the same machinery the built-in Kubernetes addons use, including the operational dependencies that come with it.

Delegation is why the library is worth the dependency weight

The alternative to using this library is to write an aggregated API server yourself, and the hard part is not the CRUD endpoints. It is the trust boundary.

An aggregated API server sits behind the front proxy, and clients reach it with credentials that the front proxy has already validated. The aggregated server still has to decide whether the request is allowed, which it does by asking the main API server rather than by keeping its own user database. That request path, the authentication delegation and the authorization delegation, is the machinery this library provides.

Writing that by hand means implementing token review, service account handling, SubjectAccessReview calls and the wiring to make a locally served resource appear under an aggregated discovery document. It is a lot of security-sensitive surface, and the reason the built-in consumers use this library rather than their own.

The tradeoff is that you inherit the aggregation contract, including its discovery format and its admission behaviour. A server that validates objects differently from the built-in addons will behave differently from what users expect from a Kubernetes extension.

The optional admission chain is worth calling out separately. Because admission is optional in the library, the same binary can be built with validation and mutation in place or without it, and the CEL dependency shows the intended direction: policies expressed as code rather than hand-written validation functions.

The repository layout tells you where to look

The top level is small and conventional. There is pkg/, plugin/, doc.go, go.mod, go.sum, ARCHITECTURE.md, CONTRIBUTING.md, OWNERS, SECURITY_CONTACTS, code-of-conduct.md, a LICENSE file and .import-restrictions.

The .import-restrictions file is the one to read first if you are planning to contribute upstream. It exists to enforce the direction of the sync, so that a change does not get made in the mirror and silently lost.

ARCHITECTURE.md is the next file to look at, because the README does not describe the internal structure and the library covers a wide surface: authentication, authorization, discovery, admission, versioning and the server plumbing that ties them together. SECURITY_CONTACTS names who handles security reports for this component, and the top-level OWNERS file identifies the reviewers responsible for it.

The plugin/ directory is worth noting for a different reason. The library exposes its extension points as plugins, which is how an aggregated API server substitutes its own resource storage, admission plugins or authorization behaviour. It is also why the plugin mechanism needs to be stable, and why the project says the API is not yet stable enough for API guarantees.

The licence is Apache-2.0. That is a permissive licence with an explicit patent grant, which matters more than usual for infrastructure libraries that end up embedded in products, and there is no copyleft obligation on code that links it.

Editorial conclusion

Use k8s.io/apiserver if you are building a Kubernetes aggregated API server and want the same machinery the built-in addons use, but pin it to the Kubernetes branch you target and treat every upgrade as a breaking change, because the project states there are no compatibility guarantees. Do not plan to contribute here, since issues and pull requests belong in kubernetes/kubernetes. Before adopting, read ARCHITECTURE.md, check the go.mod requirement of Go 1.27.0 against your build image, and mirror any local change back into staging/src/k8s.io/apiserver so it survives the next sync.

Frequently asked questions

Official sources

1. Issues
2. kubernetes/apiserver on GitHub
3. License: Apache-2.0
4. README