Documentation
¶
Overview ¶
Package apiserver contains the code that provides a rest.ful api service.
Index ¶
- Constants
- Variables
- func APIVersionHandler(s runtime.NegotiatedSerializer, ...) restful.RouteFunction
- func AddApiWebService(s runtime.NegotiatedSerializer, container *restful.Container, apiPrefix string, ...)
- func AddApisWebService(s runtime.NegotiatedSerializer, container *restful.Container, apiPrefix string, ...)
- func AddGroupWebService(s runtime.NegotiatedSerializer, container *restful.Container, path string, ...)
- func AddSupportedResourcesWebService(s runtime.NegotiatedSerializer, ws *restful.WebService, ...)
- func CORS(handler http.Handler, allowedOriginPatterns []*regexp.Regexp, ...) http.Handler
- func ConnectResource(connecter rest.Connecter, scope RequestScope, admit admission.Interface, ...) restful.RouteFunction
- func CreateNamedResource(r rest.NamedCreater, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func CreateResource(r rest.Creater, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func DeleteCollection(r rest.CollectionDeleter, checkBody bool, scope RequestScope, ...) restful.RouteFunction
- func DeleteResource(r rest.GracefulDeleter, allowsOptions bool, scope RequestScope, ...) restful.RouteFunction
- func GetResource(r rest.Getter, e rest.Exporter, scope RequestScope) restful.RouteFunction
- func GetResourceWithOptions(r rest.GetterWithOptions, scope RequestScope) restful.RouteFunction
- func GroupHandler(s runtime.NegotiatedSerializer, group unversioned.APIGroup) restful.RouteFunction
- func IndexHandler(container *restful.Container, muxHelper *MuxHelper) func(http.ResponseWriter, *http.Request)
- func InstallLogsSupport(mux Mux, container *restful.Container)
- func InstallRecoverHandler(s runtime.NegotiatedSerializer, container *restful.Container)
- func InstallServiceErrorHandler(s runtime.NegotiatedSerializer, container *restful.Container, ...)
- func InstallVersionHandler(mux Mux, container *restful.Container)
- func IsAPIPrefixNotFound(err error) bool
- func IsReadOnlyReq(req http.Request) bool
- func ListResource(r rest.Lister, rw rest.Watcher, scope RequestScope, forceWatch bool, ...) restful.RouteFunction
- func MaxInFlightLimit(c chan bool, longRunningRequestCheck LongRunningRequestCheck, ...) http.Handler
- func PatchResource(r rest.Patcher, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func ReadOnly(handler http.Handler) http.Handler
- func RecoverPanics(handler http.Handler) http.Handler
- func RootAPIHandler(s runtime.NegotiatedSerializer, ...) restful.RouteFunction
- func SupportedResourcesHandler(s runtime.NegotiatedSerializer, groupVersion unversioned.GroupVersion, ...) restful.RouteFunction
- func TimeoutHandler(h http.Handler, ...) http.Handler
- func UpdateResource(r rest.Updater, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func WithAuthorizationCheck(handler http.Handler, getAttribs RequestAttributeGetter, ...) http.Handler
- func WithImpersonation(handler http.Handler, requestContextMapper api.RequestContextMapper, ...) http.Handler
- type APIGroupVersion
- type APIInstaller
- type APIResourceLister
- type ContextFunc
- type LongRunningRequestCheck
- type Mux
- type MuxHelper
- type ProxyDialerFunc
- type ProxyHandler
- type RequestAttributeGetter
- type RequestInfo
- type RequestInfoResolver
- type RequestScope
- type ScopeNamer
- type Server
- type ServerStatus
- type StripVersionNegotiatedSerializer
- type ValidatorFn
- type WatchServer
Constants ¶
const ( // Minimum duration before timing out read/write requests MinTimeoutSecs = 300 // Maximum duration before timing out read/write requests MaxTimeoutSecs = 600 )
TODO: Pipe these in through the apiserver cmd line
const MaxPatchConflicts = 5
MaxPatchConflicts is the maximum number of conflicts retry for during a patch operation before returning failure
const RetryAfter = "1"
Constant for the retry-after interval on rate limiting. TODO: maybe make this dynamic? or user-adjustable?
Variables ¶
var NamespaceSubResourcesForTest = sets.NewString(namespaceSubresources.List()...)
NamespaceSubResourcesForTest exports namespaceSubresources for testing in pkg/master/master_test.go, so we never drift
Functions ¶
func APIVersionHandler ¶ added in v0.5.1
func APIVersionHandler(s runtime.NegotiatedSerializer, getAPIVersionsFunc func(req *restful.Request) *unversioned.APIVersions) restful.RouteFunction
APIVersionHandler returns a handler which will list the provided versions as available.
func AddApiWebService ¶ added in v0.9.0
func AddApiWebService(s runtime.NegotiatedSerializer, container *restful.Container, apiPrefix string, getAPIVersionsFunc func(req *restful.Request) *unversioned.APIVersions)
Adds a service to return the supported api versions at the legacy /api.
func AddApisWebService ¶ added in v1.1.0
func AddApisWebService(s runtime.NegotiatedSerializer, container *restful.Container, apiPrefix string, f func(req *restful.Request) []unversioned.APIGroup)
Adds a service to return the supported api versions at /apis.
func AddGroupWebService ¶ added in v1.1.0
func AddGroupWebService(s runtime.NegotiatedSerializer, container *restful.Container, path string, group unversioned.APIGroup)
Adds a service to return the supported versions, preferred version, and name of a group. E.g., a such web service will be registered at /apis/extensions.
func AddSupportedResourcesWebService ¶ added in v1.1.0
func AddSupportedResourcesWebService(s runtime.NegotiatedSerializer, ws *restful.WebService, groupVersion unversioned.GroupVersion, lister APIResourceLister)
Adds a service to return the supported resources, E.g., a such web service will be registered at /apis/extensions/v1.
func CORS ¶
func CORS(handler http.Handler, allowedOriginPatterns []*regexp.Regexp, allowedMethods []string, allowedHeaders []string, allowCredentials string) http.Handler
TODO: use restful.CrossOriginResourceSharing Simple CORS implementation that wraps an http Handler For a more detailed implementation use https://github.com/martini-contrib/cors or implement CORS at your proxy layer Pass nil for allowedMethods and allowedHeaders to use the defaults
func ConnectResource ¶ added in v0.16.1
func ConnectResource(connecter rest.Connecter, scope RequestScope, admit admission.Interface, restPath string) restful.RouteFunction
ConnectResource returns a function that handles a connect request on a rest.Storage object.
func CreateNamedResource ¶ added in v0.17.0
func CreateNamedResource(r rest.NamedCreater, scope RequestScope, typer runtime.ObjectTyper, admit admission.Interface) restful.RouteFunction
CreateNamedResource returns a function that will handle a resource creation with name.
func CreateResource ¶ added in v0.12.0
func CreateResource(r rest.Creater, scope RequestScope, typer runtime.ObjectTyper, admit admission.Interface) restful.RouteFunction
CreateResource returns a function that will handle a resource creation.
func DeleteCollection ¶ added in v1.2.0
func DeleteCollection(r rest.CollectionDeleter, checkBody bool, scope RequestScope, admit admission.Interface) restful.RouteFunction
DeleteCollection returns a function that will handle a collection deletion
func DeleteResource ¶ added in v0.12.0
func DeleteResource(r rest.GracefulDeleter, allowsOptions bool, scope RequestScope, admit admission.Interface) restful.RouteFunction
DeleteResource returns a function that will handle a resource deletion
func GetResource ¶ added in v0.12.0
func GetResource(r rest.Getter, e rest.Exporter, scope RequestScope) restful.RouteFunction
GetResource returns a function that handles retrieving a single resource from a rest.Storage object.
func GetResourceWithOptions ¶ added in v0.15.0
func GetResourceWithOptions(r rest.GetterWithOptions, scope RequestScope) restful.RouteFunction
GetResourceWithOptions returns a function that handles retrieving a single resource from a rest.Storage object.
func GroupHandler ¶ added in v1.1.0
func GroupHandler(s runtime.NegotiatedSerializer, group unversioned.APIGroup) restful.RouteFunction
GroupHandler returns a handler which will return the api.GroupAndVersion of the group.
func IndexHandler ¶ added in v0.10.0
func IndexHandler(container *restful.Container, muxHelper *MuxHelper) func(http.ResponseWriter, *http.Request)
func InstallLogsSupport ¶
func InstallLogsSupport(mux Mux, container *restful.Container)
InstallLogsSupport registers the APIServer's `/logs` into a mux.
func InstallRecoverHandler ¶ added in v1.1.0
func InstallRecoverHandler(s runtime.NegotiatedSerializer, container *restful.Container)
TODO: needs to perform response type negotiation, this is probably the wrong way to recover panics
func InstallServiceErrorHandler ¶ added in v0.16.1
func InstallServiceErrorHandler(s runtime.NegotiatedSerializer, container *restful.Container, requestResolver *RequestInfoResolver, apiVersions []string)
func InstallVersionHandler ¶ added in v1.3.0
func InstallVersionHandler(mux Mux, container *restful.Container)
TODO: document all handlers InstallVersionHandler registers the APIServer's `/version` handler
func IsAPIPrefixNotFound ¶ added in v1.2.0
func IsReadOnlyReq ¶ added in v0.5.1
IsReadOnlyReq() is true for any (or at least many) request which has no observable side effects on state of apiserver (though there may be internal side effects like caching and logging).
func ListResource ¶ added in v0.12.0
func ListResource(r rest.Lister, rw rest.Watcher, scope RequestScope, forceWatch bool, minRequestTimeout time.Duration) restful.RouteFunction
ListResource returns a function that handles retrieving a list of resources from a rest.Storage object.
func MaxInFlightLimit ¶ added in v0.15.0
func MaxInFlightLimit(c chan bool, longRunningRequestCheck LongRunningRequestCheck, handler http.Handler) http.Handler
MaxInFlight limits the number of in-flight requests to buffer size of the passed in channel.
func PatchResource ¶ added in v0.13.0
func PatchResource(r rest.Patcher, scope RequestScope, typer runtime.ObjectTyper, admit admission.Interface, converter runtime.ObjectConvertor) restful.RouteFunction
PatchResource returns a function that will handle a resource patch TODO: Eventually PatchResource should just use GuaranteedUpdate and this routine should be a bit cleaner
func ReadOnly ¶ added in v0.5.1
ReadOnly passes all GET requests on to handler, and returns an error on all other requests.
func RecoverPanics ¶
RecoverPanics wraps an http Handler to recover and log panics.
func RootAPIHandler ¶ added in v1.1.0
func RootAPIHandler(s runtime.NegotiatedSerializer, f func(req *restful.Request) []unversioned.APIGroup) restful.RouteFunction
RootAPIHandler returns a handler which will list the provided groups and versions as available.
func SupportedResourcesHandler ¶ added in v1.1.0
func SupportedResourcesHandler(s runtime.NegotiatedSerializer, groupVersion unversioned.GroupVersion, lister APIResourceLister) restful.RouteFunction
SupportedResourcesHandler returns a handler which will list the provided resources as available.
func TimeoutHandler ¶ added in v1.1.0
func TimeoutHandler(h http.Handler, timeoutFunc func(*http.Request) (timeout <-chan time.Time, msg string)) http.Handler
TimeoutHandler returns an http.Handler that runs h with a timeout determined by timeoutFunc. The new http.Handler calls h.ServeHTTP to handle each request, but if a call runs for longer than its time limit, the handler responds with a 503 Service Unavailable error and the message provided. (If msg is empty, a suitable default message will be sent.) After the handler times out, writes by h to its http.ResponseWriter will return http.ErrHandlerTimeout. If timeoutFunc returns a nil timeout channel, no timeout will be enforced.
func UpdateResource ¶ added in v0.12.0
func UpdateResource(r rest.Updater, scope RequestScope, typer runtime.ObjectTyper, admit admission.Interface) restful.RouteFunction
UpdateResource returns a function that will handle a resource update
func WithAuthorizationCheck ¶ added in v0.5.1
func WithAuthorizationCheck(handler http.Handler, getAttribs RequestAttributeGetter, a authorizer.Authorizer) http.Handler
WithAuthorizationCheck passes all authorized requests on to handler, and returns a forbidden error otherwise.
func WithImpersonation ¶ added in v1.3.0
func WithImpersonation(handler http.Handler, requestContextMapper api.RequestContextMapper, a authorizer.Authorizer) http.Handler
WithImpersonation is a filter that will inspect and check requests that attempt to change the user.Info for their requests
Types ¶
type APIGroupVersion ¶ added in v0.5.1
type APIGroupVersion struct { Storage map[string]rest.Storage Root string // GroupVersion is the external group version GroupVersion unversioned.GroupVersion // RequestInfoResolver is used to parse URLs for the legacy proxy handler. Don't use this for anything else // TODO: refactor proxy handler to use sub resources RequestInfoResolver *RequestInfoResolver // OptionsExternalVersion controls the Kubernetes APIVersion used for common objects in the apiserver // 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 // empty, defaults to GroupVersion. OptionsExternalVersion *unversioned.GroupVersion Mapper meta.RESTMapper // Serializer is used to determine how to convert responses from API methods into bytes to send over // the wire. Serializer runtime.NegotiatedSerializer ParameterCodec runtime.ParameterCodec Typer runtime.ObjectTyper Creater runtime.ObjectCreater Convertor runtime.ObjectConvertor Copier runtime.ObjectCopier Linker runtime.SelfLinker Admit admission.Interface Context api.RequestContextMapper MinRequestTimeout time.Duration // 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]unversioned.GroupVersionKind // ResourceLister is an interface that knows how to list resources // for this API Group. ResourceLister APIResourceLister }
APIGroupVersion is a helper for exposing rest.Storage objects as http.Handlers via go-restful It handles URLs of the form: /${storage_key}[/${object_name}] Where 'storage_key' points to a rest.Storage object stored in storage. This object should contain all parameterization necessary for running a particular API version
func (*APIGroupVersion) InstallREST ¶ added in v0.5.1
func (g *APIGroupVersion) InstallREST(container *restful.Container) error
InstallREST registers the REST handlers (storage, watch, proxy and redirect) into a restful Container. It is expected that the provided path root prefix will serve all operations. Root MUST NOT end in a slash.
func (*APIGroupVersion) UpdateREST ¶ added in v1.1.0
func (g *APIGroupVersion) UpdateREST(container *restful.Container) error
UpdateREST registers the REST handlers for this APIGroupVersion to an existing web service in the restful Container. It will use the prefix (root/version) to find the existing web service. If a web service does not exist within the container to support the prefix this method will return an error.
type APIInstaller ¶ added in v0.12.0
type APIInstaller struct {
// contains filtered or unexported fields
}
func (*APIInstaller) Install ¶ added in v0.12.0
func (a *APIInstaller) Install(ws *restful.WebService) (apiResources []unversioned.APIResource, errors []error)
Installs handlers for API resources.
func (*APIInstaller) NewWebService ¶ added in v1.1.0
func (a *APIInstaller) NewWebService() *restful.WebService
NewWebService creates a new restful webservice with the api installer's prefix and version.
type APIResourceLister ¶ added in v1.4.1
type APIResourceLister interface {
ListAPIResources() []unversioned.APIResource
}
type ContextFunc ¶ added in v0.12.0
ContextFunc returns a Context given a request - a context must be returned
type LongRunningRequestCheck ¶ added in v1.2.0
func BasicLongRunningRequestCheck ¶ added in v1.2.0
func BasicLongRunningRequestCheck(pathRegex *regexp.Regexp, queryParams map[string]string) LongRunningRequestCheck
BasicLongRunningRequestCheck pathRegex operates against the url path, the queryParams match is case insensitive. Any one match flags the request. TODO tighten this check to eliminate the abuse potential by malicious clients that start setting queryParameters to bypass the rate limitter. This could be done using a full parse and special casing the bits we need.
type Mux ¶ added in v0.5.1
type Mux interface { Handle(pattern string, handler http.Handler) HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request)) }
mux is an object that can register http handlers.
type MuxHelper ¶ added in v0.10.0
Offers additional functionality over ServeMux, for ex: supports listing registered paths.
func (*MuxHelper) HandleFunc ¶ added in v0.10.0
type ProxyDialerFunc ¶ added in v0.20.0
type ProxyHandler ¶
type ProxyHandler struct {
// contains filtered or unexported fields
}
ProxyHandler provides a http.Handler which will proxy traffic to locations specified by items implementing Redirector.
func (*ProxyHandler) ServeHTTP ¶
func (r *ProxyHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
type RequestAttributeGetter ¶ added in v0.5.1
type RequestAttributeGetter interface {
GetAttribs(req *http.Request) (attribs authorizer.Attributes)
}
RequestAttributeGetter is a function that extracts authorizer.Attributes from an http.Request
func NewRequestAttributeGetter ¶ added in v0.5.1
func NewRequestAttributeGetter(requestContextMapper api.RequestContextMapper, requestInfoResolver *RequestInfoResolver) RequestAttributeGetter
NewAttributeGetter returns an object which implements the RequestAttributeGetter interface.
type RequestInfo ¶ added in v1.2.0
type RequestInfo struct { // IsResourceRequest indicates whether or not the request is for an API resource or subresource IsResourceRequest bool // Path is the URL path of the request Path string // Verb is the kube verb associated with the request for API requests, not the http verb. This includes things like list and watch. // for non-resource requests, this is the lowercase http verb Verb string APIPrefix string APIGroup string APIVersion string Namespace string // Resource is the name of the resource being requested. This is not the kind. For example: pods Resource string // Subresource is the name of the subresource being requested. This is a different resource, scoped to the parent resource, but it may have a different kind. // For instance, /pods has the resource "pods" and the kind "Pod", while /pods/foo/status has the resource "pods", the sub resource "status", and the kind "Pod" // (because status operates on pods). The binding resource for a pod though may be /pods/foo/binding, which has resource "pods", subresource "binding", and kind "Binding". Subresource string // Name is empty for some verbs, but if the request directly indicates a name (not in body content) then this field is filled in. Name string // Parts are the path parts for the request, always starting with /{resource}/{name} Parts []string }
RequestInfo holds information parsed from the http.Request
type RequestInfoResolver ¶ added in v1.2.0
func (*RequestInfoResolver) GetRequestInfo ¶ added in v1.2.0
func (r *RequestInfoResolver) GetRequestInfo(req *http.Request) (RequestInfo, error)
TODO write an integration test against the swagger doc to test the RequestInfo and match up behavior to responses GetRequestInfo returns the information from the http request. If error is not nil, RequestInfo holds the information as best it is known before the failure It handles both resource and non-resource requests and fills in all the pertinent information for each. Valid Inputs: Resource paths /apis/{api-group}/{version}/namespaces /api/{version}/namespaces /api/{version}/namespaces/{namespace} /api/{version}/namespaces/{namespace}/{resource} /api/{version}/namespaces/{namespace}/{resource}/{resourceName} /api/{version}/{resource} /api/{version}/{resource}/{resourceName}
Special verbs without subresources: /api/{version}/proxy/{resource}/{resourceName} /api/{version}/proxy/namespaces/{namespace}/{resource}/{resourceName} /api/{version}/redirect/namespaces/{namespace}/{resource}/{resourceName} /api/{version}/redirect/{resource}/{resourceName}
Special verbs with subresources: /api/{version}/watch/{resource} /api/{version}/watch/namespaces/{namespace}/{resource}
NonResource paths /apis/{api-group}/{version} /apis/{api-group} /apis /api/{version} /api /healthz /
type RequestScope ¶ added in v0.14.0
type RequestScope struct { Namer ScopeNamer ContextFunc Serializer runtime.NegotiatedSerializer runtime.ParameterCodec Creater runtime.ObjectCreater Convertor runtime.ObjectConvertor Copier runtime.ObjectCopier Resource unversioned.GroupVersionResource Kind unversioned.GroupVersionKind Subresource string }
RequestScope encapsulates common fields across all RESTful handler methods.
type ScopeNamer ¶ added in v0.12.0
type ScopeNamer interface { // Namespace returns the appropriate namespace value from the request (may be empty) or an // error. Namespace(req *restful.Request) (namespace string, err error) // Name returns the name from the request, and an optional namespace value if this is a namespace // scoped call. An error is returned if the name is not available. Name(req *restful.Request) (namespace, name string, err error) // ObjectName returns the namespace and name from an object if they exist, or an error if the object // does not support names. ObjectName(obj runtime.Object) (namespace, name string, err error) // SetSelfLink sets the provided URL onto the object. The method should return nil if the object // does not support selfLinks. SetSelfLink(obj runtime.Object, url string) error // GenerateLink creates a path and query for a given runtime object that represents the canonical path. GenerateLink(req *restful.Request, obj runtime.Object) (path, query string, err error) // GenerateLink creates a path and query for a list that represents the canonical path. GenerateListLink(req *restful.Request) (path, query string, err error) }
ScopeNamer handles accessing names from requests and objects
type Server ¶ added in v0.5.1
type Server struct { Addr string Port int Path string EnableHTTPS bool Validate ValidatorFn }
func (*Server) DoServerCheck ¶ added in v0.16.1
func (server *Server) DoServerCheck(prober httpprober.HTTPProber) (probe.Result, string, error)
type ServerStatus ¶
type StripVersionNegotiatedSerializer ¶ added in v1.2.0
type StripVersionNegotiatedSerializer struct {
runtime.NegotiatedSerializer
}
StripVersionNegotiatedSerializer will return stripVersionEncoder when EncoderForVersion is called. See comments for stripVersionEncoder.
func (StripVersionNegotiatedSerializer) EncoderForVersion ¶ added in v1.2.0
func (n StripVersionNegotiatedSerializer) EncoderForVersion(encoder runtime.Encoder, gv runtime.GroupVersioner) runtime.Encoder
type ValidatorFn ¶ added in v0.20.0
type WatchServer ¶
type WatchServer struct {
// contains filtered or unexported fields
}
WatchServer serves a watch.Interface over a websocket or vanilla HTTP.
func (*WatchServer) HandleWS ¶
func (s *WatchServer) HandleWS(ws *websocket.Conn)
HandleWS implements a websocket handler.
func (*WatchServer) ServeHTTP ¶
func (s *WatchServer) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP serves a series of encoded events via HTTP with Transfer-Encoding: chunked or over a websocket connection.