builder

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 NewServerBuilder() *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

Types

type Command

type Command = cobra.Command

Command is an alias for cobra.Command and is used to start the apiserver.

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

func NewServerBuilder() *Server

NewServerBuilder builds an apiserver to server Kubernetes resources and sub resources.

func (*Server) ExecuteCommand

func (a *Server) ExecuteCommand() error

Execute builds and executes the apiserver Command.

func (*Server) ToServerCommand

func (a *Server) ToServerCommand() (*Command, error)

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

func (a *Server) WithBearerToken(token string) *Server

WithBearerToken sets up an auth token that's needed to send server requests.

func (*Server) WithBindPort

func (a *Server) WithBindPort(port int) *Server

WithBindPort registers a default port to serve on. This port can still be overidden with flags.

func (*Server) WithCertKey

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

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

func (a *Server) WithOutputWriter(out io.Writer) *Server

WithOutputWriter redirects output from both stdout and stderr to a custom writer.

func (*Server) WithResource

func (a *Server) WithResource(obj resource.Object) *Server

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

func (a *Server) WithResourceFileStorage(obj resource.Object, path string) *Server

Registers a request handler for the resource that stores it on the file system.

func (*Server) WithResourceMemoryStorage

func (a *Server) WithResourceMemoryStorage(obj resource.Object, path string) *Server

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.

type Storage

type Storage = rest.Storage

Storage is an alias for rest.Storage. Storage implements the interfaces defined in the rest package to expose new REST endpoints for a Kubernetes resource.