Documentation ¶
Overview ¶
Package apiserver contains the code that provides a rest.ful api service.
Index ¶
- Constants
- Variables
- func APIVersionHandler(versions ...string) restful.RouteFunction
- func AddApiWebService(container *restful.Container, apiPrefix string, versions []string)
- func CORS(handler http.Handler, allowedOriginPatterns []*regexp.Regexp, ...) http.Handler
- func CreateResource(r rest.Creater, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func DeleteResource(r rest.GracefulDeleter, checkBody bool, scope RequestScope, ...) restful.RouteFunction
- func GetResource(r rest.Getter, scope RequestScope) restful.RouteFunction
- func GetResourceWithOptions(r rest.GetterWithOptions, scope RequestScope, getOptionsKind string, ...) restful.RouteFunction
- func IndexHandler(container *restful.Container, muxHelper *MuxHelper) func(http.ResponseWriter, *http.Request)
- func InstallLogsSupport(mux Mux)
- func InstallServiceErrorHandler(container *restful.Container)
- func InstallSupport(mux Mux, ws *restful.WebService)
- func InstallValidator(mux Mux, servers func() map[string]Server)
- 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, longRunningRequestRE *regexp.Regexp, handler http.Handler) http.Handler
- func NewAlwaysAllowAuthorizer() authorizer.Authorizer
- func NewAlwaysDenyAuthorizer() authorizer.Authorizer
- func NewAuthenticator(clientCAFile string, tokenFile string) (authenticator.Request, error)
- func NewAuthorizerFromAuthorizationConfig(authorizationMode string, authorizationPolicyFile string) (authorizer.Authorizer, error)
- func NewValidator(servers func() map[string]Server) http.Handler
- func PatchResource(r rest.Patcher, scope RequestScope, typer runtime.ObjectTyper, ...) restful.RouteFunction
- func RateLimit(rl util.RateLimiter, handler http.Handler) http.Handler
- func ReadOnly(handler http.Handler) http.Handler
- func RecoverPanics(handler 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
- type APIGroupVersion
- type APIInstaller
- type APIRequestInfo
- type APIRequestInfoResolver
- type Attributes
- type ContextFunc
- type Mux
- type MuxHelper
- type ProxyHandler
- type RedirectHandler
- type RequestAttributeGetter
- type RequestScope
- type ScopeNamer
- type Server
- type ServerStatus
- type WatchServer
Constants ¶
const ( ModeAlwaysAllow string = "AlwaysAllow" ModeAlwaysDeny string = "AlwaysDeny" ModeABAC string = "ABAC" )
const RetryAfter = "1"
Constant for the retry-after interval on rate limiting. TODO: maybe make this dynamic? or user-adjustable?
Variables ¶
var AuthorizationModeChoices = []string{ModeAlwaysAllow, ModeAlwaysDeny, ModeABAC}
Keep this list in sync with constant list above.
Functions ¶
func APIVersionHandler ¶
func APIVersionHandler(versions ...string) restful.RouteFunction
APIVersionHandler returns a handler which will list the provided versions as available.
func AddApiWebService ¶
Adds a service to return the supported api versions.
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 CreateResource ¶
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 DeleteResource ¶
func DeleteResource(r rest.GracefulDeleter, checkBody bool, scope RequestScope, admit admission.Interface) restful.RouteFunction
DeleteResource returns a function that will handle a resource deletion
func GetResource ¶
func GetResource(r rest.Getter, scope RequestScope) restful.RouteFunction
GetResource returns a function that handles retrieving a single resource from a rest.Storage object.
func GetResourceWithOptions ¶
func GetResourceWithOptions(r rest.GetterWithOptions, scope RequestScope, getOptionsKind string, subpath bool, subpathKey string) restful.RouteFunction
GetResourceWithOptions returns a function that handles retrieving a single resource from a rest.Storage object.
func IndexHandler ¶
func IndexHandler(container *restful.Container, muxHelper *MuxHelper) func(http.ResponseWriter, *http.Request)
func InstallLogsSupport ¶
func InstallLogsSupport(mux Mux)
InstallLogsSupport registers the APIServer log support function into a mux.
func InstallServiceErrorHandler ¶
func InstallServiceErrorHandler(container *restful.Container)
func InstallSupport ¶
func InstallSupport(mux Mux, ws *restful.WebService)
TODO: document all handlers InstallSupport registers the APIServer support functions
func InstallValidator ¶
TODO: Convert to go-restful
func IsReadOnlyReq ¶
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 ¶
func ListResource(r rest.Lister, rw rest.Watcher, scope RequestScope, forceWatch bool) restful.RouteFunction
ListResource returns a function that handles retrieving a list of resources from a rest.Storage object.
func MaxInFlightLimit ¶
func MaxInFlightLimit(c chan bool, longRunningRequestRE *regexp.Regexp, handler http.Handler) http.Handler
MaxInFlight limits the number of in-flight requests to buffer size of the passed in channel.
func NewAlwaysAllowAuthorizer ¶
func NewAlwaysAllowAuthorizer() authorizer.Authorizer
func NewAlwaysDenyAuthorizer ¶
func NewAlwaysDenyAuthorizer() authorizer.Authorizer
func NewAuthenticator ¶
func NewAuthenticator(clientCAFile string, tokenFile string) (authenticator.Request, error)
NewAuthenticator returns an authenticator.Request or an error
func NewAuthorizerFromAuthorizationConfig ¶
func NewAuthorizerFromAuthorizationConfig(authorizationMode string, authorizationPolicyFile string) (authorizer.Authorizer, error)
NewAuthorizerFromAuthorizationConfig returns the right sort of authorizer.Authorizer based on the authorizationMode xor an error. authorizationMode should be one of AuthorizationModeChoices.
func NewValidator ¶
NewValidator creates a validator for a set of servers.
func PatchResource ¶
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 ¶
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 UpdateResource ¶
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 ¶
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.
Types ¶
type APIGroupVersion ¶
type APIGroupVersion struct { Storage map[string]rest.Storage Root string Version string // ServerVersion 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 "v1beta3" internal objects. If // empty, defaults to Version. ServerVersion string Mapper meta.RESTMapper Codec runtime.Codec Typer runtime.ObjectTyper Creater runtime.ObjectCreater Convertor runtime.ObjectConvertor Linker runtime.SelfLinker Admit admission.Interface Context api.RequestContextMapper }
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.
func (*APIGroupVersion) InstallREST ¶
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. A restful WebService is created for the group and version.
type APIInstaller ¶
type APIInstaller struct {
// contains filtered or unexported fields
}
func (*APIInstaller) Install ¶
func (a *APIInstaller) Install() (ws *restful.WebService, errors []error)
Installs handlers for API resources.
type APIRequestInfo ¶
type APIRequestInfo struct { // Verb is the kube verb associated with the request, not the http verb. This includes things like list and watch. Verb 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 // Kind is the type of object being manipulated. For example: Pod Kind 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 // Raw is the unparsed form of everything other than parts. // Raw + Parts = complete URL path Raw []string }
APIRequestInfo holds information parsed from the http.Request
type APIRequestInfoResolver ¶
type APIRequestInfoResolver struct { APIPrefixes util.StringSet RestMapper meta.RESTMapper }
func (*APIRequestInfoResolver) GetAPIRequestInfo ¶
func (r *APIRequestInfoResolver) GetAPIRequestInfo(req *http.Request) (APIRequestInfo, error)
TODO write an integration test against the swagger doc to test the APIRequestInfo and match up behavior to responses GetAPIRequestInfo returns the information from the http request. If error is not nil, APIRequestInfo holds the information as best it is known before the failure Valid Inputs: Storage paths /namespaces /namespaces/{namespace} /namespaces/{namespace}/{resource} /namespaces/{namespace}/{resource}/{resourceName} /{resource} /{resource}/{resourceName} /{resource}/{resourceName}?namespace={namespace} /{resource}?namespace={namespace}
Special verbs: /proxy/{resource}/{resourceName} /proxy/namespaces/{namespace}/{resource}/{resourceName} /redirect/namespaces/{namespace}/{resource}/{resourceName} /redirect/{resource}/{resourceName} /watch/{resource} /watch/namespaces/{namespace}/{resource}
Fully qualified paths for above: /api/{version}/* /api/{version}/*
type ContextFunc ¶
ContextFunc returns a Context given a request - a context must be returned
type Mux ¶
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 ¶
Offers additional functionality over ServeMux, for ex: supports listing registered paths.
func (*MuxHelper) HandleFunc ¶
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 RedirectHandler ¶
type RedirectHandler struct {
// contains filtered or unexported fields
}
func (*RedirectHandler) ServeHTTP ¶
func (r *RedirectHandler) ServeHTTP(w http.ResponseWriter, req *http.Request)
type RequestAttributeGetter ¶
type RequestAttributeGetter interface {
GetAttribs(req *http.Request) (attribs authorizer.Attributes)
}
RequestAttributeGetter is a function that extracts authorizer.Attributes from an http.Request
func NewRequestAttributeGetter ¶
func NewRequestAttributeGetter(requestContextMapper api.RequestContextMapper, restMapper meta.RESTMapper, apiRoots ...string) RequestAttributeGetter
NewAttributeGetter returns an object which implements the RequestAttributeGetter interface.
type RequestScope ¶
type RequestScope struct { Namer ScopeNamer ContextFunc runtime.Codec Creater runtime.ObjectCreater Convertor runtime.ObjectConvertor Resource string Kind string APIVersion string // The version of apiserver resources to use ServerAPIVersion string }
RequestScope encapsulates common fields across all RESTful handler methods.
type ScopeNamer ¶
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 ServerStatus ¶
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 (w *WatchServer) HandleWS(ws *websocket.Conn)
HandleWS implements a websocket handler.
func (*WatchServer) ServeHTTP ¶
func (self *WatchServer) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP serves a series of JSON encoded events via straight HTTP with Transfer-Encoding: chunked.