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

      This section is empty.

      Functions

      func DefaultBuildHandlerChain

      func DefaultBuildHandlerChain(apiHandler http.Handler, c *Config) (secure, insecure 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 NewRequestInfoResolver

          func NewRequestInfoResolver(c *Config) *apirequest.RequestInfoFactory

          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 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
              	// Requires generic profiling enabled
              	EnableContentionProfiling bool
              	EnableMetrics             bool
              
              	DisabledPostStartHooks sets.String
              
              	// Version will enable the /version endpoint if non-nil
              	Version *version.Info
              	// AuditWriter is the destination for audit logs.  If nil, they will not be written.
              	AuditWriter io.Writer
              	// 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
              
              	// BuildHandlerChainsFunc allows you to build custom handler chains by decorating the apiHandler.
              	BuildHandlerChainsFunc func(apiHandler http.Handler, c *Config) (secure, insecure http.Handler)
              	// DiscoveryAddresses is used to build the IPs pass to discovery.  If nil, the ExternalAddress is
              	// always reported
              	DiscoveryAddresses DiscoveryAddresses
              	// 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 genericfilters.LongRunningRequestCheck
              
              	// InsecureServingInfo is required to serve http.  HTTP does NOT include authentication or authorization.
              	// You shouldn't be using this.  It makes sig-auth sad.
              	InsecureServingInfo *ServingInfo
              
              	// 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() *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.

                      func (*Config) WithSerializer

                      func (c *Config) WithSerializer(codecs serializer.CodecFactory) *Config

                      type DefaultDiscoveryAddresses

                      type DefaultDiscoveryAddresses struct {
                      	// DiscoveryCIDRRules is a list of CIDRs and Addresses to use if a client is in the range
                      	DiscoveryCIDRRules []DiscoveryCIDRRule
                      
                      	// DefaultAddress is the address (hostname or IP and port) that should be used in
                      	// if no CIDR matches more specifically.
                      	DefaultAddress string
                      }

                        DefaultDiscoveryAddresses is a default implementation of DiscoveryAddresses that will work in most cases

                        func (DefaultDiscoveryAddresses) ServerAddressByClientCIDRs

                        func (d DefaultDiscoveryAddresses) ServerAddressByClientCIDRs(clientIP net.IP) []metav1.ServerAddressByClientCIDR

                        type DiscoveryAddresses

                        type DiscoveryAddresses interface {
                        	ServerAddressByClientCIDRs(net.IP) []metav1.ServerAddressByClientCIDR
                        }

                        type DiscoveryCIDRRule

                        type DiscoveryCIDRRule struct {
                        	IPRange net.IPNet
                        
                        	// Address is the address (hostname or IP and port) that should be used in
                        	// if this CIDR matches
                        	Address string
                        }

                          DiscoveryCIDRRule is a rule for adding an alternate path to the master based on matching CIDR

                          func (DiscoveryCIDRRule) ServerAddressByClientCIDRs

                          func (d DiscoveryCIDRRule) ServerAddressByClientCIDRs(clientIP net.IP) []metav1.ServerAddressByClientCIDR

                          type GenericAPIServer

                          type GenericAPIServer struct {
                          
                          	// LoopbackClientConfig is a config for a privileged loopback connection to the API server
                          	LoopbackClientConfig *restclient.Config
                          
                          	// The registered APIs
                          	HandlerContainer *genericmux.APIContainer
                          
                          	SecureServingInfo   *SecureServingInfo
                          	InsecureServingInfo *ServingInfo
                          
                          	// 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         http.Handler
                          	InsecureHandler http.Handler
                          	// contains filtered or unexported fields
                          }

                            GenericAPIServer contains state for a Kubernetes cluster api server.

                            func (*GenericAPIServer) AddAPIGroupForDiscovery

                            func (s *GenericAPIServer) AddAPIGroupForDiscovery(apiGroup metav1.APIGroup)

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

                                func (s *GenericAPIServer) DynamicApisDiscovery() *restful.WebService

                                  DynamicApisDiscovery returns a webservice serving api group discovery. Note: during the server runtime apiGroupsForDiscovery might change.

                                  func (*GenericAPIServer) EffectiveSecurePort

                                  func (s *GenericAPIServer) EffectiveSecurePort() int

                                    EffectiveSecurePort returns the secure port we bound to.

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

                                        func (s *GenericAPIServer) PrepareRun() preparedGenericAPIServer

                                          PrepareRun does post API installation setup steps.

                                          func (*GenericAPIServer) RemoveAPIGroupForDiscovery

                                          func (s *GenericAPIServer) RemoveAPIGroupForDiscovery(groupName string)

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

                                              RunPostStartHooks runs the PostStartHooks for the server

                                              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
                                              }

                                                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 {
                                                    	ServingInfo
                                                    
                                                    	// 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
                                                    }

                                                    func (*SecureServingInfo) NewLoopbackClientConfig

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

                                                    type ServingInfo

                                                    type ServingInfo 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
                                                    }

                                                    func (*ServingInfo) NewLoopbackClientConfig

                                                    func (s *ServingInfo) NewLoopbackClientConfig(token string) (*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.