Documentation ¶
Overview ¶
Package builder contains a builder for creating a new Kubernetes apiserver.
API Extension Servers ¶
API extension servers and apiserver aggregation are techniques for extending the Kubernetes API surface without using CRDs. Rather than registering a resource type as a CRD stored by the apiserver in etcd, apiserver aggregation registers REST endpoints provided by the extension server, and requests are proxied by the main control-plane apiserver to the extension apiserver.
Use Cases ¶
Following are use cases where one may consider using an extension API server rather than CRDs for implementing an extension resource type.
* Resource types which are not backed by storage -- e.g. metrics
* Resource types which may not fit in etcd
* Using a separate etcd instance for the extension types
Registering Types ¶
New resource types may be registered with the API server by implementing the go struct for the type under YOUR_MODULE/pkg/apis/YOUR_GROUP/VERSION/types.go and then calling WithResource. You will need to generate deepcopy and openapi go code for your types to be registered.
Install the code generators (from your module):
$ go get sigs.k8s.io/apiserver-runtime/tools/apiserver-runtime-gen $ apiserver-runtime-gen --install
Add the code generation tag to you main package:
//go:generate apiserver-runtime-gen package main
Run the code generation after having defined your types:
$ go generate ./...
To also generate clients, provide the -g option to apiserver-runtime-gen for the client, lister and informer generators.
$ apiserver-runtime-gen -g client-gen -g deepcopy-gen -g informer-gen -g lister-gen -g openapi-gen
Implementing Type Specific Logic ¶
* How an object is stored may be customized by either 1) implementing interfaces defined in pkg/builder/resource/resourcestrategy or 2) providing a Strategy when registering the type with the builder.
* How a request is handled may be customized by either 1) implementing the interfaces defined in pkg/builder/resource/resourcerest or 2) providing a HandlerProvider when registering the type with the builder.
If the go struct for the resource type implements the resource interfaces, they will automatically be used when the resource type is registered with the builder.
Index ¶
- type Command
- type DefaultStrategy
- type GenericAPIServer
- type OpenAPIDefinition
- type Server
- func (a *Server) ExecuteCommand() error
- func (a *Server) ToServerCommand() (*Command, error)
- func (a *Server) ToServerOptions() (*start.TiltServerOptions, error)
- func (a *Server) WithBearerToken(token string) *Server
- func (a *Server) WithBindPort(port int) *Server
- func (a *Server) WithCertKey(certKey options.GeneratableKeyCert) *Server
- func (a *Server) WithConnProvider(connProvider apiserver.ConnProvider) *Server
- func (a *Server) WithOpenAPIDefinitions(name, version string, openAPI openapicommon.GetOpenAPIDefinitions) *Server
- func (a *Server) WithOutputWriter(out io.Writer) *Server
- func (a *Server) WithResource(obj resource.Object) *Server
- func (a *Server) WithResourceAndHandler(obj resource.Object, sp rest.ResourceHandlerProvider) *Server
- func (a *Server) WithResourceFileStorage(obj resource.Object, path string) *Server
- func (a *Server) WithResourceMemoryStorage(obj resource.Object, path string) *Server
- func (a *Server) WithSubResourceAndHandler(parent resource.Object, subResourcePath string, ...) *Server
- type Storage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DefaultStrategy ¶
type DefaultStrategy = builderrest.DefaultStrategy
DefaultStrategy is a default strategy that may be embedded into other strategies
type GenericAPIServer ¶
type GenericAPIServer = pkgserver.GenericAPIServer
GenericAPIServer is an alias for pkgserver.GenericAPIServer
type OpenAPIDefinition ¶
type OpenAPIDefinition = common.OpenAPIDefinition
OpenAPIDefinition is an alias for common.OpenAPIDefinition
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server builds a new apiserver for a single API group
func NewServerBuilder ¶ added in v0.2.0
func NewServerBuilder() *Server
NewServerBuilder builds an apiserver to server Kubernetes resources and sub resources.
func (*Server) ExecuteCommand ¶ added in v0.2.0
Execute builds and executes the apiserver Command.
func (*Server) ToServerCommand ¶ added in v0.2.0
Builds a cobra command that runs the server. Intended when connecting the server to a CLI.
func (*Server) ToServerOptions ¶
func (a *Server) ToServerOptions() (*start.TiltServerOptions, error)
Builds a server options interpreter that can run the server. Intended when calling the server programatically.
func (*Server) WithBearerToken ¶ added in v0.3.0
WithBearerToken sets up an auth token that's needed to send server requests.
func (*Server) WithBindPort ¶ added in v0.2.0
WithBindPort registers a default port to serve on. This port can still be overidden with flags.
func (*Server) WithCertKey ¶ added in v0.3.1
func (a *Server) WithCertKey(certKey options.GeneratableKeyCert) *Server
WithCertKey injects options for a certificate-key pair that the server will use to identify itself. If no pair is provided, the server will automatically generate one a self-signed one for "localhost".
Note that generating a certificate is expensive. A test certificate is provided under testdata.
func (*Server) WithConnProvider ¶ added in v0.2.0
func (a *Server) WithConnProvider(connProvider apiserver.ConnProvider) *Server
WithConnProvider registers a provider of connections.
If this is set, the server will use this listener and dialer instead of a network host/port.
Mostly useful for testing.
func (*Server) WithOpenAPIDefinitions ¶
func (a *Server) WithOpenAPIDefinitions( name, version string, openAPI openapicommon.GetOpenAPIDefinitions) *Server
WithOpenAPIDefinitions registers resource OpenAPI definitions generated by openapi-gen.
export K8sAPIS=k8s.io/apimachinery/pkg/api/resource,\ k8s.io/apimachinery/pkg/apis/meta/v1,\ k8s.io/apimachinery/pkg/runtime,\ k8s.io/apimachinery/pkg/version export MY_APIS=my-go-pkg/pkg/apis/my-group/my-version export OPENAPI=my-go-pkg/pkg/generated/openapi openapi-gen --input-dirs $K8SAPIS,$MY_APIS --output-package $OPENAPI \ -O zz_generated.openapi --output-base ../../.. --go-header-file ./hack/boilerplate.go.txt
func (*Server) WithOutputWriter ¶ added in v0.2.0
WithOutputWriter redirects output from both stdout and stderr to a custom writer.
func (*Server) WithResource ¶ added in v0.12.0
WithResource registers a resource that is not backed by any storage.
func (*Server) WithResourceAndHandler ¶
func (a *Server) WithResourceAndHandler(obj resource.Object, sp rest.ResourceHandlerProvider) *Server
WithResourceAndHandler registers a request handler for the resource rather than the default etcd backed storage.
Note: WithResourceAndHandler should never be called after the GroupResource has already been registered with another version.
Note: WithResourceAndHandler will NOT register the "status" subresource for the resource object.
func (*Server) WithResourceFileStorage ¶
Registers a request handler for the resource that stores it on the file system.
func (*Server) WithResourceMemoryStorage ¶
Registers a request handler for the resource that stores it in memory.
func (*Server) WithSubResourceAndHandler ¶
func (a *Server) WithSubResourceAndHandler( parent resource.Object, subResourcePath string, sp rest.ResourceHandlerProvider) *Server
WithSubResourceAndHandler registers a request handler for the subresource rather than the default etcd backed storage.
Note: WithSubResource does NOT register the request or parent with the SchemeBuilder. If they were not registered through a WithResource call, then this must be done manually with WithAdditionalSchemeInstallers.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package resource defines interfaces that may be implemented by types -- e.g.
|
Package resource defines interfaces that may be implemented by types -- e.g. |
resourcerest
Package resourcerest defines interfaces for resource REST implementations.
|
Package resourcerest defines interfaces for resource REST implementations. |
resourcestrategy
Package resourcestrategy defines interfaces for customizing how resources are converted and stored.
|
Package resourcestrategy defines interfaces for customizing how resources are converted and stored. |
util
Package util contains a set of utility functions that help plumbing new kubernetes resources into an aggregated apiserver.
|
Package util contains a set of utility functions that help plumbing new kubernetes resources into an aggregated apiserver. |
Package rest contains libraries for implementing resource request handlers.
|
Package rest contains libraries for implementing resource request handlers. |