package admission

import "sigs.k8s.io/controller-runtime/pkg/webhook/admission"

Package admission provides implementation for admission webhook and methods to implement admission webhook handlers.

See examples/mutatingwebhook.go and examples/validatingwebhook.go for examples of admission webhooks.

Index ¶

• func DefaultLogConstructor(base logr.Logger, req *Request) logr.Logger
• func DefaulterRemoveUnknownOrOmitableFields(o *defaulterOptions)
• func NewContextWithRequest(ctx context.Context, req Request) context.Context
• func StandaloneWebhook(hook *Webhook, opts StandaloneOptions) (http.Handler, error)
• type CustomDefaulter
• type CustomValidator
• type Decoder
• func NewDecoder(scheme *runtime.Scheme) Decoder
• type DefaulterOption
• type Handler
• func MultiMutatingHandler(handlers ...Handler) Handler
• func MultiValidatingHandler(handlers ...Handler) Handler
• type HandlerFunc
• func (f HandlerFunc) Handle(ctx context.Context, req Request) Response
• type Request
• func RequestFromContext(ctx context.Context) (Request, error)
• type Response
• func Allowed(message string) Response
• func Denied(message string) Response
• func Errored(code int32, err error) Response
• func PatchResponseFromRaw(original, current []byte) Response
• func Patched(message string, patches ...jsonpatch.JsonPatchOperation) Response
• func ValidationResponse(allowed bool, message string) Response
• func (r *Response) Complete(req Request) error
• func (r Response) WithWarnings(warnings ...string) Response
• type StandaloneOptions
• type Warnings
• type Webhook
• func WithCustomDefaulter(scheme *runtime.Scheme, obj runtime.Object, defaulter CustomDefaulter, opts ...DefaulterOption) *Webhook
• func WithCustomValidator(scheme *runtime.Scheme, obj runtime.Object, validator CustomValidator) *Webhook
• func (wh *Webhook) Handle(ctx context.Context, req Request) (response Response)
• func (wh *Webhook) ServeHTTP(w http.ResponseWriter, r *http.Request)
• func (wh *Webhook) WithRecoverPanic(recoverPanic bool) *Webhook

Functions ¶

func DefaultLogConstructor ¶

func DefaultLogConstructor(base logr.Logger, req *Request) logr.Logger

DefaultLogConstructor adds some commonly interesting fields to the given logger.

func DefaulterRemoveUnknownOrOmitableFields ¶

func DefaulterRemoveUnknownOrOmitableFields(o *defaulterOptions)

DefaulterRemoveUnknownOrOmitableFields makes the defaulter prune fields that are in the json object retrieved by the webhook but not in the local go type json representation. This happens for example when the CRD in the apiserver has fields that our go type doesn't know about, because it's outdated, or the field has a zero value and is `omitempty`.

func NewContextWithRequest ¶

func NewContextWithRequest(ctx context.Context, req Request) context.Context

NewContextWithRequest returns a new Context, derived from ctx, which carries the provided admission.Request.

func StandaloneWebhook ¶

func StandaloneWebhook(hook *Webhook, opts StandaloneOptions) (http.Handler, error)

StandaloneWebhook prepares a webhook for use without a webhook.Server, passing in the information normally populated by webhook.Server and instrumenting the webhook with metrics.

Use this to attach your webhook to an arbitrary HTTP server or mux.

Note that you are responsible for terminating TLS if you use StandaloneWebhook in your own server/mux. In order to be accessed by a kubernetes cluster, all webhook servers require TLS.

Types ¶

type CustomDefaulter ¶

type CustomDefaulter interface {
	Default(ctx context.Context, obj runtime.Object) error
}

CustomDefaulter defines functions for setting defaults on resources.

type CustomValidator ¶

type CustomValidator interface {
	// ValidateCreate validates the object on creation.
	// The optional warnings will be added to the response as warning messages.
	// Return an error if the object is invalid.
	ValidateCreate(ctx context.Context, obj runtime.Object) (warnings Warnings, err error)

	// ValidateUpdate validates the object on update.
	// The optional warnings will be added to the response as warning messages.
	// Return an error if the object is invalid.
	ValidateUpdate(ctx context.Context, oldObj, newObj runtime.Object) (warnings Warnings, err error)

	// ValidateDelete validates the object on deletion.
	// The optional warnings will be added to the response as warning messages.
	// Return an error if the object is invalid.
	ValidateDelete(ctx context.Context, obj runtime.Object) (warnings Warnings, err error)
}

CustomValidator defines functions for validating an operation. The object to be validated is passed into methods as a parameter.

type Decoder ¶

type Decoder interface {
	// Decode decodes the inlined object in the AdmissionRequest into the passed-in runtime.Object.
	// If you want decode the OldObject in the AdmissionRequest, use DecodeRaw.
	// It errors out if req.Object.Raw is empty i.e. containing 0 raw bytes.
	Decode(req Request, into runtime.Object) error

	// DecodeRaw decodes a RawExtension object into the passed-in runtime.Object.
	// It errors out if rawObj is empty i.e. containing 0 raw bytes.
	DecodeRaw(rawObj runtime.RawExtension, into runtime.Object) error
}

Decoder knows how to decode the contents of an admission request into a concrete object.

func NewDecoder ¶

func NewDecoder(scheme *runtime.Scheme) Decoder

NewDecoder creates a decoder given the runtime.Scheme.

type DefaulterOption ¶

type DefaulterOption func(*defaulterOptions)

DefaulterOption defines the type of a CustomDefaulter's option

type Handler ¶

type Handler interface {
	// Handle yields a response to an AdmissionRequest.
	//
	// The supplied context is extracted from the received http.Request, allowing wrapping
	// http.Handlers to inject values into and control cancelation of downstream request processing.
	Handle(context.Context, Request) Response
}

Handler can handle an AdmissionRequest.

func MultiMutatingHandler ¶

func MultiMutatingHandler(handlers ...Handler) Handler

MultiMutatingHandler combines multiple mutating webhook handlers into a single mutating webhook handler. Handlers are called in sequential order, and the first `allowed: false` response may short-circuit the rest. Users must take care to ensure patches are disjoint.

func MultiValidatingHandler ¶

func MultiValidatingHandler(handlers ...Handler) Handler

MultiValidatingHandler combines multiple validating webhook handlers into a single validating webhook handler. Handlers are called in sequential order, and the first `allowed: false` response may short-circuit the rest.

type HandlerFunc ¶

type HandlerFunc func(context.Context, Request) Response

HandlerFunc implements Handler interface using a single function.

func (HandlerFunc) Handle ¶

func (f HandlerFunc) Handle(ctx context.Context, req Request) Response

Handle process the AdmissionRequest by invoking the underlying function.

type Request ¶

type Request struct {
	admissionv1.AdmissionRequest
}

Request defines the input for an admission handler. It contains information to identify the object in question (group, version, kind, resource, subresource, name, namespace), as well as the operation in question (e.g. Get, Create, etc), and the object itself.

func RequestFromContext ¶

func RequestFromContext(ctx context.Context) (Request, error)

RequestFromContext returns an admission.Request from ctx.

type Response ¶

type Response struct {
	// Patches are the JSON patches for mutating webhooks.
	// Using this instead of setting Response.Patch to minimize
	// overhead of serialization and deserialization.
	// Patches set here will override any patches in the response,
	// so leave this empty if you want to set the patch response directly.
	Patches []jsonpatch.JsonPatchOperation
	// AdmissionResponse is the raw admission response.
	// The Patch field in it will be overwritten by the listed patches.
	admissionv1.AdmissionResponse
}

Response is the output of an admission handler. It contains a response indicating if a given operation is allowed, as well as a set of patches to mutate the object in the case of a mutating admission handler.

func Allowed ¶

func Allowed(message string) Response

Allowed constructs a response indicating that the given operation is allowed (without any patches).

func Denied ¶

func Denied(message string) Response

Denied constructs a response indicating that the given operation is not allowed.

func Errored ¶

func Errored(code int32, err error) Response

Errored creates a new Response for error-handling a request.

func PatchResponseFromRaw ¶

func PatchResponseFromRaw(original, current []byte) Response

PatchResponseFromRaw takes 2 byte arrays and returns a new response with json patch. The original object should be passed in as raw bytes to avoid the roundtripping problem described in https://github.com/kubernetes-sigs/kubebuilder/issues/510.

func Patched ¶

func Patched(message string, patches ...jsonpatch.JsonPatchOperation) Response

Patched constructs a response indicating that the given operation is allowed, and that the target object should be modified by the given JSONPatch operations.

func ValidationResponse ¶

func ValidationResponse(allowed bool, message string) Response

ValidationResponse returns a response for admitting a request.

func (*Response) Complete ¶

func (r *Response) Complete(req Request) error

Complete populates any fields that are yet to be set in the underlying AdmissionResponse, It mutates the response.

func (Response) WithWarnings ¶

func (r Response) WithWarnings(warnings ...string) Response

WithWarnings adds the given warnings to the Response. If any warnings were already given, they will not be overwritten.

type StandaloneOptions ¶

type StandaloneOptions struct {
	// Logger to be used by the webhook.
	// If none is set, it defaults to log.Log global logger.
	Logger logr.Logger
	// MetricsPath is used for labelling prometheus metrics
	// by the path is served on.
	// If none is set, prometheus metrics will not be generated.
	MetricsPath string
}

StandaloneOptions let you configure a StandaloneWebhook.

type Warnings ¶

type Warnings []string

Warnings represents warning messages.

type Webhook ¶

type Webhook struct {
	// Handler actually processes an admission request returning whether it was allowed or denied,
	// and potentially patches to apply to the handler.
	Handler Handler

	// RecoverPanic indicates whether the panic caused by webhook should be recovered.
	// Defaults to true.
	RecoverPanic *bool

	// WithContextFunc will allow you to take the http.Request.Context() and
	// add any additional information such as passing the request path or
	// headers thus allowing you to read them from within the handler
	WithContextFunc func(context.Context, *http.Request) context.Context

	// LogConstructor is used to construct a logger for logging messages during webhook calls
	// based on the given base logger (which might carry more values like the webhook's path).
	// Note: LogConstructor has to be able to handle nil requests as we are also using it
	// outside the context of requests.
	LogConstructor func(base logr.Logger, req *Request) logr.Logger
	// contains filtered or unexported fields
}

Webhook represents each individual webhook.

It must be registered with a webhook.Server or populated by StandaloneWebhook to be ran on an arbitrary HTTP server.

func WithCustomDefaulter ¶

func WithCustomDefaulter(scheme *runtime.Scheme, obj runtime.Object, defaulter CustomDefaulter, opts ...DefaulterOption) *Webhook

WithCustomDefaulter creates a new Webhook for a CustomDefaulter interface.

func WithCustomValidator ¶

func WithCustomValidator(scheme *runtime.Scheme, obj runtime.Object, validator CustomValidator) *Webhook

WithCustomValidator creates a new Webhook for validating the provided type.

func (*Webhook) Handle ¶

func (wh *Webhook) Handle(ctx context.Context, req Request) (response Response)

Handle processes AdmissionRequest. If the webhook is mutating type, it delegates the AdmissionRequest to each handler and merge the patches. If the webhook is validating type, it delegates the AdmissionRequest to each handler and deny the request if anyone denies.

func (*Webhook) ServeHTTP ¶

func (wh *Webhook) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Webhook) WithRecoverPanic ¶

func (wh *Webhook) WithRecoverPanic(recoverPanic bool) *Webhook

WithRecoverPanic takes a bool flag which indicates whether the panic caused by webhook should be recovered. Defaults to true.

Source Files ¶

decode.go defaulter_custom.go doc.go http.go multi.go response.go validator_custom.go webhook.go

Directories ¶