genericapiserver

Documentation

Overview

Package genericapiserver contains code to setup a generic kubernetes-like API server. This does not contain any kubernetes API specific code. Note that this is a work in progress. We are pulling out generic code (specifically from pkg/master and pkg/apiserver) here. We plan to move this package into a separate repo on github once it is done. For more details: https://github.com/kubernetes/kubernetes/issues/2742

Index

• Constants
• func NewHandlerContainer(mux *http.ServeMux, s runtime.NegotiatedSerializer) *restful.Container
• type APIGroupInfo
• type APIGroupVersionOverride
• type Config
• type GenericAPIServer
  • func New(c *Config) (*GenericAPIServer, error)
  • func (s *GenericAPIServer) AddAPIGroupForDiscovery(apiGroup unversioned.APIGroup)
  • func (s *GenericAPIServer) HandleFuncWithAuth(pattern string, handler func(http.ResponseWriter, *http.Request))
  • func (s *GenericAPIServer) HandleWithAuth(pattern string, handler http.Handler)
  • func (s *GenericAPIServer) InstallAPIGroups(groupsInfo []APIGroupInfo) error
  • func (s *GenericAPIServer) InstallSwaggerAPI()
  • func (s *GenericAPIServer) NewRequestInfoResolver() *apiserver.RequestInfoResolver
  • func (s *GenericAPIServer) RemoveAPIGroupForDiscovery(groupName string)
  • func (s *GenericAPIServer) Run(options *ServerRunOptions)
  • func (s *GenericAPIServer) StorageDecorator() generic.StorageDecorator
• type ServerRunOptions
  • func NewServerRunOptions() *ServerRunOptions
• type StorageDestinations
  • func NewStorageDestinations() StorageDestinations
  • func (s *StorageDestinations) AddAPIGroup(group string, defaultStorage storage.Interface)
  • func (s *StorageDestinations) AddStorageOverride(group, resource string, override storage.Interface)
  • func (s *StorageDestinations) Backends() []string
  • func (s *StorageDestinations) Get(group, resource string) storage.Interface
  • func (s *StorageDestinations) Search(groups []string, resource string) storage.Interface
• type StorageDestinationsForAPIGroup

Constants

const (
	DefaultEtcdPathPrefix = "/registry"
)

Functions

func NewHandlerContainer

func NewHandlerContainer(mux *http.ServeMux, s runtime.NegotiatedSerializer) *restful.Container

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
	// True, if this is the legacy group ("/v1").
	IsLegacyGroup bool
	// OptionsExternalVersion controls the APIVersion used for common objects in the
	// schema like api.Status, api.DeleteOptions, and api.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 *unversioned.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
}

Info about an API group.

type APIGroupVersionOverride

type APIGroupVersionOverride struct {
	// Whether to enable or disable this group version.
	Disable bool
	// List of overrides for individual resources in this group version.
	ResourceOverrides map[string]bool
}

Specifies the overrides for various API group versions. This can be used to enable/disable entire group versions or specific resources.

type Config

type Config struct {
	StorageDestinations StorageDestinations
	// StorageVersions is a map between groups and their storage versions
	StorageVersions map[string]string
	// allow downstream consumers to disable the core controller loops
	EnableLogsSupport bool
	EnableUISupport   bool
	// allow downstream consumers to disable swagger
	EnableSwaggerSupport bool
	// Allows api group versions or specific resources to be conditionally enabled/disabled.
	APIGroupVersionOverrides map[string]APIGroupVersionOverride
	// allow downstream consumers to disable the index route
	EnableIndex           bool
	EnableProfiling       bool
	EnableWatchCache      bool
	APIPrefix             string
	APIGroupPrefix        string
	CorsAllowedOriginList []string
	Authenticator         authenticator.Request
	// TODO(roberthbailey): Remove once the server no longer supports http basic auth.
	SupportsBasicAuth      bool
	Authorizer             authorizer.Authorizer
	AdmissionControl       admission.Interface
	MasterServiceNamespace string

	// Map requests to contexts. Exported so downstream consumers can provider their own mappers
	RequestContextMapper api.RequestContextMapper

	// Required, the interface for serializing and converting objects to and from the wire
	Serializer runtime.NegotiatedSerializer

	// If specified, all web services will be registered into this container
	RestfulContainer *restful.Container

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

	// Number of masters running; all masters must be started with the
	// same value for this field. (Numbers > 1 currently untested.)
	MasterCount int

	// The port on PublicAddress where a read-write server will be installed.
	// Defaults to 6443 if not set.
	ReadWritePort int

	// ExternalHost is the host name to use for external (public internet) facing URLs (e.g. Swagger)
	ExternalHost string

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

	// Control the interval that pod, node IP, and node heath status caches
	// expire.
	CacheTimeout time.Duration

	// The range of IPs to be assigned to services with type=ClusterIP or greater
	ServiceClusterIPRange *net.IPNet

	// The IP address for the GenericAPIServer service (must be inside ServiceClusterIPRange)
	ServiceReadWriteIP net.IP

	// Port for the apiserver service.
	ServiceReadWritePort int

	// The range of ports to be assigned to services with type=NodePort or greater
	ServiceNodePortRange utilnet.PortRange

	// Used to customize default proxy dial/tls options
	ProxyDialer          apiserver.ProxyDialerFunc
	ProxyTLSClientConfig *tls.Config

	// Additional ports to be exposed on the GenericAPIServer service
	// extraServicePorts is injectable in the event that more ports
	// (other than the default 443/tcp) are exposed on the GenericAPIServer
	// and those ports need to be load balanced by the GenericAPIServer
	// service because this pkg is linked by out-of-tree projects
	// like openshift which want to use the GenericAPIServer but also do
	// more stuff.
	ExtraServicePorts []api.ServicePort
	// Additional ports to be exposed on the GenericAPIServer endpoints
	// Port names should align with ports defined in ExtraServicePorts
	ExtraEndpointPorts []api.EndpointPort

	KubernetesServiceNodePort int
}

Config is a structure used to configure a GenericAPIServer.

type GenericAPIServer

type GenericAPIServer struct {
	// "Inputs", Copied from Config
	ServiceClusterIPRange *net.IPNet
	ServiceNodePortRange  utilnet.PortRange

	MinRequestTimeout time.Duration

	MuxHelper        *apiserver.MuxHelper
	HandlerContainer *restful.Container
	RootWebService   *restful.WebService

	APIPrefix      string
	APIGroupPrefix string

	AdmissionControl         admission.Interface
	MasterCount              int
	ApiGroupVersionOverrides map[string]APIGroupVersionOverride
	RequestContextMapper     api.RequestContextMapper

	// ExternalAddress is the address (hostname or IP and port) that should be used in
	// external (public internet) URLs for this GenericAPIServer.
	ExternalAddress string
	// ClusterIP is the IP address of the GenericAPIServer within the cluster.
	ClusterIP            net.IP
	PublicReadWritePort  int
	ServiceReadWriteIP   net.IP
	ServiceReadWritePort int

	ExtraServicePorts  []api.ServicePort
	ExtraEndpointPorts []api.EndpointPort

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

	// Used for custom proxy dialing, and proxy TLS options
	ProxyTransport http.RoundTripper

	KubernetesServiceNodePort int
	// contains filtered or unexported fields
}

GenericAPIServer contains state for a Kubernetes cluster api server.

func New

func New(c *Config) (*GenericAPIServer, error)

New returns a new instance of GenericAPIServer from the given config. Certain config fields will be set to a default value if unset, including:

ServiceClusterIPRange
ServiceNodePortRange
MasterCount
ReadWritePort
PublicAddress

Public fields:

Handler -- The returned GenericAPIServer has a field TopHandler which is an
http.Handler which handles all the endpoints provided by the GenericAPIServer,
including the API, the UI, and miscellaneous debugging endpoints.  All
these are subject to authorization and authentication.
InsecureHandler -- an http.Handler which handles all the same
endpoints as Handler, but no authorization and authentication is done.

Public methods:

HandleWithAuth -- Allows caller to add an http.Handler for an endpoint
that uses the same authentication and authorization (if any is configured)
as the GenericAPIServer's built-in endpoints.
If the caller wants to add additional endpoints not using the GenericAPIServer's
auth, then the caller should create a handler for those endpoints, which delegates the
any unhandled paths to "Handler".

func (*GenericAPIServer) AddAPIGroupForDiscovery

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

func (*GenericAPIServer) HandleFuncWithAuth

func (s *GenericAPIServer) HandleFuncWithAuth(pattern string, handler func(http.ResponseWriter, *http.Request))

HandleFuncWithAuth adds an http.Handler for pattern to an http.ServeMux Applies the same authentication and authorization (if any is configured) to the request is used for the GenericAPIServer's built-in endpoints.

func (*GenericAPIServer) HandleWithAuth

func (s *GenericAPIServer) HandleWithAuth(pattern string, handler http.Handler)

HandleWithAuth adds an http.Handler for pattern to an http.ServeMux Applies the same authentication and authorization (if any is configured) to the request is used for the GenericAPIServer's built-in endpoints.

func (*GenericAPIServer) InstallAPIGroups

func (s *GenericAPIServer) InstallAPIGroups(groupsInfo []APIGroupInfo) error

Exposes the given group versions in API.

func (*GenericAPIServer) InstallSwaggerAPI

func (s *GenericAPIServer) InstallSwaggerAPI()

InstallSwaggerAPI installs the /swaggerapi/ endpoint to allow schema discovery and traversal. It is optional to allow consumers of the Kubernetes GenericAPIServer to register their own web services into the Kubernetes mux prior to initialization of swagger, so that other resource types show up in the documentation.

func (*GenericAPIServer) NewRequestInfoResolver

func (s *GenericAPIServer) NewRequestInfoResolver() *apiserver.RequestInfoResolver

func (*GenericAPIServer) RemoveAPIGroupForDiscovery

func (s *GenericAPIServer) RemoveAPIGroupForDiscovery(groupName string)

func (*GenericAPIServer) Run

func (s *GenericAPIServer) Run(options *ServerRunOptions)

func (*GenericAPIServer) StorageDecorator

func (s *GenericAPIServer) StorageDecorator() generic.StorageDecorator

type ServerRunOptions

type ServerRunOptions struct {
	BindAddress          net.IP
	CertDirectory        string
	ClientCAFile         string
	EtcdQuorumRead       bool
	InsecureBindAddress  net.IP
	InsecurePort         int
	LongRunningRequestRE string
	MaxRequestsInFlight  int
	SecurePort           int
	TLSCertFile          string
	TLSPrivateKeyFile    string
}

ServerRunOptions contains the options while running a generic api server.

func NewServerRunOptions

func NewServerRunOptions() *ServerRunOptions

type StorageDestinations

type StorageDestinations struct {
	APIGroups map[string]*StorageDestinationsForAPIGroup
}

StorageDestinations is a mapping from API group & resource to the underlying storage interfaces.

func NewStorageDestinations

func NewStorageDestinations() StorageDestinations

func (*StorageDestinations) AddAPIGroup

func (s *StorageDestinations) AddAPIGroup(group string, defaultStorage storage.Interface)

AddAPIGroup replaces 'group' if it's already registered.

func (*StorageDestinations) AddStorageOverride

func (s *StorageDestinations) AddStorageOverride(group, resource string, override storage.Interface)

func (*StorageDestinations) Backends

func (s *StorageDestinations) Backends() []string

Get all backends for all registered storage destinations. Used for getting all instances for health validations.

func (*StorageDestinations) Get

func (s *StorageDestinations) Get(group, resource string) storage.Interface

Get finds the storage destination for the given group and resource. It will Fatalf if the group has no storage destination configured.

func (*StorageDestinations) Search

func (s *StorageDestinations) Search(groups []string, resource string) storage.Interface

Search is like Get, but can be used to search a list of groups. It tries the groups in order (and Fatalf's if none of them exist). The intention is for this to be used for resources that move between groups.

type StorageDestinationsForAPIGroup

type StorageDestinationsForAPIGroup struct {
	Default   storage.Interface
	Overrides map[string]storage.Interface
}