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.

Example

Example registers a resource with the apiserver using etcd for storage. If ExampleResource implements resource.Defaulter it will be used for defaulting

package main

import (
	"fmt"

	"sigs.k8s.io/apiserver-runtime/internal/example/v1alpha1"
	"sigs.k8s.io/apiserver-runtime/internal/sample-apiserver/pkg/generated/openapi"
	"sigs.k8s.io/apiserver-runtime/pkg/builder"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/resource"
)

func main() {
	var _ resource.Object = &v1alpha1.ExampleResource{}

	cmd, err := builder.APIServer.
		// Definitions should be generated apiserver-runtime-gen:
		// go get sigs.k8s.io/apiserver-runtime/tools/apiserver-runtime-gen and then add
		// `//go:generate apiserver-runtime-gen` to your main package and run `go generate`
		WithOpenAPIDefinitions("example", "v0.0.0", openapi.GetOpenAPIDefinitions).
		WithResource(&v1alpha1.ExampleResource{}).
		Build()
	if err != nil {
		panic(err)
	}
	// Call Execute on cmd
	fmt.Println(cmd)
}

Index

• Variables
• type Command
• type DefaultStrategy
• type GenericAPIServer
• type OpenAPIDefinition
• type Server
  • func (a *Server) Build() (*Command, error)
  • func (a *Server) DisableAdmissionControllers() *Server
  • func (a *Server) DisableAuthorization() *Server
  • func (a *Server) Execute() error
  • func (a *Server) ExposeLoopbackAuthorizer() *Server
  • func (a *Server) ExposeLoopbackClientConfig() *Server
  • func (a *Server) WithAdditionalSchemeInstallers(fns ...func(*runtime.Scheme) error) *Server
  • func (a *Server) WithAdditionalSchemesToBuild(s ...*runtime.Scheme) *Server
  • func (a *Server) WithConfigFns(fns ...func(config *pkgserver.RecommendedConfig) *pkgserver.RecommendedConfig) *Server
  • func (a *Server) WithFlagFns(fns ...func(set *pflag.FlagSet) *pflag.FlagSet) *Server
  • func (a *Server) WithLocalDebugExtension() *Server
  • func (a *Server) WithOpenAPIDefinitions(name, version string, openAPI openapicommon.GetOpenAPIDefinitions) *Server
  • func (a *Server) WithOptionsFns(fns ...func(*ServerOptions) *ServerOptions) *Server
  • func (a *Server) WithResource(obj resource.Object) *Server
  • func (a *Server) WithResourceAndHandler(obj resource.Object, sp rest.ResourceHandlerProvider) *Server
  • func (a *Server) WithResourceAndStorage(obj resource.Object, fn rest.StoreFn) *Server
  • func (a *Server) WithResourceAndStrategy(obj resource.Object, strategy rest.Strategy) *Server
  • func (a *Server) WithServerFns(fns ...func(server *GenericAPIServer) *GenericAPIServer) *Server
  • func (a *Server) WithSubResource(parent resource.Object, subResource resource.SubResource) *Server
  • func (a *Server) WithSubResourceAndHandler(parent resource.Object, subResource resource.SubResource, ...) *Server
  • func (a *Server) WithSubResourceAndStrategy(parent resource.Object, subResource resource.SubResource, ...) *Server
• type ServerOptions
• type Storage

Examples

• Package
• Server.WithResource
• Server.WithResourceAndHandler
• Server.WithResourceAndStrategy

Variables

var APIServer = &Server{
	storage: map[schema.GroupResource]*singletonProvider{},
}

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

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 (*Server) Build

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

Build returns a Command used to run the apiserver

func (*Server) DisableAdmissionControllers

func (a *Server) DisableAdmissionControllers() *Server

DisableAdmissionControllers disables delegated authentication and authorization

func (*Server) DisableAuthorization

func (a *Server) DisableAuthorization() *Server

DisableAuthorization disables delegated authentication and authorization

func (*Server) Execute

func (a *Server) Execute() error

Execute builds and executes the apiserver Command.

func (*Server) ExposeLoopbackAuthorizer

func (a *Server) ExposeLoopbackAuthorizer() *Server

ExposeLoopbackAuthorizer exposes loopback authorizer as an external singleton.

func (*Server) ExposeLoopbackClientConfig

func (a *Server) ExposeLoopbackClientConfig() *Server

ExposeLoopbackClientConfig exposes loopback client config as an external singleton.

func (*Server) WithAdditionalSchemeInstallers

func (a *Server) WithAdditionalSchemeInstallers(fns ...func(*runtime.Scheme) error) *Server

WithAdditionalSchemeInstallers registers functions to install additional functions or resources into the Scheme. This can be used to manually registering defaulting functions, conversion functions, or resource types, rather than registering them automatically by implementing the corresponding interfaces on the resources.

func (*Server) WithAdditionalSchemesToBuild

func (a *Server) WithAdditionalSchemesToBuild(s ...*runtime.Scheme) *Server

WithAdditionalSchemesToBuild will add types and functions to these Schemes in addition to the apiserver.Scheme. This can be used to register the resource types, defaulting functions, and conversion functions with additional Scheme's.

func (*Server) WithConfigFns

func (a *Server) WithConfigFns(fns ...func(config *pkgserver.RecommendedConfig) *pkgserver.RecommendedConfig) *Server

WithConfigFns sets functions to customize the RecommendedConfig

func (*Server) WithFlagFns

func (a *Server) WithFlagFns(fns ...func(set *pflag.FlagSet) *pflag.FlagSet) *Server

WithFlagFns sets functions to customize the flags for the compiled binary.

func (*Server) WithLocalDebugExtension

func (a *Server) WithLocalDebugExtension() *Server

WithLocalDebugExtension adds an optional local-debug mode to the apiserver so that it can be tested locally without involving a complete kubernetes cluster. A flag named "--standalone-debug-mode" will also be added the binary which forcily requires "--bind-address" to be "127.0.0.1" in order to avoid security issues.

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) WithOptionsFns

func (a *Server) WithOptionsFns(fns ...func(*ServerOptions) *ServerOptions) *Server

WithOptionsFns sets functions to customize the ServerOptions used to create the apiserver

func (*Server) WithResource

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

WithResource registers the resource with the apiserver.

If no versions of this GroupResource have already been registered, a new default handler will be registered. If the object implements rest.Getter, rest.Updater or rest.Creator then the provided object itself will be used as the rest handler for the resource type.

If no versions of this GroupResource have already been registered and the object does NOT implement the rest interfaces, then a new etcd backed storage will be created for the object and used as the handler. The storage will use a DefaultStrategy, which delegates functions to the object if the object implements interfaces defined in the "apiserver-runtime/pkg/builder/rest" package. Otherwise it will provide a default behavior.

WithResource will automatically register the "status" subresource if the object implements the resource.StatusGetSetter interface.

WithResource will automatically register version-specific defaulting for this GroupVersionResource if the object implements the resource.Defaulter interface.

WithResource automatically adds the object and its list type to the known types. If the object also declares itself as the storage version, the object and its list type will be added as storage versions to the SchemeBuilder as well. The storage version is the version accepted by the handler.

If another version of the object's GroupResource has already been registered, then the resource will use the handler already registered for that version of the GroupResource. Objects for this version will be converted to the object version which the handler accepts before the handler is invoked.

Example

Registers multiple versions of the same resource with the apiserver, using etcd for storage. The storage version is the first one registered (v1alpha1), and alternate versions (v1beta1) are converted to the storage version before being stored. Requires that conversion functions be registered with the apiserver.Scheme to convert alternate versions to/from the storage version.

package main

import (
	"fmt"

	"sigs.k8s.io/apiserver-runtime/internal/example/v1alpha1"
	"sigs.k8s.io/apiserver-runtime/internal/example/v1beta1"
	"sigs.k8s.io/apiserver-runtime/internal/sample-apiserver/pkg/generated/openapi"
	"sigs.k8s.io/apiserver-runtime/pkg/builder"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/resource"
)

func main() {
	var _ resource.Object = &v1alpha1.ExampleResource{}
	var _ resource.Object = &v1beta1.ExampleResource{}

	cmd, err := builder.APIServer.
		// Definitions should be generated apiserver-runtime-gen:
		// go get sigs.k8s.io/apiserver-runtime/tools/apiserver-runtime-gen and then add
		// `//go:generate apiserver-runtime-gen` to your main package and run `go generate`
		WithOpenAPIDefinitions("example", "v0.0.0", openapi.GetOpenAPIDefinitions).
		// v1alpha1 will be the storage version because it was registered first
		WithResource(&v1alpha1.ExampleResource{}).
		// v1beta1 objects will be converted to v1alpha1 versions before being stored
		WithResource(&v1beta1.ExampleResource{}).
		Build()
	if err != nil {
		panic(err)
	}
	// Call Execute on cmd
	fmt.Println(cmd)
}

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.

Example

Register a resource with the apiserver using the ExampleHandlerProvider to handle requests rather than etcd based storage. Request handler handles v1alpha1 versions of the resource, and v1beta1 versions are converted to v1alpha1 versions before being handled.

package main

import (
	"fmt"

	"sigs.k8s.io/apiserver-runtime/internal/example/handler"
	"sigs.k8s.io/apiserver-runtime/internal/example/v1alpha1"
	"sigs.k8s.io/apiserver-runtime/internal/example/v1beta1"
	"sigs.k8s.io/apiserver-runtime/internal/sample-apiserver/pkg/generated/openapi"
	"sigs.k8s.io/apiserver-runtime/pkg/builder"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/resource"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/rest"
)

func main() {
	var _ resource.Object = &v1alpha1.ExampleResource{}
	var _ resource.Object = &v1beta1.ExampleResource{}
	var _ rest.ResourceHandlerProvider = handler.ExampleHandlerProvider

	cmd, err := builder.APIServer.
		// Definitions should be generated apiserver-runtime-gen:
		// go get sigs.k8s.io/apiserver-runtime/tools/apiserver-runtime-gen and then add
		// `//go:generate apiserver-runtime-gen` to your main package and run `go generate`
		WithOpenAPIDefinitions("example", "v0.0.0", openapi.GetOpenAPIDefinitions).
		// v1alpha1 will be the storage version because it was registered first
		WithResourceAndHandler(&v1alpha1.ExampleResource{}, handler.ExampleHandlerProvider).
		// v1beta1 objects will be converted to v1alpha1 versions before the ExampleHandler is invoked
		WithResource(&v1beta1.ExampleResource{}).
		Build()
	if err != nil {
		panic(err)
	}
	// Call Execute on cmd
	fmt.Println(cmd)
}

func (*Server) WithResourceAndStorage

func (a *Server) WithResourceAndStorage(obj resource.Object, fn rest.StoreFn) *Server

WithResourceAndStorage registers the resource with the apiserver, applying fn to the storage for the resource before completing it.

May be used to change low-level storage configuration or swap out the storage backend to something other than etcd.

Note: WithResourceAndHandler should never be called after the GroupResource has already been registered with another version.

func (*Server) WithResourceAndStrategy

func (a *Server) WithResourceAndStrategy(obj resource.Object, strategy rest.Strategy) *Server

WithResourceAndStrategy registers the resource with the apiserver creating a new etcd backed storage for the GroupResource using the provided strategy. In most cases callers should instead use WithResource and implement the interfaces defined in "apiserver-runtime/pkg/builder/rest" to control the Strategy.

Note: WithResourceAndHandler should never be called after the GroupResource has already been registered with another version.

Example

Registers a resource with the apiserver using the ExampleStrategy to configure etcd storage. Alternate versions (v1beta1) are converted to v1alpha1 versions before being stored using the ExampleStrategy.

package main

import (
	"fmt"

	"sigs.k8s.io/apiserver-runtime/internal/example/strategy"
	"sigs.k8s.io/apiserver-runtime/internal/example/v1alpha1"
	"sigs.k8s.io/apiserver-runtime/internal/example/v1beta1"
	"sigs.k8s.io/apiserver-runtime/internal/sample-apiserver/pkg/generated/openapi"
	"sigs.k8s.io/apiserver-runtime/pkg/builder"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/resource"
	"sigs.k8s.io/apiserver-runtime/pkg/builder/rest"
)

func main() {
	var _ resource.Object = &v1alpha1.ExampleResource{}
	var _ resource.Object = &v1beta1.ExampleResource{}
	var _ rest.Strategy = &strategy.ExampleStrategy{}

	cmd, err := builder.APIServer.
		// Definitions should be generated apiserver-runtime-gen:
		// go get sigs.k8s.io/apiserver-runtime/tools/apiserver-runtime-gen and then add
		// `//go:generate apiserver-runtime-gen` to your main package and run `go generate`
		WithOpenAPIDefinitions("example", "v0.0.0", openapi.GetOpenAPIDefinitions).
		// v1alpha1 will be the storage version because it was registered first, and objects will be stored
		// using the provided Strategy
		WithResourceAndStrategy(&v1alpha1.ExampleResource{}, strategy.ExampleStrategy{}).
		// v1beta1 objects will be converted to v1alpha1 versions before being stored using the ExampleStrategy
		WithResource(&v1beta1.ExampleResource{}).
		Build()
	if err != nil {
		panic(err)
	}
	// Call Execute on cmd
	fmt.Println(cmd)
}

func (*Server) WithServerFns

func (a *Server) WithServerFns(fns ...func(server *GenericAPIServer) *GenericAPIServer) *Server

WithServerFns sets functions to customize the GenericAPIServer

func (*Server) WithSubResource

func (a *Server) WithSubResource(
	parent resource.Object, subResource resource.SubResource) *Server

WithSubResource registers a subresource with the apiserver under an existing resource. Subresource can be used to implement interfaces which may be implemented by multiple resources -- e.g. "scale".

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.

func (*Server) WithSubResourceAndHandler

func (a *Server) WithSubResourceAndHandler(
	parent resource.Object, subResource resource.SubResource, 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.

func (*Server) WithSubResourceAndStrategy

func (a *Server) WithSubResourceAndStrategy(
	parent resource.Object, subResource resource.SubResource, strategy rest.Strategy) *Server

WithSubResourceAndStrategy registers a subresource with the apiserver under an existing resource. Subresource can be used to implement interfaces which may be implemented by multiple resources -- e.g. "scale".

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 ServerOptions

type ServerOptions = server.ServerOptions

ServerOptions is an alias for server.ServerOptions

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.