README
¶
⚠️ This is an automatically published staged repository for Kubernetes.
Contributions, including issues and pull requests, should be made to the main Kubernetes repository: https://github.com/kubernetes/kubernetes.
This repository is read-only for importing, and not used for direct contributions.
See CONTRIBUTING.md for more details.
apiserver
Generic library for building a Kubernetes aggregated API server.
Purpose
This library contains code to create Kubernetes aggregation server complete with delegated authentication and authorization,
kubectl compatible discovery information, optional admission chain, and versioned types. It's first consumers are
k8s.io/kubernetes, k8s.io/kube-aggregator, and github.com/kubernetes-incubator/service-catalog.
Compatibility
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 we more cleanly separate the layers, we will review the compatibility guarantee. We have a goal to make this easier to use in the future.
Where does it come from?
apiserver is synced from https://github.com/kubernetes/kubernetes/blob/master/staging/src/k8s.io/apiserver.
Code changes are made in that location, merged into k8s.io/kubernetes and later synced here.
Things you should NOT do
- Directly modify any files under
pkgin this repo. Those are driven fromk8s.io/kubernetes/staging/src/k8s.io/apiserver. - Expect compatibility. This repo is changing quickly in direct support of Kubernetes and the API isn't yet stable enough for API guarantees.
Documentation
¶
Overview ¶
Package apiserver provides the machinery for building Kubernetes-style API servers.
This library is the foundation for the Kubernetes API server (`kube-apiserver`), and is also the primary framework for developers building custom API servers to extend the Kubernetes API.
An extension API server is a user-provided, standalone web server that registers itself with the main kube-apiserver to handle specific API groups. This allows developers to extend Kubernetes with their own APIs that behave like core Kubernetes APIs, complete with typed clients, authentication, authorization, and discovery.
Key Packages ¶
The `apiserver` library is composed of several key packages:
- `pkg/server`: This is the core of the library, providing the `GenericAPIServer` and the main machinery for building the server.
- `pkg/admission`: This package contains the admission control framework. Developers can use this to build custom admission plugins that can validate or mutate requests to enforce custom policies. This is a common way to extend Kubernetes behavior without adding a full API server.
- `pkg/authentication`: This package provides the framework for authenticating requests.
- `pkg/authorization`: This package provides the framework for authorizing requests.
- `pkg/endpoints`: This package contains the machinery for building the REST endpoints for the API server.
- `pkg/registry`: This package provides the storage interface for the API server.
Instantiating a GenericAPIServer ¶
The `GenericAPIServer` struct is the heart of any extension server. It is responsible for assembling and running the HTTP serving stack. See the runnable example for a demonstration of how to instantiate a `GenericAPIServer`.
Building an Extension API Server (API Aggregation) ¶
The mechanism that enables extension API servers is API aggregation. The primary apiserver (typically the kube-apiserver) acts as a proxy, forwarding requests for a specific API group (e.g., /apis/myextension.io/v1) to a registered extension server. The apiserver is configured using APIService objects.
For most use cases, custom resources (CustomResourceDefinitions) are the preferred way to extend the Kubernetes API.
Building an Admission Plugin ¶
The `pkg/admission` package provides a way to add admission policies directly into an apiserver. Admission plugins can be used to validate or mutate objects during write operations. The kube-apiserver uses admission plugins to provide a variety of core system capabilities.
For most extension use cases dynamic admission control using policies (ValidatingAdmissionPolicies or MutatingAdmissionPolicies) or webhooks (ValidatingWebhookConfiguration and MutatingWebhookConfiguration) are the preferred way to extend admission control.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
pkg
|
|
|
admission/plugin/policy/internal/generic
Package generic contains a typed wrapper over cache SharedIndexInformer and Lister (maybe eventually should have a home there?)
|
Package generic contains a typed wrapper over cache SharedIndexInformer and Lister (maybe eventually should have a home there?) |
|
admission/plugin/resourcequota
Package resourcequota enforces all incoming requests against any applied quota in the namespace context of the request
|
Package resourcequota enforces all incoming requests against any applied quota in the namespace context of the request |
|
admission/plugin/resourcequota/apis/resourcequota/install
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery.
|
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery. |
|
admission/plugin/resourcequota/apis/resourcequota/v1
Package v1 is the v1 version of the API.
|
Package v1 is the v1 version of the API. |
|
admission/plugin/resourcequota/apis/resourcequota/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
|
Package v1alpha1 is the v1alpha1 version of the API. |
|
admission/plugin/resourcequota/apis/resourcequota/v1beta1
Package v1beta1 is the v1beta1 version of the API.
|
Package v1beta1 is the v1beta1 version of the API. |
|
admission/plugin/webhook/config/apis/webhookadmission/install
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery.
|
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery. |
|
admission/plugin/webhook/config/apis/webhookadmission/v1
Package v1 is the v1 version of the API.
|
Package v1 is the v1 version of the API. |
|
admission/plugin/webhook/config/apis/webhookadmission/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
|
Package v1alpha1 is the v1alpha1 version of the API. |
|
admission/plugin/webhook/errors
Package errors contains utilities for admission webhook specific errors
|
Package errors contains utilities for admission webhook specific errors |
|
admission/plugin/webhook/mutating
Package mutating delegates admission checks to dynamically configured mutating webhooks.
|
Package mutating delegates admission checks to dynamically configured mutating webhooks. |
|
admission/plugin/webhook/predicates/namespace
Package namespace defines the utilities that are used by the webhook plugin to decide if a webhook should be applied to an object based on its namespace.
|
Package namespace defines the utilities that are used by the webhook plugin to decide if a webhook should be applied to an object based on its namespace. |
|
admission/plugin/webhook/predicates/object
Package object defines the utilities that are used by the webhook plugin to decide if a webhook should run, as long as either the old object or the new object has labels matching the webhook config's objectSelector.
|
Package object defines the utilities that are used by the webhook plugin to decide if a webhook should run, as long as either the old object or the new object has labels matching the webhook config's objectSelector. |
|
admission/plugin/webhook/request
Package request creates admissionReview request based on admission attributes.
|
Package request creates admissionReview request based on admission attributes. |
|
admission/plugin/webhook/testcerts
Package testcerts contains generated key pairs used by the unit tests of mutating and validating webhooks.
|
Package testcerts contains generated key pairs used by the unit tests of mutating and validating webhooks. |
|
admission/plugin/webhook/validating
Package validating makes calls to validating (i.e., non-mutating) webhooks during the admission process.
|
Package validating makes calls to validating (i.e., non-mutating) webhooks during the admission process. |
|
apis/apidiscovery/v2
Once the v2beta1 types are removed (intended for Kubernetes v1.33), this file will be removed.
|
Once the v2beta1 types are removed (intended for Kubernetes v1.33), this file will be removed. |
|
apis/apiserver
Package apiserver is the internal version of the API.
|
Package apiserver is the internal version of the API. |
|
apis/apiserver/v1
Package v1 is the v1 version of the API.
|
Package v1 is the v1 version of the API. |
|
apis/apiserver/v1alpha1
Package v1alpha1 is the v1alpha1 version of the API.
|
Package v1alpha1 is the v1alpha1 version of the API. |
|
apis/apiserver/v1beta1
Package v1beta1 is the v1beta1 version of the API.
|
Package v1beta1 is the v1beta1 version of the API. |
|
apis/apiserver/validation
Package validation validates EncryptionConfiguration.
|
Package validation validates EncryptionConfiguration. |
|
apis/audit/install
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery.
|
Package install installs the experimental API group, making it available as an option to all of the API encoding/decoding machinery. |
|
apis/example
package example contains an example API used to demonstrate how to create api groups.
|
package example contains an example API used to demonstrate how to create api groups. |
|
apis/example/install
Package install installs the example API group, making it available as an option to all of the API encoding/decoding machinery.
|
Package install installs the example API group, making it available as an option to all of the API encoding/decoding machinery. |
|
apis/example2
+k8s:deepcopy-gen=package +groupName=example2.k8s.io
|
+k8s:deepcopy-gen=package +groupName=example2.k8s.io |
|
apis/example2/install
Package install installs the example2 API group, making it available as an option to all of the API encoding/decoding machinery.
|
Package install installs the example2 API group, making it available as an option to all of the API encoding/decoding machinery. |
|
audit
TODO: Delete this file if we generate a clientset.
|
TODO: Delete this file if we generate a clientset. |
|
authentication/cel
Package cel contains the CEL related interfaces and structs for authentication.
|
Package cel contains the CEL related interfaces and structs for authentication. |
|
authentication/request/x509
Package x509 provides a request authenticator that validates and extracts user information from client certificates
|
Package x509 provides a request authenticator that validates and extracts user information from client certificates |
|
authentication/user
Package user contains utilities for dealing with simple user exchange in the auth packages.
|
Package user contains utilities for dealing with simple user exchange in the auth packages. |
|
authorization/path
Package path contains an authorizer that allows certain paths and path prefixes.
|
Package path contains an authorizer that allows certain paths and path prefixes. |
|
authorization/union
Package union implements an authorizer that combines multiple subauthorizer.
|
Package union implements an authorizer that combines multiple subauthorizer. |
|
endpoints
Package endpoints contains the generic code that provides a RESTful Kubernetes-style API service.
|
Package endpoints contains the generic code that provides a RESTful Kubernetes-style API service. |
|
endpoints/filters
Package filters contains all the http handler chain filters which _are_ api related, i.e.
|
Package filters contains all the http handler chain filters which _are_ api related, i.e. |
|
endpoints/handlers
Package handlers contains HTTP handlers to implement the apiserver APIs.
|
Package handlers contains HTTP handlers to implement the apiserver APIs. |
|
endpoints/handlers/negotiation
Package negotiation contains media type negotiation logic.
|
Package negotiation contains media type negotiation logic. |
|
endpoints/handlers/responsewriters
Package responsewriters containers helpers to write responses in HTTP handlers.
|
Package responsewriters containers helpers to write responses in HTTP handlers. |
|
endpoints/request
Package request contains everything around extracting info from a http request object.
|
Package request contains everything around extracting info from a http request object. |
|
registry
Package registry contains the generic implementation of the storage and system logic.
|
Package registry contains the generic implementation of the storage and system logic. |
|
registry/generic
Package generic provides a generic object store interface and a generic label/field matching type.
|
Package generic provides a generic object store interface and a generic label/field matching type. |
|
registry/generic/registry
Package etcd has a generic implementation of a registry that stores things in etcd.
|
Package etcd has a generic implementation of a registry that stores things in etcd. |
|
registry/generic/rest
Package rest has generic implementations of resources used for REST responses
|
Package rest has generic implementations of resources used for REST responses |
|
registry/rest
Package rest defines common logic around changes to Kubernetes-style resources.
|
Package rest defines common logic around changes to Kubernetes-style resources. |
|
server
Package server contains the plumbing to create kubernetes-like API server command.
|
Package server contains the plumbing to create kubernetes-like API server command. |
|
server/filters
Package filters contains all the http handler chain filters which are not api related.
|
Package filters contains all the http handler chain filters which are not api related. |
|
server/flagz/api/v1alpha1
Package v1alpha1 contains API Schema definitions for the zpages v1alpha1 API group
|
Package v1alpha1 contains API Schema definitions for the zpages v1alpha1 API group |
|
server/healthz
Package healthz implements basic http server health checking.
|
Package healthz implements basic http server health checking. |
|
server/httplog
Package httplog contains a helper object and functions to maintain a log along with an http response.
|
Package httplog contains a helper object and functions to maintain a log along with an http response. |
|
server/mux
Package mux contains abstractions for http multiplexing of APIs.
|
Package mux contains abstractions for http multiplexing of APIs. |
|
server/options
package options is the public flags and options used by a generic api server.
|
package options is the public flags and options used by a generic api server. |
|
server/resourceconfig
Package resourceconfig contains the resource config related helper functions.
|
Package resourceconfig contains the resource config related helper functions. |
|
server/routes
Package routes holds a collection of optional genericapiserver http handlers.
|
Package routes holds a collection of optional genericapiserver http handlers. |
|
server/statusz/api/v1alpha1
Package v1alpha1 contains API Schema definitions for the zpages v1alpha1 API group
|
Package v1alpha1 contains API Schema definitions for the zpages v1alpha1 API group |
|
server/storage
Package storage contains the plumbing to setup the etcd storage of the apiserver.
|
Package storage contains the plumbing to setup the etcd storage of the apiserver. |
|
storage
Interfaces for database-related operations.
|
Interfaces for database-related operations. |
|
storage/errors
Package storage provides conversion of storage errors to API errors.
|
Package storage provides conversion of storage errors to API errors. |
|
storage/value
Package value contains methods for assisting with transformation of values in storage.
|
Package value contains methods for assisting with transformation of values in storage. |
|
storage/value/encrypt/aes
Package aes transforms values for storage at rest using AES-GCM.
|
Package aes transforms values for storage at rest using AES-GCM. |
|
storage/value/encrypt/envelope
Package envelope transforms values for storage at rest using a Envelope provider
|
Package envelope transforms values for storage at rest using a Envelope provider |
|
storage/value/encrypt/envelope/kmsv2
Package kmsv2 transforms values for storage at rest using a Envelope v2 provider
|
Package kmsv2 transforms values for storage at rest using a Envelope v2 provider |
|
storage/value/encrypt/envelope/kmsv2/v2
Package v2 contains definition of kms-plugin's serialized types.
|
Package v2 contains definition of kms-plugin's serialized types. |
|
storage/value/encrypt/secretbox
Package secretbox transforms values for storage at rest using XSalsa20 and Poly1305.
|
Package secretbox transforms values for storage at rest using XSalsa20 and Poly1305. |
|
util/flowcontrol/fairqueuing/queueset
Package queueset implements a technique called "fair queuing for server requests".
|
Package queueset implements a technique called "fair queuing for server requests". |
|
util/flushwriter
Package flushwriter implements a wrapper for a writer that flushes on every write if that writer implements the io.Flusher interface
|
Package flushwriter implements a wrapper for a writer that flushes on every write if that writer implements the io.Flusher interface |
|
util/proxy
Among other files, this directory contains functionality for two stream proxies: streamtranslator.go and streamtunnel.go.
|
Among other files, this directory contains functionality for two stream proxies: streamtranslator.go and streamtunnel.go. |
|
util/webhook
Package webhook implements a generic HTTP webhook plugin.
|
Package webhook implements a generic HTTP webhook plugin. |
|
util/wsstream
Deprecated: This WebSockets package under apiserver is no longer in use.
|
Deprecated: This WebSockets package under apiserver is no longer in use. |
|
plugin
|
|
|
pkg/audit
Package audit contains implementations for pkg/audit/AuditBackend interface
|
Package audit contains implementations for pkg/audit/AuditBackend interface |
|
pkg/audit/buffered
Package buffered provides an implementation for the audit.Backend interface that batches incoming audit events and sends batches to the delegate audit.Backend.
|
Package buffered provides an implementation for the audit.Backend interface that batches incoming audit events and sends batches to the delegate audit.Backend. |
|
pkg/audit/fake
Package fake provides a fake audit.Backend interface implementation for testing.
|
Package fake provides a fake audit.Backend interface implementation for testing. |
|
pkg/audit/truncate
Package truncate provides an implementation for the audit.Backend interface that truncates audit events and sends them to the delegate audit.Backend.
|
Package truncate provides an implementation for the audit.Backend interface that truncates audit events and sends them to the delegate audit.Backend. |
|
pkg/audit/webhook
Package webhook implements the audit.Backend interface using HTTP webhooks.
|
Package webhook implements the audit.Backend interface using HTTP webhooks. |
|
pkg/authenticator
Package authenticator contains implementations for pkg/auth/authenticator interfaces
|
Package authenticator contains implementations for pkg/auth/authenticator interfaces |
|
pkg/authenticator/token/oidc
oidc implements the authenticator.Token interface using the OpenID Connect protocol.
|
oidc implements the authenticator.Token interface using the OpenID Connect protocol. |
|
pkg/authenticator/token/webhook
Package webhook implements the authenticator.Token interface using HTTP webhooks.
|
Package webhook implements the authenticator.Token interface using HTTP webhooks. |
|
pkg/authorizer/webhook
Package webhook implements the authorizer.Authorizer interface using HTTP webhooks.
|
Package webhook implements the authorizer.Authorizer interface using HTTP webhooks. |
Click to show internal directories.
Click to hide internal directories.