server

package
Version: v1.7.0 Latest Latest
Warning

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

Go to latest
Published: Jun 29, 2017 License: Apache-2.0 Imports: 64 Imported by: 0

Documentation

Overview

Package server contains the plumbing to create kubernetes-like API server command.

Index

Constants

View Source
const (
	// DefaultLegacyAPIPrefix is where the the legacy APIs will be located.
	DefaultLegacyAPIPrefix = "/api"

	// APIGroupPrefix is where non-legacy API group will be located.
	APIGroupPrefix = "/apis"
)
View Source
const LoopbackClientServerNameOverride = "apiserver-loopback-client"

LoopbackClientServerNameOverride is passed to the apiserver from the loopback client in order to select the loopback certificate via SNI if TLS is used.

Variables

View Source
var EmptyDelegate = emptyDelegate{
	// contains filtered or unexported fields
}

Functions

func DefaultBuildHandlerChain

func DefaultBuildHandlerChain(apiHandler http.Handler, c *Config) http.Handler

func DefaultOpenAPIConfig

func DefaultOpenAPIConfig(getDefinitions openapicommon.GetOpenAPIDefinitions, scheme *runtime.Scheme) *openapicommon.Config

func DefaultSwaggerConfig

func DefaultSwaggerConfig() *swagger.Config

DefaultSwaggerConfig returns a default configuration without WebServiceURL and WebServices set.

func GetNamedCertificateMap

func GetNamedCertificateMap(certs []NamedTLSCert) (map[string]*tls.Certificate, error)

getNamedCertificateMap returns a map of *tls.Certificate by name. It's is suitable for use in tls.Config#NamedCertificates. Returns an error if any of the certs cannot be loaded. Returns nil if len(certs) == 0

func LoopbackHostPort added in v1.7.0

func LoopbackHostPort(bindAddress string) (string, string, error)

LoopbackHostPort returns the host and port loopback REST clients should use to contact the server.

func NewRequestInfoResolver

func NewRequestInfoResolver(c *Config) *apirequest.RequestInfoFactory

func RegisterAllAdmissionPlugins added in v1.7.0

func RegisterAllAdmissionPlugins(plugins *admission.Plugins)

RegisterAllAdmissionPlugins registers all admission plugins

func RunServer added in v1.7.0

func RunServer(server *http.Server, network string, stopCh <-chan struct{}) (int, error)

RunServer listens on the given port, then spawns a go-routine continuously serving until the stopCh is closed. The port is returned. This function does not block.

Types

type APIGroupInfo

type APIGroupInfo struct {
	GroupMeta apimachinery.GroupMeta
	// Info about the resources in this group. Its a map from version to resource to the storage.
	VersionedResourcesStorageMap map[string]map[string]rest.Storage
	// OptionsExternalVersion controls the APIVersion used for common objects in the
	// schema like api.Status, api.DeleteOptions, and metav1.ListOptions. Other implementors may
	// define a version "v1beta1" but want to use the Kubernetes "v1" internal objects.
	// If nil, defaults to groupMeta.GroupVersion.
	// TODO: Remove this when https://github.com/kubernetes/kubernetes/issues/19018 is fixed.
	OptionsExternalVersion *schema.GroupVersion
	// MetaGroupVersion defaults to "meta.k8s.io/v1" and is the scheme group version used to decode
	// common API implementations like ListOptions. Future changes will allow this to vary by group
	// version (for when the inevitable meta/v2 group emerges).
	MetaGroupVersion *schema.GroupVersion

	// Scheme includes all of the types used by this group and how to convert between them (or
	// to convert objects from outside of this group that are accepted in this API).
	// TODO: replace with interfaces
	Scheme *runtime.Scheme
	// NegotiatedSerializer controls how this group encodes and decodes data
	NegotiatedSerializer runtime.NegotiatedSerializer
	// ParameterCodec performs conversions for query parameters passed to API calls
	ParameterCodec runtime.ParameterCodec

	// SubresourceGroupVersionKind contains the GroupVersionKind overrides for each subresource that is
	// accessible from this API group version. The GroupVersionKind is that of the external version of
	// the subresource. The key of this map should be the path of the subresource. The keys here should
	// match the keys in the Storage map above for subresources.
	SubresourceGroupVersionKind map[string]schema.GroupVersionKind
}

Info about an API group.

func NewDefaultAPIGroupInfo

func NewDefaultAPIGroupInfo(group string, registry *registered.APIRegistrationManager, scheme *runtime.Scheme, parameterCodec runtime.ParameterCodec, codecs serializer.CodecFactory) APIGroupInfo

NewDefaultAPIGroupInfo returns an APIGroupInfo stubbed with "normal" values exposed for easier composition from other packages

type APIServerHandler added in v1.7.0

type APIServerHandler struct {
	// FullHandlerChain is the one that is eventually served with.  It should include the full filter
	// chain and then call the Director.
	FullHandlerChain http.Handler
	// The registered APIs.  InstallAPIs uses this.  Other servers probably shouldn't access this directly.
	GoRestfulContainer *restful.Container
	// NonGoRestfulMux is the final HTTP handler in the chain.
	// It comes after all filters and the API handling
	// This is where other servers can attach handler to various parts of the chain.
	NonGoRestfulMux *mux.PathRecorderMux

	// Director is here so that we can properly handle fall through and proxy cases.
	// This looks a bit bonkers, but here's what's happening.  We need to have /apis handling registered in gorestful in order to have
	// swagger generated for compatibility.  Doing that with `/apis` as a webservice, means that it forcibly 404s (no defaulting allowed)
	// all requests which are not /apis or /apis/.  We need those calls to fall through behind goresful for proper delegation.  Trying to
	// register for a pattern which includes everything behind it doesn't work because gorestful negotiates for verbs and content encoding
	// and all those things go crazy when gorestful really just needs to pass through.  In addition, openapi enforces unique verb constraints
	// which we don't fit into and it still muddies up swagger.  Trying to switch the webservices into a route doesn't work because the
	//  containing webservice faces all the same problems listed above.
	// This leads to the crazy thing done here.  Our mux does what we need, so we'll place it in front of gorestful.  It will introspect to
	// decide if the the route is likely to be handled by goresful and route there if needed.  Otherwise, it goes to PostGoRestful mux in
	// order to handle "normal" paths and delegation. Hopefully no API consumers will ever have to deal with this level of detail.  I think
	// we should consider completely removing gorestful.
	// Other servers should only use this opaquely to delegate to an API server.
	Director http.Handler
}

APIServerHandlers holds the different http.Handlers used by the API server. This includes the full handler chain, the director (which chooses between gorestful and nonGoRestful, the gorestful handler (used for the API) which falls through to the nonGoRestful handler on unregistered paths, and the nonGoRestful handler (which can contain a fallthrough of its own) FullHandlerChain -> Director -> {GoRestfulContainer,NonGoRestfulMux} based on inspection of registered web services

func NewAPIServerHandler added in v1.7.0

func NewAPIServerHandler(name string, contextMapper request.RequestContextMapper, s runtime.NegotiatedSerializer, handlerChainBuilder HandlerChainBuilderFn, notFoundHandler http.Handler) *APIServerHandler

func (*APIServerHandler) ListedPaths added in v1.7.0

func (a *APIServerHandler) ListedPaths() []string

ListedPaths returns the paths that should be shown under /

func (*APIServerHandler) ServeHTTP added in v1.7.0

func (a *APIServerHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP makes it an http.Handler

type Config

type Config struct {
	// SecureServingInfo is required to serve https
	SecureServingInfo *SecureServingInfo

	// LoopbackClientConfig is a config for a privileged loopback connection to the API server
	// This is required for proper functioning of the PostStartHooks on a GenericAPIServer
	LoopbackClientConfig *restclient.Config
	// Authenticator determines which subject is making the request
	Authenticator authenticator.Request
	// Authorizer determines whether the subject is allowed to make the request based only
	// on the RequestURI
	Authorizer authorizer.Authorizer
	// AdmissionControl performs deep inspection of a given request (including content)
	// to set values and determine whether its allowed
	AdmissionControl      admission.Interface
	CorsAllowedOriginList []string

	EnableSwaggerUI bool
	EnableIndex     bool
	EnableProfiling bool
	EnableDiscovery bool
	// Requires generic profiling enabled
	EnableContentionProfiling bool
	EnableMetrics             bool

	DisabledPostStartHooks sets.String

	// Version will enable the /version endpoint if non-nil
	Version *version.Info
	// LegacyAuditWriter is the destination for audit logs.  If nil, they will not be written.
	LegacyAuditWriter io.Writer
	// AuditBackend is where audit events are sent to.
	AuditBackend audit.Backend
	// AuditPolicyChecker makes the decision of whether and how to audit log a request.
	AuditPolicyChecker auditpolicy.Checker
	// SupportsBasicAuth indicates that's at least one Authenticator supports basic auth
	// If this is true, a basic auth challenge is returned on authentication failure
	// TODO(roberthbailey): Remove once the server no longer supports http basic auth.
	SupportsBasicAuth bool
	// ExternalAddress is the host name to use for external (public internet) facing URLs (e.g. Swagger)
	// Will default to a value based on secure serving info and available ipv4 IPs.
	ExternalAddress string

	// SharedInformerFactory provides shared informers for resources
	SharedInformerFactory informers.SharedInformerFactory

	// BuildHandlerChainFunc allows you to build custom handler chains by decorating the apiHandler.
	BuildHandlerChainFunc func(apiHandler http.Handler, c *Config) (secure http.Handler)
	// DiscoveryAddresses is used to build the IPs pass to discovery.  If nil, the ExternalAddress is
	// always reported
	DiscoveryAddresses discovery.Addresses
	// The default set of healthz checks. There might be more added via AddHealthzChecks dynamically.
	HealthzChecks []healthz.HealthzChecker
	// LegacyAPIGroupPrefixes is used to set up URL parsing for authorization and for validating requests
	// to InstallLegacyAPIGroup.  New API servers don't generally have legacy groups at all.
	LegacyAPIGroupPrefixes sets.String
	// RequestContextMapper maps requests to contexts. Exported so downstream consumers can provider their own mappers
	// TODO confirm that anyone downstream actually uses this and doesn't just need an accessor
	RequestContextMapper apirequest.RequestContextMapper
	// Serializer is required and provides the interface for serializing and converting objects to and from the wire
	// The default (api.Codecs) usually works fine.
	Serializer runtime.NegotiatedSerializer
	// OpenAPIConfig will be used in generating OpenAPI spec. This is nil by default. Use DefaultOpenAPIConfig for "working" defaults.
	OpenAPIConfig *openapicommon.Config
	// SwaggerConfig will be used in generating Swagger spec. This is nil by default. Use DefaultSwaggerConfig for "working" defaults.
	SwaggerConfig *swagger.Config

	// RESTOptionsGetter is used to construct RESTStorage types via the generic registry.
	RESTOptionsGetter genericregistry.RESTOptionsGetter

	// If specified, requests will be allocated a random timeout between this value, and twice this value.
	// Note that it is up to the request handlers to ignore or honor this timeout. In seconds.
	MinRequestTimeout int
	// MaxRequestsInFlight is the maximum number of parallel non-long-running requests. Every further
	// request has to wait. Applies only to non-mutating requests.
	MaxRequestsInFlight int
	// MaxMutatingRequestsInFlight is the maximum number of parallel mutating requests. Every further
	// request has to wait.
	MaxMutatingRequestsInFlight int
	// Predicate which is true for paths of long-running http requests
	LongRunningFunc apirequest.LongRunningRequestCheck

	// The port on PublicAddress where a read-write server will be installed.
	// Defaults to 6443 if not set.
	ReadWritePort int
	// PublicAddress is the IP address where members of the cluster (kubelet,
	// kube-proxy, services, etc.) can reach the GenericAPIServer.
	// If nil or 0.0.0.0, the host's default interface will be used.
	PublicAddress net.IP
}

Config is a structure used to configure a GenericAPIServer. It's members are sorted roughly in order of importance for composers.

func NewConfig

func NewConfig(codecs serializer.CodecFactory) *Config

NewConfig returns a Config struct with the default values

func (*Config) ApplyClientCert

func (c *Config) ApplyClientCert(clientCAFile string) (*Config, error)

func (*Config) Complete

func (c *Config) Complete() completedConfig

Complete fills in any fields not set that are required to have valid data and can be derived from other fields. If you're going to `ApplyOptions`, do that first. It's mutating the receiver.

func (*Config) SkipComplete

func (c *Config) SkipComplete() completedConfig

SkipComplete provides a way to construct a server instance without config completion.

type DelegationTarget added in v1.7.0

type DelegationTarget interface {
	// UnprotectedHandler returns a handler that is NOT protected by a normal chain
	UnprotectedHandler() http.Handler

	// RequestContextMapper returns the existing RequestContextMapper.  Because we cannot rewire all existing
	// uses of this function, this will be used in any delegating API server
	RequestContextMapper() apirequest.RequestContextMapper

	// PostStartHooks returns the post-start hooks that need to be combined
	PostStartHooks() map[string]postStartHookEntry

	// HealthzChecks returns the healthz checks that need to be combined
	HealthzChecks() []healthz.HealthzChecker

	// ListedPaths returns the paths for supporting an index
	ListedPaths() []string

	// OpenAPISpec returns the OpenAPI spec of the delegation target if exists, nil otherwise.
	OpenAPISpec() *spec.Swagger
}

DelegationTarget is an interface which allows for composition of API servers with top level handling that works as expected.

type GenericAPIServer

type GenericAPIServer struct {

	// LoopbackClientConfig is a config for a privileged loopback connection to the API server
	LoopbackClientConfig *restclient.Config

	SecureServingInfo *SecureServingInfo

	// ExternalAddress is the address (hostname or IP and port) that should be used in
	// external (public internet) URLs for this GenericAPIServer.
	ExternalAddress string

	// Serializer controls how common API objects not in a group/version prefix are serialized for this server.
	// Individual APIGroups may define their own serializers.
	Serializer runtime.NegotiatedSerializer

	// "Outputs"
	// Handler holdes the handlers being used by this API server
	Handler *APIServerHandler

	// DiscoveryGroupManager serves /apis
	DiscoveryGroupManager discovery.GroupManager

	// Enables updating OpenAPI spec using update method.
	OpenAPIService *openapi.OpenAPIService

	// auditing. The backend is started after the server starts listening.
	AuditBackend audit.Backend
	// contains filtered or unexported fields
}

GenericAPIServer contains state for a Kubernetes cluster api server.

func (*GenericAPIServer) AddHealthzChecks

func (s *GenericAPIServer) AddHealthzChecks(checks ...healthz.HealthzChecker) error

AddHealthzCheck allows you to add a HealthzCheck.

func (*GenericAPIServer) AddPostStartHook

func (s *GenericAPIServer) AddPostStartHook(name string, hook PostStartHookFunc) error

AddPostStartHook allows you to add a PostStartHook.

func (*GenericAPIServer) EffectiveSecurePort

func (s *GenericAPIServer) EffectiveSecurePort() int

EffectiveSecurePort returns the secure port we bound to.

func (*GenericAPIServer) HealthzChecks added in v1.7.0

func (s *GenericAPIServer) HealthzChecks() []healthz.HealthzChecker

func (*GenericAPIServer) InstallAPIGroup

func (s *GenericAPIServer) InstallAPIGroup(apiGroupInfo *APIGroupInfo) error

Exposes the given api group in the API.

func (*GenericAPIServer) InstallLegacyAPIGroup

func (s *GenericAPIServer) InstallLegacyAPIGroup(apiPrefix string, apiGroupInfo *APIGroupInfo) error

func (*GenericAPIServer) ListedPaths added in v1.7.0

func (s *GenericAPIServer) ListedPaths() []string

func (*GenericAPIServer) MinRequestTimeout

func (s *GenericAPIServer) MinRequestTimeout() time.Duration

MinRequestTimeout is exposed so that third party resource storage can be build in a different location. TODO refactor third party resource storage

func (*GenericAPIServer) OpenAPISpec added in v1.7.0

func (s *GenericAPIServer) OpenAPISpec() *spec.Swagger

func (*GenericAPIServer) PostStartHooks added in v1.7.0

func (s *GenericAPIServer) PostStartHooks() map[string]postStartHookEntry

func (*GenericAPIServer) PrepareOpenAPIService added in v1.7.0

func (s *GenericAPIServer) PrepareOpenAPIService()

PrepareOpenAPIService installs OpenAPI handler if it does not exists.

func (*GenericAPIServer) PrepareRun

func (s *GenericAPIServer) PrepareRun() preparedGenericAPIServer

PrepareRun does post API installation setup steps.

func (*GenericAPIServer) RequestContextMapper

func (s *GenericAPIServer) RequestContextMapper() apirequest.RequestContextMapper

RequestContextMapper is exposed so that third party resource storage can be build in a different location. TODO refactor third party resource storage

func (*GenericAPIServer) RunPostStartHooks

func (s *GenericAPIServer) RunPostStartHooks(stopCh <-chan struct{})

RunPostStartHooks runs the PostStartHooks for the server

func (*GenericAPIServer) UnprotectedHandler added in v1.7.0

func (s *GenericAPIServer) UnprotectedHandler() http.Handler

type HandlerChainBuilderFn added in v1.7.0

type HandlerChainBuilderFn func(apiHandler http.Handler) http.Handler

HandlerChainBuilderFn is used to wrap the GoRestfulContainer handler using the provided handler chain. It is normally used to apply filtering like authentication and authorization

type NamedTLSCert

type NamedTLSCert struct {
	TLSCert tls.Certificate

	// names is a list of domain patterns: fully qualified domain names, possibly prefixed with
	// wildcard segments.
	Names []string
}

type PostStartHookContext

type PostStartHookContext struct {
	// LoopbackClientConfig is a config for a privileged loopback connection to the API server
	LoopbackClientConfig *restclient.Config
	// StopCh is the channel that will be closed when the server stops
	StopCh <-chan struct{}
}

PostStartHookContext provides information about this API server to a PostStartHookFunc

type PostStartHookFunc

type PostStartHookFunc func(context PostStartHookContext) error

PostStartHookFunc is a function that is called after the server has started. It must properly handle cases like:

1. asynchronous start in multiple API server processes
2. conflicts between the different processes all trying to perform the same action
3. partially complete work (API server crashes while running your hook)
4. API server access **BEFORE** your hook has completed

Think of it like a mini-controller that is super privileged and gets to run in-process If you use this feature, tag @deads2k on github who has promised to review code for anyone's PostStartHook until it becomes easier to use.

type PostStartHookProvider

type PostStartHookProvider interface {
	PostStartHook() (string, PostStartHookFunc, error)
}

PostStartHookProvider is an interface in addition to provide a post start hook for the api server

type SecureServingInfo

type SecureServingInfo struct {
	// BindAddress is the ip:port to serve on
	BindAddress string
	// BindNetwork is the type of network to bind to - defaults to "tcp", accepts "tcp",
	// "tcp4", and "tcp6".
	BindNetwork string

	// Cert is the main server cert which is used if SNI does not match. Cert must be non-nil and is
	// allowed to be in SNICerts.
	Cert *tls.Certificate

	// CACert is an optional certificate authority used for the loopback connection of the Admission controllers.
	// If this is nil, the certificate authority is extracted from Cert or a matching SNI certificate.
	CACert *tls.Certificate

	// SNICerts are the TLS certificates by name used for SNI.
	SNICerts map[string]*tls.Certificate

	// ClientCA is the certificate bundle for all the signers that you'll recognize for incoming client certificates
	ClientCA *x509.CertPool

	// MinTLSVersion optionally overrides the minimum TLS version supported.
	// Values are from tls package constants (https://golang.org/pkg/crypto/tls/#pkg-constants).
	MinTLSVersion uint16

	// CipherSuites optionally overrides the list of allowed cipher suites for the server.
	// Values are from tls package constants (https://golang.org/pkg/crypto/tls/#pkg-constants).
	CipherSuites []uint16
}

func (*SecureServingInfo) NewLoopbackClientConfig

func (s *SecureServingInfo) NewLoopbackClientConfig(token string, loopbackCert []byte) (*restclient.Config, error)

Directories

Path Synopsis
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.
Package healthz implements basic http server health checking.
Package healthz implements basic http server health checking.
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.
Package mux contains abstractions for http multiplexing of APIs.
Package mux contains abstractions for http multiplexing of APIs.
Package openapi contains code to generate OpenAPI discovery spec (which initial version of it also known as Swagger 2.0).
Package openapi contains code to generate OpenAPI discovery spec (which initial version of it also known as Swagger 2.0).
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.
Package routes holds a collection of optional genericapiserver http handlers.
Package routes holds a collection of optional genericapiserver http handlers.
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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL