From 05b1074d0efa9bf7053ec1295713c0180b9e1db7 Mon Sep 17 00:00:00 2001 From: deads2k Date: Mon, 5 Dec 2016 10:47:41 -0500 Subject: [PATCH] re-organize and document genericapiserver config --- pkg/genericapiserver/config.go | 125 +++++++++++++++++---------------- 1 file changed, 66 insertions(+), 59 deletions(-) diff --git a/pkg/genericapiserver/config.go b/pkg/genericapiserver/config.go index fe3fdcada43..ed7782ac9a8 100644 --- a/pkg/genericapiserver/config.go +++ b/pkg/genericapiserver/config.go @@ -74,87 +74,94 @@ const ( ) // Config is a structure used to configure a GenericAPIServer. +// It's members are sorted rougly in order of importance for composers. type Config struct { - // Destination for audit logs - AuditWriter io.Writer - // Allow downstream consumers to disable swagger. - // This includes returning the generated swagger spec at /swaggerapi and swagger ui at /swagger-ui. - EnableSwaggerSupport bool - // Allow downstream consumers to disable swagger ui. - // Note that this is ignored if EnableSwaggerSupport is false - EnableSwaggerUI bool - // Allows api group versions or specific resources to be conditionally enabled/disabled. - APIResourceConfigSource APIResourceConfigSource - // allow downstream consumers to disable the index route - EnableIndex bool - EnableProfiling bool - // Requires generic profiling enabled - EnableContentionProfiling bool - EnableMetrics bool - EnableGarbageCollection bool - - Version *version.Info - 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 + // 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 - // Map requests to contexts. Exported so downstream consumers can provider their own mappers - RequestContextMapper api.RequestContextMapper + EnableSwaggerSupport bool + EnableSwaggerUI bool + EnableIndex bool + EnableProfiling bool + // Requires generic profiling enabled + EnableContentionProfiling bool + EnableGarbageCollection bool + EnableMetrics bool + EnableOpenAPISupport bool - // Required, the interface for serializing and converting objects to and from the wire - Serializer runtime.NegotiatedSerializer + // 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 - // 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 - - SecureServingInfo *SecureServingInfo - InsecureServingInfo *ServingInfo + //=========================================================================== + // Fields you probably don't care about changing + //=========================================================================== + // 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 port on PublicAddress where a read-write server will be installed. - // Defaults to 6443 if not set. - ReadWritePort int - - // ExternalAddress is the host name to use for external (public internet) facing URLs (e.g. Swagger) - ExternalAddress 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 - - // EnableOpenAPISupport enables OpenAPI support. Allow downstream customers to disable OpenAPI spec. - EnableOpenAPISupport bool - - // OpenAPIConfig will be used in generating OpenAPI spec. + // 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 api.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 has "working" defaults. OpenAPIConfig *common.Config - + // 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 - // Build the handler chains by decorating the apiHandler. - BuildHandlerChainsFunc func(apiHandler http.Handler, c *Config) (secure, insecure http.Handler) + // 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 - // LegacyAPIGroupPrefixes is used to set up URL parsing for authorization and for validating requests - // to InstallLegacyAPIGroup - LegacyAPIGroupPrefixes sets.String + //=========================================================================== + // values below here are targets for removal + //=========================================================================== + + APIResourceConfigSource APIResourceConfigSource + // 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 } type ServingInfo struct {