The kubernetes-sample-apiserver repository is a reference implementation demonstrating how to build a functional API server using the k8s.io/apiserver library. Written in Go, it serves as a practical guide for developers who need to extend Kubernetes with custom APIs, either through API Aggregation or as a stand-alone Kubernetes-style API server.
The repository is synced from the Kubernetes main repository at kubernetes/kubernetes/staging/src/k8s.io/sample-apiserver, with code changes made upstream and periodically synced to this location. This ensures that the sample implementation stays aligned with the latest developments in the Kubernetes API server ecosystem. The HEAD of this repository maintains compatibility with the HEAD of k8s.io/apiserver, k8s.io/apimachinery, and k8s.io/client-go, making it a reliable reference for current Kubernetes API patterns.
The repository explicitly acknowledges that developers have alternative approaches available. For simple resource additions to a Kubernetes cluster, Custom Resource Definitions (CRDs) are recommended as they require less coding and rebasing effort. For those building Extension API servers, the apiserver-builder framework is presented as a more complete alternative. However, for developers who choose to use this repository, the recommended pattern is to fork it, modify it to add custom types, and periodically rebase changes to incorporate improvements and bug fixes.
The codebase supports multiple dependency management approaches. It historically used godep and GOPATH but is transitioning to Go 1.11 modules. Developers can fetch the sample-apiserver and its dependencies using either the traditional godep approach or the newer go modules system. For code generation purposes, developers using go modules may need to create a vendor directory to ensure code-generator dependencies are in usable locations.
Building and deploying the sample-apiserver involves several steps. When API object type definitions in pkg/apis/.../types.go files are modified, developers must run hack/update-codegen.sh to regenerate dependent files. The repository supports customizable authentication plugins beyond the sparse default selection, allowing developers to add support for methods like OIDC by importing appropriate packages into main.go. The binary can be built with standard Go commands, and container images can be created and pushed to registries for deployment into Kubernetes clusters.
For development purposes, the repository supports running sample-apiserver stand-alone without a Kubernetes API server for authentication and authorization. This mode uses local client certificate-based X.509 authentication, requiring developers to generate a CA, create signed client certificates, and configure the server with appropriate kubeconfig files and flags. The stand-alone setup enables developers to test their API server implementation during development using tools like curl, wget, or httpie for making authenticated requests.
The repository is classified within the Kubernetes ecosystem as covering API servers, custom resources, sample implementations, controllers, resource management, extensions, cluster integration, and operator development patterns. It provides a practical foundation for understanding how to extend Kubernetes functionality through custom API servers while maintaining compatibility with Kubernetes conventions and best practices.
