builder

package
v1.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 27, 2022 License: Apache-2.0 Imports: 31 Imported by: 23

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-generators

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

Output:

Index

Examples

Constants

This section is empty.

Variables

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

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

Functions

This section is empty.

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) ExposeLoopbackMasterClientConfig added in v1.0.3 

func (a *Server) ExposeLoopbackMasterClientConfig() *Server

ExposeLoopbackMasterClientConfig exposes loopback client config for accessing the configured master cluster's kube-apiserver 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) WithPostStartHook added in v1.0.3 

func (a *Server) WithPostStartHook(name string, hookFunc genericapiserver.PostStartHookFunc) *Server

WithPostStartHook registers a post start hook which will be invoked after the apiserver is started and before it's ready for serving requests.

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

Output:

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

Output:

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

Output:

func (*Server) WithServerFns 

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

WithServerFns sets functions to customize the GenericAPIServer

func (*Server) WithoutEtcd added in v1.0.1 

func (a *Server) WithoutEtcd() *Server

WithoutEtcd removes etcd related settings from apiserver.

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.

Source Files

View all 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.